@forgeax/engine-app 0.1.4 → 0.1.7

package/src/__tests__/consumer-migration.unit.test.ts

@@ -1,3 +1,5 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
 import { Time, Update, World } from '@forgeax/engine-ecs';
 import { describe, expect, it } from 'vitest';
 
@@ -18,4 +20,15 @@ describe('callback consumer migration', () => {
     world.update(1 / 60).unwrap();
     expect(observed).toBeCloseTo(1 / 60);
   });
+
+  it('uses the receipt-bound renderer host contract', () => {
+    const source = [
+      readFileSync(resolve(process.cwd(), 'packages/app/src/create-app.ts'), 'utf8'),
+      readFileSync(resolve(process.cwd(), 'packages/app/src/internal/frame-loop.ts'), 'utf8'),
+    ].join('\n');
+    expect(source).toContain('renderer.attach(');
+    expect(source).toContain('renderer.draw({');
+    expect(source).not.toContain('renderer.ready');
+    expect(source).not.toContain('renderer.device');
+  });
 });

package/src/__tests__/create-app-error-retention.integration.test.ts

@@ -0,0 +1,125 @@
+import { Update, World } from '@forgeax/engine-ecs';
+import type { Renderer } from '@forgeax/engine-render';
+import { RhiError } from '@forgeax/engine-rhi';
+import { describe, expect, it, vi } from 'vitest';
+import { createApp } from '../create-app';
+import type { AppDispatchError } from '../types';
+
+function makeRenderer(): {
+  readonly renderer: Renderer;
+  readonly draw: ReturnType<typeof vi.fn>;
+  readonly emit: (error: RhiError) => void;
+} {
+  const draw = vi.fn(() => ({ ok: true as const, value: undefined }));
+  let listener: ((event: { readonly kind: 'error'; readonly error: RhiError }) => void) | undefined;
+  const renderer = {
+    backend: 'webgpu' as const,
+    ready: Promise.resolve({ ok: true as const, value: undefined }),
+    draw,
+    attach: () => ({ ok: true as const, value: { dispose: () => undefined } }),
+    attachWorld: () => ({ ok: true as const, value: undefined }),
+    detachWorld: () => undefined,
+    subscribe: (next: (event: { readonly kind: 'error'; readonly error: RhiError }) => void) => {
+      listener = next;
+      return () => {
+        if (listener === next) listener = undefined;
+      };
+    },
+    onLost: () => () => undefined,
+    dispose: () => undefined,
+  } as unknown as Renderer;
+  return { renderer, draw, emit: (error) => listener?.({ kind: 'error', error }) };
+}
+
+function installFaultingSystem(world: World, cause: Error): void {
+  world
+    .addSystem(Update, {
+      name: 'retention-faulting-update',
+      queries: [],
+      fn: () => {
+        throw cause;
+      },
+    })
+    .unwrap();
+}
+
+async function createPausedApp(world: World, renderer: Renderer, silenceUnhandledErrors = true) {
+  const result = await createApp({ renderer, world, silenceUnhandledErrors });
+  expect(result.ok).toBe(true);
+  if (!result.ok) throw result.error;
+  result.value.start().unwrap();
+  result.value.pause().unwrap();
+  return result.value;
+}
+
+describe('createApp error retention', () => {
+  it('retains a real frame/update system failure through the main dispatch owner', async () => {
+    const cause = new Error('boom');
+    const world = new World();
+    installFaultingSystem(world, cause);
+    const { renderer, draw } = makeRenderer();
+    const app = await createPausedApp(world, renderer);
+    let observed: AppDispatchError | undefined;
+    app.onError((error) => {
+      observed = error;
+    });
+
+    const frame = app.stepFrame(1 / 60);
+
+    expect(frame.ok).toBe(false);
+    if (frame.ok) return;
+    expect(frame.error.code).toBe('app-system-update-failed');
+    if (frame.error.code !== 'app-system-update-failed') return;
+    const updateError = frame.error.detail.cause as {
+      readonly code?: string;
+      readonly detail?: { readonly cause?: unknown };
+    };
+    expect(updateError.code).toBe('system-failed');
+    expect(updateError.detail?.cause).toBe(cause);
+    expect(observed).toBe(frame.error);
+    expect(app.lastError).toBe(frame.error);
+    expect(world.execution.health).toBe('poisoned');
+    expect(world.inspect().systems.map((system) => system.name)).toContain(
+      'retention-faulting-update',
+    );
+    expect(draw).not.toHaveBeenCalled();
+  });
+
+  it('retains the same structured failure when console fallback is the only observer', async () => {
+    const consoleError = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+    const world = new World();
+    installFaultingSystem(world, new Error('unobserved boom'));
+    const { renderer } = makeRenderer();
+    const app = await createPausedApp(world, renderer, false);
+
+    const frame = app.stepFrame(1 / 60);
+
+    expect(frame.ok).toBe(false);
+    if (!frame.ok) {
+      expect(consoleError).toHaveBeenCalledTimes(1);
+      expect(consoleError).toHaveBeenCalledWith(frame.error);
+      expect(app.lastError).toBe(frame.error);
+    }
+    consoleError.mockRestore();
+  });
+
+  it('preserves renderer device-loss identity and retention', async () => {
+    const world = new World();
+    const { renderer, emit } = makeRenderer();
+    const app = await createPausedApp(world, renderer);
+    let observed: AppDispatchError | undefined;
+    app.onError((error) => {
+      observed = error;
+    });
+    const deviceLoss = new RhiError({
+      code: 'device-lost',
+      expected: 'the test device remains available',
+      hint: 'rebuild the renderer after device recovery',
+    });
+
+    emit(deviceLoss);
+
+    expect(observed).toBe(deviceLoss);
+    expect(app.lastError).toBe(deviceLoss);
+  });
+});

