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

package/src/index.ts

@@ -0,0 +1,190 @@
+// @forgeax/engine-app -- public surface (M5: errors.ts complete).
+//
+// AI users:
+//   - One-screen takeoff: `await createApp(canvas)`. Lands in M4 (M1 stub
+//     returns a structured error pointing at the assemble entry).
+//   - Assemble form: `await createApp({ renderer, world, input?, schedule? })`.
+//     M3 ships rAF + frame-loop wired; M4 wires error fan-out + console.error
+//     fallback + canvas-detach guard; M5 ships the AppError class + 5-member
+//     closed AppErrorCode union + APP_ERROR_HINTS / APP_EXPECTED tables.
+//   - loadGame validates the native default Cordis plugin exported by a project.
+//
+// Single import path:
+//   import {
+//     createApp,
+//     loadGame,
+//     AppError, LoadGameError,
+//     APP_ERROR_HINTS, LOAD_GAME_ERROR_HINTS,
+//     APP_EXPECTED, LOAD_GAME_EXPECTED,
+//     isAppError, isLoadGameError,
+//     type App, type GameHost, type Plugin,
+//     type AppAssembleArgs, type CreateAppOptions,
+//     type AppErrorCode, type LoadGameErrorCode,
+//     type AppErrorDetail, type LoadGameErrorDetail,
+//     type AppErrorDetailFor, type LoadGameErrorDetailFor,
+//     type AppDetailCanvasDetached, type AppDetailSystemUpdateFailed,
+//     type LoadGameDetailImportFailed, type LoadGameDetailInvalidFormat,
+//     type LoadGameDetailModuleNotFound, type GamePluginResolver,
+//   } from '@forgeax/engine-app';
+
+export type {
+  Effect,
+  EffectMeta,
+  Fiber,
+  Inject,
+  Plugin,
+} from '@forgeax/engine-plugin';
+export { Context } from '@forgeax/engine-plugin';
+export {
+  createFullscreenRenderFeature,
+  type FullscreenRenderFeatureOptions,
+} from '@forgeax/engine-render/authoring';
+export {
+  type BrowserFrameSubmitted,
+  FORGEAX_FRAME_SUBMITTED_DATASET,
+  FORGEAX_FRAME_SUBMITTED_EVENT,
+  publishBrowserFrameSubmitted,
+  resetBrowserFrameSubmitted,
+} from './browser-frame-signal';
+export { createApp, measureCanvasDrawingBuffer, syncCanvasDrawingBuffer } from './create-app';
+export type {
+  AppDetailCanvasDetached,
+  AppDetailEmpty,
+  AppDetailExecutionBootstrapFailed,
+  AppDetailExecutionDeadlineExceeded,
+  AppDetailExecutionKernelFailed,
+  AppDetailExecutionRebuildFailed,
+  AppDetailExecutionStaleWorld,
+  AppDetailExecutionTierUnavailable,
+  AppDetailPluginActivationFailed,
+  AppDetailSystemUpdateFailed,
+  AppErrorCode,
+  AppErrorDetail,
+  AppErrorDetailFor,
+} from './errors';
+export {
+  APP_ERROR_HINTS,
+  APP_EXPECTED,
+  AppError,
+  isAppError,
+} from './errors';
+export type {
+  ExecutionAssetCatalog,
+  ExecutionBootstrapEntry,
+  ExecutionBootstrapHost,
+  ExecutionBootstrapValue,
+  ExecutionCapabilities,
+  ExecutionCapabilityFact,
+  ExecutionCapabilityName,
+  ExecutionControl,
+  ExecutionEngineHealth,
+  ExecutionFault,
+  ExecutionMeasurement,
+  ExecutionOptions,
+  ExecutionReport,
+  ExecutionRequestedTier,
+  ExecutionSelection,
+  ExecutionSelectionReason,
+  ExecutionTier,
+  ExecutionWorldHealth,
+  KernelDispatchReason,
+  PreparedExecutionBootstrap,
+} from './execution';
+export {
+  createExecutionReport,
+  EXECUTION_CAPABILITY_NAMES,
+  EXECUTION_REPORT_SCHEMA_VERSION,
+  EXECUTION_REQUESTED_TIERS,
+  EXECUTION_TIERS,
+  executionBootstrapHostPlugin,
+  isExecutionReport,
+  loadBootstrapEntry,
+  missingExecutionCapabilities,
+  prepareBootstrapEntry,
+  probeExecutionCapabilities,
+  selectExecutionTier,
+  unavailableExecutionCapabilities,
+  validateExecutionBootstrapData,
+} from './execution';
+export { ensureFallbackCamera } from './fallback-camera';
+export type {
+  GameActionArgsSchema,
+  GameActionDef,
+  GameHost,
+  GameProjectionRegistrar,
+  GameProjectionValue,
+  GameReadDef,
+} from './game-context';
+export { gameHostPlugin } from './game-context';
+export { inputPlugin } from './plugin-factories';
+export type { RenderFeatureHost } from './renderer-plugin';
+export {
+  ownedRendererPlugin,
+  rendererPlugin,
+  renderFeatureHostPlugin,
+  renderFeaturePlugin,
+} from './renderer-plugin';
+
+import {
+  isLoadGameError,
+  LOAD_GAME_ERROR_HINTS,
+  LOAD_GAME_EXPECTED,
+  LoadGameError,
+} from './load-game-errors';
+
+export type { GamePluginResolver } from './load-game';
+export { loadGame } from './load-game';
+export type {
+  LoadGameDetailImportFailed,
+  LoadGameDetailInvalidFormat,
+  LoadGameDetailModuleNotFound,
+  LoadGameErrorCode,
+  LoadGameErrorDetail,
+  LoadGameErrorDetailFor,
+} from './load-game-errors';
+export {
+  createToolPreviewHost,
+  replayToolPreviewCapture,
+  type ToolPreviewCaptureResult,
+  type ToolPreviewHost,
+  type ToolPreviewHostError,
+  type ToolPreviewHostOptions,
+  type ToolPreviewResourceFacts,
+  type ToolPreviewResourceKind,
+  type ToolPreviewResourceRequest,
+  type ToolPreviewRunResult,
+} from './tool-preview/bootstrap';
+export {
+  createToolPreviewEvidence,
+  joinResourcePreviewEvidence,
+  joinToolPreviewEvidence,
+  type ToolPreviewEvidence,
+} from './tool-preview/evidence';
+export {
+  fitToolPreviewCameraToAabb,
+  type ToolPreviewCameraFrame,
+} from './tool-preview/framing';
+export {
+  createToolPreviewRecipe,
+  type ToolPreviewAction,
+  type ToolPreviewPresentation,
+  type ToolPreviewRecipe,
+  type ToolPreviewRecipeOptions,
+  type ToolPreviewTrace,
+  type ToolPreviewTraceEvent,
+  validateToolPreviewTrace,
+} from './tool-preview/recipe';
+export type {
+  App,
+  AppAssembleArgs,
+  AssembleAppError,
+  BundlerOptions,
+  CanvasAppError,
+  CanvasDrawingBufferSize,
+  CreateAppOptions,
+  DrawSource,
+  DrawSourceResult,
+  ExecutionApp,
+} from './types';
+export { APP_PHASE_CATALOG } from './types';
+export { isLoadGameError, LOAD_GAME_ERROR_HINTS, LOAD_GAME_EXPECTED, LoadGameError };

