@forgeax/engine-render 0.1.33 → 0.1.34

package/src/__tests__/receipt-observation-retirement.unit.test.ts

@@ -0,0 +1,65 @@
+import type { Buffer, MappedBuffer, RhiDevice, Texture } from '@forgeax/engine-rhi';
+import { ok } from '@forgeax/engine-types';
+import { expect, it, vi } from 'vitest';
+import { createRendererObservationCaptureOwner } from '../assembly/webgpu-renderer-observation-owner';
+
+function deferred<T>(): { readonly promise: Promise<T>; readonly resolve: (value: T) => void } {
+  let resolve!: (value: T) => void;
+  const promise = new Promise<T>((next) => {
+    resolve = next;
+  });
+  return { promise, resolve };
+}
+
+it('retires a receipt observation readback only after its pending map completes', async () => {
+  const mapStarted = deferred<void>();
+  const mapCompleted = deferred<ReturnType<typeof ok<MappedBuffer>>>();
+  const mappedBytes = new ArrayBuffer(256);
+  const unmap = vi.fn();
+  const buffer = {
+    mapAsync: async () => {
+      mapStarted.resolve();
+      return mapCompleted.promise;
+    },
+  } as unknown as Buffer;
+  const texture = {} as Texture;
+  const destroyBuffer = vi.fn(() => ok(undefined));
+  const device = { destroyBuffer } as unknown as RhiDevice;
+  const errors: unknown[] = [];
+  const owner = createRendererObservationCaptureOwner((error) => errors.push(error));
+  const capture = {
+    domain: 'linear-hdr' as const,
+    format: 'rgba8unorm' as const,
+    device,
+    texture,
+    buffer,
+    frameNumber: 17,
+    deviceGeneration: 3,
+    graphGeneration: 9,
+    backendId: 'null' as const,
+    width: 1,
+    height: 1,
+    bytesPerRow: 256,
+  };
+  owner.observationCaptureOwner.register(capture);
+  expect(owner.observationCaptureOwner.consume(17)).toEqual([capture]);
+
+  const pending = owner.readObservationCapture(capture);
+  await mapStarted.promise;
+  expect(destroyBuffer).not.toHaveBeenCalled();
+  expect(owner.stats).toMatchObject({ liveCount: 1, mapCount: 1, readbackCount: 0 });
+
+  mapCompleted.resolve(
+    ok({
+      getMappedRange: () => ok(mappedBytes),
+      unmap,
+    } as unknown as MappedBuffer),
+  );
+  await expect(pending).resolves.toMatchObject({ ok: true, value: new Uint8Array(256) });
+  expect(unmap).toHaveBeenCalledTimes(1);
+  expect(destroyBuffer).toHaveBeenCalledTimes(1);
+  expect(owner.stats).toMatchObject({ liveCount: 0, mapCount: 1, readbackCount: 1 });
+  expect(errors).toEqual([]);
+  expect(owner.disposeReceiptObservationCaptures()).toBeUndefined();
+  expect(destroyBuffer).toHaveBeenCalledTimes(1);
+});

package/src/__tests__/recovery-candidate-prepare.contract.test.ts

@@ -22,6 +22,10 @@ const rendererRecoverySource = readFileSync(
   resolve(import.meta.dirname, '../assembly/recovery/renderer-recover.ts'),
   'utf8',
 );
