@forgeax/engine-app 0.1.2

package/src/execution/schema.ts

@@ -0,0 +1,168 @@
+import {
+  EXECUTION_CAPABILITY_NAMES,
+  EXECUTION_REQUESTED_TIERS,
+  EXECUTION_TIERS,
+  type ExecutionReport,
+} from './types';
+
+export const EXECUTION_REPORT_SCHEMA_VERSION = 1 as const;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function hasExactKeys(value: Record<string, unknown>, keys: readonly string[]): boolean {
+  const actual = Object.keys(value);
+  return actual.length === keys.length && keys.every((key) => key in value);
+}
+
+function isMeasurement(value: unknown): boolean {
+  if (!isRecord(value) || !hasExactKeys(value, ['samples', 'p50', 'p95', 'p99', 'jitter'])) {
+    return false;
+  }
+  return (
+    Number.isInteger(value.samples) &&
+    (value.samples as number) > 0 &&
+    ['p50', 'p95', 'p99', 'jitter'].every(
+      (key) => typeof value[key] === 'number' && Number.isFinite(value[key]) && value[key] >= 0,
+    )
+  );
+}
+
+export function isExecutionReport(value: unknown): value is ExecutionReport {
+  if (!isRecord(value)) return false;
+  if (
+    !hasExactKeys(value, [
+      'schemaVersion',
+      'requestedTier',
+      'actualTier',
+      'selectionReason',
+      'sharedEvidencePassed',
+      'capabilities',
+      'engine',
+      'world',
+      'kernelDispatch',
+      'performance',
+      'audio',
+      'fault',
+    ])
+  ) {
+    return false;
+  }
+  const report = value as unknown as Partial<ExecutionReport>;
+  if (report.schemaVersion !== EXECUTION_REPORT_SCHEMA_VERSION) return false;
+  if (!EXECUTION_REQUESTED_TIERS.includes(report.requestedTier as never)) return false;
+  if (report.actualTier !== null && !EXECUTION_TIERS.includes(report.actualTier as never)) {
+    return false;
+  }
+  if (typeof report.sharedEvidencePassed !== 'boolean' || report.capabilities === undefined) {
+    return false;
+  }
+  if (
+    !EXECUTION_CAPABILITY_NAMES.every((name) => {
+      const fact = report.capabilities?.[name];
+      return typeof fact?.available === 'boolean' && typeof fact.reason === 'string';
+    })
+  )
+    return false;
+  const engine = report.engine;
+  const world = report.world;
+  const dispatch = report.kernelDispatch;
+  const performance = report.performance;
+  const audio = report.audio;
+  if (!isRecord(engine) || !hasExactKeys(engine, ['realm', 'health'])) return false;
+  if (!['host', 'worker'].includes(engine.realm as string)) return false;
+  if (!['idle', 'starting', 'running', 'stopped', 'faulted'].includes(engine.health as string)) {
+    return false;
+  }
+  if (
+    !isRecord(world) ||
+    !hasExactKeys(world, ['identity', 'health', 'partialWrite', 'retryable'])
+  ) {
+    return false;
+  }
+  if (world.identity !== null && typeof world.identity !== 'string') return false;
+  if (!['healthy', 'poisoned'].includes(world.health as string)) return false;
+  if (typeof world.partialWrite !== 'boolean' || typeof world.retryable !== 'boolean') return false;
+  if (
+    !isRecord(dispatch) ||
+    !hasExactKeys(dispatch, ['eligible', 'usedShared', 'reason', 'dispatched', 'completed'])
+  ) {
+    return false;
+  }
+  if (typeof dispatch.eligible !== 'boolean' || typeof dispatch.usedShared !== 'boolean')
+    return false;
+  if (
+    ![
+      'no-eligible-kernel',
+      'zero-work',
+      'small-span',
+      'forced-inline',
+      'shared',
+      'poisoned',
+    ].includes(dispatch.reason as string)
+  )
+    return false;
+  if (!Number.isInteger(dispatch.dispatched) || !Number.isInteger(dispatch.completed)) return false;
+  if (
+    !isRecord(performance) ||
+    !hasExactKeys(performance, ['hostFrameMs', 'engineUpdateMs', 'kernelWaitMs', 'hostAudioMs'])
+  )
+    return false;
+  for (const key of ['hostFrameMs', 'engineUpdateMs', 'kernelWaitMs', 'hostAudioMs'] as const) {
+    const measurement = performance[key];
+    if (measurement !== null && !isMeasurement(measurement)) return false;
+  }
+  if (
+    !isRecord(audio) ||
+    !hasExactKeys(audio, ['owner', 'contextState', 'activeSourceCount', 'lastError'])
+  )
+    return false;
+  if (audio.owner !== 'host') return false;
+  if (!['running', 'suspended', 'closed'].includes(audio.contextState as string)) return false;
+  if (!Number.isInteger(audio.activeSourceCount) || (audio.activeSourceCount as number) < 0)
+    return false;
+  if (audio.lastError !== null) {
+    if (!isRecord(audio.lastError)) return false;
+    if (!hasExactKeys(audio.lastError, ['code', 'expected', 'hint', 'detail'])) return false;
+    if (
+      typeof audio.lastError.code !== 'string' ||
+      typeof audio.lastError.expected !== 'string' ||
+      typeof audio.lastError.hint !== 'string'
+    )
+      return false;
+  }
+  if (report.fault !== null) {
+    if (!isRecord(report.fault)) return false;
+    if (
+      !hasExactKeys(report.fault, [
+        'source',
+        'code',
+        'expected',
+        'hint',
+        'detail',
+        'partialWrite',
+        'retryable',
+      ])
+    )
+      return false;
+    if (
+      !['bootstrap', 'handshake', 'runtime', 'kernel', 'world', 'rebuild'].includes(
+        report.fault.source as string,
+      )
+    )
+      return false;
+    if (
+      typeof report.fault.code !== 'string' ||
+      typeof report.fault.expected !== 'string' ||
+      typeof report.fault.hint !== 'string'
+    )
+      return false;
+    if (
+      typeof report.fault.partialWrite !== 'boolean' ||
+      typeof report.fault.retryable !== 'boolean'
+    )
+      return false;
+  }
+  return true;
+}