package/src/input-map-plugin.ts

@@ -0,0 +1,21 @@
+import { type ActionConfig, INPUT_MAP_KEY } from '@forgeax/engine-input';
+import type { Plugin } from '@forgeax/engine-plugin';
+
+/** Install the canvas-form action map as an App-owned World contribution. */
+export function inputMapPlugin(configs: readonly ActionConfig[]): Plugin {
+  const deduped = new Map<string, ActionConfig>();
+  for (const config of configs) {
+    if (config.action.length > 0) deduped.set(config.action, config);
+  }
+  const inputMap = Object.freeze([...deduped.values()]);
+  return {
+    name: 'input-map',
+    inject: ['world'],
+    apply(ctx) {
+      ctx.effect(() => {
+        ctx.world.insertResource(INPUT_MAP_KEY, inputMap);
+        return () => ctx.world.removeResource(INPUT_MAP_KEY);
+      }, 'input/action-map');
+    },
+  };
+}

package/src/input-plugin.ts

@@ -0,0 +1,26 @@
+import { Update } from '@forgeax/engine-ecs';
+import { INPUT_BACKEND_KEY, InputFrameStartScan, InputSet } from '@forgeax/engine-input';
+import type { Plugin } from '@forgeax/engine-plugin';
+
+/** Project one Host-owned input provider into reversible World contributions. */
+export function inputPlugin(): Plugin {
+  return {
+    name: 'input',
+    inject: ['world', 'input'],
+    apply(ctx) {
+      const world = ctx.world;
+      const input = ctx.input;
+      if (input === undefined) throw new Error('Cordis activated input without its provider');
+      ctx.effect(() => {
+        world.insertResource(INPUT_BACKEND_KEY, input);
+        return () => {
+          world.removeResource(INPUT_BACKEND_KEY);
+        };
+      }, 'input/resource');
+      ctx.effect(() => {
+        world.addSystems(Update, InputSet, [InputFrameStartScan]).unwrap();
+        return () => world.removeSystem(Update, InputFrameStartScan.name);
+      }, 'input/frame-start-scan');
+    },
+  };
+}

