@vgai/engine 0.2.0

package/src/input/schema.ts

@@ -0,0 +1,129 @@
+// T4.6 — the `.inputmap.json` schema.
+//
+// Was TS-types-only (`input-types.ts`) until T4.6 authored this Zod schema —
+// see docs/BACKBONE-TASKS.md T4.6. `InputManager.loadMap` (input-manager.ts)
+// is this schema's runtime reader: it parses via this schema, then copies
+// each action's `bindings` array straight into `this.actions`.
+//
+// Every field has a `.describe()` (repo policy — powers
+// `scripts/generate-schema.ts` and the T4.1/T4.6 schema-walk coverage test).
+// No runtime dependency beyond `zod`, matching the `scene/schema/` and
+// `manifest/schema.ts` precedent.
+//
+// T4.1 inheritance: `input-manager.ts`'s `isPressed`/`isJustPressed`/
+// `isJustReleased` switch on `binding.type` and only ever handle `key`,
+// `mouse_button`, `gamepad_button`, and `gamepad_axis` — `mouse_move` and
+// `gamepad_axis_pair` are authored-but-unhandled binding kinds (mouse look is
+// read via a free-standing `mouseDelta`/`lookStick` accumulator that no
+// binding gates, and there is no code path that reads `xAxis`/`yAxis` as a
+// pair). Authoring either kind is a confirmed dead stub — REJECTED at parse,
+// mirroring the `scene/schema/ui.ts` dead-field mechanism (a `.superRefine`
+// that throws naming the field).
+
+import { z } from 'zod';
+import type { InputAction, InputBinding, InputMapFile } from './input-types';
+
+const KeyBindingSchema = z.object({
+  type: z.literal('key').describe('Binding kind: a keyboard key (KeyboardEvent.code)'),
+  code: z.string().describe('KeyboardEvent.code value, e.g. "KeyW", "Space", "ArrowUp"'),
+});
+
+const MouseButtonBindingSchema = z.object({
+  type: z.literal('mouse_button').describe('Binding kind: a mouse button'),
+  button: z.number().describe('MouseEvent.button index (0 = left, 1 = middle, 2 = right)'),
+});
+
+const MouseMoveBindingSchema = z.object({
+  type: z
+    .literal('mouse_move')
+    .describe(
+      'Binding kind: raw mouse movement. REJECTED at parse (T4.1/T4.6): declared but has no ' +
+        'runtime reader — authoring this binding throws. Do not author.',
+    ),
+});
+
+const GamepadButtonBindingSchema = z.object({
+  type: z.literal('gamepad_button').describe('Binding kind: a gamepad face/shoulder button'),
+  button: z.number().describe('Standard Gamepad API button index'),
+});
+
+const GamepadAxisBindingSchema = z.object({
+  type: z.literal('gamepad_axis').describe('Binding kind: a single thresholded gamepad axis'),
+  axis: z.number().describe('Standard Gamepad API axis index'),
+  direction: z
+    .enum(['positive', 'negative'])
+    .describe('Which side of the deadzone counts as "pressed"'),
+  deadzone: z.number().optional().describe('Deadzone magnitude (default 0.15 if omitted)'),
+});
+
+const GamepadAxisPairBindingSchema = z.object({
+  type: z
+    .literal('gamepad_axis_pair')
+    .describe(
+      'Binding kind: a coupled (x, y) gamepad axis pair, e.g. a stick used as a 2D vector ' +
+        '(look/aim). REJECTED at parse (T4.1/T4.6): declared but has no runtime reader — only ' +
+        '`gamepad_axis` (a single thresholded axis) is handled by isPressed/isJustPressed/' +
+        'isJustReleased. Authoring this binding throws. Do not author.',
+    ),
+  xAxis: z.number().describe('Standard Gamepad API axis index for the X component'),
+  yAxis: z.number().describe('Standard Gamepad API axis index for the Y component'),
+  deadzone: z.number().optional().describe('Deadzone magnitude (default 0.15 if omitted)'),
+});
+
+/**
+ * A single input binding. `mouse_move`/`gamepad_axis_pair` are dead-by-decision
+ * (see the per-variant `.describe()` above) — the `.superRefine` below is the
+ * actual enforcement, mirroring `scene/schema/ui.ts`'s dead-field mechanism.
+ */
+export const InputBindingSchema: z.ZodType<InputBinding> = z
+  .discriminatedUnion('type', [
+    KeyBindingSchema,
+    MouseButtonBindingSchema,
+    MouseMoveBindingSchema,
+    GamepadButtonBindingSchema,
+    GamepadAxisBindingSchema,
+    GamepadAxisPairBindingSchema,
+  ])
+  .superRefine((binding, ctx) => {
+    if (binding.type === 'mouse_move') {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message:
+          '`mouse_move` binding kind is authored but not implemented — InputManager.isPressed/' +
+          'isJustPressed/isJustReleased never handle it (mouse look is read via a free-standing ' +
+          'mouseDelta/lookStick accumulator, not gated by any action binding). See T4.1/T4.6.',
+        path: ['type'],
+      });
+    }
+    if (binding.type === 'gamepad_axis_pair') {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message:
+          '`gamepad_axis_pair` binding kind is authored but not implemented — no reader consumes ' +
+          '`xAxis`/`yAxis` as a coupled pair (only `gamepad_axis`, a single thresholded axis, is ' +
+          'handled by isPressed/isJustPressed/isJustReleased). See T4.1/T4.6.',
+        path: ['type'],
+      });
+    }
+  }) as z.ZodType<InputBinding>;
+
+/** An action has a name (the record key) and one or more bindings. */
+export const InputActionSchema: z.ZodType<InputAction> = z.object({
+  bindings: z
+    .array(InputBindingSchema)
+    .describe('Bindings that all trigger this action (any one firing is enough)'),
+});
+
+/**
+ * The `.inputmap.json` file format (`InputManager.loadMap`).
+ *
+ * `version` is RESERVED (no range-check reader exists yet for this format —
+ * same convention `2d.version`/`Scene2DSchema` used before T2.3 gave the 3D
+ * scene version axis a real reader; see `schema-consumption-map.ts`).
+ */
+export const InputMapFileSchema: z.ZodType<InputMapFile> = z.object({
+  version: z.number().describe('Input map file format version (RESERVED — no range check yet)'),
+  actions: z
+    .record(z.string(), InputActionSchema)
+    .describe('Named actions, each with a list of bindings (InputManager.loadMap)'),
+}) as z.ZodType<InputMapFile>;

