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

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

@@ -0,0 +1,84 @@
+import {
+  type AnimationPayloadLookup,
+  animationPayloadsPlugin,
+  animationRuntimePlugin,
+} from '@forgeax/engine-animation';
+import type { DebugDraw } from '@forgeax/engine-debug-draw';
+import {
+  type ActionConfig,
+  type InputBackend,
+  inputBackendPlugin,
+  ownedInputBackendPlugin,
+} from '@forgeax/engine-input';
+import type { Plugin } from '@forgeax/engine-plugin';
+import { renderComponentsPlugin } from '@forgeax/engine-render';
+import { scenePlugin } from '@forgeax/engine-scene';
+import { statePlugin } from '@forgeax/engine-state';
+import { inputMapPlugin } from '../input-map-plugin';
+import { inputPlugin } from '../input-plugin';
+import {
+  ownedRendererPlugin,
+  type RenderFeatureHost,
+  renderFeatureHostPlugin,
+} from '../renderer-plugin';
+import { assetsWorldPlugin, rendererAssetsPlugin } from './assets-world-plugin';
+import { createDebugDrawOnReady, type RendererDebugDrawHost, releaseDebugDraw } from './debug-draw';
+import type { EngineProfileBase } from './engine-profile-common';
+
+export interface MainEngineProfileOptions extends EngineProfileBase {
+  readonly rendererDebugDrawHost?: RendererDebugDrawHost;
+  readonly rendererFeatureHost?: RenderFeatureHost;
+  readonly animationPayloads: AnimationPayloadLookup;
+  readonly onDebugDrawReady?: (debugDraw: DebugDraw) => void;
+  readonly input?: InputBackend;
+  readonly inputDispose?: () => void;
+  readonly inputMap?: readonly ActionConfig[];
+}
+
+function debugDrawPlugin(
+  context: RendererDebugDrawHost,
+  onReady: (debugDraw: DebugDraw) => void,
+): Plugin {
+  return {
+    name: 'debug-draw',
+    async apply(ctx) {
+      try {
+        const debugDraw = await createDebugDrawOnReady(context);
+        onReady(debugDraw);
+        ctx.effect(() => () => releaseDebugDraw(context, debugDraw), 'render/debug-draw');
+      } catch {
+        // DebugDraw is optional; renderer error reporting owns creation failures.
+      }
+    },
+  };
+}
+
+/** Static browser-main selection; dependency order remains owned by inject/provide. */
+export function mainEngineProfile(options: MainEngineProfileOptions): Plugin[] {
+  return [
+    ownedRendererPlugin(options.renderer),
+    renderComponentsPlugin(),
+    ...(options.rendererFeatureHost === undefined
+      ? []
+      : [renderFeatureHostPlugin(options.rendererFeatureHost)]),
+    rendererAssetsPlugin(options.assets),
+    assetsWorldPlugin(),
+    ...(options.input === undefined
+      ? []
+      : [
+          options.inputDispose === undefined
+            ? inputBackendPlugin(options.input)
+            : ownedInputBackendPlugin(options.input, options.inputDispose),
+        ]),
+    scenePlugin(),
+    animationPayloadsPlugin(options.animationPayloads),
+    animationRuntimePlugin(),
+    statePlugin(),
+    ...(options.onDebugDrawReady === undefined || options.rendererDebugDrawHost === undefined
+      ? []
+      : [debugDrawPlugin(options.rendererDebugDrawHost, options.onDebugDrawReady)]),
+    ...(options.input === undefined ? [] : [inputPlugin()]),
+    ...(options.inputMap === undefined ? [] : [inputMapPlugin(options.inputMap)]),
+    ...(options.extensions ?? []),
+  ];
+}

package/src/internal/remote-serve-flag.ts