package/src/internal/assembled-engine-profile.ts

@@ -0,0 +1,14 @@
+import type { Plugin } from '@forgeax/engine-plugin';
+import { rendererPlugin } from '../renderer-plugin';
+import { assetsWorldPlugin, rendererAssetsPlugin } from './assets-world-plugin';
+import type { EngineProfileBase } from './engine-profile-common';
+
+/** Assemble-form roots plus explicitly selected host capabilities. */
+export function assembledEngineProfile(options: EngineProfileBase): Plugin[] {
+  return [
+    rendererPlugin(options.renderer),
+    rendererAssetsPlugin(options.assets),
+    assetsWorldPlugin(),
+    ...(options.extensions ?? []),
+  ];
+}

package/src/internal/assets-world-plugin.ts

@@ -0,0 +1,33 @@
+import type { AssetRegistry } from '@forgeax/engine-assets-runtime';
+import type { Plugin } from '@forgeax/engine-plugin';
+
+const ASSET_REGISTRY_RESOURCE_KEY = 'AssetRegistry' as const;
+
+/** Project the Renderer-owned AssetRegistry as a declared dependent service. */
+export function rendererAssetsPlugin(assets: AssetRegistry | undefined): Plugin {
+  return {
+    name: 'renderer-assets',
+    inject: ['renderer'],
+    provide: 'assets',
+    apply(ctx) {
+      if (assets !== undefined) ctx.provide('assets', assets);
+    },
+  };
+}
+
+/** Project the realm AssetRegistry into legacy World resource lookup reversibly. */
+export function assetsWorldPlugin(): Plugin {
+  return {
+    name: 'assets-world',
+    inject: ['world', 'assets'],
+    apply(ctx) {
+      if (ctx.assets === undefined) return;
+      ctx.effect(() => {
+        ctx.world.insertResource(ASSET_REGISTRY_RESOURCE_KEY, ctx.assets);
+        return () => {
+          ctx.world.removeResource(ASSET_REGISTRY_RESOURCE_KEY);
+        };
+      }, 'assets/world-resource');
+    },
+  };
+}

package/src/internal/browser-remote-bridge.ts

