@forgeax/engine-render 0.1.23 → 0.1.25

package/src/__tests__/device-loss-fanout.unit.test.ts

@@ -0,0 +1,107 @@
+import type { RhiDevice } from '@forgeax/engine-rhi';
+import { rhi } from '@forgeax/engine-rhi-null';
+import { describe, expect, it } from 'vitest';
+import { attachDeviceLostFanout } from '../assembly/recovery/device-loss-fanout';
+import {
+  HealthListenerRegistry,
+  LostListenerRegistry,
+  RhiErrorListenerRegistry,
+} from '../lifecycle';
+
+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 };
+}
+
+describe('device loss fan-out generation fence', () => {
+  it('counts a late old-generation notification without changing active health', async () => {
+    const lost = deferred<{ readonly reason: 'unknown'; readonly message: string }>();
+    const lostRegistry = new LostListenerRegistry();
+    const errorRegistry = new RhiErrorListenerRegistry();
+    const healthRegistry = new HealthListenerRegistry();
+    const currentGeneration = 2;
+    let staleLossEvents = 0;
+    let lostEvents = 0;
+    let healthEvents = 0;
+    let errorEvents = 0;
+    const device = { lost: lost.promise } as unknown as RhiDevice;
+    lostRegistry.add(() => {
+      lostEvents += 1;
+    });
+    healthRegistry.add(() => {
+      healthEvents += 1;
+    });
+    errorRegistry.add(() => {
+      errorEvents += 1;
+    });
+
+    attachDeviceLostFanout(
+      device,
+      { rhi },
+      {
+        lostRegistry,
+        errorRegistry,
+        healthRegistry,
+        generation: 1,
+        currentGeneration: () => currentGeneration,
+        onStaleLoss: () => {
+          staleLossEvents += 1;
+        },
+      },
+    );
+
+    lost.resolve({ reason: 'unknown', message: 'late retired-device notification' });
+    await Promise.resolve();
+    await Promise.resolve();
+
+    expect(currentGeneration).toBe(2);
+    expect(staleLossEvents).toBe(1);
+    expect(lostEvents).toBe(0);
+    expect(healthEvents).toBe(0);
+    expect(errorEvents).toBe(0);
+    expect(healthRegistry.getLastSnapshot().reason).toBe('alive');
+  });
+
+  it('uses the backend loss projection for deterministic recovery fixtures', async () => {
+    const native = deferred<{ readonly reason: 'unknown'; readonly message: string }>();
+    const projected = deferred<{ readonly reason: 'unknown'; readonly message: string }>();
+    const lostRegistry = new LostListenerRegistry();
+    const errorRegistry = new RhiErrorListenerRegistry();
+    const healthRegistry = new HealthListenerRegistry();
+    let lostEvents = 0;
+    lostRegistry.add(() => {
+      lostEvents += 1;
+    });
+    const device = { lost: native.promise } as unknown as RhiDevice;
+
+    attachDeviceLostFanout(
+      device,
+      {
+        rhi,
+        instrumentation: {
+          deviceLost: () => projected.promise,
+        },
+      },
+      {
+        lostRegistry,
+        errorRegistry,
+        healthRegistry,
+        generation: 0,
+        currentGeneration: () => 0,
+      },
+    );
+
+    projected.resolve({ reason: 'unknown', message: 'fixture-projected loss' });
+    await Promise.resolve();
+    await Promise.resolve();
+
+    expect(lostEvents).toBe(1);
+    expect(healthRegistry.getLastSnapshot().reason).toBe('device-lost');
+  });
+});

package/src/__tests__/device-scope-lifecycle.unit.test.ts

@@ -148,4 +148,25 @@ describe('DeviceScope lifecycle transaction', () => {
     expect(scope.state).toBe('disposed');
     expect(scope.resourceDelta()).toBe(0);
   });
+
+  it('runs an adopted cleanup once across repeated scope termination', async () => {
+    const scope = DeviceScope.create(31, 'renderer');
+    let cleanupCount = 0;
+    const transaction = new LifecycleTransaction(scope);
+    transaction.add({
+      kind: 'pipeline',
+      create: () => ({ id: 'candidate-pipeline' }),
+      cleanup: () => {
+        cleanupCount += 1;
+      },
+    });
+
+    const result = await transaction.commit();
+
+    expect(result.ok).toBe(true);
+    scope.retire();
+    scope.dispose();
+    scope.abandon();
+    expect(cleanupCount).toBe(1);
+  });
 });

