@forgeax/engine-render 0.1.32 → 0.1.34

package/src/__tests__/gpu-driven-view-gpu-evidence.ts

@@ -7,8 +7,13 @@ import { BatchTopology } from '../gpu-driven/batch-topology';
 import { GPU_DRIVEN_VIEW_WGSL, GpuDrivenView } from '../gpu-driven/view-gpu';
 import { GpuScene } from '../gpu-scene';
 import { GPU_BUFFER_USAGE_COPY_DST, GPU_BUFFER_USAGE_MAP_READ } from '../gpu-usage';
+import { getOpaqueResourceIdentity } from '../record/frame-snapshot';
 import type { MaterialSnapshot, RenderableSnapshot } from '../render-system-extract';
 import { RenderScene } from '../scene/render-scene';
+import {
+  type SurfaceSubmissionCandidate,
+  SurfaceSubmissionObservationOwner,
+} from '../surface/submission-observation';
 
 const GPU_MAP_MODE_READ = 0x0001;
 
@@ -62,6 +67,10 @@ export interface GpuDrivenViewGpuEvidence {
   readonly firstInstance: number;
   readonly overflow: number;
   readonly persistentTranslationX: number;
+  readonly firstReadbackFrame: number;
+  readonly recoveredReadbackFrame: number;
+  readonly firstVisible: number;
+  readonly recoveredVisible: number;
 }
 
 export interface GpuDrivenViewLifecycleEvidence {
@@ -71,7 +80,7 @@ export interface GpuDrivenViewLifecycleEvidence {
 }
 
 export async function runGpuDrivenViewLifecycleEvidence(
-  frames = 300,
+  frames = 60,
 ): Promise<GpuDrivenViewLifecycleEvidence> {
   const adapter = (await rhi.requestAdapter()).unwrap();
   const device = (await adapter.requestDevice()).unwrap();
@@ -247,7 +256,27 @@ export async function runGpuDrivenViewGpuEvidence(): Promise<GpuDrivenViewGpuEvi
     })
     .unwrap();
   const graph = new RenderGraphBuilder<{ readonly encoder: RhiCommandEncoder }>();
-  view.addPasses(graph).unwrap();
+  const submissionOwner = new SurfaceSubmissionObservationOwner(() => 1);
+  const beginSubmission = (frameId: number, indirectOffset: number): SurfaceSubmissionCandidate => {
+    const candidate = submissionOwner.begin({
+      frameId,
+      requestedLane: 'gpu-driven',
+      deviceGeneration: 1,
+      resourceGeneration: view.inspect().resourceGeneration,
+    });
+    for (const pass of ['nearest-layer', 'color'] as const) {
+      candidate.record(pass, {
+        kind: 'draw-indexed-indirect',
+        indirectBufferIdentity: getOpaqueResourceIdentity(indirect as object),
+        indirectOffset,
+        pipelineIdentity: 33,
+      });
+    }
+    return candidate;
+  };
+  let currentSubmission = beginSubmission(10, 0);
+  view.setTelemetrySubmit({ frameId: 1, deviceGeneration: 0 });
+  view.addPasses(graph, 'gpu-driven', true, () => currentSubmission).unwrap();
   const compiled = graph.compile({ device, surfaceSize: { width: 1, height: 1 } }).unwrap();
   const encoder = device.createCommandEncoder({ label: 'gpu-driven-evidence' }).unwrap();
   compiled.execute({ encoder }).unwrap();
@@ -262,6 +291,7 @@ export async function runGpuDrivenViewGpuEvidence(): Promise<GpuDrivenViewGpuEvi
     64,
   );
   device.queue.submit([encoder.finish().unwrap()]).unwrap();
+  currentSubmission.submit(device.queue.onSubmittedWorkDone(), 1);
 
   // Start observing immediately, then submit the cached graph again before
   // the first mapAsync settles. The second copy must be skipped while the