@@ -0,0 +1,269 @@
+// @forgeax/engine-app/internal/browser-remote-bridge — DEV-only page-side bridge
+// that makes a live BROWSER engine drivable over a loopback relay.
+//
+// WHY: @forgeax/engine-remote's only external transport is a Node WebSocket
+// server (packages/remote/src/server.ts). A browser page cannot bind a listening
+// socket, so createApp's startServer attempt throws on ws's browser shim and
+// app.remote stays undefined — the running engine is unreachable in a real
+// `pnpm --filter <app> dev` browser. But a page CAN dial OUT. So we open a
+// WebSocket CLIENT to the loopback relay
+// (skills/forgeax-engine-cli/scripts/remote-bridge-server.mjs) and run
+// @forgeax/engine-remote/execute (the ws-free eval core) in the page realm
+// against the live world/renderer/assets/rhiCapture. A CLI POSTs to the relay;
+// the relay forwards to us; we eval and reply. This is the engine-side mirror of
+// the editor's ViewportComponent DEV bridge.
+//
+// This module is reached only via a DEV-gated dynamic import from create-app.ts,
+// so production (import.meta.env.DEV === false) never bundles it (tree-shake /
+// zero-injection). It carries NO static top-level @forgeax/engine-remote
+// dependency — the eval core is pulled by a further dynamic import, keeping
+// @forgeax/engine-app free of a runtime dep on @forgeax/engine-remote (same
+// discipline as the createApp startServer path). The import is deliberately
+// left visible to Vite: the SDK host aliases the focused package to its exact
+// installed path, while @vite-ignore would make a browser resolve the bare
+// specifier from the consumer document root and yield a 500.
+
+import { Update, type World } from '@forgeax/engine-ecs';
+import { createEcsImportModule } from './ecs-import';
+
+type ExecuteResult = { ok: true; value: unknown } | { ok: false; error: unknown };
+
+type ExecuteModule = {
+  executeScript: (
+    script: string,
+    ctx: {
+      world: unknown;
+      renderer: unknown;
+      assets: unknown;
+      rhiCapture?: unknown;
+      profiler?: unknown;
+      execution?: unknown;
+      importModule?: (specifier: string) => Promise<unknown>;
+    },
+  ) => Promise<ExecuteResult>;
+};
+
+type ComponentLike = { readonly name: string };
+
+/**
+ * Project component exports onto the tokens already stored by this World.
+ *
+ * WHY: Vite may evaluate a workspace package once through the host package's
+ * dist graph and once through a source graph. Component ids are process-local,
+ * so equal `{ name, schema }` objects are not interchangeable with World
+ * access. The bridge is the one place that can reconcile the public module
+ * recipe with the live World's archetype SSOT.
+ */
+function canonicalRuntimeModule(moduleValue: unknown, world: World): unknown {
+  if (moduleValue === null || typeof moduleValue !== 'object') return moduleValue;
+  const componentsByName = new Map<string, ComponentLike>();
+  for (const [name, component] of world.components.entries()) {
+    if (!componentsByName.has(name)) componentsByName.set(name, component);
+  }
+  const projected: Record<string, unknown> = { ...(moduleValue as Record<string, unknown>) };
+  for (const [key, value] of Object.entries(projected)) {
+    if (value === null || typeof value !== 'object' || !('name' in value)) continue;
+    const canonical = componentsByName.get((value as ComponentLike).name);
+    if (canonical !== undefined) projected[key] = canonical;
+  }
+  return projected;
+}
+
+export interface BrowserRemoteBridgeDeps {
+  readonly world: World;
+  readonly renderer: unknown;
+  readonly assets: unknown;
+  /** The host's already-loaded runtime namespace; preserves component-token identity. */
+  readonly runtimeModule: unknown;
+  readonly rhiCapture?: unknown;
+  /** The host's explicit CPU profiler capability, when opted in. */
+  readonly profiler?: unknown;
+  readonly execution?: unknown;
+  /** Relay port. */
+  readonly port: string;
+}
+
+/** Serialize a RemoteError-shaped object (or any thrown value) into a JSON-safe
+ *  {code, expected, hint, detail?} envelope. AI users branch on error.code by
+ *  property access, so the four structured fields must survive the wire. */
+function serializeError(error: unknown): Record<string, unknown> {
+  if (error !== null && typeof error === 'object') {
+    const e = error as {
+      code?: unknown;
+      expected?: unknown;
+      hint?: unknown;
+      detail?: unknown;
+      message?: unknown;
+    };
+    const out: Record<string, unknown> = {
+      code: typeof e.code === 'string' ? e.code : 'script-runtime-error',
+    };
+    if (typeof e.expected === 'string') out.expected = e.expected;
+    if (typeof e.hint === 'string') out.hint = e.hint;
+    if (e.detail !== undefined) out.detail = e.detail;
+    if (out.hint === undefined && typeof e.message === 'string') out.hint = e.message;
+    return out;
+  }
+  return { code: 'script-runtime-error', hint: String(error) };
+}
+
+/**
+ * Install the DEV-only browser remote bridge. Idempotent per call site; the
+ * caller gates on import.meta.env.DEV so this never runs in production.
+ *
+ * Returns a teardown function that stops reconnection and closes the socket —
+ * the caller wires it to import.meta.hot.dispose so a vite HMR of the host app
+ * does not stack duplicate bridges.
+ */
+export async function installBrowserRemoteBridge(
+  deps: BrowserRemoteBridgeDeps,
+): Promise<() => void> {
+  const { world, renderer, assets, rhiCapture, profiler, execution, port } = deps;
+
+  // The ws-free eval core. Dynamic import keeps @forgeax/engine-app free of a
+  // static @forgeax/engine-remote dependency while allowing the consumer's
+  // Vite config to resolve the focused package through its SDK alias.
+  const mod = (await import('@forgeax/engine-remote/execute')) as ExecuteModule;
+  const executeScript = mod.executeScript;
+  const importModule = createEcsImportModule((specifier: string): Promise<unknown> => {
+    // The host app and the bridge must share the same component-token objects.
+    // Vite can otherwise serve `/@id/@forgeax/engine-runtime` as a second
+    // module graph entry, so `world.get(entity, Transform)` sees a different
+    // Component id even though the token has the same name and schema.
+    if (specifier === '@forgeax/engine-runtime')
+      return Promise.resolve(canonicalRuntimeModule(deps.runtimeModule, world));
+    const browserSpecifier = specifier.startsWith('@') ? `/@id/${specifier}` : specifier;
+    return import(/* @vite-ignore */ browserSpecifier).then((moduleValue) =>
+      canonicalRuntimeModule(moduleValue, world),
+    );
+  });
+
+  let ws: WebSocket | null = null;
+  let backoff = 1000;
+  let stopped = false;
+
+  // Frame-start eval queue: a WebSocket `message` fires at an arbitrary phase of
+  // the rAF tick, so running eval inline would land world writes at an
+  // unpredictable phase. Enqueue instead and drain from Update system (frame
+  // start) so every bridge write passes through this frame's systems.
+  const evalQueue: Array<{ id: number; code: string }> = [];
+
+  const drainEvalQueue = (): void => {
+    if (evalQueue.length === 0) return;
+    // Snapshot + clear so an eval that enqueues runs next frame, not in an
+    // unbounded same-frame loop.
+    const jobs = evalQueue.splice(0, evalQueue.length);
+    for (const job of jobs) {
+      const reply = (payload: unknown): void => {
+        // Reply on the CURRENT socket (it may have reconnected since enqueue).
+        // The relay keys replies by request id, so the live socket resolves it.
+        try {
+          ws?.send(JSON.stringify({ type: 'result', id: job.id, payload }));
+        } catch {
+          /* socket gone; relay times the request out */
+        }
+      };
+      void (async () => {
+        let res: ExecuteResult;
+        try {
+          res = await executeScript(job.code, {
+            world,
+            renderer,
+            assets,
+            rhiCapture,
+            profiler: profiler,
+            execution,
+            importModule,
+          });
+        } catch (e) {
+          reply({
+            ok: false,
+            error: { code: 'BRIDGE_EVAL_THREW', hint: String((e as Error)?.message ?? e) },
+          });
+          return;
+        }
+        const envelope = res.ok
+          ? { ok: true as const, value: res.value }
+          : { ok: false as const, error: serializeError(res.error) };
+        // JSON-guard: non-serializable values (opaque engine handles, cycles)
+        // degrade to a marker so one bad field never wedges the channel.
+        try {
+          JSON.stringify(envelope);
+          reply(envelope);
+        } catch {
+          reply({ ok: true, value: '[unserializable value — inspect in the live window]' });
+        }
+      })();
+    }
+  };
+  world
+    .addSystem(Update, {
+      name: 'browser-remote-bridge-drain-eval-queue',
+      queries: [],
+      fn: drainEvalQueue,
+    })
+    .unwrap();
+
+  const connect = (): void => {
+    if (stopped) return;
+    try {
+      ws = new WebSocket(`ws://127.0.0.1:${port}/bridge`);
+    } catch {
+      return;
+    }
+    ws.addEventListener('open', () => {
+      backoff = 1000;
+    });
+    ws.addEventListener('message', (ev: MessageEvent) => {
+      let msg: { type?: string; id?: number; code?: string };
+      try {
+        msg = JSON.parse(typeof ev.data === 'string' ? ev.data : '');
+      } catch {
+        return;
+      }
+      if (msg?.type !== 'eval' || typeof msg.id !== 'number' || typeof msg.code !== 'string')
+        return;
+      evalQueue.push({ id: msg.id, code: msg.code });
+    });
+    const retry = (): void => {
+      ws = null;
+      if (stopped) return;
+      setTimeout(connect, backoff);
+      backoff = Math.min(backoff * 2, 15000);
+    };
+    ws.addEventListener('close', retry);
+    ws.addEventListener('error', () => {
+      try {
+        ws?.close();
+      } catch {
+        /* */
+      }
+    });
+  };
+  connect();
+
+  const teardown = (): void => {
+    if (stopped) return;
+    stopped = true;
+    world.removeSystem(Update, 'browser-remote-bridge-drain-eval-queue');
+    const s = ws;
+    ws = null;
+    if (s) {
+      try {
+        s.onclose = null;
+        s.close();
+      } catch {
+        /* */
+      }
+    }
+  };
+
+  // Self-register HMR teardown so a vite HMR of the host app does not stack
+  // duplicate bridges. Kept here (not in create-app.ts) so create-app.ts carries
+  // no import.meta.hot reference — the rhi-debug guard gate requires every
+  // import.meta.hot there to sit inside the FORGEAX_ENGINE_RHI_DEBUG block.
+  const hot = (import.meta as { hot?: { dispose(cb: () => void): void } }).hot;
+  if (hot) hot.dispose(teardown);
+
+  return teardown;
+}