@@ -0,0 +1,41 @@
+// @forgeax/engine-app/internal/remote-serve-flag -- FORGEAX_ENGINE_REMOTE_SERVE
+// dual-source resolution (plan-strategy secondary D-7).
+//
+// The remote eval server is auto-started in dev mode (vite's import.meta.env.DEV)
+// and production builds skip it. Headless/dawn-node can opt in via the
+// FORGEAX_ENGINE_REMOTE_SERVE=1 env var.
+//
+// Dual sources (mirrors rhi-debug-flag.ts pattern):
+//   browser (vite): import.meta.env.DEV is statically replaced by vite
+//     (true in dev server, false in production build).
+//   dawn-node     : import.meta may be undefined; fallback to
+//     globalThis.process.env.FORGEAX_ENGINE_REMOTE_SERVE === '1'.
+//
+// The SSOT precedence: import.meta.env.DEV wins when available;
+// process.env is the headless opt-in path.
+
+/** Minimal structural view of an env bag carrying the serve flag. */
+interface RemoteServeEnv {
+  readonly FORGEAX_ENGINE_REMOTE_SERVE?: string | undefined;
+}
+
+/**
+ * Resolve whether the remote eval server should be started.
+ *
+ * Returns `true` when:
+ *   - vite dev mode (import.meta.env.DEV === true), OR
+ *   - headless/dawn-node with FORGEAX_ENGINE_REMOTE_SERVE=1 opt-in
+ *
+ * Returns `false` in production builds and headless without explicit opt-in.
+ *
+ * @param isDev flag from import.meta.env.DEV (undefined when import.meta absent)
+ * @param processEnv globalThis.process?.env when present, else undefined
+ */
+export function resolveRemoteServeFlag(
+  isDev: boolean | undefined,
+  processEnv: RemoteServeEnv | undefined,
+): boolean {
+  if (isDev === true) return true;
+  if (processEnv?.FORGEAX_ENGINE_REMOTE_SERVE === '1') return true;
+  return false;
+}

package/src/internal/remote-server-plugin.ts

@@ -0,0 +1,16 @@
+import type { Plugin } from '@forgeax/engine-plugin';
+
+export interface RemoteServerHandle {
+  readonly port: number;
+  close(): Promise<void>;
+}
+
+/** Own a Node remote server with the App Fiber while App still exposes its handle. */
+export function remoteServerPlugin(handle: RemoteServerHandle): Plugin {
+  return {
+    name: 'remote-server',
+    apply(ctx) {
+      ctx.effect(() => async () => handle.close(), 'remote/server');
+    },
+  };
+}

package/src/internal/rhi-capture.ts