package/src/__tests__/environment-generation.integration.test.ts

@@ -154,4 +154,27 @@ describe('Environment generation candidate and LKG lifecycle (M2)', () => {
     expect(recovered.value.generation).not.toBe(old.value.generation);
     expect(recovered.value.liveHandle).not.toBe(old.value.liveHandle);
   });
+
+  it('prepares a recovery root on a detached lifecycle without changing the active owner', async () => {
+    const active = new EnvironmentLifecycle(DeviceScope.create(20, 'environment-active'));
+    const initial = await active.ensure(frame('sky-active'));
+    expect(initial.ok).toBe(true);
+    if (!initial.ok) return;
+    active.publish(initial.value);
+    active.resetForRecover(21);
+    const before = active.inspect();
+
+    const candidateScope = DeviceScope.create(21, 'environment-candidate');
+    const candidate = active.createRecoveryCandidate(candidateScope);
+    const root = candidate.createRecoveryRoot(candidateScope);
+    const recovered =
+      (await root.create()) as import('../environment/generation').EnvironmentGeneration;
+
+    expect(active.inspect()).toEqual(before);
+    expect(candidate.inspect().candidate?.generation).toBe(recovered.generation);
+
+    await root.cleanup(recovered);
+    expect(candidate.inspect().candidate).toBeUndefined();
+    expect(active.inspect()).toEqual(before);
+  });
 });

package/src/__tests__/expose-renderer-errors.unit.test.ts

@@ -0,0 +1,34 @@
+import { err } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { exposeRenderer } from '../assembly/factory';
+import type { RendererHostImplementation } from '../assembly/host-contract';
+import { RendererContractFailureError } from '../errors/render';
+
+describe('exposeRenderer error projection', () => {
+  it('reports an internal draw contract failure as a device operation failure', () => {
+    const host = {
+      inspect: () => ({ state: 'alive' }),
+      subscribeHostEvents: () => () => undefined,
+      drawFrame: () =>
+        err(
+          new RendererContractFailureError(
+            'draw',
+            'the Standard render owner did not submit a command buffer',
+          ),
+        ),
+    } as unknown as RendererHostImplementation;
+    const renderer = exposeRenderer(host);
+
+    const result = renderer.draw({} as never);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.code).toBe('device-operation-failed');
+      if (result.error.code !== 'device-operation-failed') return;
+      expect(result.error.detail.cause).toMatchObject({
+        code: 'renderer-contract-failed',
+        detail: { operation: 'draw' },
+      });
+    }
+  });
+});

package/src/__tests__/factory-contract.integration.test.ts

@@ -32,6 +32,7 @@ import { renderLifecycleManifestUrl } from './shader-manifest-fixture';
 
 const assemblyDirectory = dirname(fileURLToPath(import.meta.url));
 const factorySourcePath = resolve(assemblyDirectory, '../assembly/factory.ts');