+const recoveryPipelineSource = readFileSync(
+  resolve(import.meta.dirname, '../record/recovery-pipeline.ts'),
+  'utf8',
+);
 
 describe('recovery candidate preparation contract', () => {
   it('does not restore the lost device SSR history when publishing a detached candidate', () => {
@@ -145,6 +149,31 @@ describe('recovery candidate preparation contract', () => {
     expect(resolver).not.toContain('internals.device.limits');
   });
 
+  it('rehydrates capability variants before copying late-installed material declarations', () => {
+    const preparation = rendererRecoverySource.indexOf('await prepareMaterialShaders(');
+    const copy = rendererRecoverySource.indexOf(
+      'const activeShaderCatalog = getActiveShaderState().shaderInstance',
+    );
+    expect(preparation).toBeGreaterThanOrEqual(0);
+    expect(copy).toBeGreaterThan(preparation);
+    const copyBlock = rendererRecoverySource.slice(copy);
+    expect(copyBlock).toContain('candidateShaderCatalog.findMaterialArtifact(identifier).ok');
+    expect(copyBlock).toContain('candidateShaderCatalog.installMaterialArtifact(identifier');
+  });
+
+  it('rehydrates Surface dynamic page bytes before candidate GPU preparation', () => {
+    const start = recoveryCandidateSource.indexOf('let recoverySurfaceDynamicInput =');
+    const end = recoveryCandidateSource.indexOf(
+      'if (candidateGpuDrivenScene.state !== undefined)',
+      start,
+    );
+    const surface = recoveryCandidateSource.slice(start, end);
+    expect(surface).toContain('candidateSurfacePage.bytes.set(source.page.bytes)');
+    expect(surface.indexOf('candidateSurfacePage.bytes.set(source.page.bytes)')).toBeLessThan(
+      surface.indexOf('recoverySurfaceDynamicInput = {'),
+    );
+  });
+
   it('keeps render-system residency bindings live across publication', () => {
     const start = rendererSource.indexOf('const renderSystem: RenderSystem = createRenderSystem({');
     const end = rendererSource.indexOf('errorRegistry: internals.errorRegistry', start);
@@ -155,4 +184,44 @@ describe('recovery candidate preparation contract', () => {
     expect(assembly).not.toMatch(/\n\s*gpuStore,\n/);
     expect(assembly).not.toMatch(/\n\s*dynamicTextureStore,\n/);
   });
+
+  it('rebuilds candidate shaders from accepted receipts with candidate-bound adapters', () => {
+    expect(rendererRecoverySource).toContain('entry.value.receipt === undefined');
+    expect(rendererRecoverySource).toContain('{ receipt: entry.value.receipt }');
+    expect(rendererRecoverySource).toContain(
+      'getShaderModuleAdapter().createShaderModule(descriptor)',
+    );
+    expect(rendererRecoverySource).toContain(
+      'getImmediateShaderModuleAdapter().createShaderModule(descriptor)',
+    );
+    expect(renderSystemSource).toContain('materialArtifacts: frameState.recoveryMaterialArtifacts');
+    expect(recoveryCandidateSource).toContain('materialArtifacts.size === 0');
+    expect(recoveryCandidateSource).toContain('{ materialArtifacts }');
+    expect(recoveryCandidateSource).toContain('domain: range.domain');
+    expect(recoveryCandidateSource).not.toContain('recovery-water-domain');
+  });
+
+  it('prepares the submitted forward specialization with the direct Surface ABI', () => {
+    expect(recoveryPipelineSource).toContain('readonly dispatch: readonly DispatchEntry[]');
+    expect(recoveryPipelineSource).toContain(
+      "candidate.tags.LightMode !== 'Forward' || candidate.materialShaderId === undefined",
+    );
+    expect(recoveryPipelineSource).toContain('forwardProgram?.materialShaderId');
+    expect(recoveryPipelineSource).toContain("'surface-direct-cluster-pbr' as const");
+    expect(recoveryPipelineSource).toContain("'surface-direct-pbr' as const");
+    expect(recoveryPipelineSource).toContain("'immediate',");
+  });
+
+  it('retires the candidate display view before publishing its prepared owners', () => {
+    const start = recoveryCandidateSource.indexOf('const publishRecoveryGraphCandidate');
+    const publish = recoveryCandidateSource.slice(start);
+    const retire = publish.indexOf('candidateDisplayGraph?.retire()');
+    const publication = publish.indexOf('Object.assign(frameState, candidate.frameState)');
+
+    expect(retire).toBeGreaterThanOrEqual(0);
+    expect(publication).toBeGreaterThan(retire);
+    expect(publish).toContain('candidate.frameState.compiledFrameGraph = null');
+    expect(publish).toContain('candidate.frameState.compiledFrameGraphTopologyKey = null');
+    expect(publish).toContain('candidate.frameState.perFrameGraph = null');
+  });
 });

package/src/__tests__/render-error-code-owner.test-d.ts

@@ -39,7 +39,9 @@ const expectedCodes = [
   'dynamic-resolution-invalid-parameter',
   'dynamic-resolution-requires-taa',
   'dynamic-resolution-timing-unavailable',
+  'barrel-distortion-invalid-parameter',
   'motion-blur-invalid-params',
+
   'shadow-invalid-config',
   'equirect-projection-failed',
   'standard-light-budget-exceeded',
@@ -87,6 +89,11 @@ const expectedCodes = [
   'volume-invalid-bounds',
   'volume-invalid-parameters',
   'projector-binding-failed',
+  'cloud-layer-invalid-parameter',
+  'cloud-layer-owner-conflict',
+  'cloud-layer-cache-invalid',
+  'cloud-layer-capability-missing',
+  'cloud-layer-resource-failed',
 ] as const satisfies readonly RenderErrorCode[];
 type ExpectedCodeUnion = (typeof expectedCodes)[number];
 

package/src/__tests__/render-feature-diagnostics.unit.test.ts

@@ -12,7 +12,17 @@ function gatedFeature(): RenderFeature<{ readonly frame: number }> {
     identity: 'synthetic.gated',
     requiredCapabilities: ['compute'],
     extract: ({ frameNumber }) => ok({ frame: frameNumber }),
-    plan: () => ok({ resources: [], passes: [] }),
+    plan: () =>
+      ok({
+        resources: [
+          {
+            kind: 'fullscreen-program' as const,
+            name: 'synthetic.gated.program',
+            source: 'synthetic',
+          },
+        ],
+        passes: [],
+      }),
   };
 }
 
@@ -82,7 +92,10 @@ describe('render feature diagnostics and capability gate', () => {
       caps: caps(false),
     });
 
-    expect(first.stageEvents).toEqual([]);
+    expect(first.stageEvents).toEqual([
+      { featureIdentity: 'synthetic.gated', order: 0, stage: 'extract' },
+      { featureIdentity: 'synthetic.gated', order: 0, stage: 'plan' },
+    ]);
     expect(first.errors).toHaveLength(1);
     expect(first.errors[0]?.code).toBe('render-feature-capability-missing');
     expect(host.diagnostics()[0]?.status).toBe('disabled');

package/src/__tests__/render-feature-error-reporting.unit.test.ts

@@ -1,12 +1,15 @@
 import { describe, expect, it } from 'vitest';
+import { type RenderError, RenderFeatureStageFailedError } from '../errors/render.js';
 import {
   PENDING_RENDER_FEATURE_ERROR_REPORT_INTERVAL_FRAMES,
+  type PendingRenderFeatureErrorReport,
+  reportPendingRenderFeatureErrors,
   shouldReportPendingRenderFeatureError,
 } from '../features/error-reporting.js';
 
 describe('pending render-feature error reporting', () => {
   it('reports the first failure, suppresses the hot-loop, and reopens the cooldown', () => {
-    const lastReportedFrame = new Map<string, number>();
+    const lastReportedFrame = new Map<string, PendingRenderFeatureErrorReport>();
     expect(shouldReportPendingRenderFeatureError(lastReportedFrame, 'feature\0plan', 10)).toBe(
       true,
     );
@@ -22,3 +25,20 @@ describe('pending render-feature error reporting', () => {
     ).toBe(true);
   });
 });
+
+describe('changed render-feature failures', () => {
+  it('reports a new cause immediately without flooding repeats', () => {
+    const lastReportedFrame = new Map<string, PendingRenderFeatureErrorReport>();
+    const reported: RenderError[] = [];
+    const registry = { fire: (error: RenderError) => reported.push(error) };
+    const failure = (message: string) =>
+      new RenderFeatureStageFailedError('recovery', 0, 'plan', 'next-frame', new Error(message));
+    reportPendingRenderFeatureErrors([failure('invalid-format')], 1, lastReportedFrame, registry);
+    reportPendingRenderFeatureErrors([failure('invalid-format')], 2, lastReportedFrame, registry);
+    reportPendingRenderFeatureErrors([failure('cycle')], 3, lastReportedFrame, registry);
+    expect(reported).toHaveLength(2);
+    reportPendingRenderFeatureErrors([failure('cycle')], 4, lastReportedFrame, registry);
+    expect(reported).toHaveLength(2);
+    expect(lastReportedFrame.size).toBe(1);
+  });
+});

package/src/__tests__/render-feature-prepared-diagnostics.unit.test.ts

@@ -23,7 +23,16 @@ function feature(mode: 'healthy' | 'failed'): RenderFeature<{ readonly ready: tr
               'next-frame',
             ),
           )
-        : ok({ resources: [], passes: [] }),
+        : ok({
+            resources: [
+              {
+                kind: 'fullscreen-program' as const,
+                name: 'synthetic.diagnostics.program',
+                source: 'synthetic',
+              },
+            ],
+            passes: [],
+          }),
   };
 }
 

package/src/__tests__/render-feature-retry.unit.test.ts

@@ -55,7 +55,17 @@ describe('render feature retry rules', () => {
       identity: 'synthetic.capability-retry',
       requiredCapabilities: ['compute'],
       extract: ({ frameNumber }) => ok({ frame: frameNumber }),
-      plan: () => ok({ resources: [], passes: [] }),
+      plan: () =>
+        ok({
+          resources: [
+            {
+              kind: 'fullscreen-program' as const,
+              name: 'synthetic.capability-retry.program',
+              source: 'synthetic',
+            },
+          ],
+          passes: [],
+        }),
     };
     const host = createRenderFeatureHost([feature], caps(false)).unwrap();
 
@@ -65,6 +75,7 @@ describe('render feature retry rules', () => {
       frameNumber: 1,
       caps: caps(false),
     });
+    expect(host.diagnostics()[0]?.status).toBe('disabled');
     expect(
       runRenderFeatureFrame(host, {
         worlds: [],

package/src/__tests__/render-scene-mixed-updates.integration.test.ts

@@ -1,4 +1,4 @@
-import { AssetRegistry, HANDLE_CUBE } from '@forgeax/engine-assets-runtime';
+import { AssetRegistry, HANDLE_CUBE, RuntimeMaterialValue } from '@forgeax/engine-assets-runtime';
 import type { EntityHandle } from '@forgeax/engine-ecs';
 import { World } from '@forgeax/engine-ecs';
 import { createRenderReadLease } from '@forgeax/engine-ecs/projection';
@@ -15,7 +15,7 @@ import {
   Visibility,
   VisibilityStateValue,
 } from '../components';
-import { InstanceCollectionStore } from '../instances';
+import { InstanceProjectionStore } from '../instances';
 import { type ExtractedFrame, extractFrames } from '../render-system-extract';
 import {
   type PersistentRenderCandidateRequest,
@@ -47,7 +47,7 @@ function material(values: Record<string, unknown>): MaterialAsset {
   };
 }
 
-function createWorld(instanceCollections: InstanceCollectionStore, withCamera: boolean) {
+function createWorld(withCamera: boolean) {
   const world = new World();
   registerPropagateTransforms(world);
   const values: Record<string, unknown> = {
@@ -80,7 +80,6 @@ function createWorld(instanceCollections: InstanceCollectionStore, withCamera: b
       { component: Visibility, data: { state: VisibilityStateValue.visible } },
     )
     .unwrap();
-  const mixedCollection = instanceCollections.create({ transforms: matrices(2, 0) }).unwrap();
   const mixed = world
     .spawn(
       { component: Transform, data: { pos: [0, 0, 0] } },
@@ -88,7 +87,7 @@ function createWorld(instanceCollections: InstanceCollectionStore, withCamera: b
       { component: Visibility, data: { state: VisibilityStateValue.inherited } },
       { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
       { component: MeshRenderer, data: { materials: [materialHandle] } },
-      { component: Instances, data: { collectionId: mixedCollection.collectionId } },
+      { component: Instances, data: { transforms: matrices(2, 0) } },
     )
     .unwrap();
   const sharedConsumer = world
@@ -119,7 +118,6 @@ function createWorld(instanceCollections: InstanceCollectionStore, withCamera: b
     world,
     values,
     materialHandle,
-    mixedCollectionId: mixedCollection.collectionId,
     mixed,
     sharedConsumer,
     hiddenTarget,
@@ -167,10 +165,59 @@ function rowFor(frame: ExtractedFrame, worldId: number, entityKey: EntityHandle)
 }
 
 describe('PersistentRenderScene mixed World updates', () => {
+  it('publishes instance inspection only with the accepted Scene and retires removed components', () => {
+    const { world, mixed } = createWorld(true);
+    const instanceCollections = new InstanceProjectionStore();
+    const scene = new PersistentRenderScene({ instanceCollections });
+    const lease = createRenderReadLease(world);
+    const owner = { cameraOwner: 0, resourceOwner: 0 };
+    let rejectCandidate = false;
+    const build = (request: PersistentRenderCandidateRequest) => {
+      const frame = extractFrames([world], owner, undefined, undefined, undefined, {
+        cull: 'none',
+        retainHidden: true,
+        renderables: request,
+        instanceCollections,
+      });
+      if (rejectCandidate && request !== 'none') throw new Error('reject prepared candidate');
+      return frame;
+    };
+    const draw = () => scene.extractComposition([world], owner, 0, build, [lease]);
+    try {
+      draw();
+      const before = instanceCollections._inspections(0);
+      expect(before).toHaveLength(1);
+      world.set(mixed, Instances, { transforms: matrices(3, 9) }).unwrap();
+      rejectCandidate = true;
+      expect(draw).toThrow('reject prepared candidate');
+      expect(instanceCollections._inspections(0)).toEqual(before);
+      rejectCandidate = false;
+      expect(rowFor(draw(), 0, mixed)?.instances?.instanceCount).toBe(3);
+      expect(instanceCollections._inspections(0)[0]?.revision).toBe((before[0]?.revision ?? 0) + 1);
+      world.removeComponent(mixed, Instances).unwrap();
+      draw();
+      expect(instanceCollections._inspections(0)).toEqual([]);
+      world
+        .addComponent(mixed, { component: Instances, data: { transforms: matrices(1, 2) } })
+        .unwrap();
+      draw();
+      expect(instanceCollections._inspections(0)[0]?.collectionId).not.toBe(
+        before[0]?.collectionId,
+      );
+      world.despawn(mixed).unwrap();
+      draw();
+      expect(instanceCollections._inspections(0)).toEqual([]);
+    } finally {
+      lease.dispose();
+      scene.dispose();
+      instanceCollections.dispose();
+    }
+  });
+
   it('reconciles mixed fields against a fresh extract while retaining other slot history', () => {
-    const instanceCollections = new InstanceCollectionStore();
-    const first = createWorld(instanceCollections, true);
-    const second = createWorld(instanceCollections, false);
+    const instanceCollections = new InstanceProjectionStore();
+    const first = createWorld(true);
+    const second = createWorld(false);
     const worlds = [first.world, second.world] as const;
     const leases = [
       createRenderReadLease(first.world),
@@ -226,15 +273,24 @@ describe('PersistentRenderScene mixed World updates', () => {
       expect(initialOtherWorld).toBeDefined();
 
       requests.length = 0;
-      instanceCollections.replace(first.mixedCollectionId, matrices(3, 2)).unwrap();
+      first.world.set(first.mixed, Instances, { transforms: matrices(3, 2) }).unwrap();
       first.world.set(first.mixed, Transform, { pos: [0.25, 0, 0] }).unwrap();
       first.world.set(first.mixed, ChildOf, { parent: first.parentB }).unwrap();
       first.world.set(first.parentA, Visibility, { state: VisibilityStateValue.hidden }).unwrap();
       first.world
         .set(first.hiddenTarget, Visibility, { state: VisibilityStateValue.hidden })
         .unwrap();
-      first.values.baseColor = [0, 1, 0, 1];
-      first.world.sharedRefs.markChanged(first.materialHandle).unwrap();
+      first.world
+        .spawn({
+          component: RuntimeMaterialValue,
+          data: {
+            asset: first.materialHandle,
+            parameter: 'baseColor',
+            kind: 2,
+            value: [0, 1, 0, 1],
+          },
+        })
+        .unwrap();
       first.world.update(0).unwrap();
 
       const mixed = draw();
@@ -264,7 +320,7 @@ describe('PersistentRenderScene mixed World updates', () => {
       submit(mixed);
 
       requests.length = 0;
-      instanceCollections.replace(first.mixedCollectionId, matrices(0, 0)).unwrap();
+      first.world.set(first.mixed, Instances, { transforms: matrices(0, 0) }).unwrap();
       first.world.update(0).unwrap();
       const zero = draw();
       expect(frameFacts(zero)).toEqual(frameFacts(drawableOracle()));
@@ -274,7 +330,7 @@ describe('PersistentRenderScene mixed World updates', () => {
       submit(zero);
 
       requests.length = 0;
-      instanceCollections.replace(first.mixedCollectionId, matrices(1, -2)).unwrap();
+      first.world.set(first.mixed, Instances, { transforms: matrices(1, -2) }).unwrap();
       first.world.update(0).unwrap();
       const one = draw();
       expect(frameFacts(one)).toEqual(frameFacts(drawableOracle()));
@@ -290,9 +346,9 @@ describe('PersistentRenderScene mixed World updates', () => {
   });
 
   it('retains slot and temporal history across World reorder and catalog refresh', () => {
-    const instanceCollections = new InstanceCollectionStore();
-    const first = createWorld(instanceCollections, true);
-    const second = createWorld(instanceCollections, false);
+    const instanceCollections = new InstanceProjectionStore();
+    const first = createWorld(true);
+    const second = createWorld(false);
     let worlds: readonly World[] = [first.world, second.world];
     let leases = [createRenderReadLease(first.world), createRenderReadLease(second.world)];
     let owner = { cameraOwner: 0, resourceOwner: 0 };
@@ -373,8 +429,8 @@ describe('PersistentRenderScene mixed World updates', () => {
   });
 
   it('scopes parent and leaf visibility changes while preserving unrelated snapshots', () => {
-    const instanceCollections = new InstanceCollectionStore();
-    const first = createWorld(instanceCollections, true);
+    const instanceCollections = new InstanceProjectionStore();
+    const first = createWorld(true);
     const lease = createRenderReadLease(first.world);
     const scene = new PersistentRenderScene({ instanceCollections });
     const assets = new AssetRegistry({
@@ -424,3 +480,73 @@ describe('PersistentRenderScene mixed World updates', () => {
     }
   });
 });
+
+it('two Renderers independently observe shared content replacement, rebinding, deletion and retry', () => {
+  const fixture = createWorld(true);
+  const { world, materialHandle, sharedConsumer } = fixture;
+  const owner = { cameraOwner: 0, resourceOwner: 0 };
+  const assets = new AssetRegistry({
+    findMaterialArtifact: () => ({ ok: false, error: new Error('not registered') }),
+  } as unknown as ShaderRegistry);
+  const consumers = [0, 1].map(() => {
+    const instanceCollections = new InstanceProjectionStore();
+    const scene = new PersistentRenderScene({ instanceCollections });
+    const lease = createRenderReadLease(world);
+    let fail = false;
+    const build = (request: PersistentRenderCandidateRequest) => {
+      if (fail) {
+        fail = false;
+        throw new Error('injected extraction failure');
+      }
+      return extractFrames([world], owner, assets, undefined, scene.materialSnapshotCacheStore(), {
+        cull: 'none',
+        retainHidden: true,
+        renderables: request,
+        instanceCollections,
+      });
+    };
+    return {
+      scene,
+      lease,
+      draw: () => scene.extractComposition([world], owner, 0, build, [lease]),
+      fail: () => {
+        fail = true;
+      },
+    };
+  });
+  const color = (frame: ExtractedFrame) =>
+    Array.from(rowFor(frame, 0, sharedConsumer)?.material.baseColor ?? []);
+  try {
+    for (const consumer of consumers) expect(color(consumer.draw())).toEqual([1, 0, 0]);
+    const content = world
+      .spawn({
+        component: RuntimeMaterialValue,
+        data: {
+          asset: materialHandle,
+          parameter: 'baseColor',
+          kind: 2,
+          value: [0, 1, 0, 1],
+        },
+      })
+      .unwrap();
+    for (const consumer of consumers) {
+      consumer.fail();
+      expect(() => consumer.draw()).toThrow('injected extraction failure');
+      expect(color(consumer.draw())).toEqual([0, 1, 0]);
+    }
+    const other = world.allocSharedRef('MaterialAsset', material({ baseColor: [0, 0, 1, 1] }));
+    world.set(content, RuntimeMaterialValue, { asset: other }).unwrap();
+    for (const consumer of consumers) expect(color(consumer.draw())).toEqual([1, 0, 0]);
+    world
+      .set(content, RuntimeMaterialValue, { asset: materialHandle, value: [0, 0, 1, 1] })
+      .unwrap();
+    for (const consumer of consumers) expect(color(consumer.draw())).toEqual([0, 0, 1]);
+    world.despawn(content).unwrap();
+    for (const consumer of consumers) expect(color(consumer.draw())).toEqual([1, 0, 0]);
+  } finally {
+    for (const consumer of consumers) {
+      consumer.lease.dispose();
+      consumer.scene.dispose();
+    }
+  }
+});

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

@@ -1,3 +1,4 @@
+import { RuntimeMeshVertices } from '@forgeax/engine-assets-runtime';
 import { World } from '@forgeax/engine-ecs';
 import { createRenderReadLease } from '@forgeax/engine-ecs/projection';
 import { vec3 } from '@forgeax/engine-math';
@@ -16,7 +17,7 @@ import {
   PointLightShadow,
   SpotLight,
 } from '../components';
-import { InstanceCollectionStore } from '../instances';
+import { InstanceProjectionStore } from '../instances';
 import { makeZeroCameraFallbackSnapshot } from '../record/frame-snapshot';
 import type {
   DispatchEntry,
@@ -302,13 +303,12 @@ describe('RenderScene canonical owner', () => {
 
   it('classifies an Instances-only collection revision without widening the content update', () => {
     const world = new World();
-    const instanceCollections = new InstanceCollectionStore();
+    const instanceCollections = new InstanceProjectionStore();
     const initialTransforms = new Float32Array(16);
     initialTransforms[0] = 1;
     initialTransforms[5] = 1;
     initialTransforms[10] = 1;
     initialTransforms[15] = 1;
-    const collection = instanceCollections.create({ transforms: initialTransforms }).unwrap();
     const entity = world
       .spawn(
         {
@@ -317,14 +317,18 @@ describe('RenderScene canonical owner', () => {
         },
         { component: MeshFilter, data: { assetHandle: 1 as never } },
         { component: MeshRenderer, data: { materials: [] } },
-        { component: Instances, data: { collectionId: collection.collectionId } },
+        { component: Instances, data: { transforms: initialTransforms } },
       )
       .unwrap();
     const lease = createRenderReadLease(world);
     const requests: PersistentRenderCandidateRequest[] = [];
     const build = (request: PersistentRenderCandidateRequest): ExtractedFrame => {
       requests.push(request);
-      const detached = instanceCollections.snapshot(collection.collectionId).unwrap();
+      const detached = instanceCollections.project(
+        world,
+        entity,
+        world.get(entity, Instances).unwrap().transforms,
+      );
       return {
         cameras: [{ ...makeZeroCameraFallbackSnapshot(), worldId: 0, entityKey: 1 }],
         renderables: [
@@ -349,7 +353,7 @@ describe('RenderScene canonical owner', () => {
       ]);
       const nextTransforms = new Float32Array(initialTransforms);
       nextTransforms[12] = 4;
-      instanceCollections.replace(collection.collectionId, nextTransforms).unwrap();
+      world.set(entity, Instances, { transforms: nextTransforms }).unwrap();
       persistent.extractComposition([world], { cameraOwner: 0, resourceOwner: 0 }, 0, build, [
         lease,
       ]);
@@ -734,8 +738,8 @@ describe('RenderScene canonical owner', () => {
     const world = new World();
     const lease = createRenderReadLease(world);
     const handle = world.allocSharedRef('MeshAsset', { kind: 'mesh' });
-    const onSharedRefMutation = vi.fn();
-    const persistent = new PersistentRenderScene({ onSharedRefMutation });
+    const onRuntimeAssetChange = vi.fn();
+    const persistent = new PersistentRenderScene({ onRuntimeAssetChange });
     const frame = {
       cameras: [],
       renderables: [],
@@ -746,12 +750,12 @@ describe('RenderScene canonical owner', () => {
     persistent.extractComposition([world], { cameraOwner: 0, resourceOwner: 0 }, 0, () => frame, [
       lease,
     ]);
-    world.sharedRefs.markChanged(handle).unwrap();
+    world.spawn({ component: RuntimeMeshVertices, data: { asset: handle, vertices: [] } }).unwrap();
     persistent.extractComposition([world], { cameraOwner: 0, resourceOwner: 0 }, 0, () => frame, [
       lease,
     ]);
 
-    expect(onSharedRefMutation).toHaveBeenCalledWith(0, handle);
+    expect(onRuntimeAssetChange).toHaveBeenCalledWith(0, handle);
     lease.dispose();
     persistent.dispose();
   });
@@ -974,6 +978,7 @@ describe('RenderScene canonical owner', () => {
       expect(projected.renderables).toEqual(cameraMoved.renderables);
       expect(projected.dispatch).toEqual(cameraMoved.dispatch);
       expect(initial.renderables).toHaveLength(1);
+      // Transform spans update poses without a second source-identity scan.
       expect(persistent.inspect()).toMatchObject({ fullRebuilds: 1, worldEntitiesScanned: 0 });
     } finally {
       lease.dispose();
@@ -1373,7 +1378,7 @@ describe('RenderScene', () => {
     } as unknown as ExtractedFrame;
 
     const projected = scene.extractComposition(
-      [{} as World],
+      [new World()],
       { cameraOwner: 0, resourceOwner: 0 },
       0,
       () => frame,
@@ -1515,3 +1520,23 @@ describe('projected bounds query', () => {
     scene.dispose();
   });
 });
+
+it('does not publish an earlier transform when later CPU candidate preparation fails', () => {
+  const scene = new RenderScene();
+  scene.apply([updateSnapshot(snapshot(1, 0)), updateSnapshot(snapshot(2, 0))]);
+  const changed = snapshot(1, 7).transform.world;
+  const malformed = snapshot(2, 9);
+  Object.defineProperty(malformed, 'transform', {
+    get() {
+      throw new Error('candidate copy failure');
+    },
+  });
+  expect(() =>
+    scene.apply([
+      { kind: 'update', worldId: 0, entityKey: 1, world: changed },
+      updateSnapshot(malformed),
+    ]),
+  ).toThrow('candidate copy failure');
+  expect(scene.slot(0, 1)?.snapshot.transform.world[12]).toBe(0);
+  expect(scene.slot(0, 2)?.snapshot.transform.world[12]).toBe(0);
+});