package/src/__tests__/create-app-features.test.ts

@@ -1,23 +1,31 @@
 import type { RenderFeature } from '@forgeax/engine-render';
 import { describe, expect, it, vi } from 'vitest';
 
-const createRenderer = vi.hoisted(() => vi.fn());
+const constructRuntimeRendererHost = vi.hoisted(() => vi.fn());
 
 vi.mock('@forgeax/engine-runtime', async (importOriginal) => {
   const actual = await importOriginal<typeof import('@forgeax/engine-runtime')>();
-  return { ...actual, createRenderer };
+  return actual;
 });
 
+vi.mock('@forgeax/engine-runtime/internal/renderer-host', () => ({
+  constructRuntimeRendererHost,
+  loadRhiPack: vi.fn(),
+}));
+
 import { createApp } from '../create-app';
 
 function rendererStub() {
+  const lease = {};
   return {
-    backend: 'webgpu' as const,
-    ready: Promise.resolve({ ok: true as const, value: undefined }),
-    draw: () => ({ ok: true as const, value: undefined }),
+    attach: () => ({ ok: true as const, value: lease }),
+    draw: () => ({ ok: true as const, value: {} }),
+    observe: async () => ({ ok: true as const, value: {} }),
+    releaseSurface: () => ({ ok: true as const, value: undefined }),
+    restoreSurface: () => ({ ok: true as const, value: undefined }),
+    recover: async () => ({ ok: true as const, value: undefined }),
     onError: () => () => undefined,
     onLost: () => () => undefined,
-    onHealthChange: () => () => undefined,
     dispose: () => undefined,
   };
 }
@@ -27,14 +35,17 @@ describe('createApp features passthrough', () => {
     const first = { identity: 'test.first' } as unknown as RenderFeature<unknown>;
     const second = { identity: 'test.second' } as unknown as RenderFeature<unknown>;
     const features = [first, second] as const;
-    createRenderer.mockResolvedValue(rendererStub());
+    constructRuntimeRendererHost.mockResolvedValue({
+      ok: true,
+      value: { renderer: rendererStub(), assets: undefined },
+    });
 
     const canvas = { tagName: 'canvas', isConnected: true } as HTMLCanvasElement;
     const result = await createApp(canvas, { features });
 
     expect(result.ok).toBe(true);
-    expect(createRenderer).toHaveBeenCalledTimes(1);
-    expect(createRenderer.mock.calls[0]?.[1]).toMatchObject({ features });
-    expect(createRenderer.mock.calls[0]?.[1].features).toBe(features);
+    expect(constructRuntimeRendererHost).toHaveBeenCalledTimes(1);
+    expect(constructRuntimeRendererHost.mock.calls[0]?.[1]).toMatchObject({ features });
+    expect(constructRuntimeRendererHost.mock.calls[0]?.[1].features).toBe(features);
   });
 });