@@ -0,0 +1,211 @@
+import type { RhiBackendInstrumentation } from '@forgeax/engine-render/internal/construct-renderer';
+import { RhiError } from '@forgeax/engine-rhi';
+import type {
+  CaptureFrameOptions,
+  EncodedTape,
+  RecorderAttachment,
+  RhiDebugError,
+} from '@forgeax/engine-rhi-debug';
+import { createRhiDebugError } from '@forgeax/engine-rhi-debug';
+import { err, ok, type Result } from '@forgeax/engine-types';
+import type { FrameLoopHandle } from './frame-loop';
+
+export interface RhiTapeArtifactRef {
+  readonly kind: 'rhi-tape';
+  readonly digest: string;
+  readonly bytes: Uint8Array;
+}
+
+export interface RhiCapture {
+  captureFrame(options?: CaptureFrameOptions): Promise<Result<RhiTapeArtifactRef, RhiDebugError>>;
+}
+
+type CaptureResult = Result<EncodedTape, RhiDebugError>;
+type CaptureFrameDriver = Pick<FrameLoopHandle, 'getState' | 'pause' | 'resume' | 'stepFrame'>;
+
+const captureDrivers = new WeakMap<RhiCapture, CaptureFrameDriver>();
+
+export function createRhiCapture(attachment: RecorderAttachment): RhiCapture {
+  let activeCapture: Promise<Result<RhiTapeArtifactRef, RhiDebugError>> | undefined;
+  const capture: RhiCapture = {
+    captureFrame(options) {
+      const driver = captureDrivers.get(capture);
+      if (driver === undefined) return captureAttachment(attachment, options);
+      if (activeCapture !== undefined) {
+        return Promise.resolve(
+          err(
+            createRhiDebugError('capture-busy', {
+              stage: 'capture',
+              cause: 'another App capture transaction is active',
+            }),
+          ),
+        );
+      }
+      const request = captureWithAppFrame(attachment, driver, options);
+      activeCapture = request;
+      void request.then(
+        () => {
+          if (activeCapture === request) activeCapture = undefined;
+        },
+        () => {
+          if (activeCapture === request) activeCapture = undefined;
+        },
+      );
+      return request;
+    },
+  };
+  return capture;
+}
+
+/** Bind the App-owned frame authority to its host capture capability. */
+export function bindRhiCaptureFrameDriver(capture: RhiCapture, driver: CaptureFrameDriver): void {
+  captureDrivers.set(capture, driver);
+}
+
+async function captureAttachment(
+  attachment: RecorderAttachment,
+  options: CaptureFrameOptions | undefined,
+): Promise<Result<RhiTapeArtifactRef, RhiDebugError>> {
+  const result = await attachment.captureFrame(options);
+  if (!result.ok) return result;
+  return ok(toArtifact(result.value));
+}
+
+async function captureWithAppFrame(
+  attachment: RecorderAttachment,
+  driver: CaptureFrameDriver,
+  options: CaptureFrameOptions | undefined,
+): Promise<Result<RhiTapeArtifactRef, RhiDebugError>> {
+  const state = driver.getState();
+  if (state !== 'running' && state !== 'paused') {
+    return err(
+      createRhiDebugError('capture-unavailable', {
+        stage: 'capture',
+        cause: `App capture requires a running or paused frame loop, received '${state}'`,
+      }),
+    );
+  }
+  if (options?.signal?.aborted) return captureAttachment(attachment, options);
+
+  const resumeAfter = state === 'running';
+  if (resumeAfter) {
+    const paused = driver.pause();
+    if (!paused.ok) {
+      return err(
+        createRhiDebugError('capture-unavailable', {
+          stage: 'capture',
+          cause: `App capture could not pause the frame loop: ${describeFailure(paused.error)}`,
+        }),
+      );
+    }
+  }
+
+  const controller = new AbortController();
+  const abortFromUser = (): void => controller.abort();
+  options?.signal?.addEventListener('abort', abortFromUser, { once: true });
+  let captureResult: Promise<CaptureResult>;
+  try {
+    captureResult = attachment.captureFrame({
+      ...(options ?? {}),
+      signal: controller.signal,
+    });
+  } catch (cause: unknown) {
+    options?.signal?.removeEventListener('abort', abortFromUser);
+    if (resumeAfter && driver.getState() === 'paused') driver.resume();
+    return err(
+      createRhiDebugError('capture-unavailable', {
+        stage: 'capture',
+        cause: `App capture could not arm the recorder: ${describeFailure(cause)}`,
+      }),
+    );
+  }
+
+  let result: CaptureResult | undefined;
+  let transactionError: RhiDebugError | undefined;
+  try {
+    const snapshot = await attachment.frameBoundary();
+    if (!snapshot.ok) {
+      result = await captureResult;
+    } else if (options?.signal?.aborted) {
+      controller.abort();
+      result = await captureResult;
+    } else {
+      const stepped = driver.stepFrame(0);
+      if (!stepped.ok) {
+        transactionError = createRhiDebugError('capture-unavailable', {
+          stage: 'capture',
+          cause: `App capture frame failed: ${describeFailure(stepped.error)}`,
+        });
+        controller.abort();
+        result = await captureResult;
+      } else {
+        result = await captureResult;
+      }
+    }
+  } catch (cause: unknown) {
+    transactionError = createRhiDebugError('capture-unavailable', {
+      stage: 'capture',
+      cause: `App capture transaction failed: ${describeFailure(cause)}`,
+    });
+    controller.abort();
+    result = await captureResult;
+  } finally {
+    options?.signal?.removeEventListener('abort', abortFromUser);
+    if (resumeAfter && driver.getState() === 'paused') {
+      const resumed = driver.resume();
+      if (!resumed.ok && transactionError === undefined) {
+        transactionError = createRhiDebugError('capture-unavailable', {
+          stage: 'capture',
+          cause: `App capture could not resume the frame loop: ${describeFailure(resumed.error)}`,
+        });
+      }
+    }
+  }
+
+  if (transactionError !== undefined) return err(transactionError);
+  if (result === undefined) result = await captureResult;
+  if (!result.ok) return result;
+  return ok(toArtifact(result.value));
+}
+
+function describeFailure(cause: unknown): string {
+  if (typeof cause === 'string') return cause;
+  if (cause instanceof Error) return cause.message;
+  if (typeof cause === 'object' && cause !== null && 'hint' in cause) {
+    const hint = (cause as { hint?: unknown }).hint;
+    if (typeof hint === 'string') return hint;
+  }
+  return String(cause);
+}
+
+export function createRhiInstrumentation(
+  attachment: RecorderAttachment,
+): RhiBackendInstrumentation {
+  return {
+    resolveSurfaceDevice(device) {
+      const resolved = attachment.backend.unwrapDeviceForSurface(device);
+      if (resolved.ok) return resolved;
+      return err(
+        new RhiError({
+          code: 'rhi-not-available',
+          expected: 'the recorder can resolve the wrapped surface device',
+          hint: resolved.error.hint,
+        }),
+      );
+    },
+    onFrameBoundary() {
+      void attachment.frameBoundary();
+    },
+    onDeviceLost() {
+      attachment.deviceLost();
+    },
+  };
+}
+
+function toArtifact(encoded: EncodedTape): RhiTapeArtifactRef {
+  return {
+    kind: 'rhi-tape',
+    digest: encoded.digest,
+    bytes: encoded.bytes,
+  };
+}