package/src/execution/selector.ts

@@ -0,0 +1,98 @@
+import { err, ok, type Result } from '@forgeax/engine-types';
+import { APP_ERROR_HINTS, APP_EXPECTED, AppError, type AppError as AppErrorType } from '../errors';
+import { missingExecutionCapabilities } from './capabilities';
+import type {
+  ExecutionCapabilities,
+  ExecutionCapabilityName,
+  ExecutionRequestedTier,
+  ExecutionSelection,
+  ExecutionTier,
+} from './types';
+
+const ENGINE_WORKER_CAPABILITIES = [
+  'worker',
+  'offscreenCanvas',
+  'workerWebGpu',
+] as const satisfies readonly ExecutionCapabilityName[];
+const SHARED_CAPABILITIES = [
+  ...ENGINE_WORKER_CAPABILITIES,
+  'crossOriginIsolated',
+  'sharedArrayBuffer',
+  'atomicsWait',
+] as const satisfies readonly ExecutionCapabilityName[];
+
+export interface ExecutionSelectionInput {
+  readonly requestedTier: ExecutionRequestedTier;
+  readonly capabilities: ExecutionCapabilities;
+  readonly sharedEvidencePassed: boolean;
+}
+
+function requiredCapabilities(tier: ExecutionTier): readonly ExecutionCapabilityName[] {
+  if (tier === 'main-serial') return [];
+  if (tier === 'engine-worker') return ENGINE_WORKER_CAPABILITIES;
+  return SHARED_CAPABILITIES;
+}
+
+function missingFor(
+  tier: ExecutionTier,
+  capabilities: ExecutionCapabilities,
+): readonly ExecutionCapabilityName[] {
+  return missingExecutionCapabilities(capabilities, requiredCapabilities(tier));
+}
+
+export function selectExecutionTier(
+  input: ExecutionSelectionInput,
+): Result<ExecutionSelection, AppErrorType> {
+  if (input.requestedTier !== 'auto') {
+    const missing = missingFor(input.requestedTier, input.capabilities);
+    if (missing.length > 0 || (input.requestedTier === 'shared' && !input.sharedEvidencePassed)) {
+      return err(
+        new AppError({
+          code: 'app-execution-tier-unavailable',
+          expected: APP_EXPECTED['app-execution-tier-unavailable'],
+          hint: APP_ERROR_HINTS['app-execution-tier-unavailable'],
+          detail: {
+            requestedTier: input.requestedTier,
+            missingCapabilities: missing,
+            sharedEvidencePassed: input.sharedEvidencePassed,
+          },
+        }),
+      );
+    }
+    return ok({
+      requestedTier: input.requestedTier,
+      actualTier: input.requestedTier,
+      selectionReason: 'explicit-request',
+      missingCapabilities: [],
+      sharedEvidencePassed: input.sharedEvidencePassed,
+    });
+  }
+
+  const sharedMissing = missingFor('shared', input.capabilities);
+  if (sharedMissing.length === 0 && input.sharedEvidencePassed) {
+    return ok({
+      requestedTier: 'auto',
+      actualTier: 'shared',
+      selectionReason: 'auto-shared',
+      missingCapabilities: [],
+      sharedEvidencePassed: true,
+    });
+  }
+  const workerMissing = missingFor('engine-worker', input.capabilities);
+  if (workerMissing.length === 0) {
+    return ok({
+      requestedTier: 'auto',
+      actualTier: 'engine-worker',
+      selectionReason: 'auto-engine-worker',
+      missingCapabilities: sharedMissing,
+      sharedEvidencePassed: input.sharedEvidencePassed,
+    });
+  }
+  return ok({
+    requestedTier: 'auto',
+    actualTier: 'main-serial',
+    selectionReason: 'auto-main-serial',
+    missingCapabilities: workerMissing,
+    sharedEvidencePassed: input.sharedEvidencePassed,
+  });
+}

