@vgai/editor 0.2.0

package/src/ingest-mode.ts

@@ -0,0 +1,2092 @@
+/**
+ * Ingest-mode orchestrator — load an UNMODIFIED three.js OR PixiJS game into
+ * the real editor and make its live scene editable, with ZERO edits to the
+ * game's code.
+ *
+ * Phase B (the inversion done right): this is a thin HOST. It mounts the game
+ * through the {@link mountIngestGame} `GameAdapter` path — which captures the
+ * game's live scene and returns a `MountedGame` whose `authoring` is an
+ * {@link IngestAuthoringAdapter} implemented DIRECTLY over the live `Object3D`
+ * tree (NO fabricated `SceneEntity`). The host then:
+ *   - installs that adapter as the editor's active authoring override, so the
+ *     hierarchy + inspector render from the adapter's providers, and
+ *   - swaps the editor viewport onto the live scene (`enterPlayScene`, which binds
+ *     by the stable `entityId` the adapter tagged) so selection + gizmo work.
+ *
+ * The first-party `.vscn` editor is untouched; the SAME editor surface now drives
+ * a foreign game. See `docs/ADAPTER-ARCHITECTURE.md` §5 (migration, steps 3–4).
+ *
+ * T6.1 slice 4 (docs/MULTI-WORLD-DESIGN.md §1.E/§3 slice 4, world2d silo
+ * retirement) adds the PixiJS sibling of this same shape below
+ * (`enterIngestModeFromManifestWorld2D` + `tryManifestIngestRoute2D`):
+ * `resolveIngest2DDescriptor` (adapter-resolver.ts) builds an `IngestGame2D`
+ * straight from an `ingest-pixi` manifest world, `mountIngestGame2D` captures
+ * its live Pixi stage via the SAME shared-instance render-trap mechanics as
+ * the three-side `shared`/`deduped` strategies, and a `World2DAuthoringAdapter`
+ * (the pixi peer of `IngestAuthoringAdapter`) becomes the active authoring
+ * override — no `SceneEntity`, no separate editor data model, exactly like
+ * the three-side path. The silo's `world2d-mode.ts` (deleted this slice) used
+ * to own this kind of session for its 'vendored'/'realgame' hand-launched
+ * demos; this is its manifest-driven, discoverable-fixture replacement.
+ */
+
+import { readGameContract } from '@engine/adapter/ingest/game-contract';
+import { extractUpstreamPin } from '@engine/adapter/ingest/upstream-pin';
+import type { ResolvedGameManifest, ResolvedWorldEntry } from '@engine/manifest/load';
+import type { Tier } from '@engine/manifest/schema';
+import type { Overlay2D } from '@engine/world2d/authoring-2d';
+import {
+  type EmbedMount2D,
+  type IframeReachableMount2D,
+  mountIngestGame2DEmbed,
+  mountIngestGame2DIframeReachableMulti,
+} from '@engine/world2d/ingest-iframe-2d';
+import type { IngestGame2D, IngestMount2D } from '@engine/world2d/ingest2d';
+import { mountIngestGame2D } from '@engine/world2d/ingest2d';
+import { createPhysics2DRegistry } from '@engine/world2d/physics2d-registry';
+import { createPhysicsAdapter2D } from '@engine/world2d/system-adapters-2d';
+import type { Container } from 'pixi.js';
+import * as PIXI from 'pixi.js';
+import {
+  computeAchievedTier,
+  computeTierShortfall,
+  formatTierShortfallMessage,
+} from './achieved-tier';
+import {
+  resolveAllWorlds,
+  resolveIngest2DDescriptor,
+  resolveIngestDescriptor,
+} from './adapter-resolver';
+import { getAuthoringOverride, setActiveAuthoring } from './authoring/active-adapter';
+import { getActiveSystems, setActiveSystems } from './authoring/active-systems';
+import {
+  CompositeAuthoringAdapter,
+  type CompositeChild,
+} from './authoring/composite-authoring-adapter';
+import { makeEmbedOnlyAdapter } from './authoring/embed-only-adapter';
+import {
+  type IngestMount,
+  type MountIngestOptions,
+  mountIngestGame,
+} from './authoring/ingest-game-adapter';
+import { type EmbedMount, mountIngestGameEmbed } from './authoring/ingest-iframe-adapter';
+import {
+  mountIngestGameIframeReachable,
+  mountIngestGameIframeReachableBundle,
+} from './authoring/ingest-iframe-reachable-adapter';
+import { loadOverlay, overlayPath, saveOverlay } from './authoring/ingest-overlay';
+import {
+  addMountFailureReport,
+  formatMountFailureMessage,
+  getMountFailureReports,
+  setMountFailureReport,
+} from './authoring/mount-failure-report';
+import {
+  buildOverlayApplyReport,
+  logOverlayApplyReport,
+  setActiveOverlayReport,
+} from './authoring/overlay-report';
+import {
+  ReactDomAuthoringAdapter,
+  type ReactDomOverlay,
+} from './authoring/react-dom-authoring-adapter';
+import { unregisterUndoAdapter } from './authoring/undo-timeline';
+import { loadWorldOverlay, saveWorldOverlay, worldOverlayPath } from './authoring/world-overlay';
+import { World2DAuthoringAdapter } from './authoring/world2d-authoring-adapter';
+import { editorConsole } from './editor-console';
+import { getEditorMode } from './editor-mode';
+import type { EditorStore } from './editor-store';
+import { setGameInputGate } from './gated-globals';
+import { getIngestGame } from './ingest/discovery';
+import { getIngestGameReact, ingestGameReactProjectRoot } from './ingest/discovery-react';
+import { getIngestGame2D } from './ingest/discovery2d';
+import type { IngestGame } from './ingest/types';
+// TYPE-ONLY (D-V2): `ingest-siblings.ts` imports from `module-mode.ts`, which
+// itself statically imports `waitForGameContainer` from THIS module — a
+// value import here would close that cycle at the wrong end. The actual
+// `mountIngestSiblings` call below is a dynamic `import()`, right where it's
+// used (`mountCompositeSiblings`); only the TYPE is needed at the top level,
+// and type-only imports are erased before the cycle could ever matter.
+import type { SiblingMount } from './ingest-siblings';
+import { fetchGameManifest } from './manifest-project';
+import { getGameContainer } from './play-mode';
+import { getCurrentProject } from './project-manager';
+
+interface IngestSession {
+  store: EditorStore;
+  /** Shared-`three` capture path (a real authoring adapter over the live scene). */
+  mount?: IngestMount;
+  /** Opaque-bundle embed path (iframe-hosted, embed-only). */
+  embed?: EmbedMount;
+  /** Keeps the captured game renderer sized to its container (host lifecycle). */
+  resizeObserver?: ResizeObserver;
+}
+
+/**
+ * F26 slot collapse (D-V1, docs/WAVE5-MULTIWORLD-INGEST-DESIGN.md): at most
+ * one ingest session is EVER active, of any kind — this is the single
+ * module-level slot for it. Pre-collapse, this was three independent
+ * per-kind singletons (`_session`/`_session2D`/`_sessionReact`, one per
+ * `IngestSession*` shape below), each with its own entry guard that only
+ * tore down its OWN slot — so switching kinds leaked the prior kind's live
+ * session (F26 residual, docs/FTUE-EXTERNAL-R3F-GAME.md :222-231).
+ * `IngestSession2D`/`IngestSessionReact` are declared further down (their
+ * own sections), referenced here by forward type reference.
+ *
+ * `siblings` (D-V2, docs/WAVE5-MULTIWORLD-INGEST-DESIGN.md, F24 composite):
+ * a composite manifest's OTHER worlds, mounted beside this session's ingest
+ * world (`ingest-siblings.ts`'s `mountIngestSiblings`) — always `[]` for
+ * every non-composite entry path (the in-tree fixture glob route, the
+ * `?ingest=` URL route, a single-world manifest). `exitActiveIngest` below
+ * disposes these, reverse order, in EVERY kind's teardown path — a sibling
+ * never outlives the session it was mounted beside.
+ */
+type ActiveIngest = (
+  | { kind: 'threejs'; session: IngestSession }
+  | { kind: 'pixi'; session: IngestSession2D }
+  | { kind: 'react'; session: IngestSessionReact }
+) & { siblings: SiblingMount[] };
+
+let _active: ActiveIngest | null = null;
+let _boundStore: EditorStore | null = null;
+
+/**
+ * Shared shortfall-reporting step for both embed-only degradation points in
+ * {@link enterIngestModeWithGame} below (T3.4 slice 1 retrofit, §1.C): both
+ * degrade to the achieved tier 'opaque-embed'; report a structured shortfall
+ * only when a declared tier is actually known (anti-shim — never fabricate
+ * one). Returns the report (for the `__vgaiIngest` dev hook) or `null`.
+ */
+function reportEmbedOnlyShortfall(
+  worldId: string,
+  declaredTier: Tier | undefined,
+): ReturnType<typeof computeTierShortfall> {
+  if (declaredTier === undefined) return null;
+  const shortfall = computeTierShortfall(worldId, declaredTier, 'opaque-embed');
+  if (shortfall) editorConsole.warn(formatTierShortfallMessage(shortfall), 'adapter');
+  return shortfall;
+}
+
+/**
+ * R5 (docs/MASTER-ARCHITECTURE-REVIEW.md §4(c)/§7.1 item 9): best-effort read
+ * of the CURRENTLY-OPEN project's `UPSTREAM.md` pin, for the overlay-identity
+ * fix — binding a saved overlay to the vendored game's actual upstream commit
+ * rather than only its (often static) manifest `version`.
+ *
+ * Fetches root-relative `/UPSTREAM.md` — the SAME "the dev server's document
+ * root IS the open project's root" convention `./manifest-project.ts`'s
+ * `fetchGameManifest` already relies on for `/vgai.game.json` (no `/@fs/`
+ * needed; that route is for ESM import specifiers, not plain-text reads).
+ * Every failure mode resolves to `null`, never throws: no dev server
+ * (`getEditorMode() === 'browser'`), a 404 (the common case — most projects/
+ * fixtures are NOT vendored upstream games and have no `UPSTREAM.md` at all,
+ * e.g. every in-tree fixture under `packages/editor/src/ingest/games/*`, or
+ * an externally-authored non-vendored project opened via the CLI-on-folder
+ * route), or a network error. READ-ONLY: this never writes `UPSTREAM.md`
+ * (anti-shim — the pin is read, never fabricated or persisted back).
+ *
+ * Only wired into the manifest / CLI-on-folder route below
+ * (`tryManifestIngestRoute`) — the in-tree fixture route (`enterIngestMode`)
+ * has no project root the dev server is serving as document root beyond the
+ * editor's OWN source tree, so there is no meaningful "current project" to
+ * fetch an `UPSTREAM.md` for there; it correctly stays `null`/never-called,
+ * same honest outcome as any other non-vendored folder.
+ */
+export async function readVendoredUpstreamPin(): Promise<string | null> {
+  if (getEditorMode() === 'browser') return null; // no dev server to serve /UPSTREAM.md from
+  try {
+    const res = await fetch('/UPSTREAM.md');
+    if (!res.ok) return null;
+    return extractUpstreamPin(await res.text());
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Bind the editor store so the dev hook / UI can launch ingestion. Called
+ * once per `ViewportPanel` mount, right before `loadInitialScene` +
+ * `autoLaunchIngestFromURL` — i.e. once per project session (`AppRoot`
+ * unmounts/remounts `DefaultEditorLayout` under a fresh `EditorProvider` on
+ * "return to project screen" -> reopen).
+ *
+ * D-W3: there is no OTHER project-switch teardown hook in this codebase
+ * today — `switchProject`/`onReturnToProjectScreen` reset React state, not
+ * this module-level ingest singleton (`_active`, D-V1's slot collapse, and
+ * the `active-adapter.ts`/`overlay-report.ts` globals it sets), and nothing
+ * calls `exitIngestMode`/`exitModuleMode` on that path — a pre-existing gap,
+ * not introduced or fixed here. This bind call is
+ * the earliest point every new project session reaches, so it is the best
+ * available place to make sure a PREVIOUS project's stale mount-failure
+ * banner never bleeds into a freshly opened one.
+ */
+export function bindIngestMode(store: EditorStore): void {
+  _boundStore = store;
+  setMountFailureReport(null);
+}
+
+/**
+ * The world kind of the currently-active ingest session, if any (F26,
+ * VGAI_FTUE_LOG.md): ingest is an ADAPTER TIER, not a mode of one kind — D-V1
+ * collapsed the three per-kind session slots this used to fixed-priority-scan
+ * (`_session` / `_session2D` / `_sessionReact`) into the single `_active` slot
+ * above, so at most one session is ever active, of any kind, and this is just
+ * that slot's tag. The play surface ({@link getIngestPlayControl}) and
+ * {@link isIngestActive} read this, never a slot directly.
+ */
+export type IngestKind = 'threejs' | 'pixi' | 'react';
+
+export function activeIngestKind(): IngestKind | null {
+  return _active?.kind ?? null;
+}
+
+/** True if an unmodified game is currently ingested — ANY kind (F26). */
+export function isIngestActive(): boolean {
+  return activeIngestKind() !== null;
+}
+
+/**
+ * The play-state control surface for the CURRENT ingest session (F17/F21,
+ * docs/FTUE-EXTERNAL-R3F-GAME.md): mounts are COLD by doctrine — the adapter
+ * sets `window.__vgaiMountCold` before the game's entry executes, and a
+ * session-driven game may defer its side-effects (backend connection,
+ * narrative, audio) until the first `play()`. Everything is contract-first
+ * (game-contract.ts): `lifecycle.start` is called AT MOST ONCE per mount —
+ * later ▶ presses resume rather than re-start, so games never need an
+ * idempotent start(); `lifecycle.pause`/`resume` are preferred over the
+ * outside-in loop gate (`MountedGame.setPaused`), which cannot gate a raw
+ * requestAnimationFrame loop (R3F games) at all. Games that declare nothing
+ * get the pre-contract wire event + loop gate, exactly as before — nothing
+ * is demanded of them.
+ */
+export interface IngestPlayControl {
+  readonly playing: boolean;
+  play(): void;
+  pause(): void;
+  resume(): void;
+}
+
+let _ingestPlaying = false;
+
+/**
+ * F26: the play surface's state is session-global (one active session,
+ * whatever its kind), so EVERY per-kind exit path resets it — the playing
+ * flag plus the cold-mount/played window globals the entry paths set.
+ */
+function resetIngestPlaySurface(): void {
+  _ingestPlaying = false;
+  const w = window as unknown as { __vgaiMountCold?: boolean; __vgaiIngestPlayed?: boolean };
+  delete w.__vgaiMountCold;
+  delete w.__vgaiIngestPlayed;
+}
+
+/**
+ * F26 helper: the active session's kind + its own honest pause capability
+ * (D-V1: dispatches on the single `_active` slot, never a per-kind global).
+ * `null` when nothing is ingested OR the session is opaque-embed (iframe
+ * realm: the game-contract global is unreachable and there is no loop to
+ * gate — no play surface is honest there).
+ */
+function activeIngestSurface(): { kind: IngestKind; setPaused(paused: boolean): void } | null {
+  const active = _active;
+  if (!active) return null;
+  switch (active.kind) {
+    case 'threejs': {
+      const mount = active.session.mount;
+      if (!mount) return null; // opaque-embed
+      return { kind: 'threejs', setPaused: (p) => mount.game.setPaused?.(p) };
+    }
+    case 'pixi': {
+      const session = active.session;
+      if (session.embed) return null; // D-W2 opaque-embed — no honest play surface, same doctrine as three's embed branch
+      return { kind: 'pixi', setPaused: (p) => session.setPaused(p) };
+    }
+    case 'react':
+      return { kind: 'react', setPaused: (p) => active.session.setPaused(p) };
+  }
+}
+
+/**
+ * D-V1 slot collapse: tears down WHATEVER kind is currently active,
+ * dispatching to that kind's own teardown body (`disposeThreejsSession`/
+ * `disposePixiSession`/`disposeReactSession`, each below in its own
+ * section) — the exact same per-kind dispose semantics as before the
+ * collapse (resizeObserver disconnect, `exitPlayScene`, mount/embed
+ * dispose, undo-adapter unregister, authoring/systems/overlay-report/
+ * mount-failure clears, canvas removal, react `stop()`), just no longer
+ * gated behind "is THIS kind the one currently active" — every
+ * `enterIngestMode*` entry guard calls this unconditionally, closing the
+ * cross-kind leak (F26 residual): switching kinds always disposes the
+ * prior session, whichever kind it was. `exitIngestMode`/`exitIngestMode2D`/
+ * `exitIngestModeReact` (the frozen public API) become thin wrappers around
+ * this that only act when `_active` is their own kind — so a same-kind
+ * caller sees the exact same observable behavior as before the collapse.
+ *
+ * D-V2 (docs/WAVE5-MULTIWORLD-INGEST-DESIGN.md, F24 composite): a composite
+ * session's `siblings` (mounted by `ingest-siblings.ts`'s
+ * `mountIngestSiblings`, attached via `attachIngestSiblings` below) tear
+ * down FIRST, in REVERSE mount order, before the primary session's own
+ * per-kind dispose body runs — every kind shares this ONE teardown path, so
+ * a sibling never outlives the ingest session it was mounted beside. A
+ * throwing sibling `dispose()` is caught individually (never blocks the rest
+ * of teardown) and logged loudly, never silently swallowed.
+ */
+function exitActiveIngest(): void {
+  const active = _active;
+  if (!active) return;
+  _active = null;
+  resetIngestPlaySurface();
+  for (let i = active.siblings.length - 1; i >= 0; i--) {
+    try {
+      active.siblings[i]!.dispose();
+    } catch (err) {
+      editorConsole.error(`Composite sibling dispose failed: ${err}`, 'ingest');
+    }
+  }
+  switch (active.kind) {
+    case 'threejs':
+      disposeThreejsSession(active.session);
+      return;
+    case 'pixi':
+      disposePixiSession(active.session);
+      return;
+    case 'react':
+      disposeReactSession(active.session);
+      return;
+  }
+}
+
+/**
+ * D-B2 (docs/WAVE6-DOCTOR-DESIGN.md Slice B, wave-5 residual closure): fan a
+ * pause/resume state out to every mounted composite sibling's OPTIONAL
+ * `SiblingMount.setPaused` (`ingest-siblings.ts`), AFTER the primary
+ * surface's own pause/resume already ran above — mirrors
+ * `exitActiveIngest`'s reverse-order dispose fan-out just above (the same
+ * "one bad sibling never breaks the rest" isolation: per-sibling try/catch,
+ * loud log on failure, never swallowed silently). A sibling with no
+ * `setPaused` at all (the bare `default-react` sibling, D-B1 — it has no
+ * loop to gate) is silently skipped via the optional call — never an error,
+ * never a fabricated pause. A no-op (empty `siblings`, or no `_active`
+ * session at all) for every non-composite entry path, unchanged.
+ */
+function fanOutSiblingPause(paused: boolean): void {
+  const active = _active;
+  if (!active) return;
+  for (const sibling of active.siblings) {
+    try {
+      sibling.setPaused?.(paused);
+    } catch (err) {
+      editorConsole.error(`Composite sibling setPaused(${paused}) failed: ${err}`, 'ingest');
+    }
+  }
+}
+
+export function getIngestPlayControl(): IngestPlayControl | null {
+  const surface = activeIngestSurface();
+  if (!surface) return null;
+  const resume = () => {
+    const lifecycle = readGameContract()?.lifecycle;
+    if (lifecycle?.resume) lifecycle.resume();
+    else surface.setPaused(false);
+    fanOutSiblingPause(false);
+    _ingestPlaying = true;
+  };
+  return {
+    get playing() {
+      return _ingestPlaying;
+    },
+    play() {
+      // Late-constructed game clients must not re-defer: the flag records
+      // that play already happened this session — and makes ▶-after-⏸ a
+      // RESUME, so `lifecycle.start` fires at most once per mount.
+      const w = window as unknown as { __vgaiIngestPlayed?: boolean };
+      if (w.__vgaiIngestPlayed) return resume();
+      w.__vgaiIngestPlayed = true;
+      // Contract-first: a game declaring `vgaiGame.lifecycle.start` gets the
+      // typed call; otherwise the wire event covers pre-contract games.
+      const lifecycle = readGameContract()?.lifecycle;
+      if (lifecycle?.start) lifecycle.start();
+      else window.dispatchEvent(new CustomEvent('vgai:ingest-play'));
+      surface.setPaused(false);
+      fanOutSiblingPause(false);
+      _ingestPlaying = true;
+    },
+    pause() {
+      const lifecycle = readGameContract()?.lifecycle;
+      if (lifecycle?.pause) lifecycle.pause();
+      else surface.setPaused(true);
+      fanOutSiblingPause(true);
+      _ingestPlaying = false;
+    },
+    resume,
+  };
+}
+
+/**
+ * D-W1 (docs/WAVE4-FTUE-HARDENING-DESIGN.md) — mount an `IngestGame` whose
+ * descriptor carries a `bundleUrl` (an externalized-`three` prebuilt bundle)
+ * via `mountIngestGameIframeReachableBundle` — the three-side sibling of
+ * {@link mountIframeReachableGame2D} below. `extraDeps` is a LAZY thunk on
+ * the descriptor (`resolveIngestDescriptor`, adapter-resolver.ts) — invoked
+ * here, right before the actual mount, so the host-namespace registry's
+ * dynamic imports only ever run for a game actually being ingested (same
+ * "resolve lazily, at mount time" discipline as the pixi sibling).
+ * `assetBaseUrl` is root-relative-resolved against the editor page's own URL
+ * here too (a static manifest can't know the dev-server port) — the exact
+ * `mountIframeReachableGame2D` idiom this mirrors.
+ */
+async function mountThreeIframeReachableBundle(
+  game: IngestGame,
+  container: HTMLElement,
+  store: EditorStore,
+  opts: MountIngestOptions,
+): Promise<IngestMount> {
+  if (!game.bundleUrl) {
+    throw new Error(
+      'mountThreeIframeReachableBundle: called with no `bundleUrl` on the descriptor — ' +
+        'unreachable given the caller already checked `game.bundleUrl` (bug if hit).',
+    );
+  }
+  const resolvedExtraDeps = game.extraDeps ? await game.extraDeps() : { namespaces: {}, urls: {} };
+  // The asset-adapter URL modifier needs an ABSOLUTE URL (see
+  // `makeAssetUrlModifier`'s doc comment), but a static manifest can't know
+  // the editor's origin/port. Resolve a root-relative manifest value against
+  // the editor page here; absolute URLs pass through `new URL()` unchanged.
+  const assetBaseUrl =
+    game.assetBaseUrl !== undefined
+      ? new URL(game.assetBaseUrl, window.location.href).href
+      : undefined;
+  return mountIngestGameIframeReachableBundle(store, container, {
+    ...opts,
+    bundleUrl: game.bundleUrl,
+    ...(game.baseHref !== undefined ? { baseHref: game.baseHref } : {}),
+    ...(assetBaseUrl !== undefined ? { assetBaseUrl } : {}),
+    ...(game.bodyHtml !== undefined ? { bodyHtml: game.bodyHtml } : {}),
+    extraDeps: resolvedExtraDeps.namespaces,
+    ...(Object.keys(resolvedExtraDeps.urls).length > 0
+      ? { extraDepUrls: resolvedExtraDeps.urls }
+      : {}),
+  });
+}
+
+/**
+ * Enter ingest mode for an already-resolved {@link IngestGame} descriptor,
+ * however it was built. Resolves once the game's live scene is captured, the
+ * authoring adapter is active, and it is shown in the editor for editing.
+ *
+ * T3.3 slice 3 (docs/CLI-ON-FOLDER-DESIGN.md §1E) split this out of
+ * `enterIngestMode` so the descriptor's ORIGIN is a separate concern from
+ * mounting it: `enterIngestMode(store, gameId)` below resolves `gameId`
+ * against the in-tree fixture glob (`ingest/discovery.ts`, the `?ingest=`
+ * URL route's discovery frontend); `enterIngestModeFromManifestWorld` builds
+ * the descriptor straight from an arbitrary project's manifest instead (the
+ * CLI-on-folder route, for a game folder never registered in source) — both
+ * end up here. `overlayId` namespaces the saved-edit overlay
+ * (`.vgai/overlays/<overlayId>.json`) and the `__vgaiIngest` dev-hook's
+ * reported `gameId`; it is always the world/game id (`game.id`), passed
+ * explicitly rather than re-read off `game` so the two callers' "id" concept
+ * — a fixture's registry-era id vs. a manifest's world id — stays one
+ * parameter, not two silently-assumed-equal fields.
+ *
+ * `declaredTier` (T3.4 slice 1, docs/ADAPTER-AUTHORING-DESIGN.md §1.C
+ * retrofit) is the world's declared `capabilities.local` tier, when known —
+ * only `enterIngestModeFromManifestWorld` has a `ResolvedWorldEntry` to read
+ * it from; the in-tree fixture route (`enterIngestMode`) has no manifest at
+ * all, so it stays `undefined` there (anti-shim: never fabricate a declared
+ * tier that was never actually declared). Both embed-only degradation points
+ * below report a shortfall through the SAME structured log
+ * (`reportTierShortfall`, `./achieved-tier.ts`) the module-adapter
+ * achieved-tier check uses, ONLY when a declared tier is actually known.
+ *
+ * `gameVersion` (T7.7, D9 — docs/DECISIONS-PENDING.md §D9) is the game's own
+ * manifest `version`, when known at this call site — it gets stamped onto the
+ * overlay envelope's `authoredAgainst.gameVersion` on save, and compared
+ * against a PREVIOUSLY-saved overlay's stamp to report a mismatch
+ * (`./authoring/overlay-report.ts`). Falls back to `game.gameVersion` (set by
+ * `ingest/discovery.ts` for the in-tree fixture route) when omitted, since
+ * `enterIngestModeFromManifestWorld` below is the only caller that has a
+ * SEPARATE source for it (the resolved manifest, which `resolveIngestDescriptor`
+ * has no access to — see `IngestGame.gameVersion`'s doc comment). Neither
+ * source existing is legal — it stamps `null` rather than fabricating a
+ * version (anti-shim).
+ *
+ * `upstreamPin` (R5, docs/MASTER-ARCHITECTURE-REVIEW.md §4(c)/§7.1 item 9) is
+ * this session's discovered `UPSTREAM.md` pin, when the caller found one
+ * (`tryManifestIngestRoute` below, via `readVendoredUpstreamPin`) — `null`
+ * when it looked and found nothing (no fallback source: unlike `gameVersion`,
+ * `IngestGame` carries no pin field, since no discovery route can populate one
+ * for the in-tree fixture glob — those fixtures are first-party, never
+ * vendored). It serves BOTH ends of the same check: at APPLY time it's
+ * compared against the loaded overlay's `authoredAgainst.upstreamPin`
+ * (`./authoring/overlay-report.ts`'s `upstreamPin.mismatch`); at SAVE time
+ * it's the value threaded into `saveOverlay`'s stamp, so a save made THIS
+ * session records what it was actually authored against.
+ */
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: one cohesive mount sequence (embed-only vs. captured-scene dispatch, capture-failure degrade, tier-shortfall reporting, gameVersion/upstreamPin resolution) — R5's one extra `??` tipped this over the threshold; splitting it would fragment the documented ordering contract rather than reduce real complexity (same precedent as game.ts's runFrame/achieved-tier fan-outs).
+export async function enterIngestModeWithGame(
+  store: EditorStore,
+  game: IngestGame,
+  overlayId: string,
+  declaredTier?: Tier,
+  gameVersion?: string,
+  upstreamPin?: string | null,
+): Promise<void> {
+  // D-V1: tear down WHATEVER kind is currently active, not just a prior
+  // threejs session — closes the cross-kind leak (F26 residual).
+  exitActiveIngest();
+  const effectiveGameVersion = gameVersion ?? game.gameVersion ?? null;
+  const effectiveUpstreamPin = upstreamPin ?? null;
+
+  const gameContainer = getGameContainer();
+  if (!gameContainer) {
+    editorConsole.error('Game container not mounted — cannot ingest', 'ingest');
+    return;
+  }
+
+  // Ingest edits are runtime-only. Autosave/save-guard no longer suppress on a
+  // flag — the active adapter installed below (setActiveAuthoring) carries its
+  // own persistence provider (overlay destination, or absent for embed-only),
+  // which is what EditorStore's autosave/saveNow now consult (design
+  // docs/PERSISTENCE-PROVIDER-DESIGN.md §2). Still switch into the guarded
+  // "playing" state so the viewport swaps onto the live scene.
+  store.setPlayState('playing');
+  editorConsole.log(`Ingesting unmodified game: ${game.name}`, 'ingest');
+
+  // R2c (docs/MASTER-ARCHITECTURE-REVIEW.md §7.1 item 10): drive the SAME
+  // input gate play-mode uses (play-mode.ts's `gameInputActive`, wired via
+  // `setGameInputGate` at ~691) so a same-realm ingested game's raw
+  // window/document input listeners (gated via gated-globals.ts's proxy —
+  // reachable here because `server/dev.ts`'s prelude now shadows the in-tree
+  // ingest fixture roots too, see game-globals-shadow.ts) only fire while the
+  // Game tab is the active viewport surface, exactly like a first-party play
+  // session. Harmless for the iframe-reachable/opaque-embed tiers below too
+  // (a separate browsing context never reads this gate at all) — set once
+  // here, unconditionally, right alongside every `_active` assignment below,
+  // rather than duplicating it per branch.
+  const ingestInputActive = () =>
+    store.playState === 'playing' && store.activeViewportTab === 'game';
+
+  // Opaque prebuilt bundle → iframe embed-only floor (no scene introspection).
+  // `embedHtml` is either an already-read string (the in-tree fixture glob
+  // route) or a D-W2 lazy thunk (a manifest-driven external folder reading
+  // its `entryHtml` file's bytes through the project-static route) —
+  // resolve either shape to a plain string before mounting.
+  if (game.embedHtml) {
+    let embedHtmlText: string;
+    try {
+      embedHtmlText = typeof game.embedHtml === 'string' ? game.embedHtml : await game.embedHtml();
+    } catch (err) {
+      editorConsole.error(
+        `Failed to load opaque-embed entryHtml for "${game.name}": ${err}`,
+        'ingest',
+      );
+      return;
+    }
+    const embed = mountIngestGameEmbed(embedHtmlText, gameContainer);
+    _active = { kind: 'threejs', session: { store, embed }, siblings: [] };
+    setGameInputGate(ingestInputActive);
+    setActiveAuthoring(makeEmbedOnlyAdapter(store, game.name));
+    store.setActiveViewportTab('game'); // show the hosted iframe
+    store.notifyIngestEdit();
+    setMountFailureReport(null); // D-W3: a (degraded-but-hosted) mount succeeded
+    editorConsole.log(`Embedded opaque bundle "${game.name}" (embed-only)`, 'ingest');
+    const shortfall = reportEmbedOnlyShortfall(overlayId, declaredTier);
+    (window as unknown as Record<string, unknown>)['__vgaiIngest'] = {
+      gameId: overlayId,
+      embedOnly: true,
+      reflected: { count: 0, meshes: 0, lights: 0 },
+      ...(shortfall ? { tierShortfall: shortfall } : {}),
+    };
+    return;
+  }
+
+  try {
+    // Load any saved overlay envelope (previous-session edits + save-time
+    // provenance — D9) to reapply on mount. `overlay.overrides` is the flat
+    // `IngestOverlay` the authoring adapter operates on; `overlay.authoredAgainst`
+    // is what the OverlayApplyReport below compares against `effectiveGameVersion`.
+    const overlay = await loadOverlay(overlayId);
+    const mountOpts: MountIngestOptions = {
+      overlay: overlay.overrides,
+      persist: (o) => saveOverlay(overlayId, o, effectiveGameVersion, effectiveUpstreamPin),
+      destination: overlayPath(overlayId),
+      captureTimeoutMs: game.captureTimeoutMs,
+    };
+
+    // Mount the unmodified game through the GameAdapter path → captured live scene
+    // + an IngestAuthoringAdapter over its Object3D tree (no SceneEntity). The
+    // adapter reapplies the overlay after walking the scene. Reachable-three
+    // prebuilt bundles (inline source OR a D-W1 externalized `bundleUrl`) run
+    // in an iframe but share the host three → same contract.
+    const mount = game.iframeReachableSrc
+      ? await mountIngestGameIframeReachable(
+          store,
+          game.iframeReachableSrc,
+          gameContainer,
+          mountOpts,
+        )
+      : game.bundleUrl
+        ? await mountThreeIframeReachableBundle(game, gameContainer, store, mountOpts)
+        : await mountIngestGame(store, game, gameContainer, mountOpts);
+    const session: IngestSession = { store, mount };
+    _active = { kind: 'threejs', session, siblings: [] };
+    setGameInputGate(ingestInputActive);
+
+    // Capture failed → the game's three is unreachable (bundled / MISMATCHED version).
+    // Degrade gracefully to embed-only (host it, no scene introspection) — never silent.
+    if (mount.embedOnly || !mount.authoring || !mount.scene) {
+      setActiveAuthoring(
+        makeEmbedOnlyAdapter(store, `${game.name} — capture failed (three unreachable/mismatched)`),
+      );
+      store.setActiveViewportTab('game');
+      store.notifyIngestEdit();
+      setMountFailureReport(null); // D-W3: a (degraded-but-hosted) mount succeeded
+      editorConsole.log(
+        `Capture failed for "${game.name}": three unreachable/mismatched — hosting embed-only`,
+        'ingest',
+      );
+      const shortfall = reportEmbedOnlyShortfall(overlayId, declaredTier);
+      (window as unknown as Record<string, unknown>)['__vgaiIngest'] = {
+        gameId: overlayId,
+        embedOnly: true,
+        captureFailed: true,
+        reflected: { count: 0, meshes: 0, lights: 0 },
+        ...(shortfall ? { tierShortfall: shortfall } : {}),
+      };
+      return;
+    }
+
+    // Host lifecycle: keep the game's renderer sized to its container (resize).
+    const ro = new ResizeObserver(() => {
+      const r = gameContainer.getBoundingClientRect();
+      if (r.width > 0 && r.height > 0) mount.game.resize?.(r.width, r.height);
+    });
+    ro.observe(gameContainer);
+    session.resizeObserver = ro;
+
+    const stats = mount.authoring.refresh();
+    const overlayCount = Object.keys(overlay.overrides).length;
+    editorConsole.log(
+      `Captured live scene (${mount.scene.children.length} top-level children, ` +
+        `${mount.capture.getDrawCount()} draws); ingested ${stats.count} objects ` +
+        `(${stats.meshes} meshes, ${stats.lights} lights)` +
+        (overlayCount ? `; reapplied ${overlayCount} saved edit(s)` : ''),
+      'ingest',
+    );
+
+    // D9 (docs/DECISIONS-PENDING.md §D9): report a version mismatch and/or
+    // orphaned overlay ids — never blocks mounting, everything applicable was
+    // already applied by the adapter's constructor-time `applyOverlay`
+    // (`mount.authoring.lastApplyResult` is that call's result). R5 adds the
+    // upstream-pin check (§4(c)) — `overlay.authoredAgainst.upstreamPin` is
+    // `undefined` for a legacy overlay (never recorded — the report's
+    // `upstreamPin.recorded` reflects that honestly) and `effectiveUpstreamPin`
+    // is this session's discovered pin (`null` if undiscoverable here).
+    const overlayReport = buildOverlayApplyReport({
+      gameId: overlayId,
+      authoredAgainst: overlay.authoredAgainst.gameVersion,
+      currentVersion: effectiveGameVersion,
+      applied: mount.authoring.lastApplyResult.applied,
+      orphanedIds: mount.authoring.lastApplyResult.orphanedIds,
+      authoredUpstreamPin: overlay.authoredAgainst.upstreamPin,
+      currentUpstreamPin: effectiveUpstreamPin,
+    });
+    logOverlayApplyReport(overlayReport);
+    setActiveOverlayReport(overlayReport);
+
+    // D-A3 (docs/WAVE6-DOCTOR-DESIGN.md): the achieved tier for a healthy,
+    // fully-captured ingest mount — 'shared'/'deduped' rank identically
+    // (TIER_RANK, achieved-tier.ts), so this collapses to 'shared' for
+    // either load()-based route; the iframe-reachable-bundle route
+    // (`game.iframeReachableSrc`/`game.bundleUrl`) reports its own rung.
+    // Ingest tier was previously console-only (`reportEmbedOnlyShortfall`
+    // covers only the embed-only floor) — doctor's headless mount phase
+    // needs it on the healthy path too, since it has no console to read.
+    const achievedTier: Tier =
+      game.iframeReachableSrc || game.bundleUrl ? 'iframe-reachable' : 'shared';
+
+    // The editor's hierarchy + inspector now render from THIS adapter.
+    setActiveAuthoring(mount.authoring);
+    // An unmodified game exposes NO engine System adapters (it owns its own
+    // physics/input/animation/etc.) → those are correctly N/A while ingested. Only
+    // the asset-path remap (done at mount) is a first-party asset-adapter behavior.
+    setActiveSystems(mount.game.systems ?? {});
+    // Bind the viewport/objectMap/gizmo to the live scene (by the tagged entityId).
+    store.enterPlayScene(mount.scene);
+    store.setActiveViewportTab('scene');
+    store.notifyIngestEdit(); // ensure panels re-render against the override
+    setMountFailureReport(null); // D-W3: mount succeeded
+
+    // Dev/proof hook: expose ingest state for automation + screenshots.
+    (window as unknown as Record<string, unknown>)['__vgaiIngest'] = {
+      gameId: overlayId,
+      drawCount: () => mount.capture.getDrawCount(),
+      reflected: stats,
+      sceneChildren: mount.scene.children.length,
+      // D-A3: achieved tier for a headless-verifiable healthy mount (see comment above).
+      achievedTier,
+      // Host-lifecycle resize: drive the game renderer's size (proof/automation).
+      resize: (w: number, h: number) => mount.game.resize?.(w, h),
+      // Loop-host: freeze/resume the game's own rAF (proof/automation).
+      setPaused: (p: boolean) => mount.game.setPaused?.(p),
+      // Recorded N/A: which engine System adapters are active for this game (none
+      // for an unmodified game — it owns its own subsystems).
+      engineSystems: () => Object.keys(getActiveSystems()),
+      // D9 (T7.7): the version-mismatch/orphan findings for this mount, for
+      // automation/proof — mirrors the embed-only branches' `tierShortfall`.
+      overlayReport,
+      // DEV-only: the live authoring adapter + store, so e2e/proof can drive the
+      // SAME providers the hierarchy/inspector/gizmo use.
+      ...(import.meta.env.DEV ? { adapter: mount.authoring, store } : {}),
+    };
+  } catch (err) {
+    editorConsole.error(`Ingest failed: ${err}`, 'ingest');
+    exitIngestMode();
+    throw err;
+  }
+}
+
+/**
+ * Enter ingest mode for an in-tree fixture game by its discovered id (the
+ * `?ingest=<id>` URL route's entry point — `ingest/discovery.ts`'s glob
+ * discovery replaces the deleted `INGEST_GAMES` registry lookup here).
+ */
+export async function enterIngestMode(store: EditorStore, gameId: string): Promise<void> {
+  const game = getIngestGame(gameId);
+  if (!game) {
+    editorConsole.error(`Unknown ingest game: ${gameId}`, 'ingest');
+    return;
+  }
+  return enterIngestModeWithGame(store, game, gameId);
+}
+
+/**
+ * Enter ingest mode straight from a manifest's `ingest-three` world — the
+ * CLI-on-folder route (T3.3 slice 3, docs/CLI-ON-FOLDER-DESIGN.md §1E): a
+ * game folder never registered in source, whose `vgai.game.json` declares an
+ * ingest-three world. Builds the descriptor via `resolveIngestDescriptor`
+ * (adapter-resolver.ts — parameterized by the manifest's ingest fields, no
+ * registry lookup) and mounts it exactly like any other {@link IngestGame}.
+ * The overlay namespaces off the world id, consistent with today's
+ * `.vgai/overlays/<id>.json` convention (the `?ingest=<id>` route's `id` IS a
+ * world id too, for the in-tree fixtures — same namespace, different origin).
+ *
+ * `gameVersion` (T7.7/D9): `resolveIngestDescriptor` only has a
+ * `ResolvedWorldEntry`, not the manifest's top-level `version` — so the caller
+ * (`tryManifestIngestRoute` below, which fetched the full `ResolvedGameManifest`)
+ * passes it here explicitly, threaded straight through to `enterIngestModeWithGame`.
+ *
+ * `upstreamPin` (R5, docs/MASTER-ARCHITECTURE-REVIEW.md §4(c)): same shape —
+ * `resolveIngestDescriptor` has no way to discover an `UPSTREAM.md` pin
+ * either, so `tryManifestIngestRoute` (which has a dev server + project root
+ * to fetch one from, via `readVendoredUpstreamPin`) passes it here explicitly.
+ */
+export async function enterIngestModeFromManifestWorld(
+  store: EditorStore,
+  world: ResolvedWorldEntry,
+  projectRoot: string,
+  gameVersion?: string,
+  upstreamPin?: string | null,
+): Promise<void> {
+  const game = resolveIngestDescriptor(world, projectRoot);
+  return enterIngestModeWithGame(
+    store,
+    game,
+    world.id,
+    world.capabilities.local,
+    gameVersion,
+    upstreamPin,
+  );
+}
+
+// ---------------------------------------------------------------------------
+// PixiJS ingest sessions (T6.1 slice 4 — docs/MULTI-WORLD-DESIGN.md §1.E)
+// ---------------------------------------------------------------------------
+
+interface IngestSession2D {
+  store: EditorStore;
+  /** Absent for a D-W2 opaque-embed session — see `embed` below. */
+  adapter?: World2DAuthoringAdapter;
+  /** Opaque prebuilt-bundle embed path (D-W2, iframe-hosted, embed-only — mirrors the three side's `IngestSession.embed`). */
+  embed?: EmbedMount2D;
+  /** The mount's own honest pause (ticker stop/start) — the F26 play surface. No-op for an opaque-embed session (no reachable pixi instance). */
+  setPaused: (paused: boolean) => void;
+  dispose: () => void;
+}
+
+/** True if an unmodified PixiJS game is currently ingested. */
+export function isIngestActive2D(): boolean {
+  return _active?.kind === 'pixi';
+}
+
+/**
+ * D-P4 (docs/PIXI-INGEST-LANDING-DESIGN.md §3) — mount-shape adapter:
+ * `IframeReachableMount2D` (`ingest-iframe-2d.ts`) has `{ iframe, capture,
+ * captured, dispose }`, not the `IngestMount2D` shape (`{ stage, capture,
+ * embedOnly, setPaused, dispose }`) the rest of ingest-mode.ts's PixiJS path
+ * expects. This wraps the former into the latter:
+ *  - `stage`: the captured runtime's stage, or `null` if capture never
+ *    yielded one (timed out / pixi unreachable) — the SAME "null stage"
+ *    signal `mountIngestGame2D`'s degrade path already produces, so the
+ *    caller's existing `!mount.stage` check covers both mounts uniformly.
+ *  - `embedOnly`: always `false` — this route has no embed-only floor
+ *    (capture either succeeded, or the mount call itself already failed
+ *    loudly / `stage` is null); never fabricate a degraded-but-hosted state.
+ *  - `setPaused`: a REAL capability, not a shim — the trap yields the live
+ *    `Application` (`captured.app`), so pausing drives its OWN
+ *    `ticker.stop()`/`start()`. If capture hasn't yielded an app yet (or
+ *    failed), this THROWS loudly rather than silently no-oping — the honest-
+ *    pause design call.
+ *  - `dispose`: delegates straight to the iframe mount's own `dispose`.
+ */
+function wrapIframeReachableMount2D(mount: IframeReachableMount2D): IngestMount2D {
+  return {
+    stage: mount.captured?.stage ?? null,
+    capture: mount.capture,
+    embedOnly: false,
+    setPaused(paused: boolean): void {
+      const app = mount.captured?.app as
+        | { ticker?: { stop: () => void; start: () => void } }
+        | undefined;
+      if (!app?.ticker) {
+        throw new Error(
+          'ingest-mode: setPaused() called on an iframe-reachable-multi mount before capture ' +
+            'yielded a live Application (or capture failed) — this never silently no-ops (D-P4, ' +
+            'docs/PIXI-INGEST-LANDING-DESIGN.md §3).',
+        );
+      }
+      if (paused) app.ticker.stop();
+      else app.ticker.start();
+    },
+    dispose: () => mount.dispose(),
+  };
+}
+
+/**
+ * Mount an `iframe-reachable` `IngestGame2D` descriptor (Track P,
+ * docs/PIXI-INGEST-LANDING-DESIGN.md §2/P2) via
+ * `mountIngestGame2DIframeReachableMulti` — the externalized-built-bundle
+ * sibling of {@link mountIngestGame2D}'s shared-instance path. `extraDeps`/
+ * `pixiNamespace` are LAZY thunks on the descriptor (`resolveIngest2DDescriptor`
+ * / `discovery2d.ts`) — invoked here, right before the actual mount, so the
+ * host-namespace registry's dynamic imports (`@pixi/sound`/`gsap`/spine/a
+ * standalone pixi build) only ever run for a game actually being ingested.
+ */
+async function mountIframeReachableGame2D(
+  game: IngestGame2D,
+  container: HTMLElement,
+): Promise<IngestMount2D> {
+  if (!game.bundleUrl) {
+    throw new Error(
+      `enterIngestModeWithGame2D: world2d ingest game "${game.id}" has neither \`load\` nor ` +
+        '`bundleUrl` — resolveIngest2DDescriptor only builds shared/deduped (load) or ' +
+        'iframe-reachable (bundleUrl) descriptors this slice.',
+    );
+  }
+  const pixiNamespace = game.pixiNamespace ? await game.pixiNamespace() : PIXI;
+  // D-Z3: two kinds — registry-known specifiers resolve to host namespaces
+  // (`.namespaces`, unchanged shape/behavior); everything else resolves via
+  // the project-node_modules fallback into verbatim importmap URLs (`.urls`).
+  const resolvedExtraDeps = game.extraDeps ? await game.extraDeps() : { namespaces: {}, urls: {} };
+  // The Assets.init basePath remap needs an ABSOLUTE URL (Pixi's Assets resolver
+  // builds URLs from window.location — see IframeReachableMultiOpts.assetBaseUrl),
+  // but a static manifest can't know the editor's origin/port. Resolve a
+  // root-relative manifest value against the editor page here; absolute URLs
+  // pass through new URL() unchanged.
+  const assetBaseUrl =
+    game.assetBaseUrl !== undefined
+      ? new URL(game.assetBaseUrl, window.location.href).href
+      : undefined;
+  const mount = await mountIngestGame2DIframeReachableMulti(pixiNamespace, container, {
+    extraDeps: resolvedExtraDeps.namespaces,
+    ...(Object.keys(resolvedExtraDeps.urls).length > 0
+      ? { extraDepUrls: resolvedExtraDeps.urls }
+      : {}),
+    bundleUrl: game.bundleUrl,
+    ...(game.baseHref !== undefined ? { baseHref: game.baseHref } : {}),
+    ...(assetBaseUrl !== undefined ? { assetBaseUrl } : {}),
+    ...(game.bodyHtml !== undefined ? { bodyHtml: game.bodyHtml } : {}),
+    ...(game.captureTimeoutMs !== undefined ? { captureTimeoutMs: game.captureTimeoutMs } : {}),
+  });
+  return wrapIframeReachableMount2D(mount);
+}
+
+/**
+ * Enter ingest mode for an already-resolved {@link IngestGame2D} descriptor —
+ * the pixi sibling of {@link enterIngestModeWithGame}. `overlayId` is always
+ * the world id, namespacing the saved overlay at the §1.G unified path
+ * (`.vgai/overlays/<worldId>.json`, `authoring/world-overlay.ts` — the SAME
+ * module `play-mode.ts`'s multi-world path already uses, NOT the retired
+ * `2d-`-prefixed `world2d-overlay.ts`).
+ */
+/**
+ * D-W2 (docs/WAVE4-FTUE-HARDENING-DESIGN.md): opaque prebuilt bundle → iframe
+ * embed-only floor (no scene introspection) — the pixi sibling of
+ * `enterIngestModeWithGame`'s identical `game.embedHtml` branch. Extracted
+ * out of {@link enterIngestModeWithGame2D} to keep that function's cognitive
+ * complexity under biome's `noExcessiveCognitiveComplexity` ceiling (this
+ * branch's own try/catch + session/hook wiring pushed it over on its own).
+ * Always a lazy thunk here (see `IngestGame2D.embedHtml`'s doc comment).
+ */
+async function enterIngestModeWithGame2DEmbed(
+  store: EditorStore,
+  game: IngestGame2D,
+  overlayId: string,
+  gameContainer: HTMLElement,
+  embedHtml: () => Promise<string>,
+): Promise<void> {
+  let embedHtmlText: string;
+  try {
+    embedHtmlText = await embedHtml();
+  } catch (err) {
+    editorConsole.error(
+      `Failed to load opaque-embed entryHtml for "${game.name}" (world2d): ${err}`,
+      'ingest',
+    );
+    store.setPlayState('stopped');
+    return;
+  }
+  const embed: EmbedMount2D = mountIngestGame2DEmbed(embedHtmlText, gameContainer);
+  _active = {
+    kind: 'pixi',
+    session: {
+      store,
+      embed,
+      setPaused: () => {},
+      dispose: () => embed.dispose(),
+    },
+    siblings: [],
+  };
+  setGameInputGate(() => store.playState === 'playing' && store.activeViewportTab === 'game');
+  setActiveAuthoring(makeEmbedOnlyAdapter(store, game.name));
+  setActiveSystems({});
+  store.setActiveViewportTab('game');
+  store.notifyIngestEdit();
+  editorConsole.log(`Embedded opaque pixi bundle "${game.name}" (embed-only, world2d)`, 'ingest');
+  (window as unknown as Record<string, unknown>)['__vgaiIngest2D'] = {
+    gameId: overlayId,
+    embedOnly: true,
+    reflected: { count: 0, sprites: 0 },
+  };
+}
+
+export async function enterIngestModeWithGame2D(
+  store: EditorStore,
+  game: IngestGame2D,
+  overlayId: string,
+): Promise<void> {
+  // D-V1: tear down WHATEVER kind is currently active, not just a prior
+  // pixi session — closes the cross-kind leak (F26 residual).
+  exitActiveIngest();
+
+  const gameContainer = getGameContainer();
+  if (!gameContainer) {
+    editorConsole.error('Game container not mounted — cannot ingest (world2d)', 'ingest');
+    return;
+  }
+
+  store.setPlayState('playing');
+  editorConsole.log(`Ingesting unmodified PixiJS game: ${game.name}`, 'ingest');
+
+  if (game.embedHtml) {
+    return enterIngestModeWithGame2DEmbed(store, game, overlayId, gameContainer, game.embedHtml);
+  }
+
+  if (!game.load && !game.bundleUrl) {
+    throw new Error(
+      `enterIngestModeWithGame2D: world2d ingest game "${game.id}" has neither \`load\` nor ` +
+        '`bundleUrl` — only shared/deduped (load) or iframe-reachable (bundleUrl) ingest-pixi ' +
+        'worlds are mountable this slice (resolveIngest2DDescriptor).',
+    );
+  }
+
+  // Track P (docs/PIXI-INGEST-LANDING-DESIGN.md §2/D-P4): the iframe-
+  // reachable-multi route mounts its OWN iframe straight into `gameContainer`
+  // (`mountIngestGame2DIframeReachableMulti`) — it needs no placeholder
+  // `<canvas>`, unlike the shared-instance path below (whose game creates its
+  // own PixiJS `Application` and needs a container element reserved for it).
+  const canvas = game.load ? document.createElement('canvas') : undefined;
+  if (canvas) gameContainer.appendChild(canvas);
+
+  // F26: same cold-mount announcement the threejs adapter makes
+  // (ingest-game-adapter.ts) — a shared-realm pixi game may declare the
+  // game contract and defer its session until ▶; games that ignore the flag
+  // (including iframe-realm bundles, which can't see it) behave as before.
+  (window as unknown as { __vgaiMountCold?: boolean }).__vgaiMountCold = true;
+  const overlay = await loadWorldOverlay<Overlay2D>(overlayId);
+  const mount = game.load
+    ? await mountIngestGame2D(
+        PIXI,
+        game,
+        game.captureTimeoutMs !== undefined ? { captureTimeoutMs: game.captureTimeoutMs } : {},
+      )
+    : await mountIframeReachableGame2D(game, gameContainer);
+
+  if (mount.embedOnly || !mount.stage) {
+    canvas?.remove();
+    mount.dispose();
+    editorConsole.error(
+      `world2d ingest capture failed for "${game.name}" (pixi unreachable) — no embed-only ` +
+        'floor exists for ingest-pixi this slice (resolveIngest2DDescriptor builds no ' +
+        'embedHtml games; iframe-reachable-multi capture just timed out/failed).',
+      'ingest',
+    );
+    return;
+  }
+
+  const stage = mount.stage as Container;
+  // The game's async setup may add display objects after its first captured frame —
+  // wait for the stage to settle (mirrors world2d-mode.ts's prior behavior).
+  for (let i = 0; i < 90 && (stage.children?.length ?? 0) === 0; i++) {
+    await new Promise((r) => requestAnimationFrame(r));
+  }
+
+  const physicsAdapter = createPhysicsAdapter2D(createPhysics2DRegistry());
+  const adapter = new World2DAuthoringAdapter(stage, physicsAdapter, store, {
+    overlay,
+    persist: (o) => saveWorldOverlay(overlayId, o),
+    destination: worldOverlayPath(overlayId),
+  });
+  const stats = adapter.refresh();
+
+  // D-A3 (docs/WAVE6-DOCTOR-DESIGN.md): pixi sibling of the three-side
+  // achieved-tier computation above — `game.load` is the shared/deduped
+  // load() route, otherwise this reached here via the iframe-reachable-multi
+  // bundleUrl route (`mountIframeReachableGame2D`).
+  const achievedTier: Tier = game.load ? 'shared' : 'iframe-reachable';
+
+  _active = {
+    kind: 'pixi',
+    session: {
+      store,
+      adapter,
+      setPaused: (p) => mount.setPaused(p),
+      dispose: () => {
+        mount.dispose();
+        canvas?.remove();
+      },
+    },
+    siblings: [],
+  };
+
+  // R2c: same-realm PixiJS ingest fixtures (`ingest/games-2d/**`) are just as
+  // unshadowed-by-default as the three.js ones — drive the same gate as
+  // {@link enterIngestModeWithGame} (see that function's doc comment).
+  setGameInputGate(() => store.playState === 'playing' && store.activeViewportTab === 'game');
+
+  setActiveAuthoring(adapter);
+  setActiveSystems({});
+  store.setActiveViewportTab('game');
+  store.notifyIngestEdit();
+  setMountFailureReport(null); // D-W3: mount succeeded
+
+  editorConsole.log(
+    `world2d ingest: captured "${game.name}" (${stats.count} nodes, ${stats.sprites} sprites)`,
+    'ingest',
+  );
+
+  (window as unknown as Record<string, unknown>)['__vgaiIngest2D'] = {
+    gameId: overlayId,
+    drawCount: () => mount.capture.getDrawCount(),
+    reflected: stats,
+    setPaused: (p: boolean) => mount.setPaused(p),
+    // D-A3: achieved tier for a headless-verifiable healthy mount (see comment above).
+    achievedTier,
+    adapter,
+    store,
+  };
+}
+
+/**
+ * Enter ingest mode straight from a manifest's `ingest-pixi` world — the pixi
+ * sibling of {@link enterIngestModeFromManifestWorld}. Builds the descriptor
+ * via `resolveIngest2DDescriptor` (adapter-resolver.ts) and mounts it exactly
+ * like any other {@link IngestGame2D}.
+ */
+export async function enterIngestModeFromManifestWorld2D(
+  store: EditorStore,
+  world: ResolvedWorldEntry,
+  projectRoot: string,
+): Promise<void> {
+  const game = resolveIngest2DDescriptor(world, projectRoot);
+  return enterIngestModeWithGame2D(store, game, world.id);
+}
+
+/**
+ * Enter ingest mode for an in-tree world2d fixture game by its discovered id
+ * (the `?ingest=<id>` URL route's pixi fallback — `ingest/discovery2d.ts`'s
+ * glob discovery replaces the deleted `WORLD2D_INGEST_GAMES` registry lookup
+ * here). Pixi sibling of {@link enterIngestMode}.
+ */
+export async function enterIngestMode2D(store: EditorStore, gameId: string): Promise<void> {
+  const game = getIngestGame2D(gameId);
+  if (!game) {
+    editorConsole.error(`Unknown world2d ingest game: ${gameId}`, 'ingest');
+    return;
+  }
+  return enterIngestModeWithGame2D(store, game, gameId);
+}
+
+/**
+ * D-V1: the pixi teardown body — byte-for-byte the pre-collapse
+ * `exitIngestMode2D` logic below, extracted so `exitActiveIngest` can
+ * dispatch to it for ANY kind switch. `_active`/`resetIngestPlaySurface` are
+ * handled by the caller (`exitActiveIngest`) — this only does the
+ * pixi-specific teardown.
+ */
+function disposePixiSession(s: IngestSession2D): void {
+  // R2c: reset the input gate — see disposeThreejsSession's identical comment.
+  setGameInputGate(() => true);
+  // v4 §7.1-13: `World2DAuthoringAdapter` now self-registers with the undo
+  // timeline (mirrors `IngestAuthoringAdapter` — see disposeThreejsSession's
+  // identical call above), so this session's entries must be dropped the same
+  // way on exit. Absent for a D-W2 opaque-embed session (no adapter, no undo entries).
+  if (s.adapter) unregisterUndoAdapter(s.adapter);
+  setActiveAuthoring(null);
+  setActiveSystems(null);
+  setMountFailureReport(null); // D-W3: no session -> no banner to show (mirrors setActiveOverlayReport(null) above)
+  s.store.setPlayState('stopped');
+  try {
+    s.dispose();
+  } catch {
+    /* ignore */
+  }
+  delete (window as unknown as Record<string, unknown>)['__vgaiIngest2D'];
+  editorConsole.log('world2d ingest mode stopped', 'ingest');
+}
+
+/**
+ * Exit PixiJS ingest mode: tear down the captured game + adapter. D-V1: a
+ * thin wrapper that only acts when a pixi session is the one currently
+ * active in `_active` — same observable behavior as before the collapse;
+ * the actual teardown is `disposePixiSession` via `exitActiveIngest`.
+ */
+export function exitIngestMode2D(): void {
+  if (_active?.kind !== 'pixi') return;
+  exitActiveIngest();
+}
+
+// ---------------------------------------------------------------------------
+// Native-React ingest sessions (Track N, N2 — docs/REACT-INGEST-LANDING-
+// DESIGN.md D-N2/D-N8)
+// ---------------------------------------------------------------------------
+
+interface IngestSessionReact {
+  store: EditorStore;
+  /** The runtime Game's real play-state control — the F26 play surface. */
+  setPaused: (paused: boolean) => void;
+  stop: () => void;
+  /** D-K4 (wave 10 Slice A): the live DOM-authoring adapter both routes now
+   *  install — self-registered with the global undo timeline at construction,
+   *  so teardown must unregister it (mirrors `IngestSession2D.adapter`). */
+  adapter: ReactDomAuthoringAdapter;
+}
+
+/** True if an ingested native-React game is currently mounted. */
+export function isIngestActiveReact(): boolean {
+  return _active?.kind === 'react';
+}
+
+/**
+ * D-L1 (wave 10 Slice B, docs/WAVE10-REACT-INGEST-DOM-AUTHORING-DESIGN.md
+ * §2) — the LIVE value behind `__vgaiIngestReact.domEvidence()`, shared by
+ * both react ingest routes below. Evaluated at scrape time (a function
+ * result, never memoized), same "read the live state fresh on every call"
+ * discipline as `__vgaiSiblingMounts` (D-H1).
+ *
+ * `elementCount` prefers the DOM's real `querySelectorAll('*').length` — a
+ * real browser `HTMLElement` (what `reactRoot()` actually returns in
+ * production) always has it — and falls back to the adapter's own
+ * structural-walk size (`nodeCount()`) only when the mounted root doesn't
+ * expose `querySelectorAll` at all (this repo's own vitest-node adapter
+ * fixtures have no real DOM). Never a fabricated number either way: both
+ * paths count real, currently-present elements.
+ *
+ * `reactRootPresent` checks for a React 19 `createRoot` own-property mount
+ * stamp (`__reactContainer$<hash>`) on `root` itself — the SAME element
+ * `reactRoot()` returned, which is exactly the element `createRoot(...)`
+ * rendered into (`create-runtime.ts`'s `ReactWorldHost.container` doc
+ * comment: "the adapter's `mount` renders its react tree INTO this exact
+ * element via `createRoot`").
+ */
+function reactDomEvidence(
+  root: HTMLElement,
+  adapter: ReactDomAuthoringAdapter,
+): { elementCount: number; hierarchyNodeCount: number; reactRootPresent: boolean } {
+  const withQuery = root as unknown as { querySelectorAll?: (sel: string) => ArrayLike<unknown> };
+  const elementCount =
+    typeof withQuery.querySelectorAll === 'function'
+      ? withQuery.querySelectorAll('*').length
+      : adapter.nodeCount();
+  const reactRootPresent = Object.keys(root as object).some((k) =>
+    k.startsWith('__reactContainer'),
+  );
+  return { elementCount, hierarchyNodeCount: adapter.nodeCount(), reactRootPresent };
+}
+
+/**
+ * Enter ingest mode for a discovered native-React fixture game (the
+ * `?ingest=<id>` URL route's react fallback, tried after the three/pixi
+ * fixture globs — see `autoLaunchIngestFromURL` below). Mounts through the
+ * EXACT SAME T6.2 react-world host stack `default-react`/multi-world react
+ * worlds use — NOT the capture-based three/pixi bridge (there is no scene to
+ * capture; the mounted tree IS React, D-N1).
+ *
+ * Reuses `resolveAllWorlds` + the WORLDS-PATH `createGameRuntime` (not the
+ * legacy single-`{canvas,adapter}` path, which is three-only and has no
+ * `ReactWorldHost`/`container` concept — see `create-runtime.ts`'s
+ * `HostContext`) rather than hand-building a `ReactWorldHost`/`Game`: a
+ * single-element `worlds` array gets EVERY host concern for free (the
+ * absolutely-positioned DOM-root layer, a real `Game`, dispose via
+ * `session.stop()`) with zero reinvention — `resolveAllWorlds`'s
+ * `MULTI_WORLD_ALLOWED_IDENTITIES` gate only fires for `worlds.length > 1`
+ * (see that function's doc comment), so a ONE-element manifest containing an
+ * `ingest-react` world resolves cleanly through it despite that identity
+ * being excluded from real multi-world manifests.
+ *
+ * D-N8 v2 / D-K4 (wave 10 Slice A, docs/WAVE10-REACT-INGEST-DOM-AUTHORING-
+ * DESIGN.md §1): the active authoring override is a real
+ * `ReactDomAuthoringAdapter` — a structural-path DOM walker over the mounted
+ * react tree, persisting edits to an overlay (never to source, see that
+ * file's doc comment). The published `achievedTier` is COMPUTED from this
+ * real adapter via `computeAchievedTier` (the same honest authority the
+ * embed-only floor used to derive `'opaque-embed'` from), not hard-coded.
+ */
+export async function enterIngestModeReact(store: EditorStore, folderId: string): Promise<void> {
+  if (getEditorMode() === 'browser') {
+    editorConsole.error(
+      'Native-React ingest needs the dev server (/@fs/ dynamic import) — unavailable in browser mode',
+      'ingest',
+    );
+    return;
+  }
+  const game = getIngestGameReact(folderId);
+  if (!game) {
+    editorConsole.error(`Unknown react ingest game: ${folderId}`, 'ingest');
+    return;
+  }
+  const projectRoot = ingestGameReactProjectRoot(folderId);
+  if (!projectRoot) {
+    editorConsole.error(
+      `React ingest "${folderId}": no __VGAI_ENGINE_ROOT__ available to resolve its entry`,
+      'ingest',
+    );
+    return;
+  }
+  const gameContainer = getGameContainer();
+  if (!gameContainer) {
+    editorConsole.error('Game container not mounted — cannot ingest (react)', 'ingest');
+    return;
+  }
+  // D-V1: tear down WHATEVER kind is currently active, not just a prior
+  // react session — closes the cross-kind leak (F26 residual).
+  exitActiveIngest();
+
+  store.setPlayState('playing');
+  editorConsole.log(`Ingesting unmodified native-React game: ${game.manifest.name}`, 'ingest');
+
+  // F26: same cold-mount announcement as the other ingest tiers — the react
+  // world's entry executes in the editor realm and may declare the game
+  // contract to defer its session until ▶. Opt-in, never demanded.
+  (window as unknown as { __vgaiMountCold?: boolean }).__vgaiMountCold = true;
+  const { createGameRuntime } = await import('@engine/runtime/create-runtime');
+  const specs = await resolveAllWorlds(game.manifest, projectRoot);
+  const w = gameContainer.clientWidth;
+  const h = gameContainer.clientHeight;
+  const session = await createGameRuntime({
+    container: gameContainer,
+    worlds: specs,
+    width: w,
+    height: h,
+  });
+
+  // D-K4: load any previously-saved DOM style overlay, then construct the
+  // real authoring adapter over the mounted world's live DOM root. The
+  // adapter has its own `selection` provider (store-backed, same shape as
+  // `ReactWorldAuthoringAdapter.selection`), so — unlike a `{ module }`
+  // adapter with none — it is installed directly, never `withStoreSelection`-wrapped.
+  const worldId = game.worldId;
+  const overlay = await loadWorldOverlay<ReactDomOverlay>(worldId);
+  const root = session.game.worlds[0]!.reactRoot();
+  const adapter = new ReactDomAuthoringAdapter(root, store, {
+    overlay,
+    persist: (o) => saveWorldOverlay(worldId, o),
+    destination: worldOverlayPath(worldId),
+  });
+  // Unlike the capture tiers, a react ingest mounts through the NATIVE
+  // runtime — its Game.play pause/resume IS the honest control (D10). Named
+  // (rather than inlined below) so `setPausedPresent`'s D-L1 `typeof`
+  // check reads the SAME real control the session actually installs, never
+  // an independent literal.
+  const setPaused = (p: boolean) => (p ? session.game.play.pause() : session.game.play.resume());
+
+  _active = {
+    kind: 'react',
+    session: {
+      store,
+      setPaused,
+      stop: () => session.stop(),
+      adapter,
+    },
+    siblings: [],
+  };
+  // Same play-mode input gate every other same-realm ingest tier drives
+  // (R2c) — harmless here too even though a native-React game's own
+  // listeners are NOT same-realm-shadowed the way `ingest/games`/`games-2d`
+  // are (see game-globals-shadow.ts's roots — `games-react` is not among
+  // them; R-N6 residual, recorded in the N2 report).
+  setGameInputGate(() => store.playState === 'playing' && store.activeViewportTab === 'game');
+
+  setActiveAuthoring(adapter);
+  setActiveSystems({});
+  store.setActiveViewportTab('game');
+  store.notifyIngestEdit();
+  setMountFailureReport(null); // D-W3: mount succeeded
+
+  (window as unknown as Record<string, unknown>)['__vgaiIngestReact'] = {
+    gameId: folderId,
+    worldId: game.worldId,
+    noAuthoring: false,
+    // D-K4: COMPUTED from the real adapter (the same honest authority
+    // `achieved-tier.ts`'s `computeAchievedTier` already was for the prior
+    // embed-only floor) — a hierarchy+inspector+persistence adapter with NO
+    // `transforms` honestly bands as 'shared', never hard-coded.
+    achievedTier: computeAchievedTier({ authoring: adapter }),
+    // D-L1 (wave 10 Slice B): the doctor MOUNTED-bar evidence accessor —
+    // see `reactDomEvidence`'s own doc comment above.
+    domEvidence: () => reactDomEvidence(root, adapter),
+    // D-L1: honest `typeof === 'function'` check on the REAL session
+    // control this route just installed above — never an independent
+    // literal `true` (mirrors `__vgaiSiblingMounts`'s identical discipline).
+    setPausedPresent: typeof setPaused === 'function',
+  };
+}
+
+/**
+ * D-Y2 (docs/EXTERNAL-REACT-AND-MODULE-DESIGN.md §1/§4 slice S2) — the
+ * manifest-route sibling of {@link enterIngestModeReact} above: an
+ * EXTERNAL-FOLDER `ingest-react` world (the opened project's OWN
+ * `vgai.game.json`, not the vendored `games-react/<id>` discovery glob)
+ * enters the same react ingest session. Exactly the same worlds-path recipe
+ * (one-element `resolveAllWorlds` + worlds-path `createGameRuntime`) and the
+ * same `ReactDomAuthoringAdapter` D-K4 wiring (see that function's doc
+ * comment) — only the SOURCE of `world`/`projectRoot` differs (the opened project's manifest +
+ * `project.rootPath`, via `tryManifestIngestRouteReact` below, instead of
+ * `getIngestGameReact`/`ingestGameReactProjectRoot`'s vendored-fixture
+ * lookup). `resolveIngestReactAdapter`'s own guards (D-N3 deduped-only,
+ * `entry` required, no `scene`) run unchanged inside `resolveAllWorlds` — this
+ * function adds no new validation of its own, mirroring
+ * `enterIngestModeFromManifestWorld2D`'s relationship to its vendored
+ * `?ingest=<id>` sibling.
+ */
+export async function enterIngestModeFromManifestWorldReact(
+  store: EditorStore,
+  manifest: ResolvedGameManifest,
+  world: ResolvedWorldEntry,
+  projectRoot: string,
+): Promise<void> {
+  if (getEditorMode() === 'browser') {
+    editorConsole.error(
+      'Native-React ingest needs the dev server (/@fs/ dynamic import) — unavailable in browser mode',
+      'ingest',
+    );
+    return;
+  }
+  const gameContainer = getGameContainer();
+  if (!gameContainer) {
+    editorConsole.error('Game container not mounted — cannot ingest (react)', 'ingest');
+    return;
+  }
+  // D-V1: tear down WHATEVER kind is currently active, not just a prior
+  // react session — closes the cross-kind leak (F26 residual).
+  exitActiveIngest();
+
+  store.setPlayState('playing');
+  editorConsole.log(
+    `Ingesting unmodified native-React game (external folder): ${world.id}`,
+    'ingest',
+  );
+
+  // F26: same cold-mount announcement the vendored route (`enterIngestModeReact`
+  // above) makes — an external-folder game may declare the game contract too.
+  (window as unknown as { __vgaiMountCold?: boolean }).__vgaiMountCold = true;
+  const { createGameRuntime } = await import('@engine/runtime/create-runtime');
+  const specs = await resolveAllWorlds({ ...manifest, worlds: [world] }, projectRoot);
+  const w = gameContainer.clientWidth;
+  const h = gameContainer.clientHeight;
+  const session = await createGameRuntime({
+    container: gameContainer,
+    worlds: specs,
+    width: w,
+    height: h,
+  });
+
+  // D-K4: same overlay-load + adapter construction as the vendored route
+  // above — `worldId` here is `world.id` (the manifest world's own id),
+  // not `game.worldId` (the vendored-fixture wrapper's field).
+  const worldId = world.id;
+  const overlay = await loadWorldOverlay<ReactDomOverlay>(worldId);
+  const root = session.game.worlds[0]!.reactRoot();
+  const adapter = new ReactDomAuthoringAdapter(root, store, {
+    overlay,
+    persist: (o) => saveWorldOverlay(worldId, o),
+    destination: worldOverlayPath(worldId),
+  });
+  // Same honest control as the vendored route (D10): a manifest-routed react
+  // ingest mounts through the NATIVE runtime, so Game.play pause/resume IS
+  // real. Named (D-L1) so `setPausedPresent` checks the SAME real control.
+  const setPaused = (p: boolean) => (p ? session.game.play.pause() : session.game.play.resume());
+
+  _active = {
+    kind: 'react',
+    session: {
+      store,
+      setPaused,
+      stop: () => session.stop(),
+      adapter,
+    },
+    siblings: [],
+  };
+  setGameInputGate(() => store.playState === 'playing' && store.activeViewportTab === 'game');
+
+  setActiveAuthoring(adapter);
+  setActiveSystems({});
+  store.setActiveViewportTab('game');
+  store.notifyIngestEdit();
+  setMountFailureReport(null); // D-W3: mount succeeded
+
+  (window as unknown as Record<string, unknown>)['__vgaiIngestReact'] = {
+    worldId: world.id,
+    noAuthoring: false,
+    // D-K4: see enterIngestModeReact's identical comment above — COMPUTED,
+    // never hard-coded.
+    achievedTier: computeAchievedTier({ authoring: adapter }),
+    // D-L1: see enterIngestModeReact's identical comment above.
+    domEvidence: () => reactDomEvidence(root, adapter),
+    setPausedPresent: typeof setPaused === 'function',
+  };
+}
+
+/**
+ * D-V1: the react teardown body — byte-for-byte the pre-collapse
+ * `exitIngestModeReact` logic below, extracted so `exitActiveIngest` can
+ * dispatch to it for ANY kind switch. `_active`/`resetIngestPlaySurface` are
+ * handled by the caller (`exitActiveIngest`) — this only does the
+ * react-specific teardown.
+ */
+function disposeReactSession(s: IngestSessionReact): void {
+  setGameInputGate(() => true);
+  // D-K4: this session's ReactDomAuthoringAdapter self-registered with the
+  // global undo timeline at construction (mirrors `IngestAuthoringAdapter`/
+  // `World2DAuthoringAdapter`/`ReactWorldAuthoringAdapter`) — drop it so any
+  // of its entries still on the global stack are dropped (with a warn), not
+  // undone against a torn-down DOM.
+  unregisterUndoAdapter(s.adapter);
+  setActiveAuthoring(null);
+  setActiveSystems(null);
+  setMountFailureReport(null); // D-W3: no session -> no banner to show (mirrors disposeThreejsSession's identical call)
+  s.store.setPlayState('stopped');
+  try {
+    s.stop();
+  } catch {
+    /* ignore */
+  }
+  delete (window as unknown as Record<string, unknown>)['__vgaiIngestReact'];
+  editorConsole.log('react ingest mode stopped', 'ingest');
+}
+
+/**
+ * Exit react ingest mode: unmount the react world + tear down its Game/loop.
+ * D-V1: a thin wrapper that only acts when a react session is the one
+ * currently active in `_active` — same observable behavior as before the
+ * collapse; the actual teardown is `disposeReactSession` via
+ * `exitActiveIngest`.
+ */
+export function exitIngestModeReact(): void {
+  if (_active?.kind !== 'react') return;
+  exitActiveIngest();
+}
+
+/**
+ * D-V1: the threejs teardown body — byte-for-byte the pre-collapse
+ * `exitIngestMode` logic below, extracted so `exitActiveIngest` can dispatch
+ * to it for ANY kind switch, not just a same-kind `exitIngestMode()` call.
+ * `_active`/`resetIngestPlaySurface` are handled by the caller
+ * (`exitActiveIngest`) — this only does the threejs-specific teardown.
+ */
+function disposeThreejsSession(s: IngestSession): void {
+  // R2c: no ingest session running — the input gate `enterIngestModeWithGame`
+  // set (alongside every `_active` assignment above) must never stay
+  // suppressed. Mirrors play-mode.ts's exitPlayMode, which resets the same
+  // way on exit.
+  setGameInputGate(() => true);
+
+  // T3.2 slice 2: this ingest session's authoring adapter is done recording —
+  // drop it from the undo timeline's live set so any of its entries still on the
+  // global stack are dropped (with a warn), not undone against a torn-down scene.
+  if (s.mount?.authoring) unregisterUndoAdapter(s.mount.authoring);
+  setActiveAuthoring(null);
+  setActiveSystems(null);
+  setActiveOverlayReport(null); // D9: no session -> no banner to show
+  setMountFailureReport(null); // D-W3: no session -> no mount-failure banner to show either
+  s.resizeObserver?.disconnect();
+  // Only the shared-`three` capture path swaps the editor scene; embed-only never did.
+  if (s.mount) {
+    try {
+      s.store.exitPlayScene();
+    } catch {
+      /* scene may not have been swapped if capture failed */
+    }
+  }
+  s.store.setPlayState('stopped');
+
+  // Tear down the mounted game (stops its loop, frees renderer, uninstalls trap)
+  // or the embedded iframe.
+  try {
+    s.mount?.game.dispose();
+    s.embed?.dispose();
+  } catch {
+    /* ignore */
+  }
+
+  delete (window as unknown as Record<string, unknown>)['__vgaiIngest'];
+  editorConsole.log('Ingest mode stopped', 'ingest');
+}
+
+/**
+ * Exit ingest mode: restore the editor scene and tear down the game. D-V1: a
+ * thin wrapper that only acts when a threejs session is the one currently
+ * active in `_active` — same observable behavior as before the collapse
+ * (a no-op if nothing, or a DIFFERENT kind, is active); the actual teardown
+ * is `disposeThreejsSession` via `exitActiveIngest`.
+ */
+export function exitIngestMode(): void {
+  if (_active?.kind !== 'threejs') return;
+  exitActiveIngest();
+}
+
+// Dev hook so the editor UI / e2e can drive ingestion against the bound store.
+if (import.meta.env.DEV) {
+  (window as unknown as Record<string, unknown>)['__vgaiIngestApi'] = {
+    enter: (gameId: string) => {
+      if (!_boundStore) throw new Error('ingest-mode not bound');
+      return enterIngestMode(_boundStore, gameId);
+    },
+    exit: exitIngestMode,
+    // This hook is the per-kind (threejs) API — keep it slot-specific;
+    // `isIngestActive` itself is kind-agnostic as of F26.
+    isActive: () => _active?.kind === 'threejs',
+    // Test/dev: reset a game's persisted overlay to empty (clean-slate ingests).
+    clearOverlay: (gameId: string) => saveOverlay(gameId, {}),
+  };
+  // Pixi sibling (T6.1 slice 4) — same shape, over the world2d ingest session.
+  (window as unknown as Record<string, unknown>)['__vgaiIngestApi2D'] = {
+    enter: (gameId: string) => {
+      if (!_boundStore) throw new Error('ingest-mode not bound');
+      return enterIngestMode2D(_boundStore, gameId);
+    },
+    exit: exitIngestMode2D,
+    isActive: isIngestActive2D,
+    clearOverlay: (worldId: string) => saveWorldOverlay(worldId, {}),
+  };
+  // React sibling (Track N, N2) — same shape, over the native-React ingest
+  // session. No `clearOverlay` (D-N8: no authoring/overlay surface in v1).
+  (window as unknown as Record<string, unknown>)['__vgaiIngestApiReact'] = {
+    enter: (folderId: string) => {
+      if (!_boundStore) throw new Error('ingest-mode not bound');
+      return enterIngestModeReact(_boundStore, folderId);
+    },
+    exit: exitIngestModeReact,
+    isActive: isIngestActiveReact,
+  };
+  // D-A3 (docs/WAVE6-DOCTOR-DESIGN.md): headless-readable mount outcomes —
+  // `packages/editor/src/authoring/mount-failure-report.ts`'s multi-entry
+  // list is otherwise only ever read by `MountFailureBanner.tsx` (a React
+  // component), invisible to `page.evaluate()`. This is a plain function
+  // returning the LIVE list (never a snapshot) — `vgai doctor`'s browser
+  // phase is this surface's first consumer, but any other dev/e2e caller can
+  // poll it the same way `__vgaiIngestApi*` are already polled.
+  (window as unknown as Record<string, unknown>)['__vgaiMountFailureReports'] = () =>
+    getMountFailureReports();
+  // D-H1 (docs/WAVE9-SIBLING-PERSISTENCE-DOCTOR-DESIGN.md Slice B):
+  // headless-readable per-sibling signal — `_active.siblings` (D-V2's
+  // composite-sibling handles, `ingest-siblings.ts`'s `SiblingMount[]`) is
+  // otherwise invisible to `page.evaluate()`, same blind spot
+  // `__vgaiMountFailureReports` closed for mount failures. A plain function
+  // returning a LIVE view (never a snapshot, re-reads `_active` on every
+  // call) of honest per-sibling flags only — no capture/draw proof, see
+  // `DoctorSiblingEvidence`'s doc comment (`packages/editor/src/doctor/report.ts`).
+  (window as unknown as Record<string, unknown>)['__vgaiSiblingMounts'] = () =>
+    (_active?.siblings ?? []).map((s) => ({
+      worldId: s.worldId,
+      setPausedPresent: typeof s.setPaused === 'function',
+      authoringPresent: !!s.authoring,
+      authoringPersist: s.authoring?.capabilities.persist === true,
+    }));
+}
+
+/**
+ * Wait for the Game-tab container (registered via a callback ref at layout
+ * mount) — poll a bounded number of rAF ticks so we don't race the first
+ * paint. Exported (T3.4 slice 2) so `module-mode.ts`'s manifest-route auto-
+ * mount for `{ module }` worlds — the sibling of `tryManifestIngestRoute`
+ * below — can reuse the SAME wait rather than duplicating it.
+ */
+export async function waitForGameContainer(): Promise<boolean> {
+  return new Promise<boolean>((resolve) => {
+    let tries = 0;
+    const tick = () => {
+      if (getGameContainer()) return resolve(true);
+      if (++tries > 120) return resolve(false); // ~2s at 60fps
+      requestAnimationFrame(tick);
+    };
+    tick();
+  });
+}
+
+/**
+ * D-V2 (docs/WAVE5-MULTIWORLD-INGEST-DESIGN.md, F24 composite): every world
+ * in `manifest.worlds` whose adapter is `{ ingest }` — a composite manifest
+ * caps this at exactly one (see each `tryManifestIngestRoute*` below); ≥2 is
+ * a loud named error via {@link reportTooManyIngestWorlds}, never a silent
+ * first-wins pick (mirrors `run-bundle.ts`'s fail-on-ambiguity pattern).
+ */
+function findIngestWorlds(manifest: ResolvedGameManifest): ResolvedWorldEntry[] {
+  return manifest.worlds.filter((w) => w.adapter.type === 'ingest');
+}
+
+/**
+ * D-V2: the "composite declares ≥2 ingest worlds" violation — named, listing
+ * every offending world id, reported once (into BOTH `editorConsole` and the
+ * D-V5 multi-entry mount-failure report, one entry per offending world so
+ * the banner names all of them) by whichever `tryManifestIngestRoute*`
+ * happens to run first (module route order: three, pixi, react — see
+ * `autoLaunchIngestFromURL`) — the caller returns `true` right after this
+ * (claims the route), so the other two ingest routes never also report it.
+ */
+function reportTooManyIngestWorlds(ingestWorlds: ResolvedWorldEntry[]): void {
+  const ids = ingestWorlds.map((w) => `"${w.id}"`).join(', ');
+  const message =
+    'a composite manifest declares exactly ONE ingest world in this slice — found ' +
+    `${ingestWorlds.length}: ${ids} (docs/WAVE5-MULTIWORLD-INGEST-DESIGN.md D-V2).`;
+  editorConsole.error(`Manifest composite ingest route: ${message}`, 'ingest');
+  for (const world of ingestWorlds) {
+    addMountFailureReport({
+      worldId: world.id,
+      kind: world.kind,
+      identity: world.adapter.identity,
+      message,
+    });
+  }
+}
+
+/**
+ * D-V2: attach a composite's sibling handles onto the JUST-entered `_active`
+ * session (set by the primary ingest world's own `enterIngestMode*` call,
+ * immediately before this runs) — a no-op if `_active` is somehow no longer
+ * set (defensive only; nothing in this synchronous call chain clears it
+ * between the primary mount and this attach).
+ */
+function attachIngestSiblings(siblings: readonly SiblingMount[]): void {
+  if (_active) _active.siblings = [...siblings];
+}
+
+/**
+ * D-V2: mount every OTHER world in a composite manifest (every world besides
+ * `ingestWorldId`, the one just entered through its own `enterIngestMode*`
+ * path) via `ingest-siblings.ts`'s `mountIngestSiblings`, and attach the
+ * resulting handles onto `_active` so `exitActiveIngest` tears them down.
+ * Dynamically imported — `ingest-siblings.ts` imports from `module-mode.ts`,
+ * which itself statically imports `waitForGameContainer` from THIS module;
+ * a static import here would close that cycle at the wrong end (mirrors
+ * `autoLaunchIngestFromURL`'s own dynamic import of `module-mode.ts` below,
+ * for the identical reason). Never throws: `mountIngestSiblings` already
+ * catches every individual sibling's failure into the mount-failure report.
+ * Returns the mounted handles so the caller can promote authoring (D-E2,
+ * {@link promoteToCompositeAuthoring}) — `store` is threaded through so each
+ * sibling gets an honest `SiblingMount.authoring` (D-E1).
+ */
+async function mountCompositeSiblings(
+  manifest: ResolvedGameManifest,
+  ingestWorldId: string,
+  gameContainer: HTMLElement,
+  projectRoot: string,
+  store: EditorStore,
+): Promise<SiblingMount[]> {
+  const { mountIngestSiblings } = await import('./ingest-siblings');
+  const siblings = await mountIngestSiblings(
+    manifest,
+    ingestWorldId,
+    gameContainer,
+    projectRoot,
+    store,
+  );
+  attachIngestSiblings(siblings);
+  return siblings;
+}
+
+/**
+ * D-E2 (docs/WAVE8-SIBLING-AUTHORING-DESIGN.md, §1F promotion on the ingest
+ * composite): when a composite's siblings actually mounted (`siblings.length
+ * > 0`), promote the active authoring override — currently the PRIMARY
+ * ingest world's own plain adapter, installed by the route's own enter path
+ * that just ran immediately before this call — to a `CompositeAuthoringAdapter`
+ * whose ordered children are the primary world FIRST (it is the route's
+ * anchor) followed by every mounted sibling in manifest order, each routed by
+ * its own manifest `kind`. A single-world mount (`siblings.length === 0`) is
+ * untouched — byte-stable, no group node, no wrapper: §1F's single-world
+ * clause.
+ *
+ * The primary's own adapter is read back via `getAuthoringOverride()` rather
+ * than threaded as a parameter — every composite route's own `enterIngestMode*`
+ * call already installed it via `setActiveAuthoring` synchronously before
+ * this runs (mirrors `attachIngestSiblings`'s identical "just installed"
+ * assumption above); `null` (defensive only — nothing in this synchronous
+ * call chain clears it in between) is a no-op, same guard shape.
+ */
+function promoteToCompositeAuthoring(
+  manifest: ResolvedGameManifest,
+  ingestWorld: ResolvedWorldEntry,
+  siblings: readonly SiblingMount[],
+): void {
+  if (siblings.length === 0) return;
+  const primaryAdapter = getAuthoringOverride();
+  if (!primaryAdapter) return;
+  const children: CompositeChild[] = [
+    { worldId: ingestWorld.id, kind: ingestWorld.kind, adapter: primaryAdapter },
+    ...siblings.map((s) => ({
+      worldId: s.worldId,
+      kind: manifest.worlds.find((w) => w.id === s.worldId)?.kind ?? 'unknown',
+      // D-E1: every successfully-mounted SiblingMount gets an honest
+      // `authoring` whenever a store was supplied — every composite route
+      // below supplies one, so this is never actually undefined in
+      // production; the non-null assertion mirrors D-E2's own spec.
+      adapter: s.authoring!,
+    })),
+  ];
+  setActiveAuthoring(new CompositeAuthoringAdapter(children));
+}
+
+/**
+ * Route 1 of `autoLaunchIngestFromURL` (T3.3 slice 3, §1E): a manifest-backed
+ * project declaring an `ingest-three` world enters ingest mode straight from
+ * that world. Returns `true` if this route applied (whether it succeeded or
+ * logged an error) — the caller must not also try route 2 in that case
+ * (§1B's "manifest wins" discovery order); `false` means "no manifest, no
+ * ingest world at all, or the one ingest world isn't ingest-three", so the
+ * next route (pixi, react, then the URL route) still gets a chance.
+ *
+ * D-V2 (F24 composite): scans ALL worlds for `{ ingest }` adapters, not just
+ * `worlds[0]` — 0 ingest worlds declines (unchanged non-ingest-manifest
+ * behavior); ≥2 claims the route and fails loudly
+ * ({@link reportTooManyIngestWorlds}), mounting nothing; exactly 1 whose
+ * identity is `ingest-three` mounts THAT world (wherever it sits in the
+ * array) through the existing enter path, then mounts every other world as a
+ * sibling ({@link mountCompositeSiblings}) — a sibling failure never
+ * unmounts the ingest world (it is caught internally, per-world, by
+ * `ingest-siblings.ts`).
+ */
+async function tryManifestIngestRoute(store: EditorStore): Promise<boolean> {
+  if (getEditorMode() === 'browser') return false; // no dev server to serve /vgai.game.json from
+  const manifest = await fetchGameManifest().catch(() => null);
+  if (!manifest) return false;
+  const ingestWorlds = findIngestWorlds(manifest);
+  if (ingestWorlds.length === 0) return false;
+  if (ingestWorlds.length > 1) {
+    reportTooManyIngestWorlds(ingestWorlds);
+    return true;
+  }
+  const ingestWorld = ingestWorlds[0]!;
+  if (ingestWorld.adapter.identity !== 'ingest-three') return false;
+
+  const project = getCurrentProject();
+  if (!project) {
+    editorConsole.error(
+      'Manifest declares an ingest-three world but no project is open — cannot auto-ingest',
+      'ingest',
+    );
+    return true;
+  }
+  const ready = await waitForGameContainer();
+  if (!ready) {
+    editorConsole.error('Game container never mounted — cannot auto-ingest', 'ingest');
+    return true;
+  }
+  try {
+    // D9/T7.7: thread the manifest's OWN version through — resolveIngestDescriptor
+    // (called inside enterIngestModeFromManifestWorld) only sees the per-world
+    // ResolvedWorldEntry, not this top-level field.
+    // R5 (§4(c)): best-effort read of this project's UPSTREAM.md pin, same
+    // spirit — resolveIngestDescriptor has no way to discover one either.
+    const upstreamPin = await readVendoredUpstreamPin();
+    await enterIngestModeFromManifestWorld(
+      store,
+      ingestWorld,
+      project.rootPath,
+      manifest.version,
+      upstreamPin,
+    );
+    // D-V2: mount every OTHER world as a composite sibling — a no-op loop
+    // when this is a single-world manifest (nothing else to iterate).
+    const gameContainer = getGameContainer();
+    if (gameContainer) {
+      const siblings = await mountCompositeSiblings(
+        manifest,
+        ingestWorld.id,
+        gameContainer,
+        project.rootPath,
+        store,
+      );
+      // D-E2: promote to a composite once any sibling actually mounted —
+      // byte-stable (no-op) for a single-world manifest.
+      promoteToCompositeAuthoring(manifest, ingestWorld, siblings);
+    }
+  } catch (err) {
+    editorConsole.error(`Manifest ingest-three auto-launch failed: ${err}`, 'ingest');
+    // D-W3 (F9): this console line was, until now, the ONLY trace this
+    // failure left anywhere in the UI — the default Untitled scene has
+    // already loaded by this point (§0.4), so nothing visibly changes.
+    // Populate the loud banner slot too.
+    setMountFailureReport({
+      worldId: ingestWorld.id,
+      kind: ingestWorld.kind,
+      identity: ingestWorld.adapter.identity,
+      message: formatMountFailureMessage(err),
+    });
+  }
+  return true;
+}
+
+/**
+ * PixiJS sibling of {@link tryManifestIngestRoute} (T6.1 slice 4): a
+ * manifest-backed project declaring an `ingest-pixi` world enters world2d
+ * ingest mode straight from that world. Same "applied or not" contract, same
+ * D-V2 composite scan/route-selection/sibling-mount shape as its three
+ * sibling above.
+ */
+async function tryManifestIngestRoute2D(store: EditorStore): Promise<boolean> {
+  if (getEditorMode() === 'browser') return false; // no dev server to serve /vgai.game.json from
+  const manifest = await fetchGameManifest().catch(() => null);
+  if (!manifest) return false;
+  const ingestWorlds = findIngestWorlds(manifest);
+  if (ingestWorlds.length === 0) return false;
+  if (ingestWorlds.length > 1) {
+    reportTooManyIngestWorlds(ingestWorlds);
+    return true;
+  }
+  const ingestWorld = ingestWorlds[0]!;
+  if (ingestWorld.adapter.identity !== 'ingest-pixi') return false;
+
+  const project = getCurrentProject();
+  if (!project) {
+    editorConsole.error(
+      'Manifest declares an ingest-pixi world but no project is open — cannot auto-ingest',
+      'ingest',
+    );
+    return true;
+  }
+  const ready = await waitForGameContainer();
+  if (!ready) {
+    editorConsole.error('Game container never mounted — cannot auto-ingest', 'ingest');
+    return true;
+  }
+  try {
+    await enterIngestModeFromManifestWorld2D(store, ingestWorld, project.rootPath);
+    const gameContainer = getGameContainer();
+    if (gameContainer) {
+      const siblings = await mountCompositeSiblings(
+        manifest,
+        ingestWorld.id,
+        gameContainer,
+        project.rootPath,
+        store,
+      );
+      // D-E2: promote to a composite once any sibling actually mounted —
+      // byte-stable (no-op) for a single-world manifest.
+      promoteToCompositeAuthoring(manifest, ingestWorld, siblings);
+    }
+  } catch (err) {
+    editorConsole.error(`Manifest ingest-pixi auto-launch failed: ${err}`, 'ingest');
+    // D-W3 (F9) — see tryManifestIngestRoute's identical comment above.
+    setMountFailureReport({
+      worldId: ingestWorld.id,
+      kind: ingestWorld.kind,
+      identity: ingestWorld.adapter.identity,
+      message: formatMountFailureMessage(err),
+    });
+  }
+  return true;
+}
+
+/**
+ * React sibling of {@link tryManifestIngestRoute}/{@link tryManifestIngestRoute2D}
+ * (D-Y2, docs/EXTERNAL-REACT-AND-MODULE-DESIGN.md §1/§4 slice S2): a
+ * manifest-backed project declaring an `ingest-react` world enters the
+ * native-React ingest session straight from that world (external folder —
+ * `vgai edit <folder>` — not the vendored `games-react/<id>` discovery glob).
+ * Same "applied or not" contract, same D-V2 composite scan/route-selection/
+ * sibling-mount shape as its three/pixi siblings above.
+ */
+async function tryManifestIngestRouteReact(store: EditorStore): Promise<boolean> {
+  if (getEditorMode() === 'browser') return false; // no dev server to serve /vgai.game.json from
+  const manifest = await fetchGameManifest().catch(() => null);
+  if (!manifest) return false;
+  const ingestWorlds = findIngestWorlds(manifest);
+  if (ingestWorlds.length === 0) return false;
+  if (ingestWorlds.length > 1) {
+    reportTooManyIngestWorlds(ingestWorlds);
+    return true;
+  }
+  const ingestWorld = ingestWorlds[0]!;
+  if (ingestWorld.adapter.identity !== 'ingest-react') return false;
+
+  const project = getCurrentProject();
+  if (!project) {
+    editorConsole.error(
+      'Manifest declares an ingest-react world but no project is open — cannot auto-ingest',
+      'ingest',
+    );
+    return true;
+  }
+  const ready = await waitForGameContainer();
+  if (!ready) {
+    editorConsole.error('Game container never mounted — cannot auto-ingest', 'ingest');
+    return true;
+  }
+  try {
+    await enterIngestModeFromManifestWorldReact(store, manifest, ingestWorld, project.rootPath);
+    const gameContainer = getGameContainer();
+    if (gameContainer) {
+      const siblings = await mountCompositeSiblings(
+        manifest,
+        ingestWorld.id,
+        gameContainer,
+        project.rootPath,
+        store,
+      );
+      // D-E2: promote to a composite once any sibling actually mounted —
+      // byte-stable (no-op) for a single-world manifest.
+      promoteToCompositeAuthoring(manifest, ingestWorld, siblings);
+    }
+  } catch (err) {
+    editorConsole.error(`Manifest ingest-react auto-launch failed: ${err}`, 'ingest');
+    // D-W3 (F9) — see tryManifestIngestRoute's identical comment above.
+    setMountFailureReport({
+      worldId: ingestWorld.id,
+      kind: ingestWorld.kind,
+      identity: ingestWorld.adapter.identity,
+      message: formatMountFailureMessage(err),
+    });
+  }
+  return true;
+}
+
+/**
+ * Hosted entry point, called once after `loadInitialScene`: auto-launch ingest
+ * mode from whichever discovery route applies, so ingestion is drivable
+ * without the dev hook. Checked in order (§1B's "manifest wins" discovery
+ * order):
+ *
+ *  1. Manifest route, `{ module }` (T3.4 slice 2, docs/ADAPTER-AUTHORING-
+ *     DESIGN.md §2/§3 slice 2, `./module-mode.ts`'s `tryManifestModuleRoute`)
+ *     — a manifest's first world declaring a custom adapter module
+ *     auto-mounts through the generic `GameAdapter`/`HostContext` contract
+ *     (or, since wave 2's D-Y1, the WORLDS PATH for a non-three module world
+ *     — see that file) and installs ITS OWN `MountedGame.authoring` as the
+ *     active override, so the SAME adapter-driven hierarchy/inspector panels
+ *     below drive it. Mutually exclusive with routes 2–4 by construction (a
+ *     world resolves to exactly one adapter identity).
+ *  2. Manifest route, three (T3.3 slice 3, docs/CLI-ON-FOLDER-DESIGN.md §1E,
+ *     `tryManifestIngestRoute` above) — the CLI-on-folder AC ("point the CLI
+ *     at an ingest game folder never registered in source -> opens, plays,
+ *     edits"). Browser-mode builds and legacy `project.json`-only projects
+ *     both fall straight through to route 5, unchanged.
+ *  3. Manifest route, pixi (T6.1 slice 4, `tryManifestIngestRoute2D` above) —
+ *     the world2d silo retirement's replacement discovery path for an
+ *     `ingest-pixi` world.
+ *  4. Manifest route, react (D-Y2, wave 2, `tryManifestIngestRouteReact`
+ *     above) — the external-folder replacement discovery path for an
+ *     `ingest-react` world (the vendored `?ingest=<id>` glob below stays the
+ *     in-tree-fixture route). A manifest's first world resolves to exactly
+ *     one adapter identity, so routes 1–4 are mutually exclusive in
+ *     practice; all are tried since neither can tell that in advance without
+ *     fetching.
+ *  5. `?ingest=<gameId>` URL route: resolves `gameId` against the in-tree
+ *     three.js fixture glob first (`ingest/discovery.ts`, unchanged), then —
+ *     T6.1 slice 4 — the world2d fixture glob (`ingest/discovery2d.ts`,
+ *     bunnymark/flappy/tilemap-camera's replacement launch route for the
+ *     retired `__vgaiWorld2dApi.enterVendored`-style dev hook), then —
+ *     Track N, N2 — the native-React fixture glob (`ingest/discovery-react
+ *     .ts`, e.g. `?ingest=react-rpg`). Unknown ids are ignored (a console
+ *     note); the editor stays a normal session.
+ */
+export async function autoLaunchIngestFromURL(store: EditorStore): Promise<void> {
+  const { tryManifestModuleRoute } = await import('./module-mode');
+  if (await tryManifestModuleRoute(store)) return;
+  if (await tryManifestIngestRoute(store)) return;
+  if (await tryManifestIngestRoute2D(store)) return;
+  if (await tryManifestIngestRouteReact(store)) return;
+
+  const gameId = new URLSearchParams(window.location.search).get('ingest');
+  if (!gameId) return;
+  const ready = await waitForGameContainer();
+  if (getIngestGame(gameId)) {
+    if (!ready) {
+      editorConsole.error('Game container never mounted — cannot auto-ingest', 'ingest');
+      return;
+    }
+    try {
+      await enterIngestMode(store, gameId);
+    } catch (err) {
+      editorConsole.error(`Auto-ingest failed: ${err}`, 'ingest');
+      // D-W3 (F9): the `?ingest=<id>` URL-fallback route has no
+      // `ResolvedWorldEntry` to read a world id/kind from (it resolves
+      // straight off the in-tree fixture globs) — `gameId` and the fixed
+      // 'threejs'/'ingest-three' vocabulary are the closest honest analog.
+      setMountFailureReport({
+        worldId: gameId,
+        kind: 'threejs',
+        identity: 'ingest-three',
+        message: formatMountFailureMessage(err),
+      });
+    }
+    return;
+  }
+  if (getIngestGame2D(gameId)) {
+    if (!ready) {
+      editorConsole.error('Game container never mounted — cannot auto-ingest', 'ingest');
+      return;
+    }
+    try {
+      await enterIngestMode2D(store, gameId);
+    } catch (err) {
+      editorConsole.error(`Auto-ingest failed (world2d): ${err}`, 'ingest');
+      setMountFailureReport({
+        worldId: gameId,
+        kind: 'pixijs',
+        identity: 'ingest-pixi',
+        message: formatMountFailureMessage(err),
+      });
+    }
+    return;
+  }
+  if (getIngestGameReact(gameId)) {
+    if (!ready) {
+      editorConsole.error('Game container never mounted — cannot auto-ingest', 'ingest');
+      return;
+    }
+    try {
+      await enterIngestModeReact(store, gameId);
+    } catch (err) {
+      editorConsole.error(`Auto-ingest failed (react): ${err}`, 'ingest');
+      setMountFailureReport({
+        worldId: gameId,
+        kind: 'react',
+        identity: 'ingest-react',
+        message: formatMountFailureMessage(err),
+      });
+    }
+    return;
+  }
+  editorConsole.error(`Unknown ingest game in ?ingest= : "${gameId}"`, 'ingest');
+}