package/src/internal/rhi-debug-flag.ts

@@ -0,0 +1,40 @@
+// @forgeax/engine-app/internal/rhi-debug-flag -- FORGEAX_ENGINE_RHI_DEBUG
+// three-segment dual-source resolution (plan-strategy D-4).
+//
+// The canvas form reads the flag from two independent sources with a precise
+// precedence + short-circuit shape so the same build serves both deployment
+// targets:
+//
+//   browser (vite): `import.meta.env.FORGEAX_ENGINE_RHI_DEBUG` is statically
+//     replaced by the vite-plugin-rhi-debug `define` hook.
+//   dawn-node     : `import.meta` may be undefined and there is no vite define,
+//     so the flag arrives through `globalThis.process.env`.
+//
+// Extracting the resolution into this pure helper lets it be unit-tested across
+// the three scenarios (browser '1' / dawn-node process.env / unset) without a
+// real bundler or runtime. The call site keeps the literal `typeof import.meta
+// !== 'undefined'` prefix (C5) -- modelled here by passing `undefined` for the
+// `importMetaEnv` argument when `import.meta` is absent.
+
+/** Minimal structural view of an env bag carrying the flag. */
+interface RhiDebugEnv {
+  readonly FORGEAX_ENGINE_RHI_DEBUG?: string | undefined;
+}
+
+/**
+ * Resolve the raw FORGEAX_ENGINE_RHI_DEBUG flag from the two sources.
+ *
+ * Precedence: `import.meta.env` wins; `globalThis.process.env` is the fallback.
+ * Returns the raw string (or undefined); the caller compares `=== '1'`.
+ *
+ * @param importMetaEnv `import.meta.env` when `import.meta` is defined,
+ *   else `undefined` (models the `typeof import.meta !== 'undefined'` prefix
+ *   short-circuiting to a falsy first operand).
+ * @param processEnv `globalThis.process?.env` when present, else `undefined`.
+ */
+export function resolveRhiDebugFlag(
+  importMetaEnv: RhiDebugEnv | undefined,
+  processEnv: RhiDebugEnv | undefined,
+): string | undefined {
+  return importMetaEnv?.FORGEAX_ENGINE_RHI_DEBUG ?? processEnv?.FORGEAX_ENGINE_RHI_DEBUG;
+}

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