package/src/__tests__/create-app-listener-sync.test.ts

@@ -6,7 +6,7 @@
 // test used the assemble form with a hand-copied registerListenerSyncSystem
 // helper — a shadow copy of the production code that left w25 untested.
 //
-// Approach: vi.mock createRenderer (only export overridden) so the canvas
+// Approach: vi.mock constructRuntimeRendererHost (only construction overridden) so the canvas
 // form does not attempt real WebGPU init; all other exports from
 // @forgeax/engine-runtime remain real (Transform, registerPropagateTransforms,
 // PROPAGATE_TRANSFORMS_SYSTEM, etc.).  globalThis.AudioContext is stubbed
@@ -34,43 +34,47 @@ import { Transform } from '@forgeax/engine-scene';
 import { describe, expect, it, vi } from 'vitest';
 import { createApp } from '../create-app';
 
+const constructRuntimeRendererHost = vi.hoisted(() => vi.fn());
+
 // ---------------------------------------------------------------------------
-// Mock createRenderer so the canvas form does not attempt real WebGPU init.
+// Mock constructRuntimeRendererHost so the canvas form does not attempt real WebGPU init.
 // All other @forgeax/engine-runtime exports stay real (Transform,
 // registerPropagateTransforms, advanceAnimationPlayer, etc.).
 // ---------------------------------------------------------------------------
 
 vi.mock('@forgeax/engine-runtime', async (importOriginal) => {
   const actual = await importOriginal<typeof import('@forgeax/engine-runtime')>();
-  const ready: Promise<{ ok: true; value: undefined }> = Promise.resolve({
-    ok: true,
-    value: undefined,
-  });
+  const lease = { dispose: vi.fn() };
   const rendererStub = {
-    backend: 'webgpu' as const,
-    ready,
-    draw(): { ok: true; value: undefined } {
-      return { ok: true, value: undefined };
-    },
-    attachWorld(): { ok: true; value: undefined } {
-      return { ok: true, value: undefined };
+    attach(): { ok: true; value: object } {
+      return { ok: true, value: lease };
     },
-    detachWorld(): void {},
-    onError(): () => void {
-      return () => {};
+    draw(): { ok: true; value: object } {
+      return { ok: true, value: {} };
     },
-    onLost(): () => void {
+    observe: async () => ({ ok: true as const, value: {} }),
+    releaseSurface: () => ({ ok: true as const, value: undefined }),
+    restoreSurface: () => ({ ok: true as const, value: undefined }),
+    recover: async () => ({ ok: true as const, value: undefined }),
+    subscribe(): () => void {
       return () => {};
     },
     dispose: vi.fn(),
-    assets: null,
   };
+  constructRuntimeRendererHost.mockResolvedValue({
+    ok: true,
+    value: { renderer: rendererStub, assets: undefined },
+  });
   return {
     ...actual,
-    createRenderer: vi.fn().mockResolvedValue(rendererStub),
   };
 });
 
+vi.mock('@forgeax/engine-runtime/internal/renderer-host', () => ({
+  constructRuntimeRendererHost,
+  loadRhiPack: vi.fn(),
+}));
+
 // ---------------------------------------------------------------------------
 // Test helpers
 // ---------------------------------------------------------------------------

package/src/__tests__/create-app-physics-plugin-failure.integration.test.ts

@@ -0,0 +1,142 @@
+import { World } from '@forgeax/engine-ecs';
+import { PhysicsError, physicsPlugin } from '@forgeax/engine-physics';
+import type { Renderer } from '@forgeax/engine-render';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { createApp } from '../create-app';
+
+const rapier3d = vi.hoisted(() => ({
+  load: vi.fn(),
+  createWorld: vi.fn(),
+  registerSystems: vi.fn(),
+}));
+
+const rapier2d = vi.hoisted(() => ({
+  load: vi.fn(),
+  createWorld: vi.fn(),
+  registerSystems: vi.fn(),
+}));
+
+vi.mock('@forgeax/engine-physics-rapier3d', () => ({
+  loadRapier3D: rapier3d.load,
+  createRapier3DPhysicsWorld: rapier3d.createWorld,
+  registerPhysicsSystems: rapier3d.registerSystems,
+}));
+
+vi.mock('@forgeax/engine-physics-rapier2d', () => ({
+  loadRapier2D: rapier2d.load,
+  createRapier2DPhysicsWorld: rapier2d.createWorld,
+  registerPhysicsSystems2D: rapier2d.registerSystems,
+}));
+
+function rendererStub(): Renderer {
+  return {
+    backend: 'webgpu',
+    ready: Promise.resolve({ ok: true, value: undefined }),
+    draw: () => ({ ok: true, value: undefined }),
+    onError: () => () => {},
+    onLost: () => () => {},
+    assets: {},
+    dispose: () => {},
+  } as unknown as Renderer;
+}
+
+function injectedWasmFailure(backend: '2D' | '3D', reason: string): PhysicsError {
+  return new PhysicsError({
+    code: 'wasm-load-failed',
+    expected: `the injected Rapier ${backend} loader to become ready`,
+    hint: `injected failure: ${reason}`,
+    detail: { code: 'wasm-load-failed', reason },
+  });
+}
+
+describe('createApp Rapier 3D activation failure', () => {
+  beforeEach(() => {
+    rapier3d.load.mockReset();
+    rapier3d.createWorld.mockReset();
+    rapier3d.registerSystems.mockReset();
+  });
+
+  it.each([
+    {
+      phase: 'loader return',
+      inject: () => rapier3d.load.mockResolvedValue(injectedWasmFailure('3D', 'loader return')),
+    },
+    {
+      phase: 'compat import',
+      inject: () => rapier3d.load.mockRejectedValue(new Error('injected compat import rejection')),
+    },
+    {
+      phase: 'WASM init',
+      inject: () => rapier3d.load.mockRejectedValue(new Error('injected WASM init rejection')),
+    },
+  ])('normalizes $phase before PhysicsWorld creation', async ({ inject }) => {
+    inject();
+    const world = new World();
+
+    const result = await createApp({
+      renderer: rendererStub(),
+      world,
+      plugins: [physicsPlugin('rapier-3d')],
+    });
+
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error.code).toBe('app-plugin-activation-failed');
+    if (result.error.code !== 'app-plugin-activation-failed') return;
+    expect(result.error.detail.cause).toMatchObject({
+      name: 'PhysicsError',
+      code: 'wasm-load-failed',
+      detail: { code: 'wasm-load-failed' },
+    });
+    expect(rapier3d.createWorld).not.toHaveBeenCalled();
+    expect(rapier3d.registerSystems).not.toHaveBeenCalled();
+    expect(world.hasResource('PhysicsWorld')).toBe(false);
+    expect(world.update(0)).toMatchObject({ ok: true });
+  });
+});
+
+describe('createApp Rapier 2D activation failure', () => {
+  beforeEach(() => {
+    rapier2d.load.mockReset();
+    rapier2d.createWorld.mockReset();
+    rapier2d.registerSystems.mockReset();
+  });
+
+  it.each([
+    {
+      phase: 'loader return',
+      inject: () => rapier2d.load.mockResolvedValue(injectedWasmFailure('2D', 'loader return')),
+    },
+    {
+      phase: 'compat import',
+      inject: () => rapier2d.load.mockRejectedValue(new Error('injected compat import rejection')),
+    },
+    {
+      phase: 'WASM init',
+      inject: () => rapier2d.load.mockRejectedValue(new Error('injected WASM init rejection')),
+    },
+  ])('normalizes $phase before PhysicsWorld creation', async ({ inject }) => {
+    inject();
+    const world = new World();
+
+    const result = await createApp({
+      renderer: rendererStub(),
+      world,
+      plugins: [physicsPlugin('rapier-2d')],
+    });
+
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error.code).toBe('app-plugin-activation-failed');
+    if (result.error.code !== 'app-plugin-activation-failed') return;
+    expect(result.error.detail.cause).toMatchObject({
+      name: 'PhysicsError',
+      code: 'wasm-load-failed',
+      detail: { code: 'wasm-load-failed' },
+    });
+    expect(rapier2d.createWorld).not.toHaveBeenCalled();
+    expect(rapier2d.registerSystems).not.toHaveBeenCalled();
+    expect(world.hasResource('PhysicsWorld')).toBe(false);
+    expect(world.update(0)).toMatchObject({ ok: true });
+  });
+});

package/src/__tests__/create-app-stop.test.ts

@@ -15,6 +15,7 @@ import type { Renderer } from '@forgeax/engine-render';
 import type { RhiError } from '@forgeax/engine-rhi/errors';
 import { ok } from '@forgeax/engine-types';
 import { describe, expect, it, vi } from 'vitest';
+import { RendererContractFailureError } from '../../../render/src/errors/render';
 
 import { createApp } from '../create-app';
 
@@ -38,16 +39,11 @@ function makeRendererStubForStop(): StubRenderer {
     draw(): { ok: true; value: undefined } {
       return { ok: true, value: undefined };
     },
-    attachWorld(): { ok: true; value: undefined } {
+    attach(): { ok: true; value: undefined } {
       return { ok: true, value: undefined };
     },
     detachWorld(): void {},
-    onError(): () => void {
-      return () => {
-        // no-op unsubscribe
-      };
-    },
-    onLost(): () => void {
+    subscribe(): () => void {
       return () => {
         // no-op unsubscribe
       };
@@ -83,11 +79,7 @@ describe('create-app-stop.test.ts', () => {
 
     it('does not restore a running loop when surface release fails', async () => {
       const { renderer } = makeRendererStubForStop();
-      const releaseError = new (await import('@forgeax/engine-rhi')).RhiError({
-        code: 'rhi-not-available',
-        expected: 'test release succeeds',
-        hint: 'forced failure',
-      });
+      const releaseError = new RendererContractFailureError('draw', 'forced failure');
       vi.mocked(renderer.releaseSurface).mockReturnValue({ ok: false, error: releaseError });
       const result = await createApp({ renderer, world: new World() });
       expect(result.ok).toBe(true);

package/src/__tests__/create-app.test-d.ts

@@ -18,21 +18,19 @@
 // - P4 consistent abstraction: both routes return the same App handle.
 
 import type { World } from '@forgeax/engine-ecs';
-import type { Renderer, RendererOptions } from '@forgeax/engine-render';
+import type { RenderError, Renderer, RendererOptions } from '@forgeax/engine-render';
 import type { RhiError } from '@forgeax/engine-rhi/errors';
-import type { EngineEnvironmentError } from '@forgeax/engine-runtime';
+import { createRenderer, type EngineEnvironmentError } from '@forgeax/engine-runtime';
 import type { Result } from '@forgeax/engine-types';
 import { describe, expectTypeOf, it } from 'vitest';
-import type { AssetRuntimeAssemblyError } from '../assets-runtime-assembly';
 import { type App, type AppError, createApp } from '../index';
-import type { RhiCaptureHook } from '../types';
 
 describe('createApp double-SSOT entry signatures (w2 acceptanceCheck)', () => {
   it('canvas form returns the App boundary error union', () => {
     const canvas = null as unknown as HTMLCanvasElement;
     const ret = createApp(canvas);
     expectTypeOf(ret).toEqualTypeOf<
-      Promise<Result<App, AppError | RhiError | AssetRuntimeAssemblyError | EngineEnvironmentError>>
+      Promise<Result<App, AppError | RhiError | EngineEnvironmentError>>
     >();
   });
 
@@ -40,9 +38,7 @@ describe('createApp double-SSOT entry signatures (w2 acceptanceCheck)', () => {
     const renderer = null as unknown as Renderer;
     const world = null as unknown as World;
     const ret = createApp({ renderer, world });
-    expectTypeOf(ret).toEqualTypeOf<
-      Promise<Result<App, AppError | RhiError | AssetRuntimeAssemblyError>>
-    >();
+    expectTypeOf(ret).toEqualTypeOf<Promise<Result<App, AppError | RhiError>>>();
   });
 
   it('app.renderer / app.world are reference-equal types at the call site (AC-09)', async () => {
@@ -54,10 +50,15 @@ describe('createApp double-SSOT entry signatures (w2 acceptanceCheck)', () => {
       expectTypeOf(result.value.world).toEqualTypeOf<World>();
     }
   });
+});
 
-  it('main and Worker execution share the same global capture hook shape', () => {
-    const captureFrame = (globalThis as { __forgeax?: RhiCaptureHook }).__forgeax?.captureFrame;
-    expectTypeOf(captureFrame).toEqualTypeOf<RhiCaptureHook['captureFrame'] | undefined>();
+describe('Runtime createRenderer Result boundary (AC-11)', () => {
+  it('requires callers to narrow the construction Result', () => {
+    const canvas = null as unknown as HTMLCanvasElement;
+    const expected = null as unknown as Promise<
+      Result<Renderer, EngineEnvironmentError | RenderError>
+    >;
+    expectTypeOf(createRenderer(canvas)).toEqualTypeOf(expected);
   });
 });
 

package/src/__tests__/create-app.test.ts

@@ -25,8 +25,7 @@ import { World } from '@forgeax/engine-ecs';
 import { Camera, orthographic, perspective } from '@forgeax/engine-render';
 import { describe, expect, it } from 'vitest';
 
-import { createApp, syncCameraAspect, syncCanvasDrawingBuffer } from '../create-app';
-import { AppError } from '../errors';
+import { syncCameraAspect, syncCanvasDrawingBuffer } from '../create-app';
 import { resolveRhiDebugFlag } from '../internal/rhi-debug-flag';
 
 describe('create-app.test.ts', () => {
@@ -119,64 +118,6 @@ describe('create-app.test.ts', () => {
       }
     });
 
-    it('applies a Host pixel-ratio cap without changing the default path', () => {
-      const canvas = {
-        clientWidth: 800,
-        clientHeight: 400,
-        width: 300,
-        height: 150,
-        style: { width: '800px', height: '400px' },
-      };
-      const before = globalThis.devicePixelRatio;
-      Object.defineProperty(globalThis, 'devicePixelRatio', { configurable: true, value: 2 });
-      try {
-        syncCanvasDrawingBuffer(canvas, 1.5);
-        expect(canvas.width).toBe(1200);
-        expect(canvas.height).toBe(600);
-      } finally {
-        Object.defineProperty(globalThis, 'devicePixelRatio', {
-          configurable: true,
-          value: before,
-        });
-      }
-    });
-
-    it('allows the Host to downsample a GPU-bound canvas below CSS pixel density', () => {
-      const canvas = {
-        clientWidth: 800,
-        clientHeight: 400,
-        width: 300,
-        height: 150,
-        style: { width: '800px', height: '400px' },
-      };
-      const before = globalThis.devicePixelRatio;
-      Object.defineProperty(globalThis, 'devicePixelRatio', { configurable: true, value: 2 });
-      try {
-        syncCanvasDrawingBuffer(canvas, 0.875);
-        expect(canvas.width).toBe(700);
-        expect(canvas.height).toBe(350);
-      } finally {
-        Object.defineProperty(globalThis, 'devicePixelRatio', {
-          configurable: true,
-          value: before,
-        });
-      }
-    });
-
-    it('rejects an invalid Host pixel-ratio cap before touching a detached canvas', async () => {
-      const result = await createApp(
-        { tagName: 'CANVAS', isConnected: false } as unknown as HTMLCanvasElement,
-        { maxCanvasPixelRatio: 0 },
-      );
-      expect(result.ok).toBe(false);
-      if (!result.ok && result.error instanceof AppError) {
-        expect(result.error.code).toBe('app-invalid-canvas-pixel-ratio');
-        if (result.error.code === 'app-invalid-canvas-pixel-ratio') {
-          expect(result.error.detail.value).toBe(0);
-        }
-      }
-    });
-
     it('leaves a zero-sized host untouched', () => {
       const canvas = { clientWidth: 0, clientHeight: 400, width: 300, height: 150 };
       syncCanvasDrawingBuffer(canvas);

package/src/__tests__/create-renderer-error.integration.test.ts

@@ -3,8 +3,9 @@ import { describe, expect, it } from 'vitest';
 import { createApp } from '../create-app';
 
 describe('app renderer construction boundary', () => {
-  it('keeps construction failures catchable', async () => {
-    await expect(createRenderer(null as never)).rejects.toBeDefined();
+  it('returns construction failures through the Runtime Result boundary', async () => {
+    const result = await createRenderer(null as never);
+    expect(result.ok).toBe(false);
   });
 
   it('returns EngineEnvironmentError through the canvas Result path', async () => {

package/src/__tests__/create-renderer-lifecycle.integration.test.ts

@@ -5,13 +5,18 @@ describe('app-facing renderer lifecycle', () => {
   it('consumes the three lifecycle Result boundaries without casts', async () => {
     const events: string[] = [];
     const renderer = {
-      ready: Promise.resolve({ ok: true as const, value: undefined }),
-      draw: () => ({ ok: true as const, value: undefined }),
+      attach: () => ({ ok: false as const, error: {} }),
+      draw: () => ({ ok: false as const, error: {} }),
+      observe: async () => ({ ok: false as const, error: {} }),
+      releaseSurface: () => ({ ok: true as const, value: undefined }),
+      restoreSurface: () => ({ ok: true as const, value: undefined }),
+      recover: async () => ({ ok: true as const, value: undefined }),
       dispose: () => events.push('dispose'),
+      onError: () => () => undefined,
+      onLost: () => () => undefined,
     } as unknown as Renderer;
-    const ready = await renderer.ready;
-    expect(ready.ok).toBe(true);
-    expect(renderer.draw([], { cameraOwner: 0, resourceOwner: 0 }).ok).toBe(true);
+    expect(renderer.attach({} as never).ok).toBe(false);
+    expect(renderer.draw({} as never).ok).toBe(false);
     renderer.dispose();
     renderer.dispose();
     expect(events).toEqual(['dispose', 'dispose']);

package/src/__tests__/draw-source-injected-world-update-visibility.test.ts

@@ -34,6 +34,7 @@
 
 import type { EntityHandle } from '@forgeax/engine-ecs';
 import { World } from '@forgeax/engine-ecs';
+import { createRenderReadLease } from '@forgeax/engine-ecs/projection';
 import type { Renderer } from '@forgeax/engine-render';
 import { registerPropagateTransforms, Transform } from '@forgeax/engine-scene';
 import { describe, expect, it } from 'vitest';
@@ -123,19 +124,12 @@ describe('drawSource injected worlds are updated same-frame (w9, stale-matrix re
     // stage performs (Transform.world is the extract SSOT).
     const observed: Array<[number, number, number]> = [];
     const renderer = {
-      backend: 'webgpu' as const,
-      ready: Promise.resolve({ ok: true, value: undefined }),
-      attachWorld: () => ({ ok: true, value: undefined }),
-      detachWorld: () => {},
-      draw(worlds: readonly World[]): { ok: true; value: undefined } {
-        // worlds is what drawSource returned; find the injected world in it.
-        const iw = worlds.find((w) => w === injectedWorld);
-        if (iw !== undefined) {
-          const r = iw.get(entity, Transform);
-          if (r.ok) {
-            const m = r.value.world as unknown as ArrayLike<number>;
-            observed.push([m[12] as number, m[13] as number, m[14] as number]);
-          }
+      attach: (world: World) => ({ ok: true, value: createRenderReadLease(world) }),
+      draw(): { ok: true; value: undefined } {
+        const r = injectedWorld.get(entity, Transform);
+        if (r.ok) {
+          const m = r.value.world as unknown as ArrayLike<number>;
+          observed.push([m[12] as number, m[13] as number, m[14] as number]);
         }
         return { ok: true, value: undefined };
       },