@forgeax/engine-app 0.0.0-dev.8d955ade1c79

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

@@ -0,0 +1,116 @@
+import { World } from '@forgeax/engine-ecs';
+import type { Renderer } from '@forgeax/engine-render';
+import { Visibility } from '@forgeax/engine-render';
+import { defaultConnect } from '@forgeax/engine-types/inspector-client';
+import { describe, expect, it } from 'vitest';
+import { WebSocket } from 'ws';
+import { createApp } from '../create-app';
+
+async function introspect(port: number): Promise<Record<string, unknown>> {
+  const ws = new WebSocket(`ws://127.0.0.1:${port}/inspector`);
+  await new Promise<void>((resolve, reject) => {
+    ws.once('open', () => resolve());
+    ws.once('error', reject);
+  });
+  try {
+    return await new Promise<Record<string, unknown>>((resolve, reject) => {
+      ws.once('message', (raw) => {
+        try {
+          const response = JSON.parse(raw.toString()) as { result: Record<string, unknown> };
+          resolve(response.result);
+        } catch (error) {
+          reject(error);
+        }
+      });
+      ws.send(JSON.stringify({ jsonrpc: '2.0', method: 'introspect', id: 1 }));
+    });
+  } finally {
+    ws.close();
+  }
+}
+
+function makeRendererStub(): Renderer {
+  return {
+    backend: 'webgpu',
+    ready: Promise.resolve({ ok: true, value: undefined }),
+    draw: () => ({ ok: true, value: undefined }),
+    onError: () => () => {},
+    onLost: () => () => {},
+    dispose: () => {},
+  } as unknown as Renderer;
+}
+
+describe('createApp to remote visibility discovery', () => {
+  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();
+    world.components.register(Visibility).unwrap();
+    const result = await createApp({ renderer: makeRendererStub(), world });
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.remote).toBeDefined();
+
+    try {
+      const port = result.value.remote?.port;
+      expect(port).toBeGreaterThan(0);
+      if (port === undefined) return;
+      const doc = await introspect(port);
+      const schemas = (doc.components as { schemas: Record<string, unknown> }).schemas;
+      expect(schemas.Visibility).toBeDefined();
+      expect((doc.methods as Array<{ name: string }>).map((method) => method.name)).toEqual([
+        'eval',
+        'introspect',
+      ]);
+
+      const connection = await defaultConnect(`ws://127.0.0.1:${port}/inspector`);
+      expect(connection.ok).toBe(true);
+      if (!connection.ok) return;
+      try {
+        const value = await connection.value.eval(`(async () => {
+          const render = await _import('@forgeax/engine-render');
+          const entity = world.spawn({
+            component: render.Visibility,
+            data: { state: render.VisibilityStateValue.hidden },
+          }).unwrap();
+          const query = world.query({ read: [render.Visibility] }).unwrap();
+          let current;
+          for (const row of query) {
+            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 });
+          const recovered = world.set(entity, render.Visibility, {
+            state: render.VisibilityStateValue.visible,
+          });
+          return {
+            current,
+            effective,
+            invalid: invalid.ok ? undefined : {
+              code: invalid.error.code,
+              expected: invalid.error.expected,
+              hint: invalid.error.hint,
+              detail: invalid.error.detail,
+            },
+            recovered: recovered.ok,
+            restored: render.resolveVisibility(world).effective(entity),
+          };
+        })()`);
+        expect(value).toMatchObject({
+          current: 'hidden',
+          effective: 'hidden',
+          invalid: { code: 'component-field-invalid-value' },
+          recovered: true,
+          restored: 'visible',
+        });
+        expect((value as { invalid: { hint: string } }).invalid.hint.length).toBeGreaterThan(0);
+      } finally {
+        await connection.value.dispose();
+      }
+    } finally {
+      await result.value.remote?.close();
+      if (previous === undefined) delete process.env.FORGEAX_ENGINE_REMOTE_SERVE;
+      else process.env.FORGEAX_ENGINE_REMOTE_SERVE = previous;
+    }
+  });
+});

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