@@ -0,0 +1,47 @@
+import {
+  type AnimationPayloadLookup,
+  animationPayloadsPlugin,
+  animationRuntimePlugin,
+} from '@forgeax/engine-animation';
+import { type AudioBackend, audioBackendPlugin } from '@forgeax/engine-audio';
+import { type InputBackend, inputBackendPlugin } from '@forgeax/engine-input';
+import type { Plugin } from '@forgeax/engine-plugin';
+import { renderComponentsPlugin } from '@forgeax/engine-render';
+import { scenePlugin } from '@forgeax/engine-scene';
+import { statePlugin } from '@forgeax/engine-state';
+import { inputPlugin } from '../input-plugin';
+import {
+  ownedRendererPlugin,
+  type RenderFeatureHost,
+  renderFeatureHostPlugin,
+} from '../renderer-plugin';
+import { assetsWorldPlugin, rendererAssetsPlugin } from './assets-world-plugin';
+import type { EngineProfileBase } from './engine-profile-common';
+
+export interface WorkerEngineProfileOptions extends EngineProfileBase {
+  readonly animationPayloads: AnimationPayloadLookup;
+  readonly input: InputBackend;
+  readonly audio: AudioBackend;
+  readonly rendererFeatureHost?: RenderFeatureHost;
+}
+
+/** Static Engine Worker selection; Host-only acquisition stays outside this realm. */
+export function workerEngineProfile(options: WorkerEngineProfileOptions): Plugin[] {
+  return [
+    ownedRendererPlugin(options.renderer),
+    renderComponentsPlugin(),
+    ...(options.rendererFeatureHost === undefined
+      ? []
+      : [renderFeatureHostPlugin(options.rendererFeatureHost)]),
+    rendererAssetsPlugin(options.assets),
+    assetsWorldPlugin(),
+    inputBackendPlugin(options.input),
+    audioBackendPlugin(options.audio),
+    scenePlugin(),
+    animationPayloadsPlugin(options.animationPayloads),
+    animationRuntimePlugin(),
+    statePlugin(),
+    inputPlugin(),
+    ...(options.extensions ?? []),
+  ];
+}

package/src/load-game-errors.ts

