@vgai/editor 0.2.0

package/src/adapter-resolver.ts

@@ -0,0 +1,1858 @@
+/**
+ * Adapter resolver — T3.3 slice 2 (docs/CLI-ON-FOLDER-DESIGN.md §1D), extended
+ * in T6.1 slice 2 (docs/MULTI-WORLD-DESIGN.md §1.D/§3 slice 2) for `default-pixi`
+ * + the multi-world resolution surface, in T6.1 slice 4 (§1.E/§3 slice 4)
+ * for `ingest-pixi` (world2d silo retirement), in T6.2 (docs/REACT-WORLD-
+ * DESIGN.md §1.B/§3 slice 1) for `default-react`, in T3.4 slice 1
+ * (docs/ADAPTER-AUTHORING-DESIGN.md §1.A/§1.C) for `{ module }` (custom
+ * adapter modules) + achieved-tier verification, and in Track N task N1
+ * (docs/REACT-INGEST-LANDING-DESIGN.md D-N2/D-N3/D-N4) for `ingest-react`
+ * (vendored native-React game ingestion — the deduped-only mount).
+ *
+ * Turns one manifest world (`ResolvedWorldEntry`, from `@engine/manifest/load`)
+ * into a mountable {@link GameAdapter} (or, for a pixijs world, a structurally
+ * distinct {@link Pixi2DGameAdapter} — see the default-pixi section below).
+ * Lives editor-side, not in the engine package: it needs `/@fs/` dynamic-import
+ * mechanics (the same route `loadProjectScripts` uses, `./script-loader.ts`),
+ * and the engine's manifest loader deliberately has no fs/vite dependency
+ * (`manifest/load.ts`'s no-fs discipline — the pure identity-resolution half
+ * stays importable anywhere, including Node CLI code; this file is the
+ * instantiation half).
+ *
+ * Coverage in this slice (per the design docs' staging):
+ *  - `default-three` -> a configured `VgaiSceneGameAdapter`, WITH
+ *    `componentRegistry` threaded from the project's `src/scripts/registry.ts`
+ *    (closes the T7.2 finding: `sceneData`/`scenePath` never passed a
+ *    registry, so scene-authored NAMED components were unreachable through
+ *    those two `VgaiSceneConfig` branches).
+ *  - `default-pixi` -> a configured `PixiSceneGameAdapter` (T6.1 slice 2, see
+ *    `resolveDefaultPixiAdapter` below for the `scene`/`entry` split and the
+ *    `entry`-for-pixi adjudication).
+ *  - `ingest-three` -> see `resolveIngestDescriptor`'s doc comment below for
+ *    the shape landed on and the structural finding it reports.
+ *  - `ingest-pixi` -> see `resolveIngest2DDescriptor`'s doc comment below (T6.1
+ *    slice 4) — same two-layer shape as ingest-three (descriptor builder +
+ *    a named-stub `GameAdapter`; the real mount is `ingest-mode.ts`'s
+ *    `enterIngestModeFromManifestWorld2D`).
+ *  - `default-react` -> a `ReactWorldAdapter` (T6.2, see
+ *    `resolveDefaultReactAdapter` below for the `entry`-only rule — `scene`
+ *    is a named error, D4 — and the two engine-seam findings its doc
+ *    comment reports).
+ *  - `ingest-react` -> also a `ReactWorldAdapter` (Track N, N1 —
+ *    docs/REACT-INGEST-LANDING-DESIGN.md D-N2/D-N3, see
+ *    `resolveIngestReactAdapter` below): same T6.2 mount machinery as
+ *    `default-react`, restricted to the `'deduped'` strategy rung (a named
+ *    error for any other strategy) with `entry` required (the D-N2 host-shim
+ *    module) — and, per D-N8, no authoring adapter anywhere in v1.
+ *  - `{ module }` -> `/@fs/`-imports the game folder's declared adapter module
+ *    (path-guarded, shape-checked) — see `resolveModuleAdapter` below (T3.4
+ *    slice 1). Achieved-tier verification (post-mount, against the actual
+ *    `MountedGame` surface) lives in `./achieved-tier.ts`, shared with the
+ *    ingest embed-only degradation path's retrofit (`ingest-mode.ts`).
+ *
+ * `resolveAllWorlds` (T6.1 slice 2, extended T6.2 for react) is the
+ * multi-world sibling of `resolveWorldAdapter`: it resolves every world in a
+ * `ResolvedGameManifest` into slice-1 `WorldMountSpec`s, enforcing the v1
+ * scope rule for manifests with more than one world (docs/MULTI-WORLD-
+ * DESIGN.md §3 slice 4, docs/REACT-WORLD-DESIGN.md §3 for react's admission).
+ */
+
+import type { GameAdapter } from '@engine/adapter';
+import { VgaiSceneGameAdapter } from '@engine/adapter';
+import { assertNever } from '@engine/adapter/world-kind';
+import { resolveUrl } from '@engine/loader';
+import type { ResolvedGameManifest, ResolvedWorldEntry } from '@engine/manifest/load';
+import { GameProvider as EngineGameProvider } from '@engine/react/game-state';
+import type {
+  MountedReactGame,
+  Pixi2DGameAdapter,
+  ReactWorldAdapter,
+  ReactWorldHost,
+  WorldMountSpec,
+} from '@engine/runtime/create-runtime';
+import type { Game } from '@engine/runtime/game';
+import type { MountEntry } from '@engine/runtime/mount-manifest';
+import type { EditorPreview } from '@engine/runtime/types';
+import type { ComponentRegistry } from '@engine/scene/component-registry';
+import { SceneParseError } from '@engine/scene/parse';
+import type { IngestGame2D } from '@engine/world2d/ingest2d';
+import { PixiSceneGameAdapter, type World2DSetupFn } from '@engine/world2d/pixi-game-adapter';
+import { type Scene2DFile, Scene2DSchema } from '@engine/world2d/schema/entity2d';
+import type { ProjectUIRegistry } from '@vgai/scene-ui/registry';
+import { type ComponentType, createElement } from 'react';
+import { flushSync } from 'react-dom';
+import { createRoot } from 'react-dom/client';
+import { reactWorldProviderImportSpecifier } from '../vite-plugin-react-world-provider';
+import { REACT_WORLD_RUNTIME_PATH } from '../vite-plugin-react-world-runtime';
+import {
+  computeAchievedTier,
+  computeTierShortfall,
+  formatTierShortfallMessage,
+} from './achieved-tier';
+import { resolveExtraDeps } from './ingest/host-namespace-registry';
+import type { IngestGame } from './ingest/types';
+import { isPackagedRuntime } from './packaged-runtime';
+import { loadProjectScripts } from './script-loader';
+
+/**
+ * Build a `/@fs/<absolute path>` dev-server import URL WITHOUT a doubled
+ * leading slash (T6.2 slice 3 finding — see the "Report back" of that
+ * slice's dispatch). `projectRoot` is always an absolute path (it starts
+ * with `/`), so the naive `` `/@fs/${projectRoot}/...` `` template produces
+ * `/@fs//abs/olute/path/...` — cosmetically harmless on its own (Vite's
+ * `/@fs/` middleware tolerates it), UNTIL the SAME file is also reached via
+ * a DIFFERENT route: a react world's entry module's own STATIC relative
+ * import (e.g. `import { useGameState } from './src/ui/game-
+ * state'`) is rewritten by Vite's normal resolver into a SINGLE-slash,
+ * symlink-canonicalized `/@fs/` URL — a textually different string than
+ * this file's hand-built double-slash one. Browser ES module identity is
+ * per-URL, so the two builds of `/@fs/` string for the SAME file produced
+ * TWO SEPARATE module instances (two `createContext()` calls for
+ * `game-state.tsx`), and `useGameState`'s `useGame()` threw "no Game in
+ * context" even though `<GameProvider>` genuinely wrapped the entry — this
+ * is what `resolveDefaultReactAdapter`'s AC e2e (T6.2 slice 3) caught. The
+ * server-side half of this fix is `canonical-path.ts` (canonicalizes
+ * `projectRoot` itself so it agrees with Vite's own symlink-resolved form);
+ * this half removes the remaining single/double-slash divergence so the
+ * two strings are BYTE-IDENTICAL once `projectRoot` is canonical.
+ */
+export function fsImportPath(projectRoot: string, relativePath: string): string {
+  const root = projectRoot.endsWith('/') ? projectRoot.slice(0, -1) : projectRoot;
+  const rel = relativePath.startsWith('/') ? relativePath.slice(1) : relativePath;
+  // Windows canonical roots ('C:/…') carry no leading slash of their own —
+  // without inserting one the URL degenerates to '/@fsC:/…', which Vite
+  // serves as a 404. POSIX roots keep the concat form (root already starts
+  // with '/'), preserving the byte-identical contract described above.
+  return root.startsWith('/') ? `/@fs${root}/${rel}` : `/@fs/${root}/${rel}`;
+}
+
+/** Optional editor-session context for {@link resolveWorldAdapter}. */
+export interface ResolveWorldAdapterOptions {
+  /**
+   * The editor's play-launch context (live in-memory scene document +
+   * viewport-camera spawn) — supplied by `play-mode.ts` when the resolver is
+   * invoked from the editor's play path, absent for non-editor callers (the
+   * CLI-on-folder flow). Threaded into BOTH `default-three` branches:
+   * the `entry` branch hands it to the project's `setup(ctx, editorPreview)`
+   * exactly like today's legacy play path (`createGameRuntime({ setup,
+   * editorPreview })` is the same `VgaiSceneGameAdapter` wrap), and the
+   * scene-only branch mounts `editorPreview.sceneData` (the LIVE document,
+   * unsaved edits included) instead of fetching `world.scene` from disk —
+   * matching the documented play-mode contract ("hands the in-memory scene
+   * document to the real engine runtime") the way `template/src/scripts/
+   * main.ts`'s generic fallback does (`editor ? loadSceneFromData(editor.
+   * sceneData) : loadScene(...)`).
+   */
+  editorPreview?: EditorPreview | undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Part B — componentRegistry via the project's script registry
+// ---------------------------------------------------------------------------
+
+/**
+ * Load the project's component registry (`src/scripts/registry.ts`'s
+ * `componentRegistry` export) via the same `/@fs/` dev-server route
+ * `loadProjectScripts` uses for `src/scripts/main.ts` (script-loader.ts).
+ *
+ * A project with no scripts registry — the file doesn't exist, doesn't export
+ * `componentRegistry`, or fails to import for any other reason — resolves to
+ * an EMPTY registry rather than throwing: most manifest-backed projects
+ * (especially ones with no named `GameComponent`s at all) have nothing here,
+ * and that must not block `default-three` resolution. This intentionally
+ * folds "file absent" and "file present but broken" into the same empty
+ * result; a project whose registry.ts has a real bug still resolves and
+ * mounts, just without any named components reachable from scene JSON
+ * (the same as today's behavior before this slice existed at all).
+ */
+export async function loadComponentRegistryForProject(
+  projectRoot: string,
+): Promise<ComponentRegistry> {
+  const modulePath = fsImportPath(projectRoot, 'src/scripts/registry.ts');
+  try {
+    const mod = (await import(/* @vite-ignore */ modulePath)) as {
+      componentRegistry?: ComponentRegistry;
+    };
+    return mod.componentRegistry ?? {};
+  } catch {
+    return {};
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Part B.2 — the project's scene-UI registry (design/24-scene-ui.md D9/D11)
+// ---------------------------------------------------------------------------
+
+/**
+ * Load the project's scene-UI registry (`src/ui/registry.ts`'s `uiRegistry`
+ * export) via the same `/@fs/` dev-server route as {@link
+ * loadComponentRegistryForProject} above — but with ONE deliberate departure
+ * from that loader's behavior: an import FAILURE (the file exists but throws
+ * — a syntax error, a bad import, a thrown top-level expression) logs a loud
+ * `editorConsole.warn` naming the real error before falling back to `null`.
+ * `loadComponentRegistryForProject` folds "absent" and "broken" into the same
+ * silent `{}` because most projects simply have no `src/scripts/registry.ts`
+ * at all; a scene-UI registry is different — the whole point of this PR is
+ * project-authored UI, so a registry with a typo silently demoting the
+ * editor back to demo fixtures (D10) is exactly the confusing failure mode
+ * this loader exists to make loud instead.
+ *
+ * The common "no registry file" case (every scaffolded project, by design —
+ * D10: the template does NOT ship one) stays silent: the editor server's
+ * `/__editor/project` response carries `hasUiRegistry` (a server-side stat of
+ * `src/ui/registry.ts`), which distinguishes "the file doesn't exist" (no
+ * warning, resolves `null`) from "the file exists but the import threw"
+ * (warns). Probing the `/@fs/` URL itself cannot make that call: a dev server
+ * answers 200 for missing files (SPA fallback), and the doomed dynamic import
+ * that follows logs an unsuppressible browser network error on every
+ * registry-less project — which strict harnesses
+ * (scripts/check-vgai-generated-project-p2p.ts) rightly fail on.
+ * Returns `null` for both "absent" and "present but empty" (`uiRegistry`
+ * undefined) — D10 treats both the same (demo mode).
+ */
+export async function loadProjectUIRegistry(
+  projectRoot: string,
+): Promise<ProjectUIRegistry | null> {
+  const modulePath = fsImportPath(projectRoot, 'src/ui/registry.ts');
+  // Inline fetch rather than editor-api's getCurrentServerProject(): this
+  // module must stay importable by headless Node/vitest suites, and
+  // editor-api's module top level pulls in ./storage.
+  let exists: boolean;
+  try {
+    const res = await fetch('/__editor/project');
+    const data = (await res.json()) as { project?: { hasUiRegistry?: boolean } | null };
+    exists = Boolean(data.project?.hasUiRegistry);
+  } catch {
+    exists = false;
+  }
+  if (!exists) return null;
+  try {
+    const mod = (await import(/* @vite-ignore */ modulePath)) as {
+      uiRegistry?: ProjectUIRegistry;
+    };
+    return mod.uiRegistry ?? null;
+  } catch (err) {
+    // Lazy dynamic import — see withAchievedTierCheck's doc comment above:
+    // this resolver is imported by headless Node/vitest suites with no
+    // `window`, and editor-console.ts's module top level touches `window`
+    // unconditionally.
+    const { editorConsole } = await import('./editor-console');
+    editorConsole.warn(
+      `src/ui/registry.ts failed to import — UI mode falls back to demo fixtures: ${String(err)}`,
+      'ui-mode',
+    );
+    return null;
+  }
+}
+
+let _cachedProjectUIRegistry: ProjectUIRegistry | null = null;
+
+/**
+ * Cache slot for the project's scene-UI registry (D9/D11) — populated by
+ * `authoring/scene-ui-layer.ts`'s design-time layer mount (once per project
+ * open, when the scene has a `ui` root to disclose — C3) and read by
+ * `resolveDefaultThreeAdapter` below so the editor-play path doesn't
+ * reload/re-parse the same module a second time per play. A headless/CLI-
+ * on-folder resolve (no editor session, no scene-UI layer ever mounts)
+ * simply reads the initial `null` — zero behavior change there.
+ */
+export function setCachedProjectUIRegistry(registry: ProjectUIRegistry | null): void {
+  _cachedProjectUIRegistry = registry;
+}
+
+/** @see setCachedProjectUIRegistry */
+export function getCachedProjectUIRegistry(): ProjectUIRegistry | null {
+  return _cachedProjectUIRegistry;
+}
+
+// ---------------------------------------------------------------------------
+// Named errors for identities not yet resolvable (report the task, not just fail)
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// Part A — default-three
+// ---------------------------------------------------------------------------
+
+async function resolveDefaultThreeAdapter(
+  world: ResolvedWorldEntry,
+  projectRoot: string,
+  opts?: ResolveWorldAdapterOptions,
+): Promise<GameAdapter> {
+  const editorPreview = opts?.editorPreview;
+
+  // `entry` is preferred when a world declares BOTH `entry` and `scene`: the
+  // code entry owns MOUNTING (the same contract `src/scripts/main.ts`
+  // satisfies today — it decides what to load, delegates to a matching
+  // example's setup for gameplay systems, etc.); `scene` remains the world's
+  // data identity (what the compat view's `defaultScene` is synthesized from,
+  // project-view.ts §1C). The manifest loader allows both
+  // (`checkAdapterSceneEntryRules` only rejects NEITHER).
+  if (world.entry !== undefined) {
+    // entry-based default-three: W1 (docs/R3F-FIRST-PARTY-DESIGN.md §1.A/§2)
+    // accepts EITHER a pre-built `adapter` export OR a `setup` function.
+    // Before W1, `loadProjectScripts` hard-threw on any entry lacking
+    // `setup`, so an `adapter`-export entry that mounted fine standalone
+    // failed here — asymmetry, not doctrine (§0's "ground truth").
+    //
+    // Precedence when BOTH are exported is `setup` FIRST — the OPPOSITE of
+    // the standalone path (`mount-game.ts:176-177` prefers `adapter`), and
+    // deliberately so. The template (and every project scaffolded from it)
+    // exports both, with `adapter = fromSetup('default', setup)` as the
+    // standalone convenience, so standalone's adapter-first is
+    // behavior-identical there. In the EDITOR the two paths are NOT
+    // equivalent: only the `setup` branch threads `editorPreview` (the live
+    // in-memory scene + viewport camera — a bare `GameAdapter.mount(host)`
+    // has no channel for it) and mounts through the firstParty-branded
+    // `VgaiSceneGameAdapter` that script-HMR's prototype swap requires.
+    // Preferring `adapter` here made every scaffolded project silently load
+    // its ON-DISK default scene instead of the scene being edited, and
+    // killed component HMR (caught by e2e 07-script-hmr +
+    // 10-render-fidelity). An adapter-ONLY entry (e.g. a react-three-fiber
+    // bridge, §1.C) still returns the project's adapter directly — it owns
+    // its full mount lifecycle, is not wrapped in `VgaiSceneGameAdapter`,
+    // and has no `setup` to prefer.
+    const { adapter, setup } = await loadProjectScripts(projectRoot, world.entry);
+    if (setup) {
+      // Byte-equivalent to the legacy play path: `createGameRuntime({ setup,
+      // editorPreview })` wraps the exact same `VgaiSceneConfig`.
+      return new VgaiSceneGameAdapter({ id: world.id, setup, editorPreview });
+    }
+    // `loadProjectScripts` only returns with neither `adapter` nor `setup`
+    // by throwing first, so `adapter` is guaranteed defined here.
+    return adapter as GameAdapter;
+  }
+  if (world.scene !== undefined) {
+    // Scene-only world (§1D): no custom setup(). Thread the project's
+    // component registry so scene-authored `components:` entries resolve —
+    // the T7.2 finding this slice closes. From the editor's play path
+    // (editorPreview present), mount the LIVE in-memory document —
+    // `VgaiSceneGameAdapter.mount()`'s `scenePath` branch reads
+    // `editorPreview` only for the viewport camera and would fetch the
+    // on-disk file, silently dropping unsaved edits — so hand it
+    // `sceneData` instead (whose branch also honors the viewport camera).
+    const componentRegistry = await loadComponentRegistryForProject(projectRoot);
+    // The project's scene-UI registry (D9/D11) — read from the CACHE
+    // `authoring/scene-ui-layer.ts`'s design-time layer mount populated, not
+    // reloaded/re-parsed here. `undefined` (not `null`) when absent/never
+    // populated (e.g. a headless/CLI-on-folder resolve, or a scene with no
+    // `ui` root) so the spread below omits the key entirely rather than
+    // passing an explicit `uiRegistry: null`.
+    const uiRegistry = getCachedProjectUIRegistry() ?? undefined;
+    if (editorPreview) {
+      return new VgaiSceneGameAdapter({
+        id: world.id,
+        sceneData: editorPreview.sceneData,
+        editorPreview,
+        componentRegistry,
+        uiRegistry,
+      });
+    }
+    return new VgaiSceneGameAdapter({
+      id: world.id,
+      scenePath: world.scene,
+      componentRegistry,
+      uiRegistry,
+    });
+  }
+  // Unreachable in practice: `load.ts`'s `checkAdapterSceneEntryRules` requires
+  // `scene` or `entry` for every 'default' adapter world at manifest-load time.
+  throw new Error(
+    `resolveWorldAdapter: world "${world.id}" is default-three with neither \`scene\` nor ` +
+      '`entry` — this should have been rejected by manifest validation.',
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Part C (T6.1 slice 2) — default-pixi
+// ---------------------------------------------------------------------------
+
+/**
+ * Fetch + validate a `.scn2d.json` file from `path` (relative to the served
+ * project root, exactly like `default-three`'s `scenePath` branch fetches a
+ * `.vscn.json` inside `@engine/scene/scene-loader`'s `loadScene` — this file
+ * does the analogous fetch itself because `PixiSceneConfig` has no `scenePath`
+ * field of its own, only `sceneData` (see `resolveDefaultPixiAdapter` below).
+ * `resolveUrl` applies the SAME asset-prefix rewriting raw `fetch()` calls
+ * elsewhere in the engine use.
+ *
+ * A malformed payload throws a `SceneParseError` naming `path`, not a raw
+ * `ZodError` — the same T4.6 convention every fetched 3D scene format
+ * (`.vscn.json`/`.prefab.json`/`.mat.json`) already follows via
+ * `parseSceneFile`/`parsePrefabFile`/`parseMaterialFile`; `.scn2d.json` was
+ * the one fetched format still raw-parsing (§7.1-14).
+ *
+ * Exported (B1, docs/unified-world-editor/26-unified-editor-spec.md §3 B1):
+ * `design-time-layers.ts` reuses this exact fetch+validate step for a pixi
+ * world's design-time display-only mount, rather than duplicating it.
+ */
+export async function fetchScene2DFile(path: string): Promise<Scene2DFile> {
+  const res = await fetch(resolveUrl(path));
+  if (!res.ok) {
+    throw new Error(
+      `resolveWorldAdapter: failed to load world2d scene "${path}" (${res.status} ${res.statusText}).`,
+    );
+  }
+  const result = Scene2DSchema.safeParse(await res.json());
+  if (!result.success) throw new SceneParseError(result.error.issues, path);
+  return result.data;
+}
+
+/**
+ * Resolve a `kind: 'pixijs'` + `adapter: 'default'` world into a
+ * `PixiSceneGameAdapter` (docs/MULTI-WORLD-DESIGN.md §1.D) — the pixi sibling
+ * of `resolveDefaultThreeAdapter` above, minus the `editorPreview`/legacy
+ * branch: v1 has NO live-document mount for pixi (§1.D — "No editorPreview
+ * equivalent in v1: the 2D editor edits flow through the overlay/authoring
+ * path, not a live-document preview"), so a pixi world always mounts from its
+ * on-disk `scene`/`entry`, editor session or not.
+ *
+ * `entry`-for-pixi ADJUDICATION (per this slice's study directive): the design
+ * doc already answers this — `World2DSetupFn` (`@engine/world2d/
+ * pixi-game-adapter.ts`) is an established, exported config shape (`PixiSceneConfig.setup`,
+ * re-exported from `@engine/world2d`'s barrel) structurally parallel to
+ * `default-three`'s `GameSetupFn`; it simply has no production caller YET
+ * (only hand-built test wiring, e.g. `create-runtime-worlds.test.ts`'s pixi
+ * world). So `entry` resolves via the SAME `/@fs/` dynamic-import route
+ * `loadProjectScripts` uses for `default-three`'s entry branch — no new
+ * mechanism invented, just a different exported shape (`setup(ctx:
+ * World2DContext)` instead of `setup(ctx: GameContext, editorPreview?)`).
+ * `loadProjectScripts`'s return type is pinned to the three-shaped
+ * `GameSetupFn`; the cast back to `World2DSetupFn` below is a type-level
+ * relabeling only — the runtime check (`typeof mod.setup === 'function'`)
+ * is shape-agnostic.
+ */
+async function resolveDefaultPixiAdapter(
+  world: ResolvedWorldEntry,
+  projectRoot: string,
+): Promise<GameAdapter> {
+  if (world.entry !== undefined) {
+    const { adapter, setup } = await loadProjectScripts(projectRoot, world.entry);
+    // W1 (docs/R3F-FIRST-PARTY-DESIGN.md §0.1's kind-parity matrix / §2 "W1b,
+    // out of scope") is a `default-three`-only parity fix — pixi has no
+    // standalone `adapter`-export factory to match, so an `adapter`-only
+    // entry is not a shape this branch can honor. `loadProjectScripts` no
+    // longer hard-throws on a `setup`-less module (it now also accepts
+    // `adapter`), so that guarantee has to be re-asserted HERE, loudly,
+    // instead of letting `undefined` silently reach `PixiSceneGameAdapter`.
+    if (!setup) {
+      throw new Error(
+        `resolveWorldAdapter: world "${world.id}"'s entry "${world.entry}" exports \`adapter\` ` +
+          `but no \`setup\` — default-pixi worlds only accept a \`setup(ctx: World2DContext)\` ` +
+          `export${adapter ? ' (an `adapter` export is default-three/R3F-only, W1b)' : ''}.`,
+      );
+    }
+    return new PixiSceneGameAdapter({
+      id: world.id,
+      setup: setup as unknown as World2DSetupFn,
+    }) as unknown as GameAdapter;
+  }
+  if (world.scene !== undefined) {
+    const sceneData = await fetchScene2DFile(world.scene);
+    return new PixiSceneGameAdapter({ id: world.id, sceneData }) as unknown as GameAdapter;
+  }
+  // Unreachable in practice: `load.ts`'s `checkAdapterSceneEntryRules` requires
+  // `scene` or `entry` for every 'default' adapter world at manifest-load time.
+  throw new Error(
+    `resolveWorldAdapter: world "${world.id}" is default-pixi with neither \`scene\` nor ` +
+      '`entry` — this should have been rejected by manifest validation.',
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Part F (T6.2 slice — docs/REACT-WORLD-DESIGN.md §1.B/§3 slice 1) — default-react
+// ---------------------------------------------------------------------------
+
+/**
+ * The shape a react world's `entry` module must satisfy: default-export a
+ * React component (docs/REACT-WORLD-DESIGN.md §1.B — "The world's `entry`
+ * module default-exports a React component"). Validated loudly at import
+ * time below — a project whose entry exports the wrong shape gets a named
+ * error naming the world and the export it actually found, not a cryptic
+ * "X is not a function" deep inside `createRoot`/`render`. Shared by BOTH
+ * react identities (`default-react` and, since Track N, `ingest-react`) —
+ * `identityLabel` only changes the error message's parenthetical so a
+ * failure is attributed to the right one; the shape requirement itself is
+ * identical (an ingest world's `entry` is a host-shim module, D-N2, but a
+ * shim is still just a module default-exporting a component).
+ */
+function loadReactEntryComponent(
+  world: ResolvedWorldEntry,
+  mod: { default?: unknown },
+  identityLabel: 'default-react' | 'ingest-react' = 'default-react',
+): ComponentType {
+  if (typeof mod.default !== 'function') {
+    throw new Error(
+      `resolveWorldAdapter: world "${world.id}" (${identityLabel}) entry module does not ` +
+        `default-export a component — got ${typeof mod.default}. A react world's \`entry\` must ` +
+        'default-export a React component (docs/REACT-WORLD-DESIGN.md §1.B).',
+    );
+  }
+  return mod.default as ComponentType;
+}
+
+/**
+ * `ReactWorldHost.game` is a typed, guaranteed field (the T6.2 slice-1 gap
+ * this function originally worked around — `mountOneReactWorld` not
+ * threading `game` onto the host — was closed the same day, `5948678`,
+ * symmetric with `HostContext.game`). The `undefined` in the return type and
+ * the loud check at the call site stay: a foreign/hand-rolled host object
+ * that skipped the engine's mount path must still fail loudly, never lie an
+ * `undefined` Game into `<GameProvider>`.
+ */
+function hostGame(host: ReactWorldHost): Game | undefined {
+  return host.game;
+}
+
+// ---------------------------------------------------------------------------
+// Part F.1 (C1, phase-b/c1-react-mount) — packaged-mode react-world mount
+// runtime (the dual-React-instance fix)
+// ---------------------------------------------------------------------------
+
+/**
+ * The three pieces of "react itself" a react-world mount needs:
+ * `createElement`/`createRoot` (to build + render the `<GameProvider><Entry/>
+ * </GameProvider>` tree) and the engine-published `GameProvider` FALLBACK
+ * (`resolveGameProviderForProject`'s "absent" branch, D-Z5). Under dev/
+ * Electron these are always the module top level's own static imports
+ * (`createElement`/`createRoot`/`EngineGameProvider` above) — byte-identical
+ * to before this type existed. See {@link resolveReactWorldMountRuntime}'s
+ * doc comment for the packaged-mode branch this type also serves.
+ */
+export interface ReactWorldMountRuntime {
+  createElement: typeof createElement;
+  createRoot: typeof createRoot;
+  /** `react-dom`'s synchronous-flush escape hatch — `design-time-layers.ts`'s
+   *  react-world layer mount needs it from the SAME react-dom peer as
+   *  `createRoot` above (both are entry points of the same installed
+   *  package). Unused by `adapter-resolver.ts`'s own two mount()s. */
+  flushSync: typeof flushSync;
+  engineGameProvider: ComponentType<{ game: Game; children?: unknown }>;
+}
+
+/** The dev/Electron default: this module's own static imports, unchanged. */
+function staticReactWorldMountRuntime(): ReactWorldMountRuntime {
+  return {
+    createElement,
+    createRoot,
+    flushSync,
+    engineGameProvider: EngineGameProvider as unknown as ComponentType<{
+      game: Game;
+      children?: unknown;
+    }>,
+  };
+}
+
+/**
+ * Import + shape-check the packaged runtime's synthetic
+ * `/__vgai-react-world-runtime` module (`vite-plugin-react-world-runtime.ts`,
+ * registered only by `packaged.ts`'s project-rooted Vite instance and by
+ * `vitest.config.ts` for test coverage — never by `dev.ts`/the root
+ * `vite.config.ts`). A loud, named failure if the module resolves but is
+ * malformed — never a silent fall-through that would re-introduce the dual-
+ * instance bug it exists to prevent.
+ */
+async function loadPackagedReactWorldMountRuntime(): Promise<ReactWorldMountRuntime> {
+  const mod = (await import(/* @vite-ignore */ REACT_WORLD_RUNTIME_PATH)) as {
+    createElement?: unknown;
+    createRoot?: unknown;
+    flushSync?: unknown;
+    EngineGameProvider?: unknown;
+  };
+  if (
+    typeof mod.createElement !== 'function' ||
+    typeof mod.createRoot !== 'function' ||
+    typeof mod.flushSync !== 'function' ||
+    typeof mod.EngineGameProvider !== 'function'
+  ) {
+    throw new Error(
+      "resolveWorldAdapter: the packaged runtime's synthetic react-world-runtime module " +
+        `("${REACT_WORLD_RUNTIME_PATH}") did not export createElement/createRoot/flushSync/` +
+        'EngineGameProvider as functions — see vite-plugin-react-world-runtime.ts.',
+    );
+  }
+  return {
+    createElement: mod.createElement as typeof createElement,
+    createRoot: mod.createRoot as typeof createRoot,
+    flushSync: mod.flushSync as typeof flushSync,
+    engineGameProvider: mod.EngineGameProvider as ComponentType<{
+      game: Game;
+      children?: unknown;
+    }>,
+  };
+}
+
+let cachedPackagedReactWorldMountRuntime: Promise<ReactWorldMountRuntime> | null = null;
+
+/**
+ * Resolve the react-world mount's OWN `createElement`/`createRoot`/engine-
+ * `GameProvider`-fallback — the C1 fix for the packaged runtime's dual-React-
+ * instance bug (`packaged.ts`'s header doc comment, "React-world OID
+ * authoring parity" section): a react world is an ISOLATED `createRoot` (its
+ * own DOM subtree / react tree) that does NOT need to share react with the
+ * editor's own UI — it only needs to be internally consistent (the wrapper +
+ * `GameProvider` + the project's entry component all sharing ONE react
+ * instance). Under the packaged runtime, the editor's own UI is a separately-
+ * built static bundle with its OWN baked-in `react`/`react-dom` copy,
+ * disconnected from the SEPARATE project-rooted Vite instance the entry
+ * component's hooks resolve `react` through — so mounting with the module top
+ * level's static imports (the editor's copy) produces two react instances and
+ * `useContext` throws on a `null` dispatcher (confirmed live, see
+ * `packaged.ts`'s header doc comment history).
+ *
+ * The fix: under the packaged runtime ONLY (gated on `isPackagedRuntime()`,
+ * `packaged-runtime.ts` — reads a `packaged` flag `/__editor/project` now
+ * reports, itself computed server-side via `isMonorepoScaffoldRoot`), resolve
+ * `createElement`/`createRoot`/the engine `GameProvider` fallback from the
+ * PROJECT's own module graph instead — via `/__vgai-react-world-runtime`, a
+ * synthetic virtual module registered only on that project-rooted Vite
+ * instance (`vite-plugin-react-world-runtime.ts`), so both the mount call and
+ * the entry component's own hooks converge on the SAME project-resolved react
+ * module instance, the same "static synthetic re-export" trick
+ * `reactWorldProviderPlugin`/`loadProjectGameProvider` already use one layer
+ * up for `GameProvider` itself.
+ *
+ * Under dev/Electron, `isPackagedRuntime()` resolves `false` (no such server
+ * flag; one shared Vite instance + root `vite.config.ts`'s `resolve.dedupe`
+ * already collapses the editor's and the project's react onto one instance)
+ * — this function then returns the module top level's own static imports,
+ * BYTE-IDENTICAL to the pre-C1 behavior. Memoized: `isPackagedRuntime()` is
+ * itself session-memoized, and the packaged module load below is cached here
+ * too, so this only ever performs at most one `/__editor/project` fetch and
+ * one dynamic import per editor session, however many react worlds mount.
+ *
+ * Exported: `design-time-layers.ts`'s OWN, separate react-world layer mount
+ * (`mountReactLayer` — the edit-mode composite's live preview of a non-
+ * focused react/pixi world, B1) needs this SAME resolution — it is a second
+ * mount call site with the identical dual-instance exposure, not routed
+ * through this file's `ReactWorldAdapter.mount()` at all.
+ */
+export async function resolveReactWorldMountRuntime(): Promise<ReactWorldMountRuntime> {
+  const packaged = await isPackagedRuntime();
+  if (!packaged) return staticReactWorldMountRuntime();
+  if (!cachedPackagedReactWorldMountRuntime) {
+    cachedPackagedReactWorldMountRuntime = loadPackagedReactWorldMountRuntime();
+  }
+  return cachedPackagedReactWorldMountRuntime;
+}
+
+/** Test-only: reset the packaged react-world mount runtime cache between
+ *  tests that toggle `isPackagedRuntime()`'s own (separately memoized, see
+ *  `packaged-runtime.ts`'s `resetPackagedRuntimeCacheForTest`) result. */
+export function resetReactWorldMountRuntimeCacheForTest(): void {
+  cachedPackagedReactWorldMountRuntime = null;
+}
+
+/**
+ * SECOND FINDING (report prominently): `GameProvider` is not an engine or
+ * editor export — by design (`docs/REACT-STATE-BRIDGE.md` §2: "colocated
+ * with `mountUI`… rather than under `packages/engine/src/runtime/` — that
+ * directory stays react-free"), it lives PER-PROJECT at
+ * `src/ui/game-state.tsx` (`packages/editor/template/src/ui/
+ * game-state.tsx`, copied verbatim into every scaffolded project by
+ * `create-vgai-project`'s `scaffoldProject` — see that package's README:
+ * "Copies the template into the target directory"). There is no engine-side
+ * canonical `GameProvider` this resolver could import once and reuse for
+ * every project — it has to load the SAME project's own copy the entry
+ * module's OWN `../ui/game-state` import resolves to (a resolver-local
+ * `createContext()` would be a SECOND, non-identical Context: `useGame()`
+ * would throw "no Game in context" against it even though `<GameProvider>`
+ * genuinely wrapped the tree).
+ *
+ * THIRD FINDING, and the actual engine-adjacent-tooling gap this slice
+ * closes (T6.2 slice 3 — verified empirically, not assumed): a hand-built
+ * runtime `import(/* @vite-ignore *\/ '/@fs/' + projectRoot + '/src/
+ * ui/game-state.tsx')` does NOT reliably land on the SAME module
+ * instance a react-world entry's own STATIC relative import of that file
+ * resolves to. Vite's dev server treats the two differently at the HTTP
+ * level (a query-string divergence was observed in practice — confirmed by
+ * logging `import.meta.url` inside two otherwise-identical fetches) even
+ * though both target the identical file on disk; since browser ES module
+ * identity is keyed by the exact request URL, that is enough to produce TWO
+ * separate `createContext()` calls — exactly the multi-instance problem
+ * this doc comment already warns about, just triggered by the RESOLVER's
+ * own fetch mechanics rather than a hand-authored duplicate. The fix:
+ * `vite-plugin-react-world-provider.ts`'s tiny synthetic module, whose body
+ * is a LITERAL, STATIC `export { GameProvider } from '/@fs/…/game-state.tsx'`
+ * — Vite's import-analysis rewrites that specifier through the SAME
+ * transform-time resolver a react-world entry's own static import goes
+ * through, converging both on the identical final module.
+ *
+ * D-Z5 (`docs/WAVE3-ADAPTER-PLUMBING-DESIGN.md` §D-Z5) revises what happens
+ * when `src/ui/game-state.tsx` is simply ABSENT: this function is now only
+ * ever called after a caller has confirmed (via `probeGameStateFileExists`)
+ * that the file genuinely exists, so the hard throw below is reserved for
+ * the file EXISTING but not exporting `GameProvider` correctly — a real bug,
+ * never swallowed. Absence itself degrades to the engine-published
+ * `GameProvider` (`@engine/react/game-state`) instead, at both call sites
+ * (`resolveDefaultReactAdapter` and `resolveIngestReactAdapter` below) — see
+ * `resolveGameProviderForProject`, the shared probe-then-load-or-fallback
+ * helper this revision introduces.
+ */
+async function loadProjectGameProvider(
+  projectRoot: string,
+): Promise<ComponentType<{ game: Game; children?: unknown }>> {
+  const modulePath = reactWorldProviderImportSpecifier(projectRoot);
+  const mod = (await import(/* @vite-ignore */ modulePath)) as {
+    GameProvider?: ComponentType<{ game: Game; children?: unknown }>;
+  };
+  if (typeof mod.GameProvider !== 'function') {
+    throw new Error(
+      'resolveWorldAdapter: could not find `GameProvider` at ' +
+        `"src/ui/game-state.tsx" under project root "${projectRoot}" — a react world's ` +
+        "mount needs the project's own GameProvider (docs/REACT-STATE-BRIDGE.md §2) so " +
+        "useGameState/useGame resolve against the SAME React context the entry's own code uses.",
+    );
+  }
+  return mod.GameProvider;
+}
+
+/**
+ * Resolve a `kind: 'react'` + `adapter: 'default'` world into a
+ * `ReactWorldAdapter` (docs/REACT-WORLD-DESIGN.md §1.B, T6.2 slice 1 task
+ * list's "Mount" item) — the react sibling of `resolveDefaultThreeAdapter`/
+ * `resolveDefaultPixiAdapter`. `entry` resolves via the SAME `/@fs/`
+ * dynamic-import route `loadProjectScripts` uses (`resolveDefaultPixiAdapter`'s
+ * own entry-adjudication precedent) — but a react entry module default-
+ * exports a component, not a `setup` function, so this reads the module
+ * directly rather than forcing it through `loadProjectScripts`'s
+ * `GameSetupFn`-shaped return.
+ *
+ * `mount(host)` follows the engine team's recorded recipe exactly:
+ * `createRoot(host.container).render(<GameProvider game={game}><Entry/></GameProvider>)`,
+ * returning `{ drivesOwnLoop: false, dispose: () => root.unmount() }`. See
+ * `hostGame`'s and `loadProjectGameProvider`'s doc comments above for the two
+ * honest gaps this depends on (the engine-merged `ReactWorldHost` not yet
+ * carrying `game`; `GameProvider` being a per-project file, not an export).
+ *
+ * D-Z5: `GameProvider` here comes from `resolveGameProviderForProject`, which
+ * now falls back to the engine-PUBLISHED `GameProvider`
+ * (`@engine/react/game-state`) plus a loud once-per-world report when the
+ * project ships no `src/ui/game-state.tsx` at all — this retires the former
+ * hard throw for that case (a project whose file EXISTS but is broken still
+ * throws for real; only genuine absence degrades). Safe by construction: the
+ * template's own `src/ui/game-state.tsx` is now itself a thin re-export of
+ * this same engine module (D-Z5 step 3), so a freshly scaffolded project's
+ * "present" and "absent" paths converge on the identical `GameProvider`
+ * either way.
+ *
+ * `scene` on a react world is a NAMED error (JSX-as-truth, D4 —
+ * docs/REACT-WORLD-DESIGN.md §1.A: "A react WORLD's truth is JSX source —
+ * … It is code; it never serializes to `ui` JSON" — there is no scene file
+ * format for a react world at all). The manifest loader's own
+ * `checkAdapterSceneEntryRules` only requires ONE of `scene`/`entry` for a
+ * `default`-adapter world (it does not forbid `scene` on a react world
+ * specifically — see `load.ts`), so this resolver is where the D4 rule is
+ * actually enforced for react worlds.
+ */
+
+/**
+ * The `default-react` shared entry-loading step, extracted (D-V3,
+ * docs/WAVE5-MULTIWORLD-INGEST-DESIGN.md) so a composite's `default-react`
+ * SIBLING mount (`packages/editor/src/ingest-siblings.ts`) can reuse the
+ * EXACT SAME D4 `scene`-forbidden / `entry`-required checks and
+ * `loadReactEntryComponent` shape validation `resolveDefaultReactAdapter`
+ * below uses, WITHOUT duplicating any of it — the sibling then renders the
+ * returned component BARE (no `<GameProvider>` wrap: there is no native
+ * `Game` beside an ingest world), while `resolveDefaultReactAdapter` wraps
+ * it in `<GameProvider>` as it always has. Exported for that one caller.
+ */
+export async function resolveReactWorldEntryComponent(
+  world: ResolvedWorldEntry,
+  projectRoot: string,
+): Promise<ComponentType> {
+  if (world.scene !== undefined) {
+    throw new Error(
+      `resolveWorldAdapter: world "${world.id}" (default-react) declares \`scene\` — react ` +
+        'worlds have no scene-file format: JSX source is the truth for a react world (D4, ' +
+        'docs/REACT-WORLD-DESIGN.md §1.A). Use `entry` (a .tsx module default-exporting a ' +
+        'component) instead.',
+    );
+  }
+  if (world.entry === undefined) {
+    // Unreachable in practice: `load.ts`'s `checkAdapterSceneEntryRules` requires
+    // `scene` or `entry` for every 'default' adapter world at manifest-load time,
+    // and the check above already rejects `scene` for a react world — so a real
+    // manifest can never reach this branch. Still fails loudly, not silently.
+    throw new Error(
+      `resolveWorldAdapter: world "${world.id}" is default-react with no \`entry\` — this should ` +
+        'have been rejected by manifest validation.',
+    );
+  }
+
+  const modulePath = fsImportPath(projectRoot, world.entry);
+  const mod = (await import(/* @vite-ignore */ modulePath)) as { default?: unknown };
+  return loadReactEntryComponent(world, mod);
+}
+
+async function resolveDefaultReactAdapter(
+  world: ResolvedWorldEntry,
+  projectRoot: string,
+): Promise<GameAdapter> {
+  const Entry = await resolveReactWorldEntryComponent(world, projectRoot);
+  const GameProvider = await resolveGameProviderForProject(projectRoot, world.id, 'default-react');
+
+  const adapter: ReactWorldAdapter = {
+    id: world.id,
+    async mount(host: ReactWorldHost): Promise<MountedReactGame> {
+      const game = hostGame(host);
+      if (!game) {
+        throw new Error(
+          `resolveWorldAdapter: world "${world.id}" (default-react) mount() received a ` +
+            'ReactWorldHost with no `game` — GameProvider needs a live Game at mount time and ' +
+            "this host did not carry one (see adapter-resolver.ts's `hostGame` doc comment for " +
+            'the engine-side gap this indicates).',
+        );
+      }
+      // C1: createElement/createRoot come from resolveReactWorldMountRuntime
+      // (the PROJECT's own react under the packaged runtime, this module's
+      // static imports otherwise) - never the module top-level statics
+      // directly, so this mount always shares ONE react instance with the
+      // entry component's own hooks. See that function's doc comment.
+      const runtime = await resolveReactWorldMountRuntime();
+      const root = runtime.createRoot(host.container);
+      root.render(
+        runtime.createElement(GameProvider, { game, children: runtime.createElement(Entry) }),
+      );
+      return {
+        kind: 'react',
+        container: host.container,
+        drivesOwnLoop: false,
+        dispose(): void {
+          root.unmount();
+        },
+      };
+    },
+  };
+  return adapter as unknown as GameAdapter;
+}
+
+// ---------------------------------------------------------------------------
+// Part G (Track N, N1 — docs/REACT-INGEST-LANDING-DESIGN.md D-N2/D-N3/D-N4) —
+// ingest-react
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve a `kind: 'react'` + `{ ingest: { strategy: 'deduped' } }` world into
+ * a `ReactWorldAdapter` — the ingest sibling of `resolveDefaultReactAdapter`
+ * immediately above. Mounts through the EXACT SAME T6.2 react host stack:
+ * the same `/@fs/` `entry`-module dynamic import, the same default-export-
+ * component validation (`loadReactEntryComponent`), the same per-project
+ * `GameProvider` wrap (`loadProjectGameProvider`), the same
+ * `createRoot(...).render(<GameProvider><Entry/></GameProvider>)` mount body.
+ * Only the adapter identity differs — D-N2's framing is explicit that this
+ * is "one stacking model, no special case": "the automatic `<GameProvider>`
+ * wrap is context-only and harmless to a foreign tree."
+ *
+ * `entry` here is NOT a first-party project's own react-world component —
+ * it is a HOST-SHIM module (D-N2) living beside the ingested game's per-game
+ * manifest (`packages/editor/src/ingest/games-react/<id>/`, N2), importing
+ * the vendored game's own `App`/store/`persistor` and default-exporting the
+ * composed component. This resolver has no knowledge of the vendored game's
+ * OWN standalone entry point (its raw `ReactDOM.render` call) either way —
+ * it only ever imports the manifest's declared `entry`, exactly like
+ * `default-react` — so that entry point is never reached through this path,
+ * matching D-N2's "never imported; it must never run."
+ *
+ * Two rules `default-react` does not need, both loud named errors — never a
+ * silent floor, matching every other ingest resolver in this file
+ * (`resolveIngestDescriptor`/`resolveIngest2DDescriptor` throw the same way
+ * for a strategy they can't build):
+ *
+ *  - `strategy` MUST be `'deduped'` — react ingestion v1 ships ONLY the
+ *    deduped rung (D-N3: "the vendored source is served through the
+ *    editor's own Vite pipeline… with react/react-dom deduped to the host's
+ *    React 19… an iframe/opaque-embed floor is recorded as out of scope for
+ *    v1"). Any other strategy is structurally legal at the manifest-load
+ *    layer (`load.ts` assigns `'ingest-react'` regardless of strategy,
+ *    exactly like `'ingest-three'`/`'ingest-pixi'` stay strategy-agnostic
+ *    there) but throws HERE, naming the strategy it actually got.
+ *  - `entry` is REQUIRED — there is no scene-or-entry choice the way
+ *    `default-three` has; an ingest-react world IS its host shim (D-N2).
+ *
+ * `scene` on an ingest-react world is already rejected before this function
+ * ever runs against a REAL manifest: `load.ts`'s `checkAdapterSceneEntryRules`
+ * forbids `scene` on any `{ ingest }`-adapter world, kind-agnostic. This
+ * function still guards it defensively (never trust a hand-built
+ * `ResolvedWorldEntry` a unit test — or a future caller — might construct
+ * past that check), with the same message shape `resolveDefaultReactAdapter`'s
+ * own `scene` check uses.
+ *
+ * D-N8 ("no authoring in v1") and D-N4 item 1 (no `writeBackend` for an
+ * ingest-react world): this function's return value is `{ id, mount }` only
+ * — structurally identical in shape to `resolveDefaultReactAdapter`'s return
+ * — there is no authoring/write-back hook anywhere on a `ReactWorldAdapter`
+ * for EITHER react identity. `ReactWorldAuthoringAdapter`/`writeBackend`
+ * wiring lives entirely outside this file, in `play-mode.ts`'s
+ * `installMultiWorldAuthoring`, keyed on `world.kind === 'react'` — not on
+ * adapter identity. That function is structurally unreachable for
+ * `ingest-react` today: `resolveAllWorlds`'s `MULTI_WORLD_ALLOWED_IDENTITIES`
+ * (below) deliberately excludes `'ingest-react'`, so an ingest-react world
+ * can only ever be the LONE world of a single-world manifest — and
+ * `play-mode.ts`'s single-world play branch calls `installPlayAuthoring`
+ * (wraps `getActiveAuthoring(store)`, the first-party
+ * `VgaiSceneAuthoringAdapter`) instead, for every world kind, never
+ * `installMultiWorldAuthoring`. So "no write-capable authoring surface" holds
+ * for `ingest-react` today by construction, not by an extra guard this
+ * function adds — recorded honestly here rather than claimed as this
+ * function's own achievement; see the N1 report for the residual this
+ * implies for N2 if react ingestion ever needs to join a multi-world
+ * manifest.
+ *
+ * D-Y3 (wave 2, docs/EXTERNAL-REACT-AND-MODULE-DESIGN.md §1) introduced ONE
+ * piece of the above: `loadProjectGameProvider`'s hard throw when
+ * `src/ui/game-state.tsx` is absent was right for `default-react` (a
+ * vgai-native world legitimately depends on the bridge) but wrong for
+ * `ingest-react` — a foreign tree ingested as-is has no reason to ship that
+ * file at all (it calls no vgai hooks unless its own shim explicitly wants
+ * them). `probeGameStateFileExists` checks (via a plain `fetch()` of the
+ * exact `/@fs/` path `loadProjectGameProvider` would import, mirroring
+ * `fetchScene2DFile`'s existing fetch-based existence check elsewhere in
+ * this file) whether the file is even THERE before ever calling the real
+ * loader.
+ *
+ * D-Z5 (`docs/WAVE3-ADAPTER-PLUMBING-DESIGN.md` §D-Z5) revises what D-Y3's
+ * "absent" branch DOES, for both react identities: absence now wraps with
+ * the engine-PUBLISHED `GameProvider` (`@engine/react/game-state`) instead
+ * of mounting unwrapped — safe because an unmodified foreign entry (or a
+ * project with no bridge file of its own) imports no vgai hooks bound to a
+ * DIFFERENT context, so there is no context-identity split to cause (see
+ * `packages/engine/src/react/game-state.tsx`'s module doc comment, and
+ * `game-state-context-split.test.tsx`'s red proof of what WOULD happen if a
+ * project's own copy were wrapped by the wrong provider). Presence still
+ * runs the real loader (so a game-state.tsx that EXISTS but is broken still
+ * throws its own real error loudly — the probe never swallows that, it only
+ * distinguishes "not there" from "there"). See `resolveGameProviderForProject`
+ * below, the shared probe-then-load-or-fallback helper both `default-react`
+ * and `ingest-react` now call.
+ */
+async function probeGameStateFileExists(projectRoot: string): Promise<boolean> {
+  const path = fsImportPath(projectRoot, 'src/ui/game-state.tsx');
+  const relative = resolveUrl(path);
+  // `fetch()` needs an absolute URL when there is no implicit browser
+  // document base to resolve a leading-slash path against (a real dev-server
+  // session always has one; a headless Node/vitest caller does not) — build
+  // one explicitly rather than relying on an environment-specific implicit
+  // base, so this probe behaves identically (and is mockable) in both.
+  const origin =
+    typeof window !== 'undefined' && window.location ? window.location.origin : 'http://localhost';
+  try {
+    const res = await fetch(new URL(relative, origin).toString());
+    // `res.ok` alone is NOT "the file exists": Vite's SPA fallback answers
+    // any unknown GET — including a missing `/@fs/…` path — with index.html
+    // and a 200, so on a real dev server the absence branch below was
+    // unreachable and a project genuinely shipping no `src/ui/game-state.tsx`
+    // crashed later inside `loadProjectGameProvider`'s synthetic re-export
+    // instead of degrading to the engine provider (found by the first such
+    // project: alien-stories' proto). A real hit comes back as transformed
+    // JS; only the fallback is `text/html`. (`headers` is optional-chained
+    // for partial `Response` stubs in tests.)
+    const contentType = res.headers?.get?.('content-type') ?? '';
+    return res.ok && !contentType.includes('text/html');
+  } catch {
+    // Fetch itself failing (network hiccup, no dev server route, …) is
+    // treated the same as "absent" — the honest fallback here is the
+    // engine-provider-plus-loud-report degrade (`resolveGameProviderForProject`),
+    // never a silent crash on an ambiguous probe failure.
+    return false;
+  }
+}
+
+/** Dedup key set for {@link reportEngineProviderFallbackOnce} — one
+ *  structured warning per (identity, world id) per session, mirroring
+ *  `runtime/game.ts`'s `reportGateShortfallOnce` "once per (kind, id)" idiom
+ *  (`docs/CAPABILITY-TIERS.md` §d's reporting precedent) rather than
+ *  re-logging on every mount of a session that re-enters the same world. */
+const REPORTED_ENGINE_PROVIDER_FALLBACK = new Set<string>();
+
+/**
+ * Greppable prefix for the D-Z5 "wrapped with the engine-published
+ * GameProvider" report — the renamed successor to wave-2's
+ * `INGEST_REACT_NO_PROVIDER_PREFIX` ("ingest-react-no-provider"), retired
+ * because that name described the OLD "mounted unwrapped" behavior; this
+ * fallback always wraps now, so the honest name says what actually happens.
+ * Shared by both `default-react` and `ingest-react` (D-Z5 extends the D-Y3
+ * ingest-only degrade to `default-react` too, since the template re-export
+ * — D-Z5 step 3 — landed in the same slice).
+ */
+export const ENGINE_GAME_PROVIDER_FALLBACK_PREFIX = 'engine-game-provider-fallback';
+
+/** Plain `console.warn` (not `editorConsole`) — same reasoning + idiom as
+ *  `runtime/game.ts`'s `reportGateShortfallOnce`: this resolver is imported
+ *  by headless Node/vitest suites with no `window`, and `editor-console.ts`
+ *  touches `window` unconditionally at its module top level, so a
+ *  first-class report here stays environment-neutral rather than forcing
+ *  every caller (test or real) to stub `window` just to see it. */
+function reportEngineProviderFallbackOnce(
+  identity: 'default-react' | 'ingest-react',
+  worldId: string,
+): void {
+  const key = `${identity}:${worldId}`;
+  if (REPORTED_ENGINE_PROVIDER_FALLBACK.has(key)) return;
+  REPORTED_ENGINE_PROVIDER_FALLBACK.add(key);
+  const locationText = identity === 'ingest-react' ? 'beside the manifest' : 'in this project';
+  // biome-ignore lint/suspicious/noConsole: structured, greppable — mirrors runtime/game.ts's reportGateShortfallOnce
+  console.warn(
+    `${ENGINE_GAME_PROVIDER_FALLBACK_PREFIX} world "${worldId}" (${identity}): no ` +
+      `src/ui/game-state.tsx ${locationText} — wrapping the entry with the engine-published ` +
+      'GameProvider (@engine/react/game-state) instead. useGameState/useGame work against the ' +
+      'engine bridge; ship your own src/ui/game-state.tsx to override with a custom bridge ' +
+      '(docs/WAVE3-ADAPTER-PLUMBING-DESIGN.md D-Z5, docs/REACT-STATE-BRIDGE.md §2/addendum). ' +
+      `${ENGINE_GAME_PROVIDER_FALLBACK_PREFIX} ${JSON.stringify({ worldId, identity })}`,
+  );
+}
+
+/**
+ * Shared probe-then-load-or-fallback helper (D-Z5) for both react
+ * identities: if the project ships `src/ui/game-state.tsx`, load it for real
+ * (`loadProjectGameProvider` — a file that exists but is broken still throws
+ * its own real error, never swallowed); if it's genuinely absent, fall back
+ * to the engine-published `GameProvider` and report once per (identity,
+ * world id). See the doc comment on `probeGameStateFileExists` above for the
+ * full D-Y3 -> D-Z5 history of this behavior.
+ *
+ * Exported (B1): `design-time-layers.ts` needs this SAME per-project
+ * resolution (a project's own `src/ui/game-state.tsx`, when present, has its
+ * own `createContext()` — wrapping it with the wrong `GameProvider` splits
+ * context and `useGame()` throws even though a provider IS in the tree, see
+ * `@engine/react/game-state`'s module doc comment) for its design-time react
+ * layer mount, rather than re-deriving project-vs-engine provider resolution.
+ */
+export async function resolveGameProviderForProject(
+  projectRoot: string,
+  worldId: string,
+  identity: 'default-react' | 'ingest-react',
+): Promise<ComponentType<{ game: Game; children?: unknown }>> {
+  const hasGameProvider = await probeGameStateFileExists(projectRoot);
+  if (hasGameProvider) {
+    return loadProjectGameProvider(projectRoot);
+  }
+  reportEngineProviderFallbackOnce(identity, worldId);
+  // C1: the engine-published `GameProvider` fallback itself must come from
+  // the SAME react instance the mount's `createRoot`/the entry component's
+  // hooks use — under the packaged runtime that is the PROJECT's react, not
+  // this module's own static `EngineGameProvider` import (the editor's
+  // separately-bundled copy). `resolveReactWorldMountRuntime` already
+  // encapsulates the dev/Electron-vs-packaged gate (byte-identical to the
+  // old `EngineGameProvider as unknown as …` cast when not packaged); reuse
+  // it here instead of re-deriving the gate.
+  const runtime = await resolveReactWorldMountRuntime();
+  return runtime.engineGameProvider;
+}
+
+async function resolveIngestReactAdapter(
+  world: ResolvedWorldEntry,
+  projectRoot: string,
+): Promise<GameAdapter> {
+  const { adapter } = world;
+  if (adapter.type !== 'ingest') {
+    throw new Error(`resolveWorldAdapter: world "${world.id}" is not an { ingest } world.`);
+  }
+  if (adapter.strategy !== 'deduped') {
+    throw new Error(
+      `resolveWorldAdapter: world "${world.id}" (ingest-react) declares strategy ` +
+        `"${adapter.strategy}" — react ingestion v1 supports ONLY the 'deduped' rung (loud ` +
+        'degrade, no silent floor: docs/REACT-INGEST-LANDING-DESIGN.md D-N3). An iframe-' +
+        'reachable/opaque-embed floor is explicitly out of scope for v1.',
+    );
+  }
+  if (world.scene !== undefined) {
+    throw new Error(
+      `resolveWorldAdapter: world "${world.id}" (ingest-react) declares \`scene\` — react ` +
+        'worlds have no scene-file format: JSX source is the truth for a react world (D4, ' +
+        'docs/REACT-WORLD-DESIGN.md §1.A), and an ingested react world doubly so — the vendored ' +
+        'game is never modified. Use `entry` (the host-shim module, D-N2) instead.',
+    );
+  }
+  if (world.entry === undefined) {
+    throw new Error(
+      `resolveWorldAdapter: world "${world.id}" (ingest-react) has no \`entry\` — an ingested ` +
+        "react world's `entry` MUST point at a host-shim module that imports the vendored " +
+        "game's own component and default-exports it (D-N2, docs/REACT-INGEST-LANDING-DESIGN.md).",
+    );
+  }
+
+  const modulePath = fsImportPath(projectRoot, world.entry);
+  const mod = (await import(/* @vite-ignore */ modulePath)) as { default?: unknown };
+  const Entry = loadReactEntryComponent(world, mod, 'ingest-react');
+  // D-Z5: always resolves to SOME GameProvider now — the project's own
+  // (present) or the engine-published fallback + a loud report (absent). See
+  // `resolveGameProviderForProject`'s doc comment for the full history.
+  const GameProvider = await resolveGameProviderForProject(projectRoot, world.id, 'ingest-react');
+
+  const reactAdapter: ReactWorldAdapter = {
+    id: world.id,
+    async mount(host: ReactWorldHost): Promise<MountedReactGame> {
+      const game = hostGame(host);
+      if (!game) {
+        throw new Error(
+          `resolveWorldAdapter: world "${world.id}" (ingest-react) mount() received a ` +
+            'ReactWorldHost with no `game` — GameProvider needs a live Game at mount time and ' +
+            "this host did not carry one (see adapter-resolver.ts's `hostGame` doc comment for " +
+            'the engine-side gap this indicates).',
+        );
+      }
+      // C1: createElement/createRoot come from resolveReactWorldMountRuntime
+      // (the PROJECT's own react under the packaged runtime, this module's
+      // static imports otherwise) - never the module top-level statics
+      // directly, so this mount always shares ONE react instance with the
+      // entry component's own hooks. See that function's doc comment.
+      const runtime = await resolveReactWorldMountRuntime();
+      const root = runtime.createRoot(host.container);
+      root.render(
+        runtime.createElement(GameProvider, { game, children: runtime.createElement(Entry) }),
+      );
+      return {
+        kind: 'react',
+        container: host.container,
+        drivesOwnLoop: false,
+        dispose(): void {
+          root.unmount();
+        },
+      };
+    },
+  };
+  return reactAdapter as unknown as GameAdapter;
+}
+
+// ---------------------------------------------------------------------------
+// Part A/D — ingest-three
+// ---------------------------------------------------------------------------
+
+/**
+ * Fetch a project-relative file's TEXT bytes through the dev-server-only
+ * `/project-game-static/<path>` route (D-W2, docs/WAVE4-FTUE-HARDENING-
+ * DESIGN.md) — the opaque-embed floor's file read, shared by BOTH kinds
+ * (`resolveIngestDescriptor`/`resolveIngest2DDescriptor` below): the route
+ * serves the CURRENTLY OPEN project's folder verbatim
+ * (`vite-plugin-project-game-static.ts`), so a manifest's `entryHtml` (a
+ * project-relative path, exactly like the in-tree fixture glob's `entryHtml`
+ * convention) maps directly to `/project-game-static/<entryHtml>`. Absolute
+ * URL construction mirrors `probeGameStateFileExists`'s origin handling
+ * above (a real dev-server session has an implicit browser document base; a
+ * headless Node/vitest caller does not — build one explicitly so this stays
+ * mockable/testable in both).
+ */
+async function fetchProjectStaticText(entryHtmlPath: string): Promise<string> {
+  const rel = entryHtmlPath.startsWith('/') ? entryHtmlPath.slice(1) : entryHtmlPath;
+  const url = `/project-game-static/${rel}`;
+  const origin =
+    typeof window !== 'undefined' && window.location ? window.location.origin : 'http://localhost';
+  const res = await fetch(new URL(url, origin).toString());
+  if (!res.ok) {
+    throw new Error(
+      `resolveIngestDescriptor: failed to load opaque-embed entryHtml "${entryHtmlPath}" via ` +
+        `${url} (${res.status} ${res.statusText}).`,
+    );
+  }
+  return res.text();
+}
+
+/**
+ * The `iframe-reachable` branch of {@link resolveIngestDescriptor} — the
+ * three-side twin of `resolveIngest2DDescriptor`'s
+ * `buildIframeReachableDescriptor2D`, split out for the same cognitive-
+ * complexity reason (biome's `noExcessiveCognitiveComplexity`). `bundleUrl`
+ * is required (an `entryHtml`-only iframe-reachable world stays an unwired
+ * named error, same text pattern pixi's sibling uses); a `pixiModuleUrl`
+ * declared on a threejs world is a DIFFERENT named error — three has no
+ * version-skew mount this wave (D-W7 explicitly parks a hypothetical
+ * `threeModuleUrl` field: "no consumer exists").
+ */
+function buildIframeReachableIngestDescriptor(
+  world: ResolvedWorldEntry,
+  adapter: Extract<ResolvedWorldEntry['adapter'], { type: 'ingest' }>,
+  base: Pick<
+    IngestGame,
+    'id' | 'name' | 'description' | 'assets' | 'domStubs' | 'captureTimeoutMs'
+  >,
+): IngestGame {
+  if (adapter.pixiModuleUrl !== undefined) {
+    throw new Error(
+      `resolveIngestDescriptor: world "${world.id}" (kind threejs, strategy ` +
+        '"iframe-reachable") declares `pixiModuleUrl` — that field is pixi-specific version-' +
+        'skew wiring (a standalone matching-major pixi build to trap instead of the host pixi) ' +
+        'with no threejs equivalent implemented this wave: D-W7 explicitly parks a hypothetical ' +
+        '`threeModuleUrl` field (docs/WAVE4-FTUE-HARDENING-DESIGN.md) — "no consumer exists".',
+    );
+  }
+  if (!adapter.bundleUrl) {
+    throw new Error(
+      `resolveIngestDescriptor: world "${world.id}" (strategy "iframe-reachable") has no ` +
+        '`bundleUrl` — only the externalized-bundle route is buildable here (an ' +
+        "`entryHtml`-only iframe-reachable world isn't wired; the manifest schema already " +
+        'requires exactly one of bundleUrl/entryHtml for this strategy).',
+    );
+  }
+  const { bundleUrl, baseHref, assetBaseUrl, extraDeps, bodyHtml } = adapter;
+  return {
+    ...base,
+    bundleUrl,
+    ...(baseHref !== undefined ? { baseHref } : {}),
+    ...(assetBaseUrl !== undefined ? { assetBaseUrl } : {}),
+    ...(extraDeps !== undefined ? { extraDeps: () => resolveExtraDeps(extraDeps) } : {}),
+    ...(bodyHtml !== undefined ? { bodyHtml } : {}),
+  };
+}
+
+/**
+ * The `opaque-embed` branch of {@link resolveIngestDescriptor} (D-W2): reads
+ * the declared `entryHtml` file's bytes through {@link fetchProjectStaticText}
+ * as a LAZY thunk on the descriptor — never eagerly, only when the game is
+ * actually mounted (`enterIngestModeWithGame` awaits `game.embedHtml()`).
+ */
+function buildOpaqueEmbedIngestDescriptor(
+  world: ResolvedWorldEntry,
+  adapter: Extract<ResolvedWorldEntry['adapter'], { type: 'ingest' }>,
+  base: Pick<
+    IngestGame,
+    'id' | 'name' | 'description' | 'assets' | 'domStubs' | 'captureTimeoutMs'
+  >,
+): IngestGame {
+  if (!adapter.entryHtml) {
+    throw new Error(
+      `resolveIngestDescriptor: world "${world.id}" (strategy "opaque-embed") has no ` +
+        '`entryHtml` — the opaque-embed floor needs the entry HTML file path to read (D-W2, ' +
+        'docs/WAVE4-FTUE-HARDENING-DESIGN.md).',
+    );
+  }
+  const entryHtml = adapter.entryHtml;
+  return { ...base, embedHtml: () => fetchProjectStaticText(entryHtml) };
+}
+
+/**
+ * Build the {@link IngestGame} descriptor an `ingest-three` world resolves
+ * to, straight from its manifest fields — deliberately WITHOUT looking up any
+ * registry. This is the part of §1D that "parameterizes by the manifest's
+ * ingest fields rather than a registry id" — and, as of T3.3 slice 3
+ * (§1E), there IS no registry left to look up: `ingest/games/registry.ts`
+ * (`INGEST_GAMES`) is deleted; the in-tree fixture games it used to list are
+ * discovered separately by `ingest/discovery.ts` (`import.meta.glob` over
+ * `./games/*\/vgai.game.json`, NOT through this function — see that file's
+ * doc comment for why). This function stays the builder for the OTHER half
+ * of §1E: an arbitrary manifest-backed project folder never registered in
+ * source (the CLI-on-folder route), whose `ingest-three` world this function
+ * turns into a mountable descriptor via `/@fs/${projectRoot}/...`.
+ *
+ * `shared`/`deduped` resolve to `IngestGame.load` via the same `/@fs/`
+ * dynamic-import route `loadProjectScripts` uses, keyed off the world's
+ * `entry` field. D-W1 (docs/WAVE4-FTUE-HARDENING-DESIGN.md) adds
+ * `iframe-reachable`: the manifest's `bundleUrl`/`baseHref`/`assetBaseUrl`/
+ * `bodyHtml` are carried straight through, `extraDeps` becomes a LAZY thunk
+ * (`IngestGame.extraDeps`) wired to `./ingest/host-namespace-registry.ts` —
+ * resolved only when the ingest-mode mount bridge actually invokes it, never
+ * eagerly here (this function stays synchronous). D-W2 adds `opaque-embed`:
+ * the declared `entryHtml`'s bytes, read through the project-static route as
+ * a lazy `embedHtml` thunk. `iframe-reachable`+`entryHtml`-only (no
+ * `bundleUrl`) stays an unwired named error on this kind too (mirrors the
+ * pixi sibling): reading a raw inline-module-source file's contents into a
+ * SHARED-instance-mounted string has no wired mechanism this wave.
+ */
+export function resolveIngestDescriptor(
+  world: ResolvedWorldEntry,
+  projectRoot: string,
+): IngestGame {
+  const { adapter } = world;
+  if (adapter.type !== 'ingest') {
+    throw new Error(`resolveIngestDescriptor: world "${world.id}" is not an { ingest } world.`);
+  }
+
+  const base: Pick<
+    IngestGame,
+    'id' | 'name' | 'description' | 'assets' | 'domStubs' | 'captureTimeoutMs'
+  > = {
+    id: world.id,
+    name: world.id,
+    // T3.3 slice 3: `description` is the manifest's new optional per-world
+    // field (schema.ts) — carried through `load.ts`'s `resolveWorld`, threaded
+    // here into `IngestGame.description` (the field's designated reader).
+    description: world.description ?? '',
+    ...(adapter.assets !== undefined ? { assets: adapter.assets } : {}),
+    ...(adapter.domStubs !== undefined ? { domStubs: adapter.domStubs } : {}),
+    ...(adapter.captureTimeoutMs !== undefined
+      ? { captureTimeoutMs: adapter.captureTimeoutMs }
+      : {}),
+  };
+
+  if (adapter.strategy === 'shared' || adapter.strategy === 'deduped') {
+    if (!world.entry) {
+      throw new Error(
+        `resolveIngestDescriptor: world "${world.id}" (strategy "${adapter.strategy}") has no ` +
+          "`entry` — shared/deduped ingest worlds need the game module's path there.",
+      );
+    }
+    const modulePath = fsImportPath(projectRoot, world.entry);
+    return { ...base, load: () => import(/* @vite-ignore */ modulePath) };
+  }
+
+  if (adapter.strategy === 'iframe-reachable') {
+    return buildIframeReachableIngestDescriptor(world, adapter, base);
+  }
+
+  if (adapter.strategy === 'opaque-embed') {
+    return buildOpaqueEmbedIngestDescriptor(world, adapter, base);
+  }
+
+  // Exhaustive per IngestStrategySchema's 4 members.
+  const exhaustive: never = adapter.strategy;
+  throw new Error(
+    `resolveIngestDescriptor: world "${world.id}" has an unhandled ingest strategy ` +
+      `${JSON.stringify(exhaustive)}.`,
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Part E (T6.1 slice 4) — ingest-pixi
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the {@link IngestGame2D} descriptor an `ingest-pixi` world resolves to,
+ * straight from its manifest fields — the pixi sibling of
+ * {@link resolveIngestDescriptor} (docs/MULTI-WORLD-DESIGN.md §1.E: "the same
+ * two-layer shape as ingest-three"). `shared`/`deduped` resolve to a `load()`
+ * thunk via the `/@fs/` dynamic-import route `loadProjectScripts` uses, keyed
+ * off the world's `entry` field. Track P (docs/PIXI-INGEST-LANDING-DESIGN.md
+ * §2/P2) adds `iframe-reachable`: the manifest's `bundleUrl`/`baseHref`/
+ * `assetBaseUrl`/`bodyHtml` are carried straight through, and `extraDeps`/
+ * `pixiModuleUrl` become LAZY thunks (`IngestGame2D.extraDeps`/
+ * `.pixiNamespace`) wired to `./ingest/host-namespace-registry.ts` / a
+ * dynamic `import()` — resolved only when the ingest-mode mount bridge
+ * actually invokes them, never eagerly here (this function stays
+ * synchronous, matching `resolveIngestDescriptor`'s shape exactly). D-W2
+ * (docs/WAVE4-FTUE-HARDENING-DESIGN.md) adds `opaque-embed`: the declared
+ * `entryHtml`'s bytes, read through the project-static route
+ * (`fetchProjectStaticText`, shared with the three side above) as a lazy
+ * `embedHtml` thunk.
+ *
+ * `tier` is set to `'shared'` for BOTH the `shared` and `deduped` manifest
+ * strategies: `IngestGame2D.tier` is descriptive-only (`mountIngestGame2D`
+ * never reads it — grep-verified) and has no `'deduped'` member of its own;
+ * both strategies are mechanically identical from `mountIngestGame2D`'s
+ * perspective (a `load()` thunk + the shared-instance capture trap), matching
+ * how `resolveIngestDescriptor` already treats them identically (both produce
+ * a `load` thunk with no strategy-specific branching).
+ */
+/**
+ * The `iframe-reachable` branch of {@link resolveIngest2DDescriptor}, split
+ * out to keep that function's cognitive complexity in check (biome's
+ * `noExcessiveCognitiveComplexity`, max 15) — same "each strategy branch is
+ * its own small builder" shape `discovery2d.ts`'s
+ * `buildIframeReachableGame2D` already uses for its in-tree-fixture sibling.
+ */
+function buildIframeReachableDescriptor2D(
+  world: ResolvedWorldEntry,
+  adapter: Extract<ResolvedWorldEntry['adapter'], { type: 'ingest' }>,
+  base: Pick<IngestGame2D, 'id' | 'name' | 'description' | 'captureTimeoutMs'>,
+): IngestGame2D {
+  if (!adapter.bundleUrl) {
+    throw new Error(
+      `resolveIngest2DDescriptor: world "${world.id}" (strategy "iframe-reachable") has no ` +
+        '`bundleUrl` — only the externalized-bundle route is buildable here (an ' +
+        "`entryHtml`-only iframe-reachable world isn't wired; the manifest schema already " +
+        'requires exactly one of bundleUrl/entryHtml for this strategy).',
+    );
+  }
+  const { bundleUrl, baseHref, assetBaseUrl, extraDeps, pixiModuleUrl, bodyHtml } = adapter;
+  return {
+    ...base,
+    tier: 'iframe-reachable',
+    bundleUrl,
+    ...(baseHref !== undefined ? { baseHref } : {}),
+    ...(assetBaseUrl !== undefined ? { assetBaseUrl } : {}),
+    ...(extraDeps !== undefined ? { extraDeps: () => resolveExtraDeps(extraDeps) } : {}),
+    ...(pixiModuleUrl !== undefined
+      ? { pixiNamespace: () => import(/* @vite-ignore */ pixiModuleUrl) }
+      : {}),
+    ...(bodyHtml !== undefined ? { bodyHtml } : {}),
+  };
+}
+
+export function resolveIngest2DDescriptor(
+  world: ResolvedWorldEntry,
+  projectRoot: string,
+): IngestGame2D {
+  const { adapter } = world;
+  if (adapter.type !== 'ingest') {
+    throw new Error(`resolveIngest2DDescriptor: world "${world.id}" is not an { ingest } world.`);
+  }
+
+  const base: Pick<IngestGame2D, 'id' | 'name' | 'description' | 'captureTimeoutMs'> = {
+    id: world.id,
+    name: world.id,
+    description: world.description ?? '',
+    ...(adapter.captureTimeoutMs !== undefined
+      ? { captureTimeoutMs: adapter.captureTimeoutMs }
+      : {}),
+  };
+
+  if (adapter.strategy === 'shared' || adapter.strategy === 'deduped') {
+    if (!world.entry) {
+      throw new Error(
+        `resolveIngest2DDescriptor: world "${world.id}" (strategy "${adapter.strategy}") has no ` +
+          "`entry` — shared/deduped ingest-pixi worlds need the game module's path there.",
+      );
+    }
+    const modulePath = fsImportPath(projectRoot, world.entry);
+    return { ...base, tier: 'shared', load: () => import(/* @vite-ignore */ modulePath) };
+  }
+
+  if (adapter.strategy === 'iframe-reachable') {
+    return buildIframeReachableDescriptor2D(world, adapter, base);
+  }
+
+  if (adapter.strategy === 'opaque-embed') {
+    if (!adapter.entryHtml) {
+      throw new Error(
+        `resolveIngest2DDescriptor: world "${world.id}" (strategy "opaque-embed") has no ` +
+          '`entryHtml` — the opaque-embed floor needs the entry HTML file path to read (D-W2, ' +
+          'docs/WAVE4-FTUE-HARDENING-DESIGN.md).',
+      );
+    }
+    const entryHtml = adapter.entryHtml;
+    return { ...base, tier: 'opaque-embed', embedHtml: () => fetchProjectStaticText(entryHtml) };
+  }
+
+  // Exhaustive per IngestStrategySchema's 4 members.
+  const exhaustive: never = adapter.strategy;
+  throw new Error(
+    `resolveIngest2DDescriptor: world "${world.id}" has an unhandled ingest strategy ` +
+      `${JSON.stringify(exhaustive)}.`,
+  );
+}
+
+/**
+ * Same shape as {@link resolveIngestThreeAdapter}: the pixi world2d ingest
+ * machinery (`mountIngestGame2D`, `World2DAuthoringAdapter`) needs an
+ * `EditorStore` and a dedicated game-container element that `HostContext`
+ * does not provide — so this resolver does NOT attempt to make ingest-pixi
+ * mountable through the generic `GameAdapter`/`HostContext` contract. It
+ * returns a `GameAdapter` whose `id`/`descriptor` are built straight from the
+ * manifest, and whose `mount()` throws a named error pointing at the real
+ * mount path: `resolveIngest2DDescriptor` + `enterIngestModeFromManifestWorld2D`
+ * (`ingest-mode.ts`), called from an ingest-mode-shaped flow that has a store
+ * and a container — exactly `enterIngestModeFromManifestWorld`'s three-side
+ * counterpart.
+ */
+function resolveIngestPixiAdapter(world: ResolvedWorldEntry, projectRoot: string): GameAdapter {
+  const descriptor = resolveIngest2DDescriptor(world, projectRoot);
+  return {
+    id: world.id,
+    /** Exposed for slice-4 callers that want the descriptor without re-deriving it. */
+    descriptor,
+    async mount() {
+      throw new Error(
+        `resolveWorldAdapter: world "${world.id}" (ingest-pixi) cannot mount through the ` +
+          'generic GameAdapter/HostContext contract — the world2d ingest machinery ' +
+          '(mountIngestGame2D + World2DAuthoringAdapter) requires an EditorStore and a ' +
+          'dedicated game-container element that HostContext does not provide (mirrors the ' +
+          "ingest-three finding, see resolveIngestPixiAdapter's doc comment). Call " +
+          'resolveIngest2DDescriptor() + enterIngestModeFromManifestWorld2D() directly from an ' +
+          'ingest-mode-shaped flow instead (ingest-mode.ts).',
+      );
+    },
+  } as GameAdapter & { descriptor: IngestGame2D };
+}
+
+/**
+ * FINDING (report this prominently, see the slice's "Report back"):
+ * `mountIngestGame`/`mountIngestGameIframeReachable`
+ * (`packages/editor/src/authoring/ingest-game-adapter.ts`,
+ * `ingest-iframe-reachable-adapter.ts`) are NOT shaped like
+ * `GameAdapter.mount(host: HostContext)` — they require an `EditorStore`
+ * (threaded straight into `new IngestAuthoringAdapter(store, ...)` for
+ * selection/undo wiring) and a dedicated game-container `HTMLElement`
+ * (`ingest-mode.ts`'s `getGameContainer()`), neither of which `HostContext`
+ * carries (`packages/engine/src/adapter/host-context.ts` — by design: it is
+ * the NEUTRAL surface any game gets, and an `EditorStore` is an editor-only
+ * concept). Building a second, `HostContext`-only capture path that skips the
+ * authoring adapter would duplicate ~most of `mountIngestGame`'s body
+ * (capture install, asset-URL modifier, DOM stubs, settle-wait, teardown) and
+ * risk the two drifting — exactly the "half-refactor" the slice's brief
+ * warns against. So this resolver does NOT attempt to make ingest-three
+ * mountable through the generic contract: it returns a `GameAdapter` whose
+ * `id` and descriptor are built straight from the manifest (no registry
+ * lookup — the AC this slice's tests hold it to), and whose `mount()` throws
+ * a named error pointing at the real mount path
+ * (`resolveIngestDescriptor` + `mountIngestGame`/
+ * `mountIngestGameIframeReachable`, called from an ingest-mode-shaped flow
+ * that has a store and a container). T3.3 slice 3 wires exactly that flow:
+ * `ingest-mode.ts`'s `enterIngestModeFromManifestWorld` calls
+ * `resolveIngestDescriptor` + the existing `enterIngestModeWithGame` (which
+ * already has both a store and `getGameContainer()`), satisfying slice 3's AC
+ * ("point the CLI at an ingest game folder never registered in source ->
+ * opens, plays, edits" — docs/CLI-ON-FOLDER-DESIGN.md §4) for the
+ * `shared`/`deduped` strategies this function builds.
+ */
+function resolveIngestThreeAdapter(world: ResolvedWorldEntry, projectRoot: string): GameAdapter {
+  const descriptor = resolveIngestDescriptor(world, projectRoot);
+  return {
+    id: world.id,
+    /** Exposed for slice-3 callers that want the descriptor without re-deriving it. */
+    descriptor,
+    async mount() {
+      throw new Error(
+        `resolveWorldAdapter: world "${world.id}" (ingest-three) cannot mount through the ` +
+          'generic GameAdapter/HostContext contract — the existing ingest machinery ' +
+          '(mountIngestGame/mountIngestGameIframeReachable) requires an EditorStore and a ' +
+          'dedicated game-container element that HostContext does not provide (T3.3 slice 2 ' +
+          "finding, see adapter-resolver.ts's resolveIngestThreeAdapter doc comment). Call " +
+          'resolveIngestDescriptor() + mountIngestGame() directly from an ingest-mode-shaped ' +
+          'flow instead; full CLI-on-folder ingest wiring is T3.3 slice 3.',
+      );
+    },
+  } as GameAdapter & { descriptor: IngestGame };
+}
+
+// ---------------------------------------------------------------------------
+// Part F (T3.4 slice 1) — module (docs/ADAPTER-AUTHORING-DESIGN.md §1.A/§1.C)
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate `adapter.module` is a game-folder-RELATIVE path with no `..`
+ * escape (§1.A: "validated game-folder-relative (normalized, no `..` escape —
+ * the same rule the save-file endpoint enforces)"). This resolver runs
+ * browser-side (no `node:path`), so the guard is hand-rolled by segment —
+ * `packages/editor/server/editor-server.ts`'s `/__editor/save-file` handler is
+ * the Node-side sibling this mirrors (reject empty, reject any `..` segment,
+ * reject an absolute/rooted path); there is no reusable isomorphic helper in
+ * the codebase today (`storage/paths.ts`'s `normalize()` collapses `.`
+ * segments but deliberately does NOT reject `..` — a different job, key
+ * canonicalization for the storage backends, not a trust-boundary check).
+ * Returns the normalized (slash-joined, no leading/trailing slash) path.
+ */
+export function guardModulePath(world: ResolvedWorldEntry, moduleId: string): string {
+  const fail = (reason: string): never => {
+    throw new Error(
+      `resolveWorldAdapter: world "${world.id}" declares { module: "${moduleId}" } — ${reason} ` +
+        '(docs/ADAPTER-AUTHORING-DESIGN.md §1.A: the module path must be game-folder-relative, ' +
+        'normalized, with no `..` escape — the same rule the save-file endpoint enforces).',
+    );
+  };
+
+  if (!moduleId || moduleId.trim() === '') fail('the module path is empty');
+  if (moduleId.includes('\\')) fail('the module path contains a backslash (not POSIX-relative)');
+  if (moduleId.startsWith('/') || /^[a-zA-Z]:/.test(moduleId)) {
+    fail('the module path is absolute, not game-folder-relative');
+  }
+
+  const segments = moduleId.split('/');
+  if (segments.some((seg) => seg === '..')) {
+    fail('the module path contains a `..` segment and would escape the game folder');
+  }
+  const normalized = segments.filter((seg) => seg.length > 0 && seg !== '.').join('/');
+  if (normalized === '') fail('the module path resolves to nothing (empty after normalization)');
+
+  return normalized;
+}
+
+/** Runtime shape every `GameAdapter` must satisfy — the module branch cannot
+ *  trust TypeScript alone (the imported value is `unknown` until checked). */
+function guardModuleShape(
+  world: ResolvedWorldEntry,
+  moduleId: string,
+  candidate: unknown,
+): asserts candidate is GameAdapter {
+  const fail = (reason: string): never => {
+    throw new Error(
+      `resolveWorldAdapter: world "${world.id}"'s custom adapter module "${moduleId}" ${reason} ` +
+        '— a { module } adapter must default-export an object shaped like `GameAdapter`: ' +
+        '`{ id: string, mount(host): Promise<MountedGame> }` (docs/ADAPTER-AUTHORING-DESIGN.md §1.A).',
+    );
+  };
+
+  if (candidate === null || typeof candidate !== 'object') {
+    fail('has no default export (or it is not an object)');
+  }
+  const obj = candidate as Record<string, unknown>;
+  if (typeof obj['id'] !== 'string' || obj['id'].length === 0) {
+    fail('default-exports an object with no non-empty string `id`');
+  }
+  if (typeof obj['mount'] !== 'function') {
+    fail('default-exports an object with no `mount` function');
+  }
+}
+
+/**
+ * Wrap a custom adapter's `mount` so that, once it resolves, the ACHIEVED
+ * tier is computed from the real `MountedGame.authoring` surface and compared
+ * against the world's declared `capabilities.local` (§1.C). `/@fs/` module
+ * imports only run in the local CLI dev server (`getEditorMode() ===
+ * 'server'` — see `editor-mode.ts`; the hosted/browser build has no such
+ * import route, matching this design's non-goal "hosted-context module
+ * adapters beyond honest tier declaration"), so `local` is the context this
+ * resolver actually mounts under. A shortfall never blocks the mount — the
+ * world still returns its (unmodified) `MountedGame`; the check only OBSERVES
+ * and logs (§1.C: "the world still mounts at its achieved tier").
+ *
+ * The actual `editorConsole.warn(...)` call is a LAZY dynamic import of
+ * `./editor-console`, not a static one: this resolver is imported by headless
+ * Node/vitest suites with no `window` (`adapter-resolver.test.ts` et al.),
+ * and `editor-console.ts`'s module top level touches `window`
+ * unconditionally. A static import would break every existing Node suite
+ * that imports this resolver; `import()` only evaluates that module the
+ * first time a shortfall is actually reported (at which point a real
+ * `window` is expected to exist — the module-adapter mount path only runs
+ * inside the editor's dev-server browser session, per the note above).
+ */
+function withAchievedTierCheck(world: ResolvedWorldEntry, adapter: GameAdapter): GameAdapter {
+  return {
+    id: adapter.id,
+    async mount(host) {
+      const mounted = await adapter.mount(host);
+      const shortfall = computeTierShortfall(
+        world.id,
+        world.capabilities.local,
+        computeAchievedTier(mounted),
+      );
+      if (shortfall) {
+        const { editorConsole } = await import('./editor-console');
+        editorConsole.warn(formatTierShortfallMessage(shortfall), 'adapter');
+      }
+      return mounted;
+    },
+  };
+}
+
+/**
+ * Resolve a `{ module }` adapter world (§1.A): `/@fs/`-import the game
+ * folder's declared module — the exact route `loadProjectScripts` uses for
+ * `default-three`'s `entry` branch (`./script-loader.ts`), so it inherits the
+ * SAME `resolve.dedupe: ['three', 'pixi.js']` collapse the root
+ * `vite.config.ts` already applies repo-wide (proven for THIS path by
+ * `vite-dedupe-module-adapter.test.ts`'s own fixture — §1.A: "Dedupe is NOT
+ * inherited silently"). Path-guarded (`guardModulePath`) before the import,
+ * shape-checked (`guardModuleShape`) after — both loud, named failures, never
+ * a silent `undefined`/crash deep in the mount call. The returned adapter's
+ * `mount` is wrapped with the achieved-tier check (§1.C, `withAchievedTierCheck`).
+ */
+export async function resolveModuleAdapter(
+  world: ResolvedWorldEntry,
+  projectRoot: string,
+): Promise<GameAdapter> {
+  const { adapter } = world;
+  if (adapter.type !== 'module') {
+    throw new Error(`resolveModuleAdapter: world "${world.id}" is not a { module } world.`);
+  }
+
+  const normalizedPath = guardModulePath(world, adapter.module);
+  const modulePath = fsImportPath(projectRoot, normalizedPath);
+  const mod = (await import(/* @vite-ignore */ modulePath)) as { default?: unknown };
+  const candidate = mod.default;
+  guardModuleShape(world, adapter.module, candidate);
+
+  return withAchievedTierCheck(world, candidate);
+}
+
+// ---------------------------------------------------------------------------
+// Entry point
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve a manifest world entry into a mountable {@link GameAdapter}
+ * (docs/CLI-ON-FOLDER-DESIGN.md §1D). Instantiation only — the returned
+ * adapter is not yet mounted; call `.mount(host)` to run it (see each
+ * identity's doc comment above for what that does or doesn't support today).
+ */
+export async function resolveWorldAdapter(
+  world: ResolvedWorldEntry,
+  projectRoot: string,
+  opts?: ResolveWorldAdapterOptions,
+): Promise<GameAdapter> {
+  const { adapter } = world;
+
+  switch (adapter.identity) {
+    case 'default-three':
+      return resolveDefaultThreeAdapter(world, projectRoot, opts);
+    case 'default-pixi':
+      return resolveDefaultPixiAdapter(world, projectRoot);
+    case 'default-react':
+      return resolveDefaultReactAdapter(world, projectRoot);
+    case 'module':
+      return resolveModuleAdapter(world, projectRoot);
+    case 'ingest-pixi':
+      return resolveIngestPixiAdapter(world, projectRoot);
+    case 'ingest-three':
+      return resolveIngestThreeAdapter(world, projectRoot);
+    case 'ingest-react':
+      return resolveIngestReactAdapter(world, projectRoot);
+    default: {
+      const exhaustive: never = adapter;
+      throw new Error(
+        `resolveWorldAdapter: unhandled adapter identity ${JSON.stringify(exhaustive)}`,
+      );
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Multi-world entry point (T6.1 slice 2 — docs/MULTI-WORLD-DESIGN.md §3 slice 2)
+// ---------------------------------------------------------------------------
+
+/**
+ * Adapter identities a manifest with MORE THAN ONE world may mix in this
+ * slice (docs/MULTI-WORLD-DESIGN.md §3 slice 4's scope rule, extended by
+ * docs/REACT-WORLD-DESIGN.md §3 slice 1/3 to admit `default-react`): only
+ * `'default'`-adapter threejs/pixijs/react worlds. `ingest-three`/
+ * `ingest-pixi` and `{ module }` still join a multi-world manifest in a
+ * LATER slice (slice 4's ingest-pixi + retirement work, T3.4's module
+ * adapters) — a worlds>1 manifest naming any of them today gets a named
+ * scope-rule error instead of a silent/confusing failure deep inside
+ * `createGameRuntime`'s worlds path. `default-react` is admitted here
+ * because `resolveAllWorlds`/`createWorldsGameRuntime` is exactly the host
+ * path a react world mounts through (docs/REACT-WORLD-DESIGN.md §1.B: a
+ * react world's DOM-root layer is "one stacking model, no special case" —
+ * `packages/engine/test/create-runtime-worlds.test.ts` and `-react-world
+ * .test.ts` already prove N worlds, including react, mounting through this
+ * exact host) — the AC fixture in that design (§2: 1 threejs + 2 react
+ * worlds) is a worlds>1 manifest by construction, so react could not stay
+ * scope-barred here without contradicting the design it is implementing.
+ *
+ * `ingest-react` (Track N, N1) stays OUT of this set on purpose — it is an
+ * `{ ingest }`-adapter identity like `ingest-three`/`ingest-pixi`, both of
+ * which are already excluded here, and docs/REACT-INGEST-LANDING-DESIGN.md
+ * ships single-world manifests only ("Track N ships single-world manifests
+ * and does not touch this", per that design's §2 seam table). This exclusion
+ * also does load-bearing work for D-N4/D-N8 (no authoring surface for an
+ * ingested react world): `installMultiWorldAuthoring` (`play-mode.ts`) is
+ * the ONLY place a `ReactWorldAuthoringAdapter`/`writeBackend` gets
+ * constructed, and it is only reachable via THIS multi-world path — keeping
+ * `ingest-react` out of it keeps that constructor permanently unreachable
+ * for a vendored game, not just unreachable today.
+ */
+const MULTI_WORLD_ALLOWED_IDENTITIES: ReadonlySet<string> = new Set([
+  'default-three',
+  'default-pixi',
+  'default-react',
+]);
+
+function throwMultiWorldScopeViolation(world: ResolvedWorldEntry): never {
+  throw new Error(
+    `resolveAllWorlds: world "${world.id}" resolved to adapter identity ` +
+      `"${world.adapter.identity}" — a manifest with more than one world may only mix ` +
+      "'default'-adapter threejs/pixijs/react worlds in this slice (docs/MULTI-WORLD-DESIGN.md " +
+      '§3 slice 4 reserves ingest/module worlds out of THIS path permanently, not just for a ' +
+      'later slice: a composite manifest (one { ingest } world + siblings) mounts via ' +
+      "`ingest-mode.ts`'s own composite route instead (docs/WAVE5-MULTIWORLD-INGEST-DESIGN.md " +
+      'D-V2..D-V7), never resolveAllWorlds/installMultiWorldAuthoring — the play path stays out ' +
+      'of scope for ingest worlds by design (docs/REACT-WORLD-DESIGN.md §3 admits default-react ' +
+      'here).',
+  );
+}
+
+/**
+ * Resolve EVERY world in a manifest into slice-1 `WorldMountSpec`s
+ * (docs/MULTI-WORLD-DESIGN.md §1.A's host-facing shape), in the manifest's
+ * already-z-sorted `worlds` order (`@engine/manifest/load`'s
+ * `loadGameManifest` sorts by `zOrder` before returning — this function does
+ * not re-sort). No `editorPreview` threading here (v1 scope decision, T6.1
+ * slice 2's report): `default-pixi` has none by design (§1.D), and a
+ * multi-world manifest's live editor document corresponds to no single one
+ * of N worlds today (the editor is still a single-scene store) — EVERY
+ * world in the worlds path mounts from its own on-disk `scene`/`entry`,
+ * matching how `default-pixi` already behaves. Single-world manifests never
+ * call this function (see `play-mode.ts`'s routing) — resolveWorldAdapter's
+ * own editorPreview threading there is completely unaffected.
+ *
+ * Called only for manifests with more than one world (the play path's own
+ * routing decision) but written to work for any `worlds.length >= 1` so a
+ * caller (or a unit test) can exercise it directly.
+ */
+
+/**
+ * Shared per-world resolution loop behind {@link resolveAllWorlds} and
+ * {@link resolveAllWorldEntries} (E4.R2 reopen fix, split out so the two
+ * never re-derive the multi-world scope check or the `resolveWorldAdapter`
+ * fan-out independently): enforces the v1 scope rule (module/ingest worlds
+ * banned from a >1-world manifest — `MULTI_WORLD_ALLOWED_IDENTITIES`), then
+ * resolves every world's adapter, in manifest order.
+ */
+async function resolveAllWorldAdapters(
+  manifest: ResolvedGameManifest,
+  projectRoot: string,
+): Promise<{ world: ResolvedWorldEntry; adapter: GameAdapter }[]> {
+  const { worlds } = manifest;
+
+  if (worlds.length > 1) {
+    for (const world of worlds) {
+      if (!MULTI_WORLD_ALLOWED_IDENTITIES.has(world.adapter.identity)) {
+        throwMultiWorldScopeViolation(world);
+      }
+    }
+  }
+
+  const resolved: { world: ResolvedWorldEntry; adapter: GameAdapter }[] = [];
+  for (const world of worlds) {
+    resolved.push({ world, adapter: await resolveWorldAdapter(world, projectRoot) });
+  }
+  return resolved;
+}
+
+export async function resolveAllWorlds(
+  manifest: ResolvedGameManifest,
+  projectRoot: string,
+): Promise<WorldMountSpec[]> {
+  const resolved = await resolveAllWorldAdapters(manifest, projectRoot);
+
+  const specs: WorldMountSpec[] = [];
+  for (const { world, adapter } of resolved) {
+    const base = { id: world.id, zOrder: world.zOrder, pausable: world.pausable, loop: world.loop };
+    if (world.kind === 'pixijs') {
+      specs.push({ ...base, kind: 'pixijs', adapter: adapter as unknown as Pixi2DGameAdapter });
+    } else if (world.kind === 'react') {
+      specs.push({ ...base, kind: 'react', adapter: adapter as unknown as ReactWorldAdapter });
+    } else if (world.kind === 'threejs') {
+      specs.push({ ...base, kind: 'threejs', adapter });
+    } else {
+      // Exhaustiveness guard (§7.4-2): `world.kind` is `WorldEntry['kind']`,
+      // the same closed `'threejs' | 'pixijs' | 'react'` union as `WorldKind`
+      // (schema.ts's `WorldEntrySchema.kind` is `z.enum([...])`, so this is
+      // NOT a plain-`string` field) — a hypothetical 4th kind must fail to
+      // compile here rather than silently default to 'threejs' as the old
+      // catch-all `else` did.
+      assertNever(world.kind, 'resolveAllWorlds');
+    }
+  }
+  return specs;
+}
+
+/**
+ * E4.R2 (reopen fix — design/26 S-D D2's "editor play mode calls it"):
+ * `resolveAllWorlds`'s composer-path sibling. Resolves every world's adapter
+ * through the SAME scope-checked loop ({@link resolveAllWorldAdapters}) but
+ * returns `mountManifestWorlds`'s own `entries` shape (`{ kind, adapter }`
+ * per world id, `@engine/runtime/mount-manifest`) instead of a hand-built
+ * `WorldMountSpec[]` — so `zOrder`/`pausable`/`loop` and the per-kind
+ * `WorldMountSpec` ASSEMBLY come from `mount-manifest.ts`'s
+ * `buildWorldMountSpec`, the one authoritative place that translation lives,
+ * rather than being hand-duplicated a second time here AND at the
+ * `mountManifestWorlds` call site (the exact duplication a reopen review
+ * found in `play-mode.ts`'s prior `resolveAllWorlds` + `createGameRuntime
+ * ({ container, worlds })` call shape).
+ *
+ * `resolveAllWorlds` itself is UNCHANGED/byte-stable for its other callers
+ * (`ingest-mode.ts`, `module-mode.ts`, its own unit tests) — this is purely
+ * an additional entry point for `play-mode.ts`'s multi-world branch, which
+ * now calls `mountManifestWorlds({ manifest, container, entries, ... })`
+ * directly instead of `createGameRuntime({ container, worlds })`.
+ */
+export async function resolveAllWorldEntries(
+  manifest: ResolvedGameManifest,
+  projectRoot: string,
+): Promise<Record<string, MountEntry>> {
+  const resolved = await resolveAllWorldAdapters(manifest, projectRoot);
+
+  const entries: Record<string, MountEntry> = {};
+  for (const { world, adapter } of resolved) {
+    if (world.kind === 'pixijs') {
+      entries[world.id] = { kind: 'pixijs', adapter: adapter as unknown as Pixi2DGameAdapter };
+    } else if (world.kind === 'react') {
+      entries[world.id] = { kind: 'react', adapter: adapter as unknown as ReactWorldAdapter };
+    } else if (world.kind === 'threejs') {
+      entries[world.id] = { kind: 'threejs', adapter };
+    } else {
+      // Exhaustiveness guard (§7.4-2) — same reasoning as `resolveAllWorlds`'s
+      // own identical guard above.
+      assertNever(world.kind, 'resolveAllWorldEntries');
+    }
+  }
+  return entries;
+}