@@ -276,9 +306,45 @@ export async function runGpuDrivenViewGpuEvidence(): Promise<GpuDrivenViewGpuEvi
   compiled.execute({ encoder: overlappingEncoder }).unwrap();
   device.queue.submit([overlappingEncoder.finish().unwrap()]).unwrap();
   const lodSelection = await pendingLodSelection;
-  if (lodSelection === undefined || lodSelection.batches.length !== lodSelection.batchCount) {
+  if (lodSelection === undefined) {
+    throw new Error('GPU-driven LOD selection readback unavailable or incomplete');
+  }
+  if (lodSelection.batches.length !== lodSelection.batchCount) {
     throw new Error('GPU-driven LOD selection readback unavailable or incomplete');
   }
+  const surfaceIndirectParameters = lodSelection.surfaceIndirectParameters;
+  if (surfaceIndirectParameters === undefined || surfaceIndirectParameters.length !== 2) {
+    throw new Error('GPU-driven Surface indirect parameter readback unavailable');
+  }
+  const firstSurfaceCommand = surfaceIndirectParameters[0];
+  if (
+    firstSurfaceCommand === undefined ||
+    firstSurfaceCommand.sequence !== lodSelection.surfaceReadback?.sequence ||
+    firstSurfaceCommand.frameId !== lodSelection.surfaceReadback?.frameId ||
+    firstSurfaceCommand.deviceGeneration !== lodSelection.surfaceReadback?.deviceGeneration ||
+    firstSurfaceCommand.resourceGeneration !== lodSelection.surfaceReadback?.resourceGeneration ||
+    firstSurfaceCommand.pass !== 'nearest-layer' ||
+    firstSurfaceCommand.indirectOffset !== 0 ||
+    firstSurfaceCommand.count !== 12 ||
+    firstSurfaceCommand.instanceCount !== 1 ||
+    firstSurfaceCommand.first !== 9 ||
+    firstSurfaceCommand.baseVertex !== 4 ||
+    firstSurfaceCommand.firstInstance !== 0
+  ) {
+    throw new Error(
+      `GPU-driven Surface indirect parameters do not match the submitted batch: ${JSON.stringify({
+        firstSurfaceCommand,
+        surfaceReadback: lodSelection.surfaceReadback,
+      })}`,
+    );
+  }
+  if (
+    lodSelection.submit === undefined ||
+    lodSelection.submit.frameId !== 1 ||
+    lodSelection.submit.deviceGeneration !== 0
+  ) {
+    throw new Error('GPU-driven LOD telemetry lost the copy submit identity');
+  }
   await device.queue.onSubmittedWorkDone();
 
   // After unmap, a later cached-graph submission must restore telemetry
@@ -292,20 +358,49 @@ export async function runGpuDrivenViewGpuEvidence(): Promise<GpuDrivenViewGpuEvi
       frustum.fromViewProjection(frustum.create(), recoveryProjection),
     )
     .unwrap();
+  view.setTelemetrySubmit({ frameId: 2, deviceGeneration: 0 });
   const recoveryEncoder = device
     .createCommandEncoder({ label: 'gpu-driven-evidence-recovery' })
     .unwrap();
+  currentSubmission = beginSubmission(11, 32);
   compiled.execute({ encoder: recoveryEncoder }).unwrap();
   device.queue.submit([recoveryEncoder.finish().unwrap()]).unwrap();
+  currentSubmission.submit(device.queue.onSubmittedWorkDone(), 1);
   await device.queue.onSubmittedWorkDone();
   const recoveredLodSelection = await view.readLodSelection();
   if (
     recoveredLodSelection === undefined ||
     recoveredLodSelection === lodSelection ||
-    recoveredLodSelection.visible === lodSelection.visible
+    recoveredLodSelection.visible === lodSelection.visible ||
+    lodSelection.surfaceReadback?.frameId !== 10 ||
+    recoveredLodSelection.surfaceReadback?.frameId !== 11
   ) {
     throw new Error('GPU-driven LOD telemetry did not recover after a skipped copy');
   }