package/src/loader.ts

@@ -0,0 +1,70 @@
+/**
+ * Shared asset loading infrastructure.
+ *
+ * Provides a single LoadingManager (for Three.js loaders) and resolveUrl()
+ * (for raw fetch calls) so that all engine asset requests go through one
+ * configurable URL prefix. Call setAssetPrefix() once at runtime startup.
+ *
+ * Three.js loaders constructed with `loadingManager` automatically rewrite
+ * URLs via setURLModifier(). For raw fetch() calls, wrap the URL with
+ * resolveUrl() to apply the same prefix.
+ */
+
+import * as THREE from 'three';
+import { DRACOLoader } from 'three/addons/loaders/DRACOLoader.js';
+import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
+
+let _prefix = '/';
+
+function rewriteUrl(url: string): string {
+  if (
+    url.startsWith('/') ||
+    url.startsWith('http') ||
+    url.startsWith('data:') ||
+    url.startsWith('blob:')
+  ) {
+    return url;
+  }
+  return _prefix + url;
+}
+
+/** Shared Three.js LoadingManager — all engine loaders should use this. */
+export const loadingManager = new THREE.LoadingManager();
+loadingManager.setURLModifier(rewriteUrl);
+
+/** Pre-configured TextureLoader using the shared manager. */
+export const textureLoader = new THREE.TextureLoader(loadingManager);
+
+/**
+ * Shared DRACOLoader for decoding DRACO-compressed GLTF/GLB meshes.
+ *
+ * The decoder wasm/js is vendored under
+ * packages/editor/template/public/jsm/libs/draco/gltf/ and served at the
+ * absolute runtime path '/jsm/libs/draco/gltf/' (DRACOLoader appends
+ * draco_wasm_wrapper.js / draco_decoder.wasm to this path). This is an
+ * absolute path, so it deliberately does NOT go through the asset prefix —
+ * the decoder is engine infrastructure, not a scene asset.
+ */
+export const dracoLoader = new DRACOLoader(loadingManager);
+dracoLoader.setDecoderPath('/jsm/libs/draco/gltf/');
+
+/** Pre-configured GLTFLoader using the shared manager, with DRACO decoding wired in. */
+export const gltfLoader = new GLTFLoader(loadingManager);
+gltfLoader.setDRACOLoader(dracoLoader);
+
+/**
+ * Set the URL prefix prepended to relative asset paths.
+ * Called once by createGameRuntime(). Defaults to '/'.
+ */
+export function setAssetPrefix(prefix: string): void {
+  _prefix = prefix.endsWith('/') ? prefix : prefix ? `${prefix}/` : '/';
+}
+
+/**
+ * Resolve a relative asset URL using the current prefix.
+ * Use this for raw fetch() calls — Three.js loaders using
+ * `loadingManager` handle this automatically.
+ */
+export function resolveUrl(url: string): string {
+  return rewriteUrl(url);
+}