+const webgpuRendererSourcePath = resolve(assemblyDirectory, '../assembly/webgpu-renderer.ts');
 const renderTargetHostSourcePath = resolve(assemblyDirectory, '../assembly/render-target-host.ts');
 
 function manifestUrl(): string {
@@ -127,7 +128,7 @@ describe('factory contract', () => {
   });
 
   it('forwards the bundler build identity into RenderSystem inspections', () => {
-    const source = readFileSync(factorySourcePath, 'utf8');
+    const source = readFileSync(webgpuRendererSourcePath, 'utf8');
     expect(source).toContain('get build() {\n      return internals.bundler?.build;\n    },');
   });
 
@@ -1700,6 +1701,15 @@ describe('factory contract', () => {
       expect((await renderer.initialization).ok).toBe(true);
       expect(world.update().ok).toBe(true);
       expect(renderer.draw(input()).ok).toBe(true);
+      expect(renderer.inspect().recovery).toMatchObject({
+        phase: null,
+        fromGeneration: 0,
+        candidateGeneration: 0,
+        attempt: 0,
+        lastOutcome: 'none',
+        rehydratedRoots: 0,
+        staleLossEvents: 0,
+      });
       const beforeLoss = renderer.inspect().bloom;
       const beforeDeviceGeneration = renderer.inspect().temporal.deviceGeneration;
       expect(beforeLoss.state).toBe('active');
@@ -1710,15 +1720,34 @@ describe('factory contract', () => {
       const failed = await renderer.recover();
       expect(failed.ok).toBe(false);
       expect(renderer.health().reason).toBe('device-lost');
+      expect(renderer.inspect().recovery).toMatchObject({
+        phase: null,
+        fromGeneration: 0,
+        candidateGeneration: 1,
+        attempt: 1,
+        lastOutcome: 'failed',
+        rehydratedRoots: 0,
+        staleLossEvents: 0,
+      });
       expect(renderer.inspect().perFramePassNames).toEqual([]);
       expect(renderer.inspect().standardLighting).toBeUndefined();
       const recovered = await renderer.recover();
       expect(recovered.ok).toBe(true);
-      // Recovery publishes a device but not a graph. The first post-recovery
-      // draw must rebuild both the graph accessors and Standard inspection
-      // against the replacement device.
-      expect(renderer.inspect().perFramePassNames).toEqual([]);
-      expect(renderer.inspect().standardLighting).toBeUndefined();
+      expect(renderer.inspect().recovery).toMatchObject({
+        phase: null,
+        fromGeneration: 0,
+        candidateGeneration: 1,
+        attempt: 2,
+        lastOutcome: 'succeeded',
+        rehydratedRoots: expect.any(Number),
+        staleLossEvents: 0,
+      });
+      expect(renderer.inspect().recovery.rehydratedRoots).toBeGreaterThan(0);
+      // Recovery publishes only after the retained CPU/LKG frame has prepared
+      // the replacement graph and visible residency. The first post-recovery
+      // draw therefore starts with graph accessors and Standard inspection.
+      expect(renderer.inspect().perFramePassNames.length).toBeGreaterThan(0);
+      expect(renderer.inspect().standardLighting).toBeDefined();
       expect(world.update().ok).toBe(true);
       expect(renderer.draw(input()).ok).toBe(true);
       expect(renderer.inspect().perFramePassNames.length).toBeGreaterThan(0);
@@ -1868,7 +1897,11 @@ describe('factory contract', () => {
       await Promise.resolve();
       await Promise.resolve();
       expect(renderer.health().reason).toBe('device-lost');
-      expect((await renderer.recover()).ok).toBe(false);
+      const failedRecovery = await renderer.recover();
+      expect(failedRecovery.ok).toBe(false);
+      if (!failedRecovery.ok) {
+        expect(failedRecovery.error.code).toBe('recovery-failed');
+      }
       expect(renderer.health().reason).toBe('device-lost');
       expect(createdReplacementHandles.size).toBeGreaterThan(0);
       expect(
@@ -1907,4 +1940,86 @@ describe('factory contract', () => {
       await renderer.dispose();
     }
   });
+
+  it('reports a structured disposed outcome when recovery is interrupted by dispose', async () => {
+    const adapter = new RhiNullAdapter();
+    const lost = deferred<{ readonly reason: 'unknown'; readonly message: string }>();
+    const recoveryAdapterEntered = deferred<void>();
+    const releaseRecoveryAdapter = deferred<void>();
+    const firstDevice = (await adapter.requestDevice()).unwrap();
+    const lostProxy = new Proxy(firstDevice, {
+      get(target, property) {
+        if (property === 'lost') return lost.promise;
+        const value = Reflect.get(target, property, target);
+        return typeof value === 'function' ? value.bind(target) : value;
+      },
+    });
+    let requestCount = 0;
+    const recoverableRhi = {
+      ...rhi,
+      requestAdapter: async () => {
+        requestCount += 1;
+        if (requestCount === 1) {
+          return ok({
+            features: adapter.features,
+            limits: adapter.limits,
+            requestDevice: async () => ok(lostProxy),
+          } as never);
+        }
+        recoveryAdapterEntered.resolve();
+        await releaseRecoveryAdapter.promise;
+        return ok({
+          features: adapter.features,
+          limits: adapter.limits,
+          requestDevice: async () => ok(firstDevice),
+        } as never);
+      },
+    } as never;
+    const renderer = await constructRenderer(
+      { width: 64, height: 64, getContext: () => null },
+      { rhi: recoverableRhi },
+      { shaderManifestUrl: renderLifecycleManifestUrl() },
+    );
+
+    try {
+      expect((await renderer.initialization).ok).toBe(true);
+      lost.reject({ reason: 'unknown', message: 'forced device loss' });
+      await Promise.resolve();
+      await Promise.resolve();
+      expect(renderer.health().reason).toBe('device-lost');
+
+      const recovery = renderer.recover();
+      await recoveryAdapterEntered.promise;
+      expect(renderer.inspect().recovery.phase).toBe('acquire-adapter');
+      expect((await renderer.dispose()).ok).toBe(true);
+      releaseRecoveryAdapter.resolve();
+
+      const result = await recovery;
+      expect(result.ok).toBe(false);
+      if (!result.ok) {
+        if (result.error.code !== 'recovery-failed') {
+          throw new Error(`Expected recovery-failed, received ${result.error.code}`);
+        }
+        expect(result.error.detail).toMatchObject({
+          phase: 'cleanup',
+          oldGeneration: 0,
+          candidateGeneration: 1,
+          attempt: 1,
+          lastOutcome: 'disposed',
+          rehydratedRoots: 0,
+          staleLossEvents: 0,
+        });
+      }
+      expect(renderer.inspect().recovery).toMatchObject({
+        phase: null,
+        attempt: 1,
+        lastOutcome: 'disposed',
+        rehydratedRoots: 0,
+        staleLossEvents: 0,
+      });
+    } finally {
+      releaseRecoveryAdapter.resolve();
+      await renderer.dispose();
+    }
+  });
 });

package/src/__tests__/fallback-row-stride-surface.unit.test.ts

@@ -3,7 +3,10 @@ import { describe, expect, it } from 'vitest';
 import { FALLBACK_BYTES_PER_ROW } from '../ibl/skylight-bind-group';
 
 const ownerSource = readFileSync(new URL('../ibl/skylight-bind-group.ts', import.meta.url), 'utf8');
-const rendererSource = readFileSync(new URL('../assembly/factory.ts', import.meta.url), 'utf8');
+const rendererSource = readFileSync(
+  new URL('../assembly/webgpu-ready.ts', import.meta.url),
+  'utf8',
+);
 
 describe('fallback texture row-stride owner', () => {
   it('keeps both 1x1 fallback upload paths on one owner', () => {

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

@@ -120,9 +120,17 @@ describe('GpuScene', () => {
     expect(created.scene.inspect().uploadBytes).toBe(bytesBefore);
 
     created.scene.commitTemporalFrame(true).unwrap();
-    expect(queue.writes).toHaveLength(writesBefore + 1);
+    expect(queue.writes).toHaveLength(writesBefore);
+    expect(created.scene.inspect().uploadBytes).toBe(bytesBefore);
+
+    const dirty = projection.apply([
+      { kind: 'update-transform', worldId: 0, entityKey: 0, world: snapshot(0, 3).transform.world },
+    ]);
+    created.scene.sync(dirty).unwrap();
+    created.scene.commitTemporalFrame(true).unwrap();
+    expect(queue.writes).toHaveLength(writesBefore + 2);
     expect(created.scene.inspect().uploadBytes).toBe(
-      bytesBefore + created.scene.inspect().tables.transform.bytes,
+      bytesBefore + 2 * GPU_SCENE_LAYOUTS.transform.stride,
     );
   });
 
@@ -200,4 +208,32 @@ describe('GpuScene', () => {
       gpuSceneFieldOffset(GPU_SCENE_LAYOUTS.transform, 'previousWorld') + 12 * 4;
     expect(new DataView(transformWrite.bytes.buffer).getFloat32(previousTranslation, true)).toBe(9);
   });
+
+  it('keeps a recycled slot allocated for the replacement identity', () => {
+    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(1, 2) }])).unwrap();
+
+    const recycled = projection.apply([
+      { kind: 'remove', worldId: 0, entityKey: 1 },
+      { kind: 'create', snapshot: snapshot(2, 7) },
+    ]);
+    expect(recycled.removedSlots[0]?.slot).toBe(recycled.createdSlots[0]?.slot);
+    created.scene.sync(recycled).unwrap();
+
+    expect(() =>
+      created.scene.sync(
+        projection.apply([
+          {
+            kind: 'update-transform',
+            worldId: 0,
+            entityKey: 2,
+            world: snapshot(2, 11).transform.world,
+          },
+        ]),
+      ),
+    ).not.toThrow();
+  });
 });

package/src/__tests__/ibl/face-uniforms.unit.test.ts

@@ -38,9 +38,11 @@ describe('IBL face uniform RHI contract', () => {
     const badFace = writeFaceUniforms(device, bufferResult.value, 6, new Float32Array(16));
     const badMatrix = writeFaceUniforms(device, bufferResult.value, 0, new Float32Array(15));
     const badSubPass = writePrefilterUniforms(device, bufferResult.value, 30, 0.5, 128);
+    const badMipCount = writePrefilterUniforms(device, bufferResult.value, 0, 0.5, 128, 0);
 
     expect(badFace).toMatchObject({ ok: false, error: { code: 'webgpu-runtime-error' } });
     expect(badMatrix).toMatchObject({ ok: false, error: { code: 'webgpu-runtime-error' } });
     expect(badSubPass).toMatchObject({ ok: false, error: { code: 'webgpu-runtime-error' } });
+    expect(badMipCount).toMatchObject({ ok: false, error: { code: 'webgpu-runtime-error' } });
   });
 });

package/src/__tests__/ibl-residency-publication.unit.test.ts

@@ -0,0 +1,113 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+
+const source = readFileSync(new URL('../device/gpu-residency.ts', import.meta.url), 'utf8');
+const iblSource = readFileSync(new URL('../ibl/IblPipelineCache.ts', import.meta.url), 'utf8');
+
+describe('IBL residency publication', () => {
+  it('publishes ready and the idempotent cube only after submission succeeds', () => {
+    const precomputeCall = source.indexOf('const runResult = await runIblPrecompute({');
+    const precomputeSuccess = source.indexOf('if (!runResult.ok)', precomputeCall);
+    const sourceReady = source.indexOf("status: 'ready'", precomputeCall);
+    const cubeRegistration = source.indexOf('const cubeHandle = regResult.value;', precomputeCall);
+    const mapPublication = source.indexOf(
+      'this.cubemapIdempotentMap.set(sourceId, cubeHandle);',
+      precomputeCall,
+    );
+    expect(precomputeCall).toBeGreaterThan(-1);
+    expect(precomputeSuccess).toBeGreaterThan(precomputeCall);
+    expect(sourceReady).toBeGreaterThan(precomputeSuccess);
+    expect(cubeRegistration).toBeGreaterThan(precomputeSuccess);
+    expect(mapPublication).toBeGreaterThan(precomputeSuccess);
+  });
+
+  it('keeps pending publication before asynchronous pipeline work', () => {
+    const pending = source.indexOf("status: 'pending'");
+    const precompute = source.indexOf('const runResult = await runIblPrecompute({');
+    expect(pending).toBeGreaterThan(-1);
+    expect(pending).toBeLessThan(precompute);
+  });
+
+  it('promotes the IBL candidate only after the completion fence', () => {
+    const runStart = iblSource.indexOf('export async function runIblPrecompute(');
+    const fence = iblSource.indexOf('await device.queue.onSubmittedWorkDone()', runStart);
+    const promotion = iblSource.indexOf(
+      'cache.irradianceTexture = promoted.irradianceTexture',
+      runStart,
+    );
+    const ready = source.indexOf("status: 'ready'", source.indexOf('_uploadCubemapFromEquirect'));
+    expect(runStart).toBeGreaterThan(-1);
+    expect(fence).toBeGreaterThan(runStart);
+    expect(promotion).toBeGreaterThan(fence);
+    expect(ready).toBeGreaterThan(fence);
+    expect(iblSource.slice(runStart, fence)).not.toContain('cache.irradianceTexture =');
+    expect(iblSource.slice(runStart, fence)).not.toContain('cache.prefilterTexture =');
+    expect(iblSource.slice(runStart, fence)).not.toContain('cache.brdfLutTexture =');
+  });
+
+  it('awaits precompute before residency publication', () => {
+    const call = source.indexOf('const runResult = await runIblPrecompute({');
+    const success = source.indexOf('if (!runResult.ok)', call);
+    const ready = source.indexOf("status: 'ready'", call);
+    const map = source.indexOf('this.cubemapIdempotentMap.set(sourceId, cubeHandle);', call);
+    expect(call).toBeGreaterThan(-1);
+    expect(success).toBeGreaterThan(call);
+    expect(ready).toBeGreaterThan(success);
+    expect(map).toBeGreaterThan(success);
+  });
+
+  it('keeps candidate and transient resources under the DeviceScope owner', () => {
+    expect(iblSource).toContain("scope._adopt('texture', texture");
+    expect(source).toContain("scope._adopt('texture', equirectGpuTex");
+    expect(source).toContain("scope._adopt('buffer', faceBuf");
+    expect(source).toContain("scope._adopt('buffer', prefBuf");
+    expect(source).toContain("scope._adopt('buffer', cubeVertex");
+    const fence = iblSource.indexOf('await device.queue.onSubmittedWorkDone()');
+    const candidateWrites = iblSource.indexOf('candidate.irradianceTexture = adoptIblTexture');
+    expect(candidateWrites).toBeLessThan(fence);
+  });
+
+  it('fences each IBL stage before recording the next stage', () => {
+    const runStart = iblSource.indexOf('export async function runIblPrecompute(');
+    const stages = ['equirect-to-cube', 'prefilter', 'brdf-lut'];
+    let previous = runStart;
+    for (const stage of stages) {
+      const marker = iblSource.indexOf(`await submitStage('${stage}'`, previous);
+      expect(marker).toBeGreaterThan(previous);
+      previous = marker;
+    }
+    expect(iblSource.match(/await submitStage\('/g)).toHaveLength(stages.length);
+    expect(iblSource).toContain('await device.queue.onSubmittedWorkDone()');
+    expect(
+      iblSource.indexOf('cache.irradianceTexture = promoted.irradianceTexture'),
+    ).toBeGreaterThan(previous);
+  });
+
+  it('does not promote or increment counters after a failed stage', () => {
+    const runStart = iblSource.indexOf('export async function runIblPrecompute(');
+    const promotion = iblSource.indexOf(
+      'cache.irradianceTexture = promoted.irradianceTexture',
+      runStart,
+    );
+    const counters = iblSource.indexOf('cache.irradianceBakeCount += 1', runStart);
+    const stageFailure = iblSource.indexOf('return err(badAlloc', runStart);
+    expect(stageFailure).toBeGreaterThan(runStart);
+    expect(stageFailure).toBeLessThan(promotion);
+    expect(promotion).toBeLessThan(counters);
+    expect(iblSource).toContain('stage}-device-scope-generation');
+  });
+
+  it('fences each irradiance face before the next face', () => {
+    const runStart = iblSource.indexOf('export async function runIblPrecompute(');
+    const irradianceStart = iblSource.indexOf('// (b) irradiance convolve', runStart);
+    const prefilterStart = iblSource.indexOf('// (c) prefilter env', irradianceStart);
+    const faceMarkers = iblSource.match(/submitStage\(`irradiance-face-\$\{face\}`/g) ?? [];
+    expect(faceMarkers).toHaveLength(1);
+    expect(iblSource.slice(irradianceStart, prefilterStart)).toMatch(
+      /await submitStage\(`irradiance-face-\$\{face\}`, true\)/,
+    );
+    expect(iblSource.slice(irradianceStart, prefilterStart)).not.toContain(
+      "await submitStage('irradiance', true)",
+    );
+  });
+});

package/src/__tests__/instances-store.unit.test.ts

@@ -0,0 +1,46 @@
+import { World } from '@forgeax/engine-ecs';
+import { describe, expect, it } from 'vitest';
+import { InstanceProjectionStore } from '../instances';
+
+function matrices(x: number): Float32Array {
+  return new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, x, 0, 0, 1]);
+}
+
+describe('renderer instance projection', () => {
+  it('derives independent complete snapshots for consumers that skip different updates', () => {
+    const world = new World();
+    const first = new InstanceProjectionStore();
+    const late = new InstanceProjectionStore();
+    const before = first.project(world, 1, matrices(0));
+    late.project(world, 1, matrices(0));
+    first.project(world, 1, matrices(1));
+    first.project(world, 1, matrices(2));
+    const latest = late.project(world, 1, matrices(2));
+    expect(before.transforms[12]).toBe(0);
+    expect(latest.transforms[12]).toBe(2);
+    const stable = late.project(world, 1, matrices(2));
+    expect(stable.transforms).toBe(latest.transforms);
+    expect(stable.revision).toBe(latest.revision);
+  });
+
+  it('does not alias identical entity numbers across World identities', () => {
+    const projection = new InstanceProjectionStore();
+    const a = projection.project(new World(), 1, matrices(10));
+    const b = projection.project(new World(), 1, matrices(99));
+    expect(a.collectionId).not.toBe(b.collectionId);
+    expect(a.transforms[12]).toBe(10);
+    expect(b.transforms[12]).toBe(99);
+  });
+
+  it('rebuilds from unchanged source after dropping renderer resources', () => {
+    const world = new World();
+    const transforms = matrices(4);
+    const projection = new InstanceProjectionStore();
+    projection.project(world, 1, transforms);
+    projection.dispose();
+    expect(projection.project(world, 1, transforms).transforms).toEqual(transforms);
+    expect(new InstanceProjectionStore().project(world, 1, transforms).transforms).toEqual(
+      transforms,
+    );
+  });
+});

package/src/__tests__/instances-world-ownership.integration.test.ts

@@ -0,0 +1,62 @@
+import { HANDLE_CUBE } from '@forgeax/engine-assets-runtime';
+import { World } from '@forgeax/engine-ecs';
+import { registerPropagateTransforms, Transform } from '@forgeax/engine-scene';
+import { describe, expect, it } from 'vitest';
+import { Camera } from '../components/camera';
+import { Instances } from '../components/instances';
+import { MeshFilter } from '../components/mesh-filter';
+import { MeshRenderer } from '../components/mesh-renderer';
+import { extractFrames } from '../render-system-extract';
+
+function matrices(count: number, x: number): Float32Array {
+  const out = new Float32Array(count * 16);
+  for (let i = 0; i < count; i++) {
+    out[i * 16] = out[i * 16 + 5] = out[i * 16 + 10] = out[i * 16 + 15] = 1;
+    out[i * 16 + 12] = x;
+  }
+  return out;
+}
+
+function scene(count: number, x: number) {
+  const world = new World();
+  registerPropagateTransforms(world);
+  world
+    .spawn(
+      { component: Transform, data: { pos: [0, 0, 5] } },
+      { component: Camera, data: { fov: Math.PI / 4, aspect: 1, near: 0.1, far: 100 } },
+    )
+    .unwrap();
+  const entity = world
+    .spawn(
+      { component: Transform, data: {} },
+      { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
+      { component: MeshRenderer, data: {} },
+      { component: Instances, data: { transforms: matrices(count, x) } },
+    )
+    .unwrap();
+  world.update(0).unwrap();
+  return { world, entity };
+}
+
+describe('World-owned instance authoring', () => {
+  it.each([1500, 10000, 20000])('extracts %s matrices without creating a Renderer', (count) => {
+    const { world } = scene(count, 0);
+    const snapshot = extractFrames([world], 0).renderables[0]?.instances;
+    expect(snapshot?.instanceCount).toBe(count);
+    expect(snapshot?.transforms).toEqual(matrices(count, 0));
+  });
+
+  it('keeps worlds isolated and lets independent consumers observe skipped updates', () => {
+    const a = scene(2, 0);
+    const b = scene(2, 1);
+    const before = extractFrames([a.world], 0).renderables[0]?.instances;
+    expect(extractFrames([b.world], 0).renderables[0]?.instances?.transforms[12]).toBe(1);
+    a.world.set(a.entity, Instances, { transforms: matrices(2, 0.5) }).unwrap();
+    extractFrames([a.world], 0);
+    a.world.set(a.entity, Instances, { transforms: matrices(2, -0.5) }).unwrap();
+    const late = extractFrames([a.world], 0).renderables[0]?.instances;
+    expect(late?.transforms[12]).toBe(-0.5);
+    expect(before?.transforms[12]).toBe(0);
+    expect(extractFrames([b.world], 0).renderables[0]?.instances?.transforms[12]).toBe(1);
+  });
+});