package/src/execution/types.ts

@@ -0,0 +1,146 @@
+import type { WorldExecutionHealth } from '@forgeax/engine-ecs/shared';
+import type { Result } from '@forgeax/engine-types';
+import type { AppError } from '../errors';
+
+export const EXECUTION_TIERS = ['main-serial', 'engine-worker', 'shared'] as const;
+export type ExecutionTier = (typeof EXECUTION_TIERS)[number];
+
+export const EXECUTION_REQUESTED_TIERS = ['auto', ...EXECUTION_TIERS] as const;
+export type ExecutionRequestedTier = (typeof EXECUTION_REQUESTED_TIERS)[number];
+
+export const EXECUTION_CAPABILITY_NAMES = [
+  'worker',
+  'offscreenCanvas',
+  'workerAnimationFrame',
+  'workerWebGpu',
+  'crossOriginIsolated',
+  'sharedArrayBuffer',
+  'atomicsWait',
+] as const;
+export type ExecutionCapabilityName = (typeof EXECUTION_CAPABILITY_NAMES)[number];
+
+export interface ExecutionCapabilityFact {
+  readonly available: boolean;
+  readonly reason: string;
+}
+
+export type ExecutionCapabilities = Readonly<
+  Record<ExecutionCapabilityName, ExecutionCapabilityFact>
+>;
+
+export type ExecutionSelectionReason =
+  | 'explicit-request'
+  | 'auto-shared'
+  | 'auto-engine-worker'
+  | 'auto-main-serial';
+
+export interface ExecutionSelection {
+  readonly requestedTier: ExecutionRequestedTier;
+  readonly actualTier: ExecutionTier;
+  readonly selectionReason: ExecutionSelectionReason;
+  readonly missingCapabilities: readonly ExecutionCapabilityName[];
+  readonly sharedEvidencePassed: boolean;
+}
+
+export type ExecutionEngineHealth = 'idle' | 'starting' | 'running' | 'stopped' | 'faulted';
+export type ExecutionWorldHealth = WorldExecutionHealth;
+
+export type KernelDispatchReason =
+  | 'no-eligible-kernel'
+  | 'zero-work'
+  | 'small-span'
+  | 'forced-inline'
+  | 'shared'
+  | 'poisoned';
+
+export interface ExecutionMeasurement {
+  readonly samples: number;
+  readonly p50: number;
+  readonly p95: number;
+  readonly p99: number;
+  readonly jitter: number;
+}
+
+export interface ExecutionFault {
+  readonly source: 'bootstrap' | 'handshake' | 'runtime' | 'kernel' | 'world' | 'rebuild';
+  readonly code: string;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: unknown;
+  readonly partialWrite: boolean;
+  readonly retryable: boolean;
+}
+
+export interface ExecutionAudioReport {
+  readonly owner: 'host';
+  readonly contextState: 'running' | 'suspended' | 'closed';
+  readonly activeSourceCount: number;
+  readonly lastError: {
+    readonly code: string;
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: unknown;
+  } | null;
+}
+
+export interface ExecutionReport {
+  readonly schemaVersion: 1;
+  readonly requestedTier: ExecutionRequestedTier;
+  readonly actualTier: ExecutionTier | null;
+  readonly selectionReason: ExecutionSelectionReason | null;
+  readonly sharedEvidencePassed: boolean;
+  readonly capabilities: ExecutionCapabilities;
+  readonly engine: {
+    readonly realm: 'host' | 'worker';
+    readonly health: ExecutionEngineHealth;
+  };
+  readonly world: {
+    readonly identity: string | null;
+    readonly health: ExecutionWorldHealth;
+    readonly partialWrite: boolean;
+    readonly retryable: boolean;
+  };
+  readonly kernelDispatch: {
+    readonly eligible: boolean;
+    readonly usedShared: boolean;
+    readonly reason: KernelDispatchReason;
+    readonly dispatched: number;
+    readonly completed: number;
+  };
+  readonly performance: {
+    readonly hostFrameMs: ExecutionMeasurement | null;
+    readonly engineUpdateMs: ExecutionMeasurement | null;
+    readonly kernelWaitMs: ExecutionMeasurement | null;
+    readonly hostAudioMs: ExecutionMeasurement | null;
+  };
+  readonly audio: ExecutionAudioReport;
+  readonly fault: ExecutionFault | null;
+}
+
+export interface ExecutionOptions {
+  readonly tier?: ExecutionRequestedTier;
+  /** Absolute or import.meta.url-relative URL of an ExecutionBootstrapEntry module. */
+  readonly bootstrap: string | URL;
+  /** Structured-cloneable input supplied identically to main and Worker realms. */
+  readonly bootstrapData?: ExecutionBootstrapValue;
+  /**
+   * Realm side of an optional typed host/game channel. The engine transfers it
+   * to a Worker when needed and otherwise preserves the same port contract.
+   */
+  readonly bootstrapPort?: MessagePort;
+  readonly startupTimeoutMs?: number;
+  readonly frameTimeoutMs?: number;
+}
+
+export type ExecutionBootstrapValue =
+  | null
+  | boolean
+  | number
+  | string
+  | readonly ExecutionBootstrapValue[]
+  | { readonly [key: string]: ExecutionBootstrapValue };
+
+export interface ExecutionControl {
+  report(): ExecutionReport;
+  rebuild(): Promise<Result<ExecutionReport, AppError>>;
+}

