@forgeax/engine-render 0.1.33 → 0.1.35

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,8 +256,27 @@ export async function runGpuDrivenViewGpuEvidence(): Promise<GpuDrivenViewGpuEvi
     })
     .unwrap();
   const graph = new RenderGraphBuilder<{ readonly encoder: RhiCommandEncoder }>();
+  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).unwrap();
+  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();
@@ -263,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
@@ -277,10 +306,43 @@ 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.submit?.frameId !== 1 || lodSelection.submit.deviceGeneration !== 0) {
+  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();
@@ -300,23 +362,45 @@ export async function runGpuDrivenViewGpuEvidence(): Promise<GpuDrivenViewGpuEvi
   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.submit?.frameId !== 2 ||
+    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}`);
@@ -348,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-scene.unit.test.ts

@@ -191,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,
@@ -888,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();
+  }
+});

package/src/__tests__/instances-culling.integration.test.ts

@@ -7,8 +7,6 @@ import { Instances } from '../components/instances';
 import { MeshFilter } from '../components/mesh-filter';
 import { MeshRenderer } from '../components/mesh-renderer';
 import { GPU_DRIVEN_VIEW_WGSL } from '../gpu-driven/view-gpu';
-import type { InstanceCollectionId } from '../instances';
-import { InstanceCollectionStore } from '../instances';
 import { extractFrames } from '../render-system-extract';
 
 const IDENTITY = new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]);
@@ -28,21 +26,13 @@ function spawnCamera(world: World): void {
     .unwrap();
 }
 
-function spawnInstancedCube(
-  world: World,
-  instanceCollections: InstanceCollectionStore,
-  entityX: number,
-  instanceX: number,
-) {
-  const collectionId = instanceCollections
-    .create({ transforms: translated(instanceX) })
-    .unwrap().collectionId;
+function spawnInstancedCube(world: World, entityX: number, instanceX: number) {
   return world
     .spawn(
       { component: Transform, data: { pos: [entityX, 0, 0] } },
       { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
       { component: MeshRenderer, data: {} },
-      { component: Instances, data: { collectionId } },
+      { component: Instances, data: { transforms: translated(instanceX) } },
     )
     .unwrap();
 }
@@ -52,13 +42,10 @@ describe('Instances CPU/GPU culling ownership', () => {
     const world = new World();
     registerPropagateTransforms(world);
     spawnCamera(world);
-    const instanceCollections = new InstanceCollectionStore();
-    const entity = spawnInstancedCube(world, instanceCollections, 20, -20);
+    const entity = spawnInstancedCube(world, 20, -20);
     world.update(0).unwrap();
 
-    const frame = extractFrames([world], 0, undefined, undefined, undefined, {
-      instanceCollections,
-    });
+    const frame = extractFrames([world], 0);
 
     expect(frame.renderables.map((renderable) => renderable.entityKey)).toContain(entity);
     expect(frame.frustumStats).toEqual({ culled: 0, total: 1 });
@@ -68,22 +55,15 @@ describe('Instances CPU/GPU culling ownership', () => {
     const world = new World();
     registerPropagateTransforms(world);
     spawnCamera(world);
-    const instanceCollections = new InstanceCollectionStore();
-    const entity = spawnInstancedCube(world, instanceCollections, 20, -20);
+    const entity = spawnInstancedCube(world, 20, -20);
     world.update(0).unwrap();
-    expect(
-      extractFrames([world], 0, undefined, undefined, undefined, { instanceCollections })
-        .renderables,
-    ).toHaveLength(1);
+    expect(extractFrames([world], 0).renderables).toHaveLength(1);
 
     world.set(entity, Transform, { pos: [40, 0, 0] }).unwrap();
-    const collectionId = world.get(entity, Instances).unwrap().collectionId;
-    instanceCollections.replace(collectionId as InstanceCollectionId, translated(-40)).unwrap();
+    world.set(entity, Instances, { transforms: translated(-40) }).unwrap();
     world.update(0).unwrap();
 
-    const frame = extractFrames([world], 0, undefined, undefined, undefined, {
-      instanceCollections,
-    });
+    const frame = extractFrames([world], 0);
     expect(frame.renderables).toHaveLength(1);
     expect(frame.renderables[0]?.instances?.instanceCount).toBe(1);
   });
@@ -92,23 +72,17 @@ describe('Instances CPU/GPU culling ownership', () => {
     const world = new World();
     registerPropagateTransforms(world);
     spawnCamera(world);
-    const instanceCollections = new InstanceCollectionStore();
-    const collectionId = instanceCollections
-      .create({ transforms: new Float32Array() })
-      .unwrap().collectionId;
     const entity = world
       .spawn(
         { component: Transform, data: { pos: [20, 0, 0] } },
         { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
         { component: MeshRenderer, data: {} },
-        { component: Instances, data: { collectionId } },
+        { component: Instances, data: { transforms: new Float32Array() } },
       )
       .unwrap();
     world.update(0).unwrap();
 
-    const frame = extractFrames([world], 0, undefined, undefined, undefined, {
-      instanceCollections,
-    });
+    const frame = extractFrames([world], 0);
     expect(
       frame.renderables.find((renderable) => renderable.entityKey === entity)?.instances,
     ).toMatchObject({ instanceCount: 0 });