package/src/internal/browser-rhi-debug-runtime.ts

@@ -0,0 +1,67 @@
+import type { Renderer } from '@forgeax/engine-render';
+import type { RhiDevice, RhiInstance } from '@forgeax/engine-rhi';
+import type {
+  CreateShaderModuleFn,
+  RecordableBackend,
+  RecorderAttachment,
+} from '@forgeax/engine-rhi-debug';
+import { attachRecorder } from '@forgeax/engine-rhi-debug';
+import { createRhiInstrumentation } from './rhi-capture';
+
+export interface BrowserRhiDebugRuntime {
+  readonly rhi: RhiInstance;
+  readonly attachment: RecorderAttachment;
+  readonly createReplayDevice: () => Promise<
+    import('@forgeax/engine-types').Result<RhiDevice, unknown>
+  >;
+  readonly createShaderModule: CreateShaderModuleFn;
+  readonly rhiInstrumentation: import('@forgeax/engine-render/internal/construct-renderer').RhiBackendInstrumentation;
+  attachRenderer(renderer: Renderer): () => void;
+}
+
+interface BackendModule extends RecordableBackend {
+  readonly ensureReady?: () => Promise<unknown>;
+}
+
+function hasWebGpu(): boolean {
+  const nav = (globalThis as { navigator?: { gpu?: unknown } }).navigator;
+  return nav?.gpu !== undefined;
+}
+
+async function loadBackend(): Promise<BackendModule> {
+  const backend = (hasWebGpu()
+    ? await import('@forgeax/engine-rhi-webgpu')
+    : await import('@forgeax/engine-rhi-wgpu')) as unknown as BackendModule;
+  if (!hasWebGpu()) await backend.ensureReady?.();
+  return backend;
+}
+
+/**
+ * Assemble the browser preview's recorder at the Runtime seam. The preview
+ * host owns the attachment and consumes only the encoded tape; it does not
+ * reach into recorder state or reintroduce the removed DebugRhi facade.
+ */
+export async function createBrowserRhiDebugRuntime(): Promise<BrowserRhiDebugRuntime> {
+  const backend = await loadBackend();
+  const attached = attachRecorder(backend);
+  if (!attached.ok) throw new Error(attached.error.hint);
+  const attachment = attached.value;
+  return {
+    rhi: attachment.backend.rhi,
+    attachment,
+    createShaderModule: backend.createShaderModule,
+    rhiInstrumentation: createRhiInstrumentation(attachment),
+    createReplayDevice: async () => {
+      const adapter = await backend.rhi.requestAdapter();
+      if (!adapter.ok) return adapter;
+      return adapter.value.requestDevice();
+    },
+    attachRenderer(_renderer: Renderer): () => void {
+      // Frame boundaries and device loss are connected by the typed
+      // rhiInstrumentation passed to createApp. This hook remains a no-op so
+      // the Preview host keeps an explicit lifecycle slot without subscribing
+      // a second boundary callback.
+      return () => {};
+    },
+  };
+}