@forgeax/engine-app 0.1.2

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

@@ -0,0 +1,119 @@
+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: () => {},
+    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 () => {
+    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 = render.visibilityStateFromU32(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),
+            visibilityStats: renderer.visibilityStats,
+          };
+        })()`);
+        expect(value).toMatchObject({
+          current: 'hidden',
+          effective: 'hidden',
+          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 {
+        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,116 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const probes = vi.hoisted(() => ({
+  audioDispose: vi.fn(),
+  inputDetach: vi.fn(),
+  sessionDispose: vi.fn(),
+  sessionListen: vi.fn(() => () => {}),
+  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();
+  });
+
+  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);
+  });
+});

package/src/animation-asset-lookup.ts

@@ -0,0 +1,13 @@
+import type { AnimationPayloadLookup } from '@forgeax/engine-animation';
+import type { AnimationClip, Asset } from '@forgeax/engine-types';
+
+export interface AnimationPayloadSource {
+  lookup<T extends Asset = Asset>(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/assets-runtime-assembly.ts

@@ -0,0 +1,70 @@
+import type { AssetDecoderLease, AssetRegistry } from '@forgeax/engine-assets-runtime';
+import { defaultAssetDecoderContributions } from '@forgeax/engine-runtime';
+import {
+  type AssetDecoderContributionRef,
+  type AssetKind,
+  err,
+  ok,
+  type Result,
+} from '@forgeax/engine-types';
+
+export interface AssetRuntimeAssemblyError {
+  readonly code: 'asset-assembly-failed';
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: { readonly kind: string; readonly cause: unknown };
+}
+
+export interface AssetRuntimeAssembly {
+  readonly registry: AssetRegistry;
+  readonly leases: readonly AssetDecoderLease[];
+  dispose(): void;
+}
+
+/** Install owner decoder contributions into the realm's one asset registry. */
+export function assembleAssetRuntime(
+  registry: AssetRegistry,
+  contributions: readonly AssetDecoderContributionRef[],
+): Result<AssetRuntimeAssembly, AssetRuntimeAssemblyError> {
+  const leases: AssetDecoderLease[] = [];
+  const overrides = new Set(contributions.map((contribution) => contribution.kind.kind));
+  const defaults = defaultAssetDecoderContributions ?? [];
+  const assembledContributions = [
+    ...defaults.filter((contribution) => !overrides.has(contribution.kind.kind)),
+    ...contributions,
+  ];
+  try {
+    const installedKinds = new Set<string>();
+    for (const contribution of assembledContributions) {
+      if (installedKinds.has(contribution.kind.kind)) {
+        throw new TypeError(`duplicate decoder kind "${contribution.kind.kind}"`);
+      }
+      installedKinds.add(contribution.kind.kind);
+      leases.push(
+        registry.installDecoder(
+          contribution.kind as AssetKind<unknown, string>,
+          contribution.decoder,
+        ),
+      );
+    }
+  } catch (cause) {
+    for (const lease of leases) lease.dispose();
+    const failed = assembledContributions[leases.length];
+    return err({
+      code: 'asset-assembly-failed',
+      expected: 'each owner decoder contribution to install exactly once in the realm registry',
+      hint: 'remove the conflicting owner contribution and assemble the current realm again',
+      detail: { kind: failed?.kind.kind ?? 'unknown', cause },
+    });
+  }
+  let disposed = false;
+  return ok({
+    registry,
+    leases: Object.freeze([...leases]),
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      for (const lease of leases) lease.dispose();
+    },
+  });
+}

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 });
+  }
+}