package/src/manifest/index.ts

@@ -0,0 +1,24 @@
+// Game manifest (vgai.game.json) — schema + loader (T3.1 slice 1).
+// See docs/GAME-MANIFEST-DESIGN.md.
+
+export type { ResolvedAdapter, ResolvedGameManifest, ResolvedWorldEntry } from './load';
+export { CAPABILITY_CEILINGS, DEFAULT_SERVER_MODULE, loadGameManifest } from './load';
+export type {
+  GameManifest,
+  IngestStrategy,
+  Tier,
+  WorldAdapter,
+  WorldEntry,
+} from './schema';
+export {
+  GameManifestSchema,
+  IngestStrategySchema,
+  TierSchema,
+  WorldAdapterSchema,
+  WorldEntrySchema,
+} from './schema';
+
+// `loadGameManifestFile` (Node-only, reads `path` via `node:fs`) is
+// deliberately NOT re-exported here — this barrel must stay import-safe for
+// browser bundles. Import it directly from `@engine/manifest/load-file` in
+// Node-only contexts (CLI, tests).

package/src/manifest/load-file.ts

@@ -0,0 +1,16 @@
+// T3.1 slice 1 — Node-only path wrapper around `loadGameManifest` (§5).
+//
+// Kept in its own module (rather than folded into `load.ts`) so that
+// `loadGameManifest` itself stays free of `node:fs` — anything that only
+// needs the pure parse/resolve function (e.g. a future browser/hosted-editor
+// caller) can import `./load` without pulling a Node-only module into its
+// bundle.
+
+import { readFileSync } from 'node:fs';
+import { loadGameManifest, type ResolvedGameManifest } from './load';
+
+/** Read + JSON.parse `path`, then resolve it via `loadGameManifest`. Node-only. */
+export function loadGameManifestFile(path: string): ResolvedGameManifest {
+  const raw: unknown = JSON.parse(readFileSync(path, 'utf-8'));
+  return loadGameManifest(raw);
+}

package/src/manifest/load.ts