@@ -0,0 +1,173 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import type { EngineToHostMessage } from '../execution/protocol';
+
+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');
+  return {
+    startEngineWorker: vi.fn(async () =>
+      ok({
+        worker: {},
+        ready: {
+          kind: 'ready' as const,
+          worldIdentity: 'worker-world',
+          realm: 'worker' as const,
+          workerWebGpu: true,
+        },
+        post: probes.sessionPost,
+        listen: probes.sessionListen,
+        dispose: probes.sessionDispose,
+      }),
+    ),
+  };
+});
+
+vi.mock('@forgeax/engine-input', () => ({
+  attachBrowserInputBackend: vi.fn(() => {
+    const detach = probes.inputDetach as typeof probes.inputDetach & {
+      backend: { sample(): object; detach(): void };
+    };
+    detach.backend = {
+      sample: () => ({
+        downKeys: new Set(),
+        upKeys: new Set(),
+        buttons: [false, false, false],
+        movementX: 0,
+        movementY: 0,
+        wheelDelta: 0,
+        focused: true,
+        pointerLocked: false,
+      }),
+      detach: probes.inputDetach,
+    };
+    return detach;
+  }),
+}));
+
+vi.mock('@forgeax/engine-audio-webaudio', () => ({
+  createHostAudioConsumer: vi.fn(() => ({
+    consume: vi.fn(),
+    dispose: probes.audioDispose,
+    state: () => ({ contextState: 'suspended', activeSourceCount: 0, lastError: null }),
+  })),
+}));
+
+import { createWorkerExecutionApp } from '../execution/host-controller';
+
+const capabilities = {
+  worker: { available: true, reason: 'test' },
+  offscreenCanvas: { available: true, reason: 'test' },
+  workerAnimationFrame: { available: true, reason: 'test' },
+  workerWebGpu: { available: true, reason: 'test' },
+  crossOriginIsolated: { available: false, reason: 'test' },
+  sharedArrayBuffer: { available: false, reason: 'test' },
+  atomicsWait: { available: false, reason: 'test' },
+} as const;
+
+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 () => {
+    const raf = vi.fn(() => 7);
+    const cancelRaf = vi.fn();
+    vi.stubGlobal('requestAnimationFrame', raf);
+    vi.stubGlobal('cancelAnimationFrame', cancelRaf);
+
+    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;
+
+    expect(result.value.start().ok).toBe(true);
+    expect(raf).toHaveBeenCalledTimes(1);
+    expect(result.value.pause().ok).toBe(true);
+    expect(cancelRaf).toHaveBeenCalledTimes(1);
+
+    expect(result.value.stop().ok).toBe(true);
+    expect(probes.inputDetach).toHaveBeenCalledTimes(1);
+    expect(probes.audioDispose).toHaveBeenCalledTimes(1);
+    expect(probes.sessionDispose).toHaveBeenCalledTimes(1);
+    expect(raf).toHaveBeenCalledTimes(1);
+    expect(cancelRaf).toHaveBeenCalledTimes(1);
+
+    const restart = result.value.start();
+    expect(restart.ok).toBe(false);
+    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

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

package/src/browser-frame-signal.ts

@@ -0,0 +1,44 @@
+/**
+ * Browser-visible render progress owned by the App frame loop.
+ *
+ * The Renderer already emits `frame-submitted` after its sole queue-submit
+ * boundary. This adapter projects that event onto the document without
+ * exposing a renderer handle or creating a second readiness registry. DevKit
+ * capture waits on the same projection, then verifies compositor pixels.
+ */
+
+export const FORGEAX_FRAME_SUBMITTED_DATASET = 'forgeaxFrameSubmitted';
+export const FORGEAX_FRAME_SUBMITTED_EVENT = 'forgeax:frame-submitted';
+
+export interface BrowserFrameSubmitted {
+  readonly frameId: number;
+  readonly deviceGeneration: number;
+}
+
+export function resetBrowserFrameSubmitted(canvas: HTMLCanvasElement): void {
+  const documentElement = canvas.ownerDocument?.documentElement;
+  if (documentElement !== undefined) {
+    delete documentElement.dataset[FORGEAX_FRAME_SUBMITTED_DATASET];
+  }
+}
+
+export function publishBrowserFrameSubmitted(
+  canvas: HTMLCanvasElement,
+  event: BrowserFrameSubmitted,
+): void {
+  const documentElement = canvas.ownerDocument?.documentElement;
+  if (documentElement !== undefined) {
+    documentElement.dataset[FORGEAX_FRAME_SUBMITTED_DATASET] = String(event.frameId);
+  }
+  // Native/Web test canvases may be structural objects without DOM event
+  // methods. The dataset projection above remains optional as well, so the
+  // signal must stay a no-op outside a browser host instead of poisoning the
+  // frame loop with a listener exception.
+  if (typeof CustomEvent === 'function' && typeof canvas.dispatchEvent === 'function') {
+    canvas.dispatchEvent(
+      new CustomEvent(FORGEAX_FRAME_SUBMITTED_EVENT, {
+        detail: Object.freeze({ ...event }),
+      }),
+    );
+  }
+}

package/src/canvas-policy.ts

@@ -0,0 +1,16 @@
+import type { World } from '@forgeax/engine-ecs';
+import { CAMERA_PROJECTION_PERSPECTIVE, Camera } from '@forgeax/engine-render';
+
+/** Keep host-owned perspective camera aspect policy in one execution-tier seam. */
+export function syncCameraAspect(world: World, canvasW: number, canvasH: number): void {
+  if (canvasW <= 0 || canvasH <= 0) return;
+  const aspect = canvasW / canvasH;
+  const query = world.query({ with: [Camera] }).unwrap();
+  for (const row of query) {
+    const camera = world.get(row.entity, Camera);
+    if (!camera.ok) continue;
+    if (camera.value.autoAspect !== true) continue;
+    if (camera.value.projection !== CAMERA_PROJECTION_PERSPECTIVE) continue;
+    world.set(row.entity, Camera, { aspect });
+  }
+}