package/src/fallback-camera.ts

@@ -0,0 +1,20 @@
+import type { World } from '@forgeax/engine-ecs';
+import { Camera, perspective } from '@forgeax/engine-render';
+import { Transform } from '@forgeax/engine-scene';
+
+/**
+ * Ensure the neutral camera used only by hosts that have no game bootstrap.
+ * An authored scene camera wins; a resolved game owns its camera policy and
+ * must not call this helper.
+ */
+export function ensureFallbackCamera(
+  world: World,
+  aspect = 1,
+): ReturnType<World['spawn']> | undefined {
+  const cameras = world.query({ with: [Camera] }).unwrap();
+  if (!cameras[Symbol.iterator]().next().done) return undefined;
+  return world.spawn(
+    { component: Transform, data: { pos: [0, 0.6, 5] } },
+    { component: Camera, data: perspective({ fov: Math.PI / 3, aspect, far: 1000 }) },
+  );
+}

package/src/game-context.ts

@@ -0,0 +1,126 @@
+// @forgeax/engine-app -- Host service for asset-resident game plugins.
+//
+// App, Preview, and Devkit provide one realm-local GameHost service. Project
+// code default-exports a native Cordis plugin that injects this service and
+// owns all non-ECS teardown through Fiber effects.
+
+import type { AssetRegistry } from '@forgeax/engine-assets-runtime';
+import type { EntityHandle } from '@forgeax/engine-ecs';
+import type { Plugin } from '@forgeax/engine-plugin';
+import type { Renderer } from '@forgeax/engine-render';
+import type { SceneAsset } from '@forgeax/engine-types';
+
+import type { App } from './types';
+
+/** JSON-shaped data a game may intentionally project through a host bridge. */
+export type GameProjectionValue =
+  | null
+  | boolean
+  | number
+  | string
+  | GameProjectionValue[]
+  | { [key: string]: GameProjectionValue };
+
+/** Lightweight, host-agnostic argument schema for a game-owned action. */
+export interface GameActionArgsSchema {
+  readonly type?: 'string' | 'number' | 'boolean' | 'object' | 'array';
+  readonly properties?: Record<string, GameActionArgsSchema>;
+  readonly required?: string[];
+  readonly enum?: GameProjectionValue[];
+  readonly items?: GameActionArgsSchema;
+  readonly nullable?: boolean;
+  readonly description?: string;
+}
+
+/**
+ * A Play-only capability owned by game code. The host may discover and invoke it,
+ * but never supplies its gameplay semantics or reaches into the game World.
+ */
+export interface GameActionDef {
+  readonly id: string;
+  readonly title: string;
+  readonly description?: string;
+  readonly argsSchema?: GameActionArgsSchema;
+  /** Return an optional JSON-shaped result for inspection clients. */
+  readonly run: (
+    args: GameProjectionValue,
+  ) => GameProjectionValue | void | Promise<GameProjectionValue | void>;
+}
+
+/** A named, serializable Play-only read projection owned by game code. */
+export interface GameReadDef {
+  readonly id: string;
+  readonly title: string;
+  readonly description?: string;
+  readonly read: () => GameProjectionValue | Promise<GameProjectionValue>;
+}
+
+/**
+ * Host-provided registration sink for one Play run. Games receive this only while
+ * bootstrapping the fresh transient world; registrations are discarded when the run is disposed.
+ */
+export interface GameProjectionRegistrar {
+  registerAction(def: GameActionDef): () => void;
+  registerRead(def: GameReadDef): () => void;
+}
+
+/** Realm-local Host capability injected into an asset-resident game plugin. */
+export interface GameHost {
+  /** Presentation canvas owned by this Host realm. */
+  readonly canvas: HTMLCanvasElement;
+  /** The WebGPU Renderer (optional — some hosts may not expose it). */
+  readonly renderer?: Renderer;
+  /** The AssetRegistry owned by the App realm. */
+  readonly assets: AssetRegistry;
+  /** The App handle for lifecycle introspection. */
+  readonly app: App;
+  /** Synthetic root entity of the host-instantiated defaultScene. Carries the
+   * SceneInstance component. Absent when the game has no defaultScene. */
+  readonly defaultSceneRoot?: EntityHandle;
+  /** The loaded SceneAsset payload for the defaultScene. Contains the
+   * author-side entity list with Name components. Absent when the game has
+   * no defaultScene. */
+  readonly defaultScene?: SceneAsset;
+  /**
+   * Controlled UI container for this run. Games must mount their DOM UI here
+   * (`(ctx.uiRoot ?? document.body).appendChild(el)`) instead of appending
+   * directly to `document.body`. In the embedded editor viewport the host
+   * removes this whole container when the run is disposed. Absent means game
+   * code falls back to `document.body`.
+   */
+  readonly uiRoot?: HTMLElement;
+  /**
+   * M2 D-3: command-set pointer-lock gate. The game template calls this
+   * when the view mode changes (e.g. `setPointerLockAllowed(mode === 'fps')`
+   * to allow lock in FPS, disallow in top-down). The host wires this to
+   * App.input.setPointerLockAllowed?.() which delegates to the input backend.
+   * Absent → the host does not support pointer-lock gating (e.g. a host
+   * that only runs top-down games).
+   */
+  readonly setPointerLockAllowed?: (allowed: boolean) => void;
+  /**
+   * Optional Play-only projection seam. A game registers its own action and read
+   * capabilities here; the host may only discover/invoke/read those closures. It
+   * is deliberately absent outside a host that can clear registrations on disposal.
+   */
+  readonly gameProjection?: GameProjectionRegistrar;
+}
+
+/**
+ * Provide the Host boundary to a native Cordis game plugin.
+ */
+export function gameHostPlugin(host: GameHost): Plugin {
+  return {
+    name: 'game-host',
+    provide: 'gameHost',
+    apply(ctx) {
+      ctx.provide('gameHost', host);
+    },
+  };
+}
+
+declare module '@forgeax/engine-plugin' {
+  interface EngineContextServices {
+    gameHost?: GameHost;
+  }
+}