+  if (
+    recoveredLodSelection.surfaceIndirectParameters?.some(
+      (command) =>
+        command.sequence !== recoveredLodSelection.surfaceReadback?.sequence ||
+        command.frameId !== recoveredLodSelection.surfaceReadback?.frameId ||
+        command.deviceGeneration !== recoveredLodSelection.surfaceReadback?.deviceGeneration ||
+        command.resourceGeneration !== recoveredLodSelection.surfaceReadback?.resourceGeneration,
+    )
+  ) {
+    throw new Error('GPU-driven recovered Surface indirect parameters lost readback identity');
+  }
+  if (
+    recoveredLodSelection.submit === undefined ||
+    recoveredLodSelection.submit.frameId !== 2 ||
+    recoveredLodSelection.submit.deviceGeneration !== 0
+  ) {
+    throw new Error('GPU-driven LOD telemetry reused a stale submit identity');
+  }
+  if (
+    lodSelection.surfaceReadback === undefined ||
+    recoveredLodSelection.surfaceReadback === undefined
+  ) {
+    throw new Error('GPU-driven LOD telemetry lost Surface readback identity');
+  }
   const validationError = await rawDevice.popErrorScope();
   if (validationError !== null) {
     throw new Error(`GPU-driven telemetry overlap validation failed: ${validationError.message}`);
@@ -337,6 +432,10 @@ export async function runGpuDrivenViewGpuEvidence(): Promise<GpuDrivenViewGpuEvi
     firstInstance: indirectValue.getUint32(16, true),
     overflow: overflowValue,
     persistentTranslationX,
+    firstReadbackFrame: lodSelection.surfaceReadback.frameId,
+    recoveredReadbackFrame: recoveredLodSelection.surfaceReadback.frameId,
+    firstVisible: lodSelection.visible,
+    recoveredVisible: recoveredLodSelection.visible,
   };
   view.dispose();
   sceneAvailability.scene.dispose();

package/src/__tests__/gpu-driven-view-graph.integration.test.ts

@@ -12,7 +12,7 @@ import { RhiErrorListenerRegistry } from '../lifecycle';
 import type { RenderFrameState } from '../record/frame-snapshot';
 import { makeZeroCameraFallbackSnapshot } from '../record/frame-snapshot';
 import type { PipelineState, RenderSystemInternals } from '../record/render-context';
