@forgeax/engine-render 0.1.28 → 0.1.30

package/src/__tests__/gpu-scene.unit.test.ts

@@ -1,10 +1,20 @@
-import type { Buffer, Result, RhiError } from '@forgeax/engine-rhi';
+import { World } from '@forgeax/engine-ecs';
+import { createRenderReadLease } from '@forgeax/engine-ecs/projection';
+import { type Buffer, type Result, RhiError } from '@forgeax/engine-rhi';
 import { RhiNullCommandEncoder, RhiNullDevice, RhiNullQueue } from '@forgeax/engine-rhi-null';
+import { createStandardPbrArtifactReceipt } from '@forgeax/engine-shader';
+import { err } from '@forgeax/engine-types';
 import { describe, expect, it } from 'vitest';
 import { GpuScene } from '../gpu-scene';
 import { GPU_SCENE_LAYOUTS, gpuSceneFieldOffset } from '../gpu-scene-schema';
-import type { MaterialSnapshot, RenderableSnapshot } from '../render-system-extract';
-import { RenderScene } from '../scene/render-scene';
+import { packMaterialProgramRow, packStandardPbrMaterialRow } from '../material-row';
+import { makeZeroCameraFallbackSnapshot } from '../record/frame-snapshot';
+import type {
+  ExtractedFrame,
+  MaterialSnapshot,
+  RenderableSnapshot,
+} from '../render-system-extract';
+import { PersistentRenderScene, RenderScene } from '../scene/render-scene';
 import { classifySceneDataCoverage } from '../temporal/coverage';
 
 interface WriteRecord {
@@ -33,6 +43,29 @@ class RecordingQueue extends RhiNullQueue {
   }
 }
 
