@forgeax/engine-app 0.1.4 → 0.1.6

package/src/__tests__/profiler-frame-token.test.ts

@@ -1,6 +1,7 @@
 import { World } from '@forgeax/engine-ecs';
+import { createRenderReadLease } from '@forgeax/engine-ecs/projection';
 import { createProfiler, type ProfileCapture } from '@forgeax/engine-profiler';
-import type { DrawOwnerOptions, Renderer } from '@forgeax/engine-render';
+import type { Renderer, RenderFrameInput } from '@forgeax/engine-render';
 import { describe, expect, it } from 'vitest';
 
 import { createFrameLoop } from '../internal/frame-loop';
@@ -32,18 +33,14 @@ function makeScheduler() {
   };
 }
 
-function makeRenderer(onDraw: (options: unknown) => void = () => {}): Renderer {
+function makeRenderer(onDraw: (profileFrame: unknown) => void = () => {}): Renderer {
   return {
-    backend: 'webgpu',
-    ready: Promise.resolve({ ok: true, value: undefined }),
-    attachWorld: () => ({ ok: true, value: undefined }),
-    detachWorld: () => {},
-    draw: (_worlds: World[], options: DrawOwnerOptions) => {
-      onDraw(options);
+    attach: (world: World) => ({ ok: true, value: createRenderReadLease(world) }),
+    draw: (request: RenderFrameInput) => {
+      onDraw(request.profileFrame);
       return { ok: true, value: undefined };
     },
-    onError: () => () => {},
-    onLost: () => () => {},
+    subscribe: () => () => {},
     dispose: () => {},
   } as unknown as Renderer;
 }
@@ -98,42 +95,32 @@ describe('App profiler frame token', () => {
     const capture = finish(profiler);
     expect(capture.phaseCatalog.app).toEqual(APP_PHASE_CATALOG);
     expect(capture.captureId).toBe('capture-0001');
-    expect(
-      capture.records.filter(
-        (record: ProfileCapture['records'][number]) => record.source === 'app',
-      ),
-    ).toHaveLength(10);
+    expect(capture.records.filter((record) => record.source === 'app')).toHaveLength(10);
     expect(
       capture.records
-        .filter(
-          (record: ProfileCapture['records'][number]) =>
-            record.source === 'app' && record.kind === 'phase',
-        )
-        .map((record: ProfileCapture['records'][number]) => record.phase),
+        .filter((record) => record.source === 'app' && record.kind === 'phase')
+        .map((record) => record.phase),
     ).toEqual(expect.arrayContaining([...FRAME_LOOP_PHASES]));
     expect(
       new Set(
         capture.records
-          .filter(
-            (record: ProfileCapture['records'][number]) =>
-              record.source === 'app' && record.kind === 'phase',
-          )
-          .map((record: ProfileCapture['records'][number]) => record.phase),
+          .filter((record) => record.source === 'app' && record.kind === 'phase')
+          .map((record) => record.phase),
       ),
     ).toEqual(new Set(FRAME_LOOP_PHASES));
     expect(
       new Set(
-        capture.records
-          .filter((record: ProfileCapture['records'][number]) => record.source === 'app')
-          .map((record: ProfileCapture['records'][number]) => record.frameId),
+        capture.records.filter((record) => record.source === 'app').map((record) => record.frameId),
       ),
     ).toEqual(new Set([1, 2]));
     expect(drawOptions).toHaveLength(2);
     expect(drawOptions[0]).toMatchObject({
-      profileFrame: { captureId: 'capture-0001', frameId: 1 },
+      captureId: 'capture-0001',
+      frameId: 1,
     });
     expect(drawOptions[1]).toMatchObject({
-      profileFrame: { captureId: 'capture-0001', frameId: 2 },
+      captureId: 'capture-0001',
+      frameId: 2,
     });
   });
 

package/src/__tests__/profiler-phase-integration.test.ts

@@ -1,6 +1,7 @@
 import { World } from '@forgeax/engine-ecs';
-import { createProfiler, type ProfileCapture } from '@forgeax/engine-profiler';
-import type { DrawOwnerOptions, Renderer } from '@forgeax/engine-render';
+import { createRenderReadLease } from '@forgeax/engine-ecs/projection';
+import { createProfiler } from '@forgeax/engine-profiler';
+import type { Renderer, RenderFrameInput } from '@forgeax/engine-render';
 import { describe, expect, it } from 'vitest';
 
 import { createFrameLoop } from '../internal/frame-loop';
@@ -24,18 +25,14 @@ function makeScheduler() {
   };
 }
 
-function makeRenderer(draw: (options: DrawOwnerOptions) => void): Renderer {
+function makeRenderer(draw: (profileFrame: unknown) => void): Renderer {
   return {
-    backend: 'webgpu',
-    ready: Promise.resolve({ ok: true, value: undefined }),
-    attachWorld: () => ({ ok: true, value: undefined }),
-    detachWorld: () => {},
-    draw: (_worlds: World[], options: DrawOwnerOptions) => {
-      draw(options);
+    attach: (world: World) => ({ ok: true, value: createRenderReadLease(world) }),
+    draw: (request: RenderFrameInput) => {
+      draw(request.profileFrame);
       return { ok: true, value: undefined };
     },
-    onError: () => () => {},
-    onLost: () => () => {},
+    subscribe: () => () => {},
     dispose: () => {},
   } as unknown as Renderer;
 }
@@ -46,7 +43,7 @@ function start(profiler: ReturnType<typeof createProfiler>) {
   return result.value;
 }
 
-function finish(profiler: ReturnType<typeof createProfiler>): ProfileCapture {
+function finish(profiler: ReturnType<typeof createProfiler>) {
   const session = profiler.activeSession();
   if (session === undefined) {
     const latest = profiler.latestCapture();
@@ -63,7 +60,7 @@ describe('App and Render profiler integration', () => {
     const profiler = createProfiler();
     start(profiler);
     const scheduler = makeScheduler();
-    const drawOptions: DrawOwnerOptions[] = [];
+    const drawOptions: unknown[] = [];
     const loop = createFrameLoop({
       world: new World(),
       renderer: makeRenderer((options) => drawOptions.push(options)),
@@ -78,16 +75,11 @@ describe('App and Render profiler integration', () => {
     loop.stop().unwrap();
 
     const capture = finish(profiler);
-    expect(
-      capture.records.filter(
-        (record: ProfileCapture['records'][number]) => record.source === 'app',
-      ),
-    ).toHaveLength(5);
-    expect(
-      capture.records.every((record: ProfileCapture['records'][number]) => record.frameId === 1),
-    ).toBe(true);
+    expect(capture.records.filter((record) => record.source === 'app')).toHaveLength(5);
+    expect(capture.records.every((record) => record.frameId === 1)).toBe(true);
     expect(drawOptions[0]).toMatchObject({
-      profileFrame: { captureId: capture.captureId, frameId: 1 },
+      captureId: capture.captureId,
+      frameId: 1,
     });
     expect(capture.phaseCatalog.app).toEqual(APP_PHASE_CATALOG);
     expect(profiler.phaseCatalog.app).toEqual([]);
@@ -120,10 +112,6 @@ describe('App and Render profiler integration', () => {
     const capture = finish(profiler);
     expect(draws).toBe(2);
     expect(errors).toHaveLength(2);
-    expect(
-      capture.records.filter(
-        (record: ProfileCapture['records'][number]) => record.source === 'app',
-      ),
-    ).toHaveLength(10);
+    expect(capture.records.filter((record) => record.source === 'app')).toHaveLength(10);
   });
 });

package/src/__tests__/surface-handoff.test.ts

@@ -30,10 +30,7 @@ describe('createApp presentation surface handoff', () => {
         drawSawReleasedSurface = surfaceReleased;
         return ok(undefined);
       },
-      onError(): () => void {
-        return () => {};
-      },
-      onLost(): () => void {
+      subscribe(): () => void {
         return () => {};
       },
       releaseSurface(): { ok: true; value: undefined } {

package/src/__tests__/visibility-remote.integration.test.ts

@@ -37,12 +37,11 @@ function makeRendererStub(): Renderer {
     onError: () => () => {},
     onLost: () => () => {},
     dispose: () => {},
-    visibilityStats: { explicitlyHidden: 1 },
   } as unknown as Renderer;
 }
 
 describe('createApp to remote visibility discovery', () => {
-  it('introspects then evaluates a Query, recovers an invalid write, and reads stats', async () => {
+  it('introspects then evaluates a Query and recovers an invalid write', async () => {
     const previous = process.env.FORGEAX_ENGINE_REMOTE_SERVE;
     process.env.FORGEAX_ENGINE_REMOTE_SERVE = '1';
     const world = new World();
@@ -77,7 +76,7 @@ describe('createApp to remote visibility discovery', () => {
           const query = world.query({ read: [render.Visibility] }).unwrap();
           let current;
           for (const row of query) {
-            current = render.visibilityStateFromU32(row.get(render.Visibility).state);
+            current = ['inherited', 'hidden', 'visible'][row.get(render.Visibility).state];
           }
           const effective = render.resolveVisibility(world).effective(entity);
           const invalid = world.set(entity, render.Visibility, { state: 99 });
@@ -95,7 +94,6 @@ describe('createApp to remote visibility discovery', () => {
             },
             recovered: recovered.ok,
             restored: render.resolveVisibility(world).effective(entity),
-            visibilityStats: renderer.visibilityStats,
           };
         })()`);
         expect(value).toMatchObject({
@@ -104,7 +102,6 @@ describe('createApp to remote visibility discovery', () => {
           invalid: { code: 'component-field-invalid-value' },
           recovered: true,
           restored: 'visible',
-          visibilityStats: { explicitlyHidden: 1 },
         });
         expect((value as { invalid: { hint: string } }).invalid.hint.length).toBeGreaterThan(0);
       } finally {

package/src/__tests__/worker-execution-stop.test.ts

@@ -1,12 +1,22 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest';
+import type { EngineToHostMessage } from '../execution/protocol';
 
-const probes = vi.hoisted(() => ({
-  audioDispose: vi.fn(),
-  inputDetach: vi.fn(),
-  sessionDispose: vi.fn(),
-  sessionListen: vi.fn(() => () => {}),
-  sessionPost: vi.fn(),
-}));
+type SessionListener = (message: EngineToHostMessage) => void;
+
+const probes = vi.hoisted(() => {
+  const sessionListeners: SessionListener[] = [];
+  return {
+    audioDispose: vi.fn(),
+    inputDetach: vi.fn(),
+    sessionDispose: vi.fn(),
+    sessionListen: vi.fn((listener: SessionListener) => {
+      sessionListeners.push(listener);
+      return () => {};
+    }),
+    sessionListeners,
+    sessionPost: vi.fn(),
+  };
+});
 
 vi.mock('../execution/engine-worker', async () => {
   const { ok } = await import('@forgeax/engine-types');
@@ -73,6 +83,7 @@ const capabilities = {
 describe('Worker ExecutionApp terminal stop', () => {
   beforeEach(() => {
     vi.clearAllMocks();
+    probes.sessionListeners.length = 0;
   });
 
   it('cleans every host owner once when stopped while paused and cannot restart', async () => {
@@ -113,4 +124,50 @@ describe('Worker ExecutionApp terminal stop', () => {
     if (!restart.ok) expect(restart.error.code).toBe('app-not-started');
     expect(raf).toHaveBeenCalledTimes(1);
   });
+
+  it('retains the existing terminal fault identity for host inspection', async () => {
+    vi.stubGlobal(
+      'requestAnimationFrame',
+      vi.fn(() => 7),
+    );
+    vi.stubGlobal('cancelAnimationFrame', vi.fn());
+    const result = await createWorkerExecutionApp({
+      canvas: {} as HTMLCanvasElement,
+      appOptions: { execution: { bootstrap: 'https://example.test/game.js' } } as never,
+      capabilities,
+      selection: {
+        requestedTier: 'engine-worker',
+        actualTier: 'engine-worker',
+        selectionReason: 'explicit-request',
+        missingCapabilities: [],
+        sharedEvidencePassed: false,
+      },
+    });
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    let observed: unknown;
+    result.value.onError((error) => {
+      observed = error;
+    });
+    const listener = probes.sessionListeners[0];
+    expect(listener).toBeTypeOf('function');
+
+    listener?.({
+      kind: 'fault',
+      worldIdentity: 'worker-world',
+      source: 'world',
+      code: 'app-system-update-failed',
+      expected: 'worker world update succeeds',
+      hint: 'inspect the retained cause',
+      detail: { cause: 'worker boom' },
+      partialWrite: true,
+      retryable: false,
+    });
+
+    expect(result.value.lastError).toBe(observed);
+    expect(result.value.lastError).toMatchObject({
+      code: 'app-system-update-failed',
+      detail: { cause: { cause: 'worker boom' } },
+    });
+  });
 });

package/src/animation-asset-lookup.ts

@@ -1,8 +1,8 @@
 import type { AnimationPayloadLookup } from '@forgeax/engine-animation';
-import type { AnimationClip, Asset } from '@forgeax/engine-types';
+import type { AnimationClip } from '@forgeax/engine-types';
 
 export interface AnimationPayloadSource {
-  lookup<T extends Asset = Asset>(guid: string): T | undefined;
+  lookup<T = unknown>(guid: string): T | undefined;
 }
 
 /** Bridge the renderer-owned GUID catalogue into the animation plugin. */