-import { ensureCompiledFrameGraph } from '../record/typed-frame-graph';
+import { ensureCompiledFrameGraph, executeCompiledFrameGraph } from '../record/typed-frame-graph';
 import type { RenderPipeline, RenderPipelineFrame } from '../render-pipeline';
 import type {
   ExtractedLights,
@@ -65,6 +65,7 @@ function updateSnapshot(value: RenderableSnapshot) {
 function preparedFrame(view: GpuDrivenView): PreparedGpuDrivenFrame {
   return {
     topologySignature: `view-generation:${view.inspect().resourceGeneration}`,
+    worldKeys: [],
     ownsAllDrawItems: true,
     standardPbrFrameResources: {
       materialBindGroups: [],
@@ -141,6 +142,7 @@ describe('GpuDrivenView graph projection', () => {
     if (first === null) return;
     const prepared: PreparedGpuDrivenFrame = {
       topologySignature: 'stable-gpu-driven-test',
+      worldKeys: [],
       ownsAllDrawItems: true,
       standardPbrFrameResources: {
         materialBindGroups: [],
@@ -239,7 +241,7 @@ describe('GpuDrivenView graph projection', () => {
       {
         name: 'gpu-driven.lod-selection-readback',
         kind: 'copy',
-        dependencies: ['gpu-driven.frustum-compact'],
+        dependencies: ['gpu-driven.frustum-compact', 'gpu-driven.finalize-indirect'],
       },
     ]);
     const encoder = device.createCommandEncoder({ label: 'gpu-driven-view' }).unwrap();
@@ -390,7 +392,21 @@ describe('GpuDrivenView graph projection', () => {
     const retirePrevious = vi.spyOn(compiledPrevious, 'retire');
     const acceptedGraph = compile(preparedFrame(view), 2);
     expect(acceptedGraph).not.toBe(compiledPrevious);
+    expect(retirePrevious).not.toHaveBeenCalled();
+    expect(destroyBuffer.mock.calls.some(([buffer]) => buffer === previousVisible)).toBe(false);
     expect(frameState.compiledFrameGraphGeneration).toBe(2);
+    expect(retirePrevious).not.toHaveBeenCalled();
+    const acceptedEncoder = device
+      .createCommandEncoder({ label: 'gpu-driven-view-accepted' })
+      .unwrap();
+    expect(
+      executeCompiledFrameGraph(
+        internals,
+        frameState,
+        { encoder: acceptedEncoder } as RenderPipelineFrame,
+        acceptedEncoder,
+      ),
+    ).toBe(true);
     expect(retirePrevious).toHaveBeenCalledOnce();
     await device.queue.onSubmittedWorkDone();
     await Promise.resolve();

package/src/__tests__/gpu-driven-view.browser.test.ts

@@ -5,14 +5,7 @@ import {
 } from './gpu-driven-view-gpu-evidence';
 
 const browserReady = typeof navigator !== 'undefined' && navigator.gpu !== undefined;
-const lifecycleFrames =
-  (
-    import.meta as ImportMeta & {
-      readonly env?: { readonly FORGEAX_BROWSER_CI_LIGHTWEIGHT?: string };
-    }
-  ).env?.FORGEAX_BROWSER_CI_LIGHTWEIGHT === '1'
-    ? 60
-    : 300;
+const lifecycleFrames = 60;
 
 describe.skipIf(!browserReady)('GPU-driven View Browser WebGPU', () => {
   it('produces compact visible IDs and portable indirect args on the real browser device', async () => {
@@ -25,6 +18,10 @@ describe.skipIf(!browserReady)('GPU-driven View Browser WebGPU', () => {
       firstInstance: 0,
       overflow: 0,
       persistentTranslationX: 0,
+      firstReadbackFrame: 10,
+      recoveredReadbackFrame: 11,
+      firstVisible: 1,
+      recoveredVisible: 0,
     });
   });
 

package/src/__tests__/gpu-driven-view.dawn.test.ts

@@ -15,12 +15,16 @@ describe('GPU-driven View Dawn', () => {
       firstInstance: 0,
       overflow: 0,
       persistentTranslationX: 0,
+      firstReadbackFrame: 10,
+      recoveredReadbackFrame: 11,
+      firstVisible: 1,
+      recoveredVisible: 0,
     });
   });
 
-  it('survives 300 frames of spawn/despawn capacity crossings without stale buffers', async () => {
+  it('survives 60 frames of spawn/despawn capacity crossings without stale buffers', async () => {
     await expect(runGpuDrivenViewLifecycleEvidence()).resolves.toEqual({
-      frames: 300,
+      frames: 60,
       bufferRebuilds: 4,
       candidateCapacity: 8,
     });

package/src/__tests__/gpu-driven-view.unit.test.ts

@@ -99,7 +99,7 @@ describe('GPU-driven batch topology and CPU oracle', () => {
 
   it('projects compact visible items into batch-local mesh and material indices', () => {
     expect(GPU_DRIVEN_VIEW_WGSL).toMatch(
-      /vec2<u32>\(\s*candidate\.submitAdmission >> 1u,\s*materialOrPalette,/,
+      /vec4<u32>\(\s*candidate\.submitAdmission >> 1u,\s*materialOrPalette,\s*candidate\.primitiveIndex \+ 1u,\s*candidate\.generation,/,
     );
     expect(GPU_DRIVEN_VIEW_WGSL).toContain('(candidate.submitAdmission & 1u)');
     expect(GPU_DRIVEN_VIEW_WGSL).toContain('instance.customDataStart');

package/src/__tests__/gpu-pass-timing-lifecycle.integration.test.ts

@@ -145,6 +145,7 @@ describe('GPU pass timing generation-safe lifecycle', () => {
     const oldReceipt = {
       frameId: oldIdentity.frameId,
       deviceGeneration: oldIdentity.deviceGeneration,
+      presentation: 'ready',
       completed: Promise.resolve(ok(undefined)),
     } as FrameReceipt;
     store.register(oldReceipt, async () => {

package/src/__tests__/gpu-pass-timing.browser.test.ts

@@ -17,9 +17,9 @@ describe.skipIf(!browserReady)('GPU pass timing Browser dev-server runner', () =
     expect(omitted.timings).toBeUndefined();
   });
 
-  // The first live lavapipe renderer pair can exceed Vitest's 15s default while
-  // the shader manifest and timestamp-query path are cold; keep this bound
-  // local to the real WebGPU owner instead of weakening the global timeout.
+  // Each timing case creates a fresh renderer. Its lavapipe initialization can
+  // exceed Vitest's 15s default, including the raster-suppressed case below.
+  // Both retain the same bounded startup allowance and three-frame assertions.
   it('keeps receipt facts and unsupported timing structured without stopping draw', {
     timeout: 30_000,
   }, async () => {
@@ -35,7 +35,9 @@ describe.skipIf(!browserReady)('GPU pass timing Browser dev-server runner', () =
     expect(result.visible).toBe(true);
   });
 
-  it('keeps raster suppression as a test-only falsifier, never timing evidence', async () => {
+  it('keeps raster suppression as a test-only falsifier, never timing evidence', {
+    timeout: 30_000,
+  }, async () => {
     const result = await runBrowserGpuPassTiming({ suppressRaster: true });
     expect(result.rasterSuppressed).toBe(true);
     expect(result.frames).toBe(3);

package/src/__tests__/gpu-pass-timing.rhi-null.unit.test.ts

@@ -16,6 +16,7 @@ function receipt(frameId: number): FrameReceipt {
   return {
     frameId,
     deviceGeneration: 1,
+    presentation: 'ready',
     completed: Promise.resolve(ok(undefined)),
   } as FrameReceipt;
 }

package/src/__tests__/gpu-resource-store-stride.unit.test.ts

@@ -107,6 +107,13 @@ describe('GpuResidencyCache mesh stride', () => {
     };
     const world = new World();
     const handle = world.allocSharedRef('MeshAsset', root);
+    // The root can be pulled before the lower pack finishes loading. A later
+    // call with the complete chain must upgrade the same cache key.
+    const rootOnly = store.ensureResident(handle, root);
+    expect(rootOnly.ok).toBe(true);
+    if (!rootOnly.ok) return;
+    expect(rootOnly.value.lodRanges).toBeUndefined();
+
     const resident = store.ensureResident(handle, root, 0, [lower]);
     expect(resident.ok).toBe(true);
     if (!resident.ok) return;
@@ -120,6 +127,11 @@ describe('GpuResidencyCache mesh stride', () => {
     expect(packedIndices).toBeDefined();
     if (packedIndices === undefined) return;
     expect(new Uint16Array(packedIndices.buffer)).toEqual(new Uint16Array([0, 1, 2, 0, 2, 1]));
+
+    // A stable chain remains an O(1) hit and does not replace the entry again.
+    const stable = store.ensureResident(handle, root, 0, [lower]);
+    expect(stable.ok).toBe(true);
+    if (stable.ok) expect(stable.value).toBe(resident.value);
   });
 
   it('refuses a payload whose bytes do not match the projected stride', async () => {

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

@@ -126,6 +126,34 @@ function instanceSnapshot(entityKey: number, translationX: number): RenderableSn
   };
 }
 
+function multiInstanceSnapshot(
+  entityKey: number,
+  translations: readonly number[],
+  generations: readonly number[],
+): RenderableSnapshot {
+  const base = snapshot(entityKey);
+  const transforms = new Float32Array(translations.length * 16);
+  for (let ordinal = 0; ordinal < translations.length; ordinal += 1) {
+    const offset = ordinal * 16;
+    transforms[offset] = 1;
+    transforms[offset + 5] = 1;
+    transforms[offset + 10] = 1;
+    transforms[offset + 12] = translations[ordinal] ?? 0;
+    transforms[offset + 15] = 1;
+  }
+  return {
+    ...base,
+    instances: {
+      transforms,
+      generations: new Uint32Array(generations),
+      instanceCount: translations.length,
+      cacheKey: entityKey,
+      archVersion: 1,
+      revision: 1,
+    },
+  };
+}
+
 function persistentFrame(
   renderables: readonly RenderableSnapshot[],
   cameras: ExtractedFrame['cameras'] = [],
@@ -163,6 +191,123 @@ function createDevice(queue: RecordingQueue): RhiNullDevice {
 }
 
 describe('GpuScene', () => {
+  it('keeps renderer-owned tables resident across World detach and reattach', () => {
+    const queue = new RecordingQueue();
+    const device = createDevice(queue);
+    const persistent = new PersistentRenderScene({ getDevice: () => device });
+    const firstWorld = new World();
+    const firstLease = createRenderReadLease(firstWorld);
+
+    persistent.extractComposition(
+      [firstWorld],
+      { cameraOwner: 0, resourceOwner: 0 },
+      0,
+      () => persistentFrame([snapshot(1)]),
+      [firstLease],
+    );
+    const first = persistent.compositionGpuDrivenState();
+    expect(first).toBeDefined();
+    if (first === undefined) return;
+
+    persistent.detach(firstWorld);
+    firstLease.dispose();
+    const secondWorld = new World();
+    const secondLease = createRenderReadLease(secondWorld);
+    persistent.extractComposition(
+      [secondWorld],
+      { cameraOwner: 0, resourceOwner: 0 },
+      1,
+      () => persistentFrame([snapshot(2)]),
+      [secondLease],
+    );
+    const second = persistent.compositionGpuDrivenState();
+    expect(second).toBeDefined();
+    expect(second?.scene).toBe(first.scene);
+
+    secondLease.dispose();
+    persistent.dispose();
+  });
+
+  it('uploads only changed material bytes for shared value updates and retries failed writes', () => {
+    const queue = new FailingQueue();
+    const created = GpuScene.create(createDevice(queue), 8).unwrap();
+    expect(created.status).toBe('available');
+    if (created.status !== 'available') return;
+    const scene = created.scene;
+    const projection = new RenderScene();
+    const sources = Array.from({ length: 4 }, (_, index) => ({
+      ...snapshot(index),
+      gpuDrivenDraws: [
+        {
+          kind: 'indexed' as const,
+          first: 0,
+          count: 36,
+          baseVertex: 0,
+          materialSlot: 0,
+          topology: 'triangle-list' as const,
+          pipelineClass: 'pbr',
+          materialResourceClass: '{}',
+        },
+      ],
+    }));
+    scene.sync(projection.apply(sources.map(updateSnapshot))).unwrap();
+    const changed = { ...material, roughness: 0.3 };
+    const updated = sources.map((source) => ({
+      ...source,
+      material: changed,
+      materials: [changed],
+    }));
+    const delta = projection.apply(updated.map(updateSnapshot));
+    queue.failWrites = true;
+    expect(scene.sync(delta).ok).toBe(false);
+    queue.failWrites = false;
+    queue.writes.length = 0;
+    const retried = scene.sync(projection.apply([])).unwrap();
+    expect(retried.bytes).toBe(4 * GPU_SCENE_LAYOUTS.material.stride);
+    expect(queue.writes).toHaveLength(1);
+    const roughness = gpuSceneFieldOffset(GPU_SCENE_LAYOUTS.material, 'roughness');
+    const upload = queue.writes[0];
+    if (upload === undefined) throw new Error('expected material upload');
+    for (let index = 0; index < 4; index++) {
+      expect(
+        new DataView(upload.bytes.buffer).getFloat32(
+          index * GPU_SCENE_LAYOUTS.material.stride + roughness,
+          true,
+        ),
+      ).toBeCloseTo(0.3);
+    }
+    // Fresh snapshots with identical bytes must not upload. Later in-place
+    // caller edits remain visible: packed rows are shared only within sync.
+    expect(scene.sync(projection.apply(updated.map(updateSnapshot))).unwrap().bytes).toBe(0);
+    changed.roughness = 0.6;
+    expect(scene.sync(projection.apply(updated.map(updateSnapshot))).unwrap().bytes).toBe(
+      4 * GPU_SCENE_LAYOUTS.material.stride,
+    );
+    const first = updated[0];
+    const draw = first?.gpuDrivenDraws[0];
+    if (first === undefined || draw === undefined) throw new Error('expected draw fixture');
+    queue.writes.length = 0;
+    const geometryChanged = {
+      ...first,
+      localAabb: new Float32Array([-2, -1, -1, 2, 1, 1]),
+      gpuDrivenDraws: [{ ...draw, first: 6, count: 12, baseVertex: -3 }],
+    };
+    expect(scene.sync(projection.apply([updateSnapshot(geometryChanged)])).unwrap().bytes).toBe(
+      GPU_SCENE_LAYOUTS.primitive.stride + GPU_SCENE_LAYOUTS.drawTemplate.stride,
+    );
+    const drawUpload = queue.writes.find(
+      ({ bytes }) => bytes.length === GPU_SCENE_LAYOUTS.drawTemplate.stride,
+    );
+    if (drawUpload === undefined) throw new Error('expected changed draw upload');
+    expect(
+      new DataView(drawUpload.bytes.buffer).getInt32(
+        gpuSceneFieldOffset(GPU_SCENE_LAYOUTS.drawTemplate, 'baseVertex'),
+        true,
+      ),
+    ).toBe(-3);
+    scene.dispose();
+  });
+
   it('preserves authored base-color alpha in the scene material row', () => {
     const row = packStandardPbrMaterialRow(createStandardPbrArtifactReceipt(), {
       ...material,
@@ -399,6 +544,69 @@ describe('GpuScene', () => {
     });
   });
 
+  it('maps GPU previous instance transforms by stable generation after reorder', () => {
+    const queue = new RecordingQueue();
+    const created = GpuScene.create(createDevice(queue), 4).unwrap();
+    if (created.status !== 'available') return;
+    const projection = new RenderScene();
+    projection.setTemporalTracking(true);
+    const initial = multiInstanceSnapshot(0, [2, 8], [101, 202]);
+    created.scene.sync(projection.apply([updateSnapshot(initial)])).unwrap();
+    projection.commitSubmission(projection.captureSubmission([{ worldId: 0, entityKey: 0 }]));
+
+    const reordered = multiInstanceSnapshot(0, [9, 3], [202, 101]);
+    const delta = projection.apply([updateInstances(reordered)]);
+    const slot = projection.slotsSnapshot()[0];
+    expect(slot).toBeDefined();
+    if (slot === undefined) return;
+    expect(projection.temporalSnapshotBySlot(slot.slot)?.motionValid).toBe(true);
+
+    queue.writes.length = 0;
+    created.scene
+      .sync(delta, (current) => projection.temporalSnapshotBySlot(current.slot))
+      .unwrap();
+    const transformWrite = queue.writes.find(
+      ({ bytes }) => bytes.byteLength === 2 * GPU_SCENE_LAYOUTS.transform.stride,
+    );
+    expect(transformWrite).toBeDefined();
+    if (transformWrite === undefined) return;
+    const previousTranslation =
+      gpuSceneFieldOffset(GPU_SCENE_LAYOUTS.transform, 'previousWorld') + 12 * 4;
+    const transforms = new DataView(transformWrite.bytes.buffer);
+    expect(transforms.getFloat32(previousTranslation, true)).toBe(8);
+    expect(
+      transforms.getFloat32(GPU_SCENE_LAYOUTS.transform.stride + previousTranslation, true),
+    ).toBe(2);
+
+    created.scene.commitTemporalFrame().unwrap();
+    projection.commitSubmission(projection.captureSubmission([{ worldId: 0, entityKey: 0 }]));
+    const retired = multiInstanceSnapshot(0, [11], [202]);
+    const retiredDelta = projection.apply([updateInstances(retired)]);
+    expect(projection.temporalSnapshotBySlot(slot.slot)?.motionValid).toBe(true);
+    queue.writes.length = 0;
+    created.scene
+      .sync(retiredDelta, (current) => projection.temporalSnapshotBySlot(current.slot))
+      .unwrap();
+    const compactedRows = queue.writes
+      .filter(({ bytes }) => bytes.byteLength % GPU_SCENE_LAYOUTS.transform.stride === 0)
+      .flatMap(({ bytes }) =>
+        Array.from({ length: bytes.byteLength / GPU_SCENE_LAYOUTS.transform.stride }, (_, row) => {
+          const view = new DataView(bytes.buffer);
+          return {
+            current: view.getFloat32(
+              row * GPU_SCENE_LAYOUTS.transform.stride + currentWorldOffset() + 12 * 4,
+              true,
+            ),
+            previous: view.getFloat32(
+              row * GPU_SCENE_LAYOUTS.transform.stride + previousTranslation,
+              true,
+            ),
+          };
+        }),
+      );
+    expect(compactedRows).toContainEqual({ current: 11, previous: 9 });
+  });
+
   it('advances GPU previous transforms after a successful temporal commit', () => {
     const queue = new RecordingQueue();
     const created = GpuScene.create(createDevice(queue), 4).unwrap();
@@ -797,20 +1005,13 @@ describe('GpuScene', () => {
     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,
+      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,
-    );
+    expect(materialOnly.bytes).toBe(GPU_SCENE_LAYOUTS.material.stride);
   });
 });
 

package/src/__tests__/instance-allocation-failure.unit.test.ts

@@ -0,0 +1,57 @@
+import { err, RhiError } from '@forgeax/engine-rhi';
+import { rhi } from '@forgeax/engine-rhi-null';
+import { expect, it, vi } from 'vitest';
+import { GPU_SHADER_STAGE_VERTEX } from '../gpu-stage';
+import { GPU_BUFFER_USAGE_STORAGE } from '../gpu-usage';
+import { resolveGeometryInstanceBuffer } from '../record/main-pass-geometry';
+
+it('refuses an instance draw when allocation fails instead of drawing the identity fallback', async () => {
+  const device = (await (await rhi.requestAdapter()).unwrap().requestDevice()).unwrap();
+  const identity = device.createBuffer({ size: 128, usage: GPU_BUFFER_USAGE_STORAGE }).unwrap();
+  const layout = device
+    .createBindGroupLayout({
+      entries: [
+        { binding: 0, visibility: GPU_SHADER_STAGE_VERTEX, buffer: { type: 'read-only-storage' } },
+      ],
+    })
+    .unwrap();
+  const failure = new RhiError({
+    code: 'rhi-not-available',
+    expected: 'an instance buffer allocation',
+    hint: 'recover the renderer',
+  });
+  const allocation = vi.spyOn(device, 'createBuffer').mockReturnValue(err(failure));
+  const bindGroup = vi.spyOn(device, 'createBindGroup');
+  const fire = vi.fn();
+  try {
+    const result = resolveGeometryInstanceBuffer(
+      {
+        runtime: { device, errorRegistry: { fire } },
+        pipelineState: { identityInstanceBuffer: identity, instancesBindGroupLayout: layout },
+        frameState: { instanceBuffers: new Map() },
+        bindGroupCounts: { createBindGroup: 0, keys: [] },
+      } as unknown as Parameters<typeof resolveGeometryInstanceBuffer>[0],
+      {
+        source: {
+          worldId: 0,
+          entityKey: 1,
+          instances: {
+            transforms: new Float32Array(32),
+            instanceCount: 2,
+            cacheKey: 1,
+            archVersion: 0,
+          },
+        },
+      } as Parameters<typeof resolveGeometryInstanceBuffer>[1],
+      [],
+      false,
+    );
+    expect(result).toBeNull();
+    expect(fire).toHaveBeenCalledWith(failure);
+    expect(bindGroup).not.toHaveBeenCalled();
+  } finally {
+    allocation.mockRestore();
+    bindGroup.mockRestore();
+    device.destroyBuffer(identity).unwrap();
+  }
+});