+class FailingQueue extends RecordingQueue {
+  failWrites = false;
+
+  override writeBuffer(
+    buffer: Buffer,
+    bufferOffset: number,
+    data: ArrayBufferView | ArrayBuffer,
+    dataOffset?: number,
+    size?: number,
+  ): Result<void, RhiError> {
+    if (this.failWrites) {
+      return err(
+        new RhiError({
+          code: 'internal-error',
+          expected: 'temporal transform upload succeeds',
+          hint: 'retry after the queue recovers',
+        }),
+      );
+    }
+    return super.writeBuffer(buffer, bufferOffset, data, dataOffset, size);
+  }
+}
+
 const material = {
   baseColor: new Float32Array([0.25, 0.5, 0.75]),
   metallic: 0.2,
@@ -59,6 +92,69 @@ function snapshot(entityKey: number, translationX = 0): 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 instanceSnapshot(entityKey: number, translationX: number): RenderableSnapshot {
+  const base = snapshot(entityKey);
+  const transforms = new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, translationX, 0, 0, 1]);
+  return {
+    ...base,
+    instances: {
+      transforms,
+      instanceCount: 1,
+      cacheKey: entityKey,
+      archVersion: 0,
+      revision: translationX + 1,
+    },
+  };
+}
+
+function persistentFrame(
+  renderables: readonly RenderableSnapshot[],
+  cameras: ExtractedFrame['cameras'] = [],
+): ExtractedFrame {
+  return {
+    cameras,
+    auxiliaryCameras: [],
+    cubeCameras: [],
+    lights: { directional: undefined, directionalCount: 0, point: [], spot: [] },
+    environment: undefined,
+    environmentReady: true,
+    renderables,
+    dispatch: [],
+    shadowCasterEntityKeys: new Set<number>(),
+    shadowCasterDrawKeys: new Set<string>(),
+    skylight: undefined,
+    skylightCount: 0,
+    skybox: undefined,
+    skyboxCount: 0,
+    fog: undefined,
+    frustumStats: { culled: 0, total: renderables.length },
+    visibilityStats: { explicitlyHidden: 0 },
+    postProcessParams: new Map(),
+    visibilitySnapshots: [],
+    featureVisibilitySnapshots: [],
+    hiddenEntityReports: [],
+  } as unknown as ExtractedFrame;
+}
+
 function createDevice(queue: RecordingQueue): RhiNullDevice {
   return new RhiNullDevice(
     queue,
@@ -67,6 +163,73 @@ function createDevice(queue: RecordingQueue): RhiNullDevice {
 }
 
 describe('GpuScene', () => {
+  it('preserves authored base-color alpha in the scene material row', () => {
+    const row = packStandardPbrMaterialRow(createStandardPbrArtifactReceipt(), {
+      ...material,
+      paramSnapshot: { baseColor: [0.25, 0.5, 0.75, 0.4] },
+    });
+    expect(
+      new DataView(row.buffer).getFloat32(
+        gpuSceneFieldOffset(GPU_SCENE_LAYOUTS.material, 'baseColor') + 3 * 4,
+        true,
+      ),
+    ).toBeCloseTo(0.4);
+  });
+
+  it('prefers extracted Standard PBR values over schema defaults', () => {
+    const row = packStandardPbrMaterialRow(createStandardPbrArtifactReceipt(), material);
+    const view = new DataView(row.buffer);
+    expect(
+      view.getFloat32(gpuSceneFieldOffset(GPU_SCENE_LAYOUTS.material, 'baseColor'), true),
+    ).toBeCloseTo(0.25);
+    expect(
+      view.getFloat32(gpuSceneFieldOffset(GPU_SCENE_LAYOUTS.material, 'metallic'), true),
+    ).toBeCloseTo(0.2);
+    expect(
+      view.getFloat32(gpuSceneFieldOffset(GPU_SCENE_LAYOUTS.material, 'roughness'), true),
+    ).toBeCloseTo(0.8);
+  });
+
+  it('packs a custom schema into the same scene row page', () => {
+    const row = packMaterialProgramRow(
+      [
+        { name: 'tint', type: 'color' },
+        { name: 'roughness', type: 'f32' },
+      ],
+      {
+        ...material,
+        materialShaderId: 'game::custom-surface',
+        materialParamSchema: [
+          { name: 'tint', type: 'color' },
+          { name: 'roughness', type: 'f32' },
+        ],
+        paramSnapshot: { tint: [0.1, 0.2, 0.3, 1], roughness: 0.7 },
+      },
+    );
+    expect(row).toBeDefined();
+    if (row === undefined) return;
+    expect(row.byteLength).toBe(GPU_SCENE_LAYOUTS.material.stride);
+    expect(new DataView(row.buffer).getFloat32(0, true)).toBeCloseTo(0.1);
+    expect(new DataView(row.buffer).getFloat32(16, true)).toBeCloseTo(0.7);
+  });
+
+  it('writes the last vector in a 512-byte page and rejects overflow', () => {
+    const schema = Array.from({ length: 32 }, (_, index) => ({
+      name: `value${index}`,
+      type: 'vec4' as const,
+    }));
+    const row = packMaterialProgramRow(schema, {
+      ...material,
+      paramSnapshot: { value31: [7, 8, 9, 10] },
+    });
+    if (row === undefined) throw new Error('512-byte row missing');
+    expect(row.byteLength).toBe(512);
+    expect(Array.from(new Float32Array(row.buffer, 496, 4))).toEqual([7, 8, 9, 10]);
+    expect(
+      packMaterialProgramRow([...schema, { name: 'overflow', type: 'f32' }], material),
+    ).toBeUndefined();
+  });
+
   it('exposes GPU scene facts as exact temporal coverage', () => {
     const coverage = classifySceneDataCoverage({
       contributors: [{ id: 'gpu-scene', kind: 'exact' }],
@@ -84,19 +247,28 @@ describe('GpuScene', () => {
     const projection = new RenderScene();
 
     const initial = projection.apply([
-      { kind: 'create', snapshot: snapshot(0) },
-      { kind: 'create', snapshot: snapshot(1) },
-      { kind: 'create', snapshot: snapshot(2) },
+      updateSnapshot(snapshot(0)),
+      updateSnapshot(snapshot(1)),
+      updateSnapshot(snapshot(2)),
     ]);
-    expect(created.scene.sync(initial).unwrap()).toMatchObject({ ranges: 5, bytes: 1088 });
+    const expectedInitialBytes =
+      3 * GPU_SCENE_LAYOUTS.primitive.stride +
+      3 * GPU_SCENE_LAYOUTS.instance.stride +
+      4 * GPU_SCENE_LAYOUTS.transform.stride +
+      3 * GPU_SCENE_LAYOUTS.drawTemplate.stride +
+      3 * GPU_SCENE_LAYOUTS.material.stride;
+    expect(created.scene.sync(initial).unwrap()).toMatchObject({
+      ranges: 5,
+      bytes: expectedInitialBytes,
+    });
     const writesAfterInitial = queue.writes.length;
 
     created.scene.sync(projection.apply([])).unwrap();
     expect(queue.writes).toHaveLength(writesAfterInitial);
 
     const dirty = projection.apply([
-      { kind: 'update-transform', worldId: 0, entityKey: 0, world: snapshot(0, 4).transform.world },
-      { kind: 'update-transform', worldId: 0, entityKey: 2, world: snapshot(2, 8).transform.world },
+      { kind: 'update', worldId: 0, entityKey: 0, world: snapshot(0, 4).transform.world },
+      { kind: 'update', worldId: 0, entityKey: 2, world: snapshot(2, 8).transform.world },
     ]);
     expect(created.scene.sync(dirty).unwrap()).toMatchObject({
       ranges: 2,
@@ -106,12 +278,12 @@ describe('GpuScene', () => {
     expect(created.scene.inspect()).toMatchObject({ noChangeFrames: 1 });
   });
 
-  it('skips previous-transform upload when temporal demand is absent', () => {
+  it('does not publish GPU previous transforms for an ordinary moving frame', () => {
     const queue = new RecordingQueue();
     const created = GpuScene.create(createDevice(queue), 1).unwrap();
     if (created.status !== 'available') return;
     const projection = new RenderScene();
-    created.scene.sync(projection.apply([{ kind: 'create', snapshot: snapshot(0, 2) }])).unwrap();
+    created.scene.sync(projection.apply([updateSnapshot(snapshot(0, 2))])).unwrap();
 
     const writesBefore = queue.writes.length;
     const bytesBefore = created.scene.inspect().uploadBytes;
@@ -124,7 +296,7 @@ describe('GpuScene', () => {
     expect(created.scene.inspect().uploadBytes).toBe(bytesBefore);
 
     const dirty = projection.apply([
-      { kind: 'update-transform', worldId: 0, entityKey: 0, world: snapshot(0, 3).transform.world },
+      { kind: 'update', worldId: 0, entityKey: 0, world: snapshot(0, 3).transform.world },
     ]);
     created.scene.sync(dirty).unwrap();
     created.scene.commitTemporalFrame(true).unwrap();
@@ -134,15 +306,68 @@ describe('GpuScene', () => {
     );
   });
 
+  it('keeps persistent GPU previous transforms unchanged until temporal commit', () => {
+    const queue = new RecordingQueue();
+    const device = createDevice(queue);
+    const world = new World();
+    const lease = createRenderReadLease(world);
+    const persistent = new PersistentRenderScene({ getDevice: () => device });
+    const source = snapshot(1, 3);
+
+    persistent.extractComposition(
+      [world],
+      { cameraOwner: 0, resourceOwner: 0 },
+      0,
+      () => persistentFrame([source]),
+      [lease],
+    );
+    const state = persistent.compositionGpuDrivenState();
+    expect(state).toBeDefined();
+    if (state === undefined) return;
+    const slot = persistent.compositionSlots()[0];
+    expect(slot).toBeDefined();
+    if (slot === undefined) return;
+
+    const movedWorld = new Float32Array(slot.snapshot.transform.world);
+    movedWorld[12] = 9;
+    state.scene
+      .sync({
+        created: 0,
+        updated: 1,
+        removed: 0,
+        recreated: 0,
+        ignoredLateUpdates: 0,
+        createdSlots: [],
+        updatedSlots: [
+          { ...slot, snapshot: { ...slot.snapshot, transform: { world: movedWorld } } },
+        ],
+        contentUpdatedSlots: [],
+        instanceUpdatedSlots: [],
+        removedSlots: [],
+        recreatedSlots: [],
+        resynced: 0,
+      })
+      .unwrap();
+    const beforeCommit = state.scene.inspect();
+
+    expect(persistent.commitTemporalFrame().ok).toBe(true);
+    expect(state.scene.inspect()).toMatchObject({
+      uploadRanges: beforeCommit.uploadRanges,
+      uploadBytes: beforeCommit.uploadBytes,
+    });
+    lease.dispose();
+    persistent.dispose();
+  });
+
   it('preserves the prior root transform on transform-only updates', () => {
     const queue = new RecordingQueue();
     const created = GpuScene.create(createDevice(queue), 1).unwrap();
     if (created.status !== 'available') return;
     const projection = new RenderScene();
-    created.scene.sync(projection.apply([{ kind: 'create', snapshot: snapshot(0, 2) }])).unwrap();
+    created.scene.sync(projection.apply([updateSnapshot(snapshot(0, 2))])).unwrap();
 
     const dirty = projection.apply([
-      { kind: 'update-transform', worldId: 0, entityKey: 0, world: snapshot(0, 9).transform.world },
+      { kind: 'update', worldId: 0, entityKey: 0, world: snapshot(0, 9).transform.world },
     ]);
     created.scene.sync(dirty).unwrap();
 
@@ -157,17 +382,171 @@ describe('GpuScene', () => {
     expect(new DataView(bytes.buffer).getFloat32(previousTranslation, true)).toBe(2);
   });
 
+  it('uploads only the instance transform span for an Instances-only update', () => {
+    const queue = new RecordingQueue();
+    const created = GpuScene.create(createDevice(queue), 1).unwrap();
+    if (created.status !== 'available') return;
+    const projection = new RenderScene();
+    created.scene.sync(projection.apply([updateSnapshot(instanceSnapshot(0, 2))])).unwrap();
+
+    const update = projection.apply([updateInstances(instanceSnapshot(0, 9))]);
+    expect(update.instanceUpdatedSlots).toHaveLength(1);
+    expect(update.contentUpdatedSlots).toHaveLength(0);
+    const synced = created.scene.sync(update).unwrap();
+    expect(synced).toMatchObject({
+      ranges: 1,
+      bytes: GPU_SCENE_LAYOUTS.transform.stride,
+    });
+  });
+
+  it('advances GPU previous transforms after a successful temporal commit', () => {
+    const queue = new RecordingQueue();
+    const created = GpuScene.create(createDevice(queue), 4).unwrap();
+    if (created.status !== 'available') return;
+    const projection = new RenderScene();
+    created.scene.sync(projection.apply([updateSnapshot(snapshot(0, 2))])).unwrap();
+    created.scene
+      .sync(
+        projection.apply([
+          {
+            kind: 'update',
+            worldId: 0,
+            entityKey: 0,
+            world: snapshot(0, 9).transform.world,
+          },
+        ]),
+      )
+      .unwrap();
+    queue.writes.length = 0;
+
+    expect(created.scene.commitTemporalFrame().ok).toBe(true);
+    expect(queue.writes).toHaveLength(1);
+    const temporalWrite = queue.writes[0];
+    expect(temporalWrite).toBeDefined();
+    if (temporalWrite === undefined) return;
+    const previousTranslation =
+      gpuSceneFieldOffset(GPU_SCENE_LAYOUTS.transform, 'previousWorld') + 12 * 4;
+    expect(new DataView(temporalWrite.bytes.buffer).getFloat32(previousTranslation, true)).toBe(9);
+  });
+
+  it.each([
+    'taa',
+    'motion-blur',
+  ] as const)('publishes GPU previous transforms for a prepared %s capture', (mode) => {
+    const queue = new RecordingQueue();
+    const device = createDevice(queue);
+    const world = new World();
+    const lease = createRenderReadLease(world);
+    const persistent = new PersistentRenderScene({ getDevice: () => device });
+    const source = snapshot(1, 3);
+    const camera =
+      mode === 'taa'
+        ? { ...makeZeroCameraFallbackSnapshot(), antialias: 'taa' as const }
+        : {
+            ...makeZeroCameraFallbackSnapshot(),
+            motionBlur: { shutterAngle: 180, maxRadiusPixels: 32, sampleCount: 8 },
+          };
+
+    persistent.extractComposition(
+      [world],
+      { cameraOwner: 0, resourceOwner: 0 },
+      0,
+      () => persistentFrame([source], [camera]),
+      [lease],
+    );
+    const state = persistent.compositionGpuDrivenState();
+    expect(state).toBeDefined();
+    if (state === undefined) return;
+    queue.writes.length = 0;
+    persistent.extractComposition(
+      [world],
+      { cameraOwner: 0, resourceOwner: 0 },
+      1,
+      () => persistentFrame([snapshot(1, 6)], [camera]),
+      [lease],
+    );
+    queue.writes.length = 0;
+    const beforeCommit = state.scene.inspect();
+
+    persistent.prepareTemporalFrame([{ worldId: 0, entityKey: 1 }]);
+    expect(persistent.commitTemporalFrame().ok).toBe(true);
+    expect(queue.writes).toHaveLength(1);
+    expect(state.scene.inspect().uploadRanges).toBe(beforeCommit.uploadRanges + 1);
+    lease.dispose();
+    persistent.dispose();
+  });
+
+  it('keeps GPU temporal history unchanged when the temporal upload fails', () => {
+    const queue = new FailingQueue();
+    const created = GpuScene.create(createDevice(queue), 4).unwrap();
+    if (created.status !== 'available') return;
+    const projection = new RenderScene();
+    created.scene.sync(projection.apply([updateSnapshot(snapshot(0, 2))])).unwrap();
+    created.scene
+      .sync(
+        projection.apply([
+          {
+            kind: 'update',
+            worldId: 0,
+            entityKey: 0,
+            world: snapshot(0, 9).transform.world,
+          },
+        ]),
+      )
+      .unwrap();
+    queue.writes.length = 0;
+    queue.failWrites = true;
+    expect(created.scene.commitTemporalFrame().ok).toBe(false);
+    expect(queue.writes).toHaveLength(0);
+
+    queue.failWrites = false;
+    expect(created.scene.commitTemporalFrame().ok).toBe(true);
+    expect(queue.writes).toHaveLength(1);
+    const temporalWrite = queue.writes[0];
+    expect(temporalWrite).toBeDefined();
+    if (temporalWrite === undefined) return;
+    const previousTranslation =
+      gpuSceneFieldOffset(GPU_SCENE_LAYOUTS.transform, 'previousWorld') + 12 * 4;
+    expect(new DataView(temporalWrite.bytes.buffer).getFloat32(previousTranslation, true)).toBe(9);
+  });
+
+  it('publishes CPU previous transforms only after a successful submission', () => {
+    const projection = new RenderScene();
+    projection.setTemporalTracking(true);
+    projection.apply([updateSnapshot(snapshot(0, 2))]);
+    projection.commitSubmission(projection.captureSubmission([{ worldId: 0, entityKey: 0 }]));
+    const slot = projection.slotsSnapshot()[0];
+    expect(slot).toBeDefined();
+    if (slot === undefined) return;
+    expect(projection.temporalSnapshotBySlot(slot.slot)?.previousTransform.world[12]).toBe(2);
+
+    projection.apply([
+      {
+        kind: 'update',
+        worldId: 0,
+        entityKey: 0,
+        world: snapshot(0, 9).transform.world,
+      },
+    ]);
+    const pending = projection.captureSubmission([{ worldId: 0, entityKey: 0 }]);
+    // A failed execute/finish/submit does not call commitSubmission. The
+    // previous frame therefore remains the last successfully submitted pose.
+    expect(projection.temporalSnapshotBySlot(slot.slot)?.previousTransform.world[12]).toBe(2);
+    projection.commitSubmission(pending);
+    expect(projection.temporalSnapshotBySlot(slot.slot)?.previousTransform.world[12]).toBe(9);
+  });
+
   it('clears removed slots, grows without losing the CPU mirror, and rebuilds a fresh table', () => {
     const queue = new RecordingQueue();
-    const created = GpuScene.create(createDevice(queue), 2).unwrap();
+    const created = GpuScene.create(createDevice(queue), 1).unwrap();
     if (created.status !== 'available') return;
     const projection = new RenderScene();
     created.scene
       .sync(
         projection.apply([
-          { kind: 'create', snapshot: snapshot(0) },
-          { kind: 'create', snapshot: snapshot(1) },
-          { kind: 'create', snapshot: snapshot(2) },
+          updateSnapshot(snapshot(0)),
+          updateSnapshot(snapshot(1)),
+          updateSnapshot(snapshot(2)),
         ]),
       )
       .unwrap();
@@ -190,13 +569,13 @@ describe('GpuScene', () => {
     const created = GpuScene.create(createDevice(queue), 1).unwrap();
     if (created.status !== 'available') return;
     const projection = new RenderScene();
-    created.scene.sync(projection.apply([{ kind: 'create', snapshot: snapshot(1, 2) }])).unwrap();
+    created.scene.sync(projection.apply([updateSnapshot(snapshot(1, 2))])).unwrap();
 
     created.scene
       .sync(
         projection.apply([
           { kind: 'remove', worldId: 0, entityKey: 1 },
-          { kind: 'create', snapshot: snapshot(1, 9) },
+          updateSnapshot(snapshot(1, 9)),
         ]),
       )
       .unwrap();
@@ -209,31 +588,232 @@ describe('GpuScene', () => {
     expect(new DataView(transformWrite.bytes.buffer).getFloat32(previousTranslation, true)).toBe(9);
   });
 
-  it('keeps a recycled slot allocated for the replacement identity', () => {
+  it('reserves transform row zero for identity and does not synthesize instance transforms', () => {
     const queue = new RecordingQueue();
-    const created = GpuScene.create(createDevice(queue), 1).unwrap();
+    const created = GpuScene.create(createDevice(queue), 4).unwrap();
     if (created.status !== 'available') return;
     const projection = new RenderScene();
-    created.scene.sync(projection.apply([{ kind: 'create', snapshot: snapshot(1, 2) }])).unwrap();
+    created.scene.sync(projection.apply([updateSnapshot(snapshot(1, 2))])).unwrap();
+
+    const transformWrite = queue.writes.find(
+      ({ bytes }) => bytes.byteLength === 2 * GPU_SCENE_LAYOUTS.transform.stride,
+    );
+    expect(transformWrite).toBeDefined();
+    if (transformWrite === undefined) return;
+    const transforms = new DataView(transformWrite.bytes.buffer);
+    const currentWorld = gpuSceneFieldOffset(GPU_SCENE_LAYOUTS.transform, 'currentWorld');
+    const previousWorld = gpuSceneFieldOffset(GPU_SCENE_LAYOUTS.transform, 'previousWorld');
+    expect(transforms.getFloat32(currentWorld, true)).toBe(1);
+    expect(transforms.getFloat32(previousWorld, true)).toBe(1);
 
     const recycled = projection.apply([
       { kind: 'remove', worldId: 0, entityKey: 1 },
-      { kind: 'create', snapshot: snapshot(2, 7) },
+      updateSnapshot(snapshot(2, 7)),
     ]);
     expect(recycled.removedSlots[0]?.slot).toBe(recycled.createdSlots[0]?.slot);
     created.scene.sync(recycled).unwrap();
 
-    expect(() =>
-      created.scene.sync(
+    const primitiveWrite = queue.writes.find(
+      ({ bytes }) => bytes.byteLength === GPU_SCENE_LAYOUTS.primitive.stride,
+    );
+    expect(primitiveWrite).toBeDefined();
+    if (primitiveWrite === undefined) return;
+    const primitive = new DataView(primitiveWrite.bytes.buffer);
+    expect(
+      primitive.getUint32(gpuSceneFieldOffset(GPU_SCENE_LAYOUTS.primitive, 'transformIndex'), true),
+    ).toBe(1);
+    const instanceWrite = queue.writes.find(
+      ({ bytes }) => bytes.byteLength === GPU_SCENE_LAYOUTS.instance.stride,
+    );
+    expect(instanceWrite).toBeDefined();
+    if (instanceWrite === undefined) return;
+    expect(
+      new DataView(instanceWrite.bytes.buffer).getUint32(
+        gpuSceneFieldOffset(GPU_SCENE_LAYOUTS.instance, 'transformIndex'),
+        true,
+      ),
+    ).toBe(0);
+  });
+
+  it('allocates root and local transform segments only for explicit Instances rows', () => {
+    const queue = new RecordingQueue();
+    const created = GpuScene.create(createDevice(queue), 4).unwrap();
+    if (created.status !== 'available') return;
+    const projection = new RenderScene();
+    const localA = new Float32Array(16);
+    localA[0] = 1;
+    localA[5] = 1;
+    localA[10] = 1;
+    localA[15] = 1;
+    localA[12] = 4;
+    const localB = new Float32Array(localA);
+    localB[12] = 8;
+    created.scene
+      .sync(
         projection.apply([
-          {
-            kind: 'update-transform',
-            worldId: 0,
-            entityKey: 2,
-            world: snapshot(2, 11).transform.world,
-          },
+          updateSnapshot({
+            ...snapshot(0, 3),
+            instances: {
+              transforms: new Float32Array([...localA, ...localB]),
+              instanceCount: 2,
+              cacheKey: 1,
+              archVersion: 1,
+              revision: 1,
+            },
+          }),
         ]),
+      )
+      .unwrap();
+
+    const primitiveWrite = queue.writes.find(
+      ({ bytes }) => bytes.byteLength === GPU_SCENE_LAYOUTS.primitive.stride,
+    );
+    const instanceWrite = queue.writes.find(
+      ({ bytes }) => bytes.byteLength === 2 * GPU_SCENE_LAYOUTS.instance.stride,
+    );
+    const transformWrite = queue.writes.find(
+      ({ bytes }) => bytes.byteLength === 4 * GPU_SCENE_LAYOUTS.transform.stride,
+    );
+    expect(primitiveWrite).toBeDefined();
+    expect(instanceWrite).toBeDefined();
+    expect(transformWrite).toBeDefined();
+    if (primitiveWrite === undefined || instanceWrite === undefined || transformWrite === undefined)
+      return;
+
+    const primitive = new DataView(primitiveWrite.bytes.buffer);
+    expect(
+      primitive.getUint32(gpuSceneFieldOffset(GPU_SCENE_LAYOUTS.primitive, 'transformIndex'), true),
+    ).toBe(1);
+    expect(
+      primitive.getUint32(gpuSceneFieldOffset(GPU_SCENE_LAYOUTS.primitive, 'instanceCount'), true),
+    ).toBe(2);
+    const instances = new DataView(instanceWrite.bytes.buffer);
+    expect(
+      instances.getUint32(gpuSceneFieldOffset(GPU_SCENE_LAYOUTS.instance, 'transformIndex'), true),
+    ).toBe(2);
+    expect(
+      instances.getUint32(
+        GPU_SCENE_LAYOUTS.instance.stride +
+          gpuSceneFieldOffset(GPU_SCENE_LAYOUTS.instance, 'transformIndex'),
+        true,
+      ),
+    ).toBe(3);
+    const transforms = new DataView(transformWrite.bytes.buffer);
+    expect(transforms.getFloat32(0, true)).toBe(1);
+    expect(
+      transforms.getFloat32(
+        GPU_SCENE_LAYOUTS.transform.stride + currentWorldOffset() + 12 * 4,
+        true,
+      ),
+    ).toBe(3);
+    expect(
+      transforms.getFloat32(
+        2 * GPU_SCENE_LAYOUTS.transform.stride + currentWorldOffset() + 12 * 4,
+        true,
       ),
-    ).not.toThrow();
+    ).toBe(4);
+    expect(
+      transforms.getFloat32(
+        3 * GPU_SCENE_LAYOUTS.transform.stride + currentWorldOffset() + 12 * 4,
+        true,
+      ),
+    ).toBe(8);
+  });
+
+  it('keeps empty Instances at zero rows and never reuses identity row on recreation', () => {
+    const queue = new RecordingQueue();
+    const created = GpuScene.create(createDevice(queue), 4).unwrap();
+    if (created.status !== 'available') return;
+    const projection = new RenderScene();
+    const empty = {
+      ...snapshot(0, 3),
+      instances: {
+        transforms: new Float32Array(),
+        instanceCount: 0,
+        cacheKey: 1,
+        archVersion: 1,
+      },
+    };
+    created.scene.sync(projection.apply([updateSnapshot(empty)])).unwrap();
+
+    const primitiveWrite = queue.writes.find(
+      ({ bytes }) => bytes.byteLength === GPU_SCENE_LAYOUTS.primitive.stride,
+    );
+    const transformWrite = queue.writes.find(
+      ({ bytes }) => bytes.byteLength === 2 * GPU_SCENE_LAYOUTS.transform.stride,
+    );
+    expect(primitiveWrite).toBeDefined();
+    expect(transformWrite).toBeDefined();
+    if (primitiveWrite === undefined || transformWrite === undefined) return;
+    const primitive = new DataView(primitiveWrite.bytes.buffer);
+    expect(
+      primitive.getUint32(gpuSceneFieldOffset(GPU_SCENE_LAYOUTS.primitive, 'instanceCount'), true),
+    ).toBe(0);
+    expect(
+      primitive.getUint32(gpuSceneFieldOffset(GPU_SCENE_LAYOUTS.primitive, 'transformIndex'), true),
+    ).toBe(1);
+
+    const writesBeforeRecreate = queue.writes.length;
+    const replacement = { ...empty, assetHandle: 10 };
+    const recreated = projection.apply([
+      { kind: 'remove', worldId: 0, entityKey: 0 },
+      updateSnapshot(replacement),
+    ]);
+    created.scene.sync(recreated).unwrap();
+    const replacementPrimitive = queue.writes
+      .slice(writesBeforeRecreate)
+      .find(({ bytes }) => bytes.byteLength === GPU_SCENE_LAYOUTS.primitive.stride);
+    expect(replacementPrimitive).toBeDefined();
+    if (replacementPrimitive === undefined) return;
+    expect(
+      new DataView(replacementPrimitive.bytes.buffer).getUint32(
+        gpuSceneFieldOffset(GPU_SCENE_LAYOUTS.primitive, 'transformIndex'),
+        true,
+      ),
+    ).toBe(1);
+  });
+  it('uploads changed rows when material, root and sparse instance edits share one update', () => {
+    const queue = new RecordingQueue();
+    const created = GpuScene.create(createDevice(queue), 128).unwrap();
+    if (created.status !== 'available') throw new Error('RHI null must expose storage tables');
+    const projection = new RenderScene();
+    const base = instanceSnapshot(8, 0);
+    if (base.instances === undefined) throw new Error('expected instance fixture');
+    const transforms = new Float32Array(64 * 16);
+    for (let index = 0; index < 64; index += 1) transforms.set(base.transform.world, index * 16);
+    const initial = { ...base, instances: { ...base.instances, instanceCount: 64, transforms } };
+    created.scene.sync(projection.apply([updateSnapshot(initial)])).unwrap();
+    const nextTransforms = new Float32Array(transforms);
+    nextTransforms[17 * 16 + 12] = 4;
+    const nextMaterial = { ...material, roughness: 0.3 };
+    const mixed = {
+      ...initial,
+      transform: snapshot(8, 3).transform,
+      material: nextMaterial,
+      materials: [nextMaterial],
+      instances: { ...initial.instances, transforms: nextTransforms, revision: 2 },
+    };
+    const delta = projection.apply([updateSnapshot(mixed)]);
+    expect(delta.updated).toBe(1);
+    const result = created.scene.sync(delta).unwrap();
+    expect(result.bytes).toBe(
+      GPU_SCENE_LAYOUTS.primitive.stride +
+        GPU_SCENE_LAYOUTS.drawTemplate.stride +
+        GPU_SCENE_LAYOUTS.material.stride +
+        2 * GPU_SCENE_LAYOUTS.transform.stride,
+    );
+    expect(result.grew).toBe(false);
+    const next = { ...mixed, material: { ...nextMaterial, roughness: 0.7 } };
+    next.materials = [next.material];
+    const materialOnly = created.scene.sync(projection.apply([updateSnapshot(next)])).unwrap();
+    expect(materialOnly.bytes).toBe(
+      GPU_SCENE_LAYOUTS.primitive.stride +
+        GPU_SCENE_LAYOUTS.drawTemplate.stride +
+        GPU_SCENE_LAYOUTS.material.stride,
+    );
   });
 });
+
+function currentWorldOffset(): number {
+  return gpuSceneFieldOffset(GPU_SCENE_LAYOUTS.transform, 'currentWorld');
+}