@@ -0,0 +1,211 @@
+// @forgeax/engine-app -- LoadGameError class + 3-code closed union +
+// LOAD_GAME_ERROR_HINTS / LOAD_GAME_EXPECTED tables.
+//
+// Isomorphic to AppError in errors.ts: class extends Error + 4-field
+// surface (.code / .expected / .hint / .detail) + discriminated detail
+// per code; the co-located policy-owner proof locks the derived views.
+//
+// Shape:
+//   - LoadGameErrorCode = closed union 3 members (charter P4 closed-union
+//     exhaustive switch needs no default fallback; tsc strict mode guards
+//     completeness; AGENTS.md "Errors are structured").
+//     Members:
+//       - 'module-not-found'
+//       - 'invalid-format'
+//       - 'import-failed'
+//
+//   - LoadGameError class = 4-field surface (.code / .expected / .hint /
+//     .detail) byte-for-byte parallel to AppError. AI users walk .code /
+//     .detail by property access (charter P3 explicit failure: never parse
+//     the message string).
+//
+//   - LoadGameError is exposed as a discriminated union (variant per code)
+//     so AI users get .detail narrowing for free after
+//     `if (err.code === '...')`:
+//
+//       if (err.code === 'module-not-found') {
+//         console.warn('game not found:', err.detail.slug);
+//       }
+//
+//   - LOAD_GAME_ERROR_HINTS / LOAD_GAME_EXPECTED are 3-key Records keyed
+//     by LoadGameErrorCode; the private policy owner below is the single
+//     source for both projections.
+//
+// Related: requirements AC-08 (LoadGameError structured error 3 codes +
+// hint + detail); plan-strategy D-3 (reuse codebase structured error
+// pattern); charter P3 (explicit failure).
+
+/**
+ * Closed LoadGameErrorCode union (3 members).
+ *
+ * | code | trigger |
+ * |:--|:--|
+ * | `'module-not-found'` | resolver throws an error distinguishable as module-not-found (e.g. "Cannot find module"). Detail carries `slug` so AI users can surface which game path failed. |
+ * | `'invalid-format'` | resolver returns a module without a valid native Cordis default export. Detail carries `exportKeys` so AI users can inspect the module shape. |
+ * | `'import-failed'` | resolver throws a generic Error (network error, build error, etc.) not distinguishable as module-not-found. Detail carries the original `cause` Error so AI users can chain narrow. |
+ *
+ * Plan-strategy D-3 locks the count at 3.
+ */
+export type LoadGameErrorCode = keyof typeof loadGameErrorPolicy;
+
+/**
+ * Detail variant for the `'module-not-found'` arm.
+ *
+ * `slug` carries the game identifier that the resolver failed to locate
+ * so AI users can surface exactly which game could not be loaded.
+ */
+export interface LoadGameDetailModuleNotFound {
+  readonly slug: string;
+}
+
+/**
+ * Detail variant for the `'invalid-format'` arm.
+ *
+ * `exportKeys` carries the keys of the module object returned by the
+ * resolver. AI users inspect these to understand why the native default
+ * plugin export was rejected.
+ */
+export interface LoadGameDetailInvalidFormat {
+  readonly exportKeys: string[];
+}
+
+/**
+ * Detail variant for the `'import-failed'` arm.
+ *
+ * `cause` carries the original thrown value verbatim so AI users can
+ * chain narrow (e.g. `cause instanceof TypeError` for network errors)
+ * without losing structure.
+ */
+export interface LoadGameDetailImportFailed {
+  readonly cause: unknown;
+}
+
+/**
+ * Conditional resolver from `LoadGameErrorCode` to its detail payload type.
+ */
+export type LoadGameErrorDetailFor<C extends LoadGameErrorCode> = C extends 'module-not-found'
+  ? LoadGameDetailModuleNotFound
+  : C extends 'invalid-format'
+    ? LoadGameDetailInvalidFormat
+    : LoadGameDetailImportFailed;
+
+/**
+ * Tagged union of `.detail` payloads carried by structured LoadGameError.
+ */
+export type LoadGameErrorDetail = LoadGameErrorDetailFor<LoadGameErrorCode>;
+
+class LoadGameErrorClass extends Error {
+  readonly code: LoadGameErrorCode;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: LoadGameErrorDetail;
+
+  constructor(args: {
+    code: LoadGameErrorCode;
+    expected: string;
+    hint: string;
+    detail: LoadGameErrorDetail;
+  }) {
+    super(`[LoadGameError ${args.code}] expected: ${args.expected}; hint: ${args.hint}`);
+    this.name = 'LoadGameError';
+    this.code = args.code;
+    this.expected = args.expected;
+    this.hint = args.hint;
+    this.detail = args.detail;
+  }
+}
+
+/**
+ * Variant intersection: a `LoadGameErrorClass` instance whose `code` literal
+ * narrows to `C` and whose `detail` narrows to `LoadGameErrorDetailFor<C>`.
+ */
+type LoadGameErrorVariant<C extends LoadGameErrorCode> = LoadGameErrorClass & {
+  readonly code: C;
+  readonly detail: LoadGameErrorDetailFor<C>;
+};
+
+/**
+ * Public LoadGameError type -- discriminated union of the 3 variants.
+ *
+ * AI-user form (charter P3 explicit failure):
+ *
+ * ```ts
+ * function recover(err: LoadGameError): string {
+ *   switch (err.code) {
+ *     case 'module-not-found': return `game not found: ${err.detail.slug}`;
+ *     case 'invalid-format':   return `bad shape, exports: ${err.detail.exportKeys.join(', ')}`;
+ *     case 'import-failed':    return err.detail.cause instanceof Error ? err.detail.cause.message : 'unknown';
+ *   }
+ * }
+ * ```
+ */
+export type LoadGameError = {
+  [C in LoadGameErrorCode]: LoadGameErrorVariant<C>;
+}[LoadGameErrorCode];
+
+interface LoadGameErrorConstructor {
+  new <C extends LoadGameErrorCode>(args: {
+    code: C;
+    expected: string;
+    hint: string;
+    detail: LoadGameErrorDetailFor<C>;
+  }): LoadGameErrorVariant<C>;
+  readonly prototype: LoadGameErrorClass;
+}
+
+/**
+ * LoadGameError constructor -- `new LoadGameError({ code, expected, hint, detail })`.
+ */
+export const LoadGameError: LoadGameErrorConstructor =
+  LoadGameErrorClass as unknown as LoadGameErrorConstructor;
+
+/**
+ * `expected` table -- the engine-side invariant that was violated when each
+ * code surfaces. AI users read this as the L2 detail (charter F2 priority
+ * text); `.hint` carries the recovery action.
+ *
+ * 3 keys; the policy-owner proof locks the exact count, order, and values.
+ */
+type LoadGameErrorPolicy = { readonly expected: string; readonly hint: string };
+
+const loadGameErrorPolicy = {
+  'module-not-found': {
+    expected:
+      'resolver should return a module with a native Cordis default export for the given slug',
+    hint: 'verify the game slug matches an existing template directory; check the resolver import path for typos',
+  },
+  'invalid-format': {
+    expected: 'resolved module must default-export a Cordis function, class, or object plugin',
+    hint: 'default-export one plugin and let the Host mount it into App.pluginContext',
+  },
+  'import-failed': {
+    expected:
+      'resolver should complete without throwing; import path, network, and build errors are forwarded here',
+    hint: 'inspect detail.cause for the original error (network failure, build error, dynamic import timeout, etc.)',
+  },
+} satisfies Record<string, LoadGameErrorPolicy>;
+
+export const LOAD_GAME_EXPECTED: Readonly<Record<LoadGameErrorCode, string>> = Object.fromEntries(
+  Object.entries(loadGameErrorPolicy).map(([code, policy]) => [code, policy.expected]),
+) as Readonly<Record<LoadGameErrorCode, string>>;
+
+/**
+ * `hint` table -- actionable recovery guidance per code (charter P3).
+ *
+ * 3 keys; the policy-owner proof locks the exact count, order, and values.
+ */
+export const LOAD_GAME_ERROR_HINTS: Readonly<Record<LoadGameErrorCode, string>> =
+  Object.fromEntries(
+    Object.entries(loadGameErrorPolicy).map(([code, policy]) => [code, policy.hint]),
+  ) as Readonly<Record<LoadGameErrorCode, string>>;
+
+/**
+ * Type guard for narrowing unknown errors to LoadGameError.
+ *
+ * AI users who catch mixed error types can call `if (isLoadGameError(e))`
+ * before walking `.code`. Uses instanceof against the internal class
+ * (the public constructor delegates to LoadGameErrorClass).
+ */
+export function isLoadGameError(err: unknown): err is LoadGameError {
+  return err instanceof LoadGameErrorClass;
+}