@@ -0,0 +1,378 @@
+// T3.1 slice 1 — the game manifest loader/validator (docs/GAME-MANIFEST-DESIGN.md §5).
+//
+// Pure data-in/data-out: `loadGameManifest(raw)` parses `raw` against
+// `GameManifestSchema`, runs the cross-field checks §3 promises beyond what
+// Zod alone can express, resolves every optional/derivable field, and
+// returns a `ResolvedGameManifest` with nothing left implicit. This is the
+// schema's runtime reader (T4.1 policy) — every described field in
+// `schema.ts` either drives a check here or is carried into the resolved
+// output explicitly (see the per-field comments below and
+// `packages/engine/test/schema-consumption-map.ts`'s `manifest.*` entries).
+//
+// No `fs` import here on purpose — `load-file.ts` is the thin Node-only
+// wrapper that reads a path and calls this function, so browser bundles that
+// only need `loadGameManifest` never pull in `node:fs`.
+
+import {
+  type GameManifest,
+  GameManifestSchema,
+  type IngestStrategy,
+  type Tier,
+  type WorldAdapter,
+  type WorldEntry,
+} from './schema';
+
+// ---------------------------------------------------------------------------
+// Resolved shapes
+// ---------------------------------------------------------------------------
+
+/** D6's resolved adapter identities. */
+export type ResolvedAdapter =
+  | {
+      readonly type: 'default';
+      readonly identity: 'default-three' | 'default-pixi' | 'default-react';
+    }
+  | { readonly type: 'module'; readonly identity: 'module'; readonly module: string }
+  | {
+      readonly type: 'ingest';
+      // 'ingest-react' (Track N, N1 — docs/REACT-INGEST-LANDING-DESIGN.md
+      // D-N2) is assigned here purely structurally (kind === 'react'), same
+      // as 'ingest-three'/'ingest-pixi': this loader stays strategy-agnostic
+      // at resolve time, exactly like the other two ingest identities
+      // (`ceilingFor`/`resolveCapabilities` below already derive tiers per
+      // `strategy` regardless of `kind`). The v1 "deduped rung only" rule
+      // (D-N3) is enforced editor-side, at the resolver
+      // (`packages/editor/src/adapter-resolver.ts`'s `resolveIngestReactAdapter`)
+      // — not here — mirroring how THIS file never rejects
+      // `ingest-three`/`ingest-pixi`'s `iframe-reachable`/`opaque-embed`
+      // strategies either; `resolveIngestDescriptor`/`resolveIngest2DDescriptor`
+      // are where "not yet buildable" strategies throw.
+      readonly identity: 'ingest-three' | 'ingest-pixi' | 'ingest-react';
+      readonly strategy: IngestStrategy;
+      readonly entryHtml: string | undefined;
+      readonly assets: Record<string, string> | undefined;
+      readonly domStubs: string[] | undefined;
+      readonly captureTimeoutMs: number | undefined;
+      /** Track P (docs/PIXI-INGEST-LANDING-DESIGN.md §2) — iframe-reachable-multi mount fields. */
+      readonly bundleUrl: string | undefined;
+      readonly baseHref: string | undefined;
+      readonly assetBaseUrl: string | undefined;
+      readonly extraDeps: string[] | undefined;
+      readonly pixiModuleUrl: string | undefined;
+      readonly bodyHtml: string | undefined;
+    };
+
+export interface ResolvedWorldEntry {
+  readonly id: string;
+  readonly kind: WorldEntry['kind'];
+  readonly description: string | undefined;
+  readonly adapter: ResolvedAdapter;
+  readonly scene: string | undefined;
+  readonly entry: string | undefined;
+  readonly zOrder: number;
+  readonly pausable: boolean;
+  readonly loop: 'gated' | 'self-driven';
+  /** Every optional resolved: both contexts always present (§4/§5). */
+  readonly capabilities: { readonly local: Tier; readonly hosted: Tier };
+}
+
+export interface ResolvedGameManifest {
+  readonly manifestVersion: 1;
+  readonly name: string;
+  readonly version: string;
+  readonly engine: { readonly version: string };
+  /** Sorted by zOrder; ties broken by original array order (§3). */
+  readonly worlds: readonly ResolvedWorldEntry[];
+  readonly server: { readonly room: string; readonly module: string } | undefined;
+  readonly resolution: { readonly width: number; readonly height: number } | undefined;
+}
+
+// ---------------------------------------------------------------------------
+// §4 — the per-context ceiling table (named + exported: the tier-table doc
+// test in slice 2 pins docs/CAPABILITY-TIERS.md's rows against this).
+// ---------------------------------------------------------------------------
+
+/**
+ * Ceiling (maximum legal declared `Tier`) per adapter type and delivery
+ * context. `default` worlds are always first-party in both contexts (D6/§2 —
+ * a first-party world is fully vgai-native everywhere). `ingest` worlds are
+ * ceilinged by their own capture `strategy`: locally the local CLI's Vite
+ * pipeline gives bundler dedupe, so every strategy reaches its own natural
+ * rung; hosted has no bundler (esbuild-wasm + externals only), and a
+ * `deduped` world is DEFINED by being source built through our pipeline — no
+ * prebuilt bundle exists to fall back to an iframe rung, and nothing
+ * implements a hosted build for it, so hosted is `unsupported` (honesty over
+ * optimism; if the hosted esbuild-wasm path ever proves capable, raising
+ * this ceiling is a non-breaking widening). `shared`/`iframe-reachable`/
+ * `opaque-embed` don't depend on a bundler either way, so they carry through
+ * unchanged. `module` adapters have no derivable ceiling ("a custom
+ * adapter's reach is not derivable", §4) — modeled here as `first-party`
+ * (the top rank), i.e. no ceiling actually constrains a module adapter's
+ * declared tier; the loader instead requires the tier to be declared
+ * explicitly for module worlds (see `resolveCapabilities`), since there is no
+ * default to derive.
+ */
+export const CAPABILITY_CEILINGS = {
+  default: { local: 'first-party', hosted: 'first-party' },
+  ingest: {
+    shared: { local: 'shared', hosted: 'shared' },
+    deduped: { local: 'deduped', hosted: 'unsupported' },
+    'iframe-reachable': { local: 'iframe-reachable', hosted: 'iframe-reachable' },
+    'opaque-embed': { local: 'opaque-embed', hosted: 'opaque-embed' },
+  },
+  module: { local: 'first-party', hosted: 'first-party' },
+} as const satisfies Record<
+  string,
+  { local: Tier; hosted: Tier } | Record<IngestStrategy, { local: Tier; hosted: Tier }>
+>;
+
+/** Total order over `Tier` (§4: `first-party > shared ≈ deduped > iframe-reachable > opaque-embed > unsupported`). */
+const TIER_RANK: Record<Tier, number> = {
+  'first-party': 5,
+  shared: 4,
+  deduped: 4,
+  'iframe-reachable': 3,
+  'opaque-embed': 2,
+  unsupported: 1,
+};
+
+/** Default relative path for `server.module` when omitted (§3) — the scaffolded Colyseus bootstrap. */
+export const DEFAULT_SERVER_MODULE = 'server/colyseus-setup.ts';
+
+const SEMVER_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z-.]+)?(?:\+[0-9A-Za-z-.]+)?$/;
+
+// ---------------------------------------------------------------------------
+// Adapter shape guards
+// ---------------------------------------------------------------------------
+
+function isModuleAdapter(
+  adapter: WorldAdapter,
+): adapter is Extract<WorldAdapter, { module: string }> {
+  return typeof adapter === 'object' && 'module' in adapter;
+}
+
+function isIngestAdapter(
+  adapter: WorldAdapter,
+): adapter is Extract<WorldAdapter, { ingest: { strategy: IngestStrategy } }> {
+  return typeof adapter === 'object' && 'ingest' in adapter;
+}
+
+// ---------------------------------------------------------------------------
+// Cross-field checks (§3 — beyond what Zod alone enforces)
+// ---------------------------------------------------------------------------
+//
+// D-V6 (docs/WAVE5-MULTIWORLD-INGEST-DESIGN.md): world-id uniqueness used to
+// be a cross-field check HERE (`checkUniqueWorldIds`, removed) — it moved
+// INTO `GameManifestSchema`'s `worlds` `superRefine` (schema.ts) instead, so
+// the generated JSON Schema and any other schema consumer see the same
+// constraint the loader always enforced. `parseManifest` below catches that
+// one recognizable schema-level issue and rethrows it as a clean, single
+// `Error` — the exact message shape `checkUniqueWorldIds` used to throw
+// directly — rather than a raw multi-issue `ZodError` dump, so existing
+// callers/tests that pattern-match the message text are unaffected by the
+// enforcement moving one layer down.
+
+function checkAdapterSceneEntryRules(world: WorldEntry): void {
+  const { adapter } = world;
+  if (adapter === 'default' && !world.scene && !world.entry) {
+    throw new Error(
+      `Game manifest: world "${world.id}" uses the 'default' adapter but declares neither ` +
+        '`scene` nor `entry` — a default-adapter world requires one of the two (§3).',
+    );
+  }
+  if (isIngestAdapter(adapter) && world.scene !== undefined) {
+    throw new Error(
+      `Game manifest: world "${world.id}" uses an { ingest } adapter but declares \`scene\` — ` +
+        'ingest adapters forbid `scene` (adapt-never-migrate: ingested games keep their own ' +
+        "formats; overlay persistence is T3.2's) (§3).",
+    );
+  }
+}
+
+// Historical note (Track N, N1): this file used to reject EVERY `kind:
+// 'react'` + `{ ingest }` world outright here (`checkReactAdapterRestriction`,
+// citing "no react ingest program is un-parked"). Track N un-parks exactly
+// that program (docs/REACT-INGEST-LANDING-DESIGN.md) — react+ingest is now a
+// structurally legal combination, resolved to the `'ingest-react'` identity
+// by `resolveAdapter` below like any other ingest world. There is nothing
+// left to reject at THIS layer: `checkAdapterSceneEntryRules` above already
+// forbids `scene` on any `{ ingest }`-adapter world (kind-agnostic), and the
+// v1 "deduped strategy only" restriction is an editor-resolver concern
+// (D-N3), not a manifest-shape concern — see the `ResolvedAdapter` type's
+// comment above.
+
+// ---------------------------------------------------------------------------
+// Resolution (§5)
+// ---------------------------------------------------------------------------
+
+function resolveAdapter(world: WorldEntry): ResolvedAdapter {
+  const { adapter, kind } = world;
+
+  if (adapter === 'default') {
+    const identity =
+      kind === 'threejs' ? 'default-three' : kind === 'pixijs' ? 'default-pixi' : 'default-react';
+    return { type: 'default', identity };
+  }
+
+  if (isModuleAdapter(adapter)) {
+    return { type: 'module', identity: 'module', module: adapter.module };
+  }
+
+  // isIngestAdapter (Track N, N1: 'ingest-react' joins 'ingest-three'/
+  // 'ingest-pixi' — see the `ResolvedAdapter` type's comment above for why
+  // this stays strategy-agnostic here).
+  const identity =
+    kind === 'threejs' ? 'ingest-three' : kind === 'pixijs' ? 'ingest-pixi' : 'ingest-react';
+  const ingest = adapter.ingest;
+  return {
+    type: 'ingest',
+    identity,
+    strategy: ingest.strategy,
+    entryHtml: ingest.entryHtml,
+    assets: ingest.assets,
+    domStubs: ingest.domStubs,
+    captureTimeoutMs: ingest.captureTimeoutMs,
+    bundleUrl: ingest.bundleUrl,
+    baseHref: ingest.baseHref,
+    assetBaseUrl: ingest.assetBaseUrl,
+    extraDeps: ingest.extraDeps,
+    pixiModuleUrl: ingest.pixiModuleUrl,
+    bodyHtml: ingest.bodyHtml,
+  };
+}
+
+function ceilingFor(adapter: WorldAdapter, context: 'local' | 'hosted'): Tier {
+  if (adapter === 'default') return CAPABILITY_CEILINGS.default[context];
+  if (isModuleAdapter(adapter)) return CAPABILITY_CEILINGS.module[context];
+  return CAPABILITY_CEILINGS.ingest[adapter.ingest.strategy][context];
+}
+
+function resolveCapabilities(world: WorldEntry): { local: Tier; hosted: Tier } {
+  const contexts = ['local', 'hosted'] as const;
+  const result = {} as { local: Tier; hosted: Tier };
+
+  for (const context of contexts) {
+    const declared = world.capabilities?.[context];
+    if (declared !== undefined) {
+      const ceiling = ceilingFor(world.adapter, context);
+      if (TIER_RANK[declared] > TIER_RANK[ceiling]) {
+        throw new Error(
+          `Game manifest: world "${world.id}": declared capabilities.${context} tier "${declared}" ` +
+            `exceeds the "${ceiling}" ceiling for this adapter in the ${context} context (§4). ` +
+            'Under-claiming (including `unsupported`) is legal; over-claiming is not.',
+        );
+      }
+      result[context] = declared;
+      continue;
+    }
+
+    // Omitted -> derive.
+    if (world.adapter === 'default') {
+      result[context] = 'first-party';
+    } else if (isModuleAdapter(world.adapter)) {
+      throw new Error(
+        `Game manifest: world "${world.id}": { module } adapter requires an explicit ` +
+          `capabilities.${context} declaration — a custom adapter's reach is not derivable (§4).`,
+      );
+    } else {
+      result[context] = CAPABILITY_CEILINGS.ingest[world.adapter.ingest.strategy][context];
+    }
+  }
+
+  return result;
+}
+
+function checkEngineVersionPin(version: string): void {
+  if (!SEMVER_RE.test(version)) {
+    throw new Error(
+      `Game manifest: engine.version "${version}" is not a valid exact semver string (e.g. ` +
+        '"0.1.0") — §1.5 requires an exact identity pin, not a range.',
+    );
+  }
+}
+
+/**
+ * Resolve one already-Zod-validated world entry into its `ResolvedWorldEntry`
+ * (adapter identity, capabilities, and a pass-through of every other field).
+ * Every `WorldEntry` field participates here or in a check above:
+ * `id`/`kind` drive adapter resolution + uniqueness; `adapter` (incl. its
+ * `module`/`ingest.*` sub-fields) drives identity + capability-ceiling
+ * resolution; `scene`/`entry` drive the scene/entry cross-field rule and are
+ * carried through; `zOrder` drives the final sort; `pausable`/`loop` are
+ * carried through as-is (their consumers are the runtime/CLI, T3.2/T3.3);
+ * `capabilities.{local,hosted}` drive tier resolution; `description` (T3.3
+ * slice 3) is carried through as-is — its consumer today is
+ * `resolveIngestDescriptor` (packages/editor/src/adapter-resolver.ts), which
+ * threads an ingest-three world's description into `IngestGame.description`.
+ */
+function resolveWorld(world: WorldEntry): ResolvedWorldEntry {
+  checkAdapterSceneEntryRules(world);
+
+  return {
+    id: world.id,
+    kind: world.kind,
+    description: world.description,
+    adapter: resolveAdapter(world),
+    scene: world.scene,
+    entry: world.entry,
+    zOrder: world.zOrder,
+    pausable: world.pausable,
+    loop: world.loop,
+    capabilities: resolveCapabilities(world),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Entry point
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse + validate + resolve a raw manifest value into a `ResolvedGameManifest`.
+ * Pure data-in/data-out (no `fs`) — see `load-file.ts` for the Node path-based
+ * wrapper. Throws a descriptive `Error` (naming the offending world/field) on
+ * any Zod validation failure or cross-field rule violation.
+ */
+export function loadGameManifest(raw: unknown): ResolvedGameManifest {
+  const parsed = GameManifestSchema.safeParse(raw);
+  if (!parsed.success) {
+    // D-V6: the `worlds` `superRefine`'s duplicate-id issue is the one
+    // schema-level violation this loader still surfaces as a clean, single
+    // `Error` (matching `checkUniqueWorldIds`'s pre-D-V6 message shape) —
+    // every other schema violation keeps propagating as the raw `ZodError`
+    // it always has (unchanged behavior, e.g. the iframe-reachable
+    // field-exclusivity / manifestVersion checks).
+    const dupIssue = parsed.error.issues.find((issue) =>
+      issue.message.startsWith('Game manifest: duplicate world id'),
+    );
+    if (dupIssue) throw new Error(dupIssue.message);
+    throw parsed.error;
+  }
+  const manifest: GameManifest = parsed.data;
+
+  checkEngineVersionPin(manifest.engine.version);
+
+  const resolvedWithIndex = manifest.worlds.map((world, index) => ({
+    world: resolveWorld(world),
+    index,
+  }));
+
+  resolvedWithIndex.sort(
+    (a, b) => a.world.zOrder - b.world.zOrder || a.index - b.index, // ties -> array order (§3)
+  );
+
+  const worlds = resolvedWithIndex.map(({ world }) => world);
+
+  const server = manifest.server
+    ? { room: manifest.server.room, module: manifest.server.module ?? DEFAULT_SERVER_MODULE }
+    : undefined;
+
+  return {
+    manifestVersion: manifest.manifestVersion,
+    name: manifest.name,
+    version: manifest.version,
+    engine: { version: manifest.engine.version },
+    worlds,
+    server,
+    resolution: manifest.resolution,
+  };
+}