@vgai/editor 0.2.0

package/src/module-mode.ts

@@ -0,0 +1,513 @@
+/**
+ * Module-adapter auto-mount route (T3.4 slice 2, docs/ADAPTER-AUTHORING-
+ * DESIGN.md §2/§3 slice 2) — the `{ module }` sibling of `ingest-mode.ts`'s
+ * `tryManifestIngestRoute`/`tryManifestIngestRoute2D`.
+ *
+ * A manifest-backed project whose FIRST world declares a custom `{ module }`
+ * adapter auto-mounts it through the generic `GameAdapter.mount(HostContext)`
+ * contract — `createGameRuntime` (the SAME engine-side host `play-mode.ts`'s
+ * legacy single-world Play branch uses) — then installs the MOUNTED game's
+ * OWN `AuthoringAdapter` (`MountedGame.authoring`) as the active authoring
+ * override (`setActiveAuthoring`).
+ *
+ * FINDING (report prominently — see this slice's "Report back"): this is a
+ * gap `play-mode.ts`'s existing `resolveWorldAdapter` call (its single-world
+ * Play branch) does NOT close. That branch always calls
+ * `installPlayAuthoring(store)`, which drives the hierarchy/inspector from
+ * `getActiveAuthoring(store)` — i.e. the FIRST-PARTY `.vscn`-over-`store`
+ * adapter — never from `session.mounted.authoring`. That's the right choice
+ * for `default-three`/`default-pixi`/`default-react` worlds (their mounted
+ * scene mirrors the store's OWN document), but it is WRONG for a `{ module }`
+ * world: a custom adapter builds its scene from its own code, so driving the
+ * inspector from the store's `.vscn` document would show an unrelated (empty,
+ * for a fresh CLI-on-folder project) tree instead of the module's real
+ * objects. `play-mode.ts` is out of scope for this slice (sibling agent's
+ * region), so rather than leave `{ module }` worlds unreachable through the
+ * real editor UI at all, this file gives them their OWN auto-mount route —
+ * mirroring ingest mode's already-established shape (auto-mount on load,
+ * install the mounted adapter as the override, swap the viewport onto the
+ * live scene) instead of Play mode's.
+ *
+ * This route reuses the SAME generic, adapter-driven `GameHierarchy`/
+ * `Inspector` panels ingest mode renders — the hierarchy panel (A2) is
+ * unconditionally contract-only; the inspector (C2, `components/
+ * Inspector.tsx`) matches registered sections per SELECTED NODE via
+ * `inspector-section-registry.ts`, and a bare `{ module }` override is never
+ * a first-party `VgaiSceneAuthoringAdapter`, so its nodes never match the
+ * first-party registrations and always render the generic built-in blocks —
+ * so a module adapter's hierarchy/inspector/gizmo reach the SAME editor UI
+ * ingest games do, with NO
+ * new panel code. The one piece those panels need that ingest's OWN capture
+ * machinery provides for free — `userData.entityId` tags on every live
+ * `Object3D`, which the viewport's gizmo/selection binds on
+ * (`ViewportPanel.tsx`'s `viewport.objectMap = store.objectMap`, built by
+ * `EditorStore.enterPlayScene` from that tag) — this route tags itself, right
+ * after mount, straight from the adapter's OWN `HierarchyProvider` (walking
+ * `mounted.scene` and asking `idForObject3D` for each object) so a `{ module
+ * }` adapter author does not have to hand-roll that tagging themselves.
+ *
+ * D-Y1 (docs/EXTERNAL-REACT-AND-MODULE-DESIGN.md §1/§4 slice S1) adds the
+ * WORLDS-PATH sibling below (`enterModuleModeWorldsPath`): a single-world
+ * manifest whose first world is `kind: 'pixijs' | 'react'` with a `{ module }`
+ * adapter no longer dead-ends in the legacy `enterModuleModeFromManifestWorld`
+ * route above (whose `HostContext`/`mounted.scene` assumptions are threejs-
+ * only — the exact gap the D-X6 guard, still below, catches). The wave-2
+ * ground-truth study found `resolveAllWorlds` ALREADY resolves a `{ module }`
+ * world for every kind (its `'module'` switch case is kind-agnostic) and
+ * ALREADY hands it back as the correctly-kinded `WorldMountSpec` — so the fix
+ * is routing, not an engine change: mirror `ingest-mode.ts`'s
+ * `enterIngestModeReact` recipe (one-element `resolveAllWorlds` + worlds-path
+ * `createGameRuntime({ container, worlds })`) instead of the legacy single-
+ * adapter path. `tryManifestModuleRoute` below picks between the two based on
+ * `firstWorld.kind` — threejs module worlds keep calling
+ * `enterModuleModeFromManifestWorld` byte-for-byte; the D-X6 guard stays
+ * reachable (and its own tests unmodified) for any caller that still invokes
+ * that function directly with a non-three world.
+ */
+
+import type { AuthoringAdapter } from '@engine/adapter';
+import type { ResolvedGameManifest, ResolvedWorldEntry } from '@engine/manifest/load';
+import type { GameSession, WorldMountSpec } from '@engine/runtime/create-runtime';
+import { setUserData } from '@engine/scene/user-data';
+import type * as THREE from 'three';
+import {
+  computeAchievedTier,
+  computeTierShortfall,
+  formatTierShortfallMessage,
+  type TierShortfallReport,
+} from './achieved-tier';
+import { resolveAllWorlds, resolveWorldAdapter } from './adapter-resolver';
+import { setActiveAuthoring } from './authoring/active-adapter';
+import { setActiveSystems } from './authoring/active-systems';
+import { makeEmbedOnlyAdapter } from './authoring/embed-only-adapter';
+import { formatMountFailureMessage, setMountFailureReport } from './authoring/mount-failure-report';
+import { editorConsole } from './editor-console';
+import { getEditorMode } from './editor-mode';
+import type { EditorStore } from './editor-store';
+import { waitForGameContainer } from './ingest-mode';
+import { fetchGameManifest } from './manifest-project';
+import { getGameContainer } from './play-mode';
+import { getCurrentProject } from './project-manager';
+
+interface ModuleSession {
+  store: EditorStore;
+  stop: () => void;
+  /** Absent on the worlds-path route (D-Y1 below) — that route owns no
+   *  standalone canvas of its own; `createGameRuntime`'s worlds-path session
+   *  builds and tears down its own per-world surface(s) directly inside the
+   *  game container. Present (and removed on exit) only for the legacy
+   *  threejs single-adapter path's own hand-created canvas. */
+  canvas?: HTMLCanvasElement | undefined;
+}
+
+let _session: ModuleSession | null = null;
+
+/** True if a `{ module }` adapter world is currently auto-mounted. */
+export function isModuleModeActive(): boolean {
+  return _session !== null;
+}
+
+/** Tag every live object a module adapter's hierarchy actually knows about with
+ *  `userData.entityId` (the SAME key `IngestAuthoringAdapter`'s own capture
+ *  uses) so the viewport's existing objectMap-keyed gizmo/selection binds to
+ *  this adapter's objects with no adapter-author effort. Best-effort: an
+ *  adapter with no `hierarchy` (opaque) has nothing to walk. */
+function tagObjectsWithEntityIds(
+  scene: THREE.Scene,
+  idForObject3D: (o: THREE.Object3D) => string | null,
+): void {
+  scene.traverse((o) => {
+    const id = idForObject3D(o);
+    if (id) setUserData(o, 'entityId', id);
+  });
+}
+
+/**
+ * Selection is editor-global UI state (the SAME rule `IngestAuthoringAdapter`'s
+ * own doc comment states) — a custom `{ module }` adapter has no `EditorStore`
+ * reference to delegate to (by design: `HostContext` is editor-neutral), so
+ * the hierarchy panel's row click (`adapter.selection?.set([node.id])`) would
+ * silently no-op without this. Wrap the mounted adapter with a store-backed
+ * `SelectionProvider` UNLESS it already declares its own (an adapter author
+ * who genuinely wants custom multi-select semantics is not overridden). This
+ * costs the adapter author nothing — they never see `EditorStore` at all.
+ */
+export function withStoreSelection(
+  authoring: AuthoringAdapter,
+  store: EditorStore,
+): AuthoringAdapter {
+  if (authoring.selection) return authoring;
+  return {
+    ...authoring,
+    selection: {
+      get: () => [...store.selectedEntityIds],
+      set: (ids) => store.selectMultiple(ids),
+    },
+  };
+}
+
+/**
+ * Mount a manifest's `{ module }` world straight through `GameAdapter.mount`
+ * and install it as the editor's live authoring override. `world.capabilities
+ * .local` (always resolved/explicit for a module world — the loader requires
+ * it, `manifest/load.ts`'s `resolveCapabilities`) is the declared tier; the
+ * ACTUAL achieved tier is recomputed here (in addition to
+ * `resolveWorldAdapter`'s own internal, warn-only check, T3.4 slice 1) purely
+ * to expose the structured values on the `__vgaiModule` dev/e2e hook below —
+ * this does not log a second shortfall line, it only reads the same pure
+ * computation slice 1 already logs from inside the resolver.
+ */
+export async function enterModuleModeFromManifestWorld(
+  store: EditorStore,
+  world: ResolvedWorldEntry,
+  projectRoot: string,
+): Promise<void> {
+  const gameContainer = getGameContainer();
+  if (!gameContainer) {
+    editorConsole.error('Game container not mounted — cannot auto-mount module adapter', 'adapter');
+    return;
+  }
+
+  store.setPlayState('playing');
+  editorConsole.log(`Mounting custom adapter module for world "${world.id}"`, 'adapter');
+
+  // `resolveWorldAdapter`'s `module` branch (T3.4 slice 1) already: path-guards
+  // + shape-checks the module, then wraps its `mount` with the achieved-tier
+  // warn-only check (`withAchievedTierCheck`) — reused verbatim here, not
+  // duplicated.
+  const adapter = await resolveWorldAdapter(world, projectRoot);
+
+  const canvas = document.createElement('canvas');
+  canvas.style.cssText = 'width:100%;height:100%;display:block;';
+  gameContainer.appendChild(canvas);
+  const w = gameContainer.clientWidth || 800;
+  const h = gameContainer.clientHeight || 600;
+
+  const { createGameRuntime } = await import('@engine/runtime/create-runtime');
+  const session = await createGameRuntime({ canvas, width: w, height: h, adapter });
+  const mounted = session.mounted;
+
+  // D-X6 honesty guard (docs/EXTERNAL-FOLDER-INGEST-DESIGN.md §2/§6 slice S4):
+  // this route only wires up THREE.Scene-shaped worlds — everything below
+  // (`tagObjectsWithEntityIds`, `store.enterPlayScene`) assumes `mounted.scene`
+  // exists. A pixi/react `{ module }` world's mounted result has NO `.scene`
+  // at all (`MountedPixiWorld`/`MountedReactWorld`, `@engine/adapter` —
+  // `guardModuleShape` only checks the ADAPTER's `id`/`mount` shape, never
+  // the resolved MOUNT result's kind), so continuing silently would pass
+  // `undefined` into `enterPlayScene` — exactly the silent dead end D-X6
+  // replaces with a loud, named error (anti-shim / degrade-loudly). Trust
+  // the mounted result's OWN self-declared `kind` tag over the manifest's
+  // `world.kind` — it is what the module ACTUALLY returned; an absent `kind`
+  // (a pre-T7.5 module adapter that never had to declare one) is treated as
+  // the historical threejs-only default, so existing module fixtures are
+  // unaffected.
+  const mountedKind = (mounted as unknown as { kind?: string }).kind;
+  if (mountedKind !== undefined && mountedKind !== 'threejs') {
+    canvas.remove();
+    store.setPlayState('stopped');
+    throw new Error(
+      `enterModuleModeFromManifestWorld: world "${world.id}" (kind: "${mountedKind}") is a ` +
+        '{ module } adapter whose mounted result is not a threejs world — v1 module-mount ' +
+        'route only wires up THREE.Scene-shaped worlds into enterPlayScene ' +
+        '(docs/EXTERNAL-FOLDER-INGEST-DESIGN.md D-X6). Pixi/react { module } worlds have no ' +
+        'mount plumbing yet — kind-parameterized HostContext + per-kind module mounting is ' +
+        'wave 2, gated on its own design doc. This throws loudly instead of silently passing ' +
+        '`undefined` into enterPlayScene.',
+    );
+  }
+
+  _session = {
+    store,
+    canvas,
+    stop: () => session.stop(),
+  };
+
+  let activeAuthoring: AuthoringAdapter;
+  if (mounted.authoring) {
+    tagObjectsWithEntityIds(mounted.scene as THREE.Scene, (o) =>
+      mounted.authoring!.hierarchy.idForObject3D(o),
+    );
+    activeAuthoring = withStoreSelection(mounted.authoring, store);
+  } else {
+    // Honest floor for a module adapter that declares no authoring surface at
+    // all — same embed-only ceiling ingest's own capture-failed path uses.
+    activeAuthoring = makeEmbedOnlyAdapter(store, `${adapter.id} (no authoring surface)`);
+  }
+  setActiveAuthoring(activeAuthoring);
+  setActiveSystems(mounted.systems ?? {});
+  store.enterPlayScene(mounted.scene as THREE.Scene);
+  store.setActiveViewportTab('scene');
+  store.notifyIngestEdit();
+  setMountFailureReport(null); // D-W3: mount succeeded
+
+  const achievedTier = computeAchievedTier(mounted);
+  const shortfall: TierShortfallReport | null = computeTierShortfall(
+    world.id,
+    world.capabilities.local,
+    achievedTier,
+  );
+  // Belt-and-suspenders: resolveWorldAdapter's own wrapping already warned once
+  // via editorConsole (slice 1) — this does not warn again, only formats the
+  // SAME message onto the structured dev/e2e hook below for assertions.
+  if (shortfall) {
+    editorConsole.log(
+      `(already warned by the resolver) ${formatTierShortfallMessage(shortfall)}`,
+      'adapter',
+    );
+  }
+
+  (window as unknown as Record<string, unknown>)['__vgaiModule'] = {
+    worldId: world.id,
+    adapterId: adapter.id,
+    declaredTier: world.capabilities.local,
+    achievedTier,
+    ...(shortfall ? { tierShortfall: shortfall } : {}),
+    // DEV-only: the ACTIVE authoring adapter (the store-backed-selection
+    // wrapper, when applied) + store, so e2e/proof can drive the SAME
+    // providers the hierarchy/inspector/gizmo use (mirrors `__vgaiIngest`).
+    ...(import.meta.env.DEV ? { adapter: activeAuthoring, store } : {}),
+  };
+}
+
+/** Tear down the auto-mounted module session (mirrors `ingest-mode.ts`'s
+ *  `exitIngestMode`). Not called by any route today (no e2e navigates away
+ *  from a module-mounted project mid-session) — provided for symmetry/hygiene
+ *  and any future caller (e.g. a project switch). */
+export function exitModuleMode(): void {
+  const s = _session;
+  if (!s) return;
+  _session = null;
+  setActiveAuthoring(null);
+  setActiveSystems(null);
+  setMountFailureReport(null); // D-W3: no session -> no banner to show (mirrors ingest-mode.ts's exitIngestMode)
+  try {
+    s.store.exitPlayScene();
+  } catch {
+    /* scene may not have been swapped if mount failed */
+  }
+  s.store.setPlayState('stopped');
+  try {
+    s.stop();
+  } catch {
+    /* ignore */
+  }
+  s.canvas?.remove();
+  delete (window as unknown as Record<string, unknown>)['__vgaiModule'];
+  editorConsole.log('Module adapter mode stopped', 'adapter');
+}
+
+// ---------------------------------------------------------------------------
+// D-Y1 (docs/EXTERNAL-REACT-AND-MODULE-DESIGN.md §1/§4 slice S1) —
+// worlds-path routing for non-three `{ module }` worlds
+// ---------------------------------------------------------------------------
+
+/**
+ * Mount a single-world manifest's `kind: 'pixijs' | 'react'` `{ module }`
+ * world through the WORLDS PATH — the D-Y1 sibling of
+ * `enterModuleModeFromManifestWorld` above, mirroring `ingest-mode.ts`'s
+ * `enterIngestModeReact` recipe exactly: one-element `resolveAllWorlds` +
+ * worlds-path `createGameRuntime({ container, worlds })`, which hands the
+ * module adapter its own native `World2DHost`/`ReactWorldHost` — no
+ * `HostContext`, no `.scene` assumption, no engine-side change needed (the
+ * wave-2 study's §0 finding: `resolveAllWorlds`'s `'module'` case is already
+ * kind-agnostic and already returns the correctly-kinded `WorldMountSpec`).
+ *
+ * Only THIS one world mounts (mirrors the legacy path's own "only ever the
+ * first world" behavior, `tryManifestModuleRoute` below): `manifest`'s other
+ * worlds (if any) are discarded via the one-element `{ ...manifest, worlds:
+ * [world] }` passed to `resolveAllWorlds` — a real multi-world manifest whose
+ * FIRST world is a non-three module adapter is out of scope here exactly as
+ * it always was for the legacy route.
+ *
+ * `withAchievedTierCheck` (already wrapped inside `resolveModuleAdapter`,
+ * reached identically through `resolveAllWorlds` -> `resolveWorldAdapter` ->
+ * the `'module'` case) runs completely unmodified here — an over-claiming
+ * module world still gets its shortfall logged loudly by the resolver itself;
+ * this function neither bypasses nor re-derives that check, only reads the
+ * SAME pure `computeAchievedTier`/`computeTierShortfall` result again to
+ * expose it on the `__vgaiModule` dev/e2e hook below (byte-identical
+ * "belt-and-suspenders" comment to the legacy path above).
+ *
+ * Authoring: whatever `mounted.authoring` the module adapter itself returns
+ * becomes the active override (store-selection-wrapped via `withStoreSelection`
+ * — the SAME policy the legacy path applies, kind-agnostic since it only
+ * touches `AuthoringAdapter.selection`); no authoring surface at all gets the
+ * same honest embed-only floor `enterModuleModeFromManifestWorld` uses. There
+ * is deliberately NO `tagObjectsWithEntityIds`/`store.enterPlayScene` call
+ * here (unlike the legacy threejs path): a pixi/react module world has no
+ * THREE scene for the editor viewport to adopt — its own canvas/DOM layer
+ * renders directly inside the game container, and the hierarchy/inspector
+ * panels are driven purely through the `AuthoringAdapter` seam (per this
+ * file's header doc comment: panel choice is adapter/node-identity-keyed,
+ * not scene-adoption-keyed) — exactly like `enterIngestModeReact`.
+ */
+/**
+ * Mount a single `{ module }` world (any kind) through the SCOPED worlds-path
+ * recipe — a one-element `resolveAllWorlds` + worlds-path `createGameRuntime`
+ * — with NO global side effects of its own (no `setActiveAuthoring`, no
+ * `store`/viewport writes, no dev hooks). Extracted (D-V4,
+ * docs/WAVE5-MULTIWORLD-INGEST-DESIGN.md) so BOTH this file's own
+ * `enterModuleModeWorldsPath` below (which layers store/authoring/dev-hook
+ * wiring on top, mounting into the WHOLE shared game container) and a
+ * composite's `{ module }` SIBLING mount (`ingest-siblings.ts`, which mounts
+ * into its own isolated layer div beside an ingest world and adds none of
+ * that global wiring) share the identical resolve+mount step, rather than
+ * duplicating it.
+ */
+export async function mountModuleWorldRuntime(
+  manifest: ResolvedGameManifest,
+  world: ResolvedWorldEntry,
+  projectRoot: string,
+  container: HTMLElement,
+  width: number,
+  height: number,
+): Promise<{ session: GameSession; specs: WorldMountSpec[] }> {
+  const { createGameRuntime } = await import('@engine/runtime/create-runtime');
+  const specs = await resolveAllWorlds({ ...manifest, worlds: [world] }, projectRoot);
+  const session = await createGameRuntime({ container, worlds: specs, width, height });
+  return { session, specs };
+}
+
+export async function enterModuleModeWorldsPath(
+  store: EditorStore,
+  manifest: ResolvedGameManifest,
+  world: ResolvedWorldEntry,
+  projectRoot: string,
+): Promise<void> {
+  const gameContainer = getGameContainer();
+  if (!gameContainer) {
+    editorConsole.error('Game container not mounted — cannot auto-mount module adapter', 'adapter');
+    return;
+  }
+
+  store.setPlayState('playing');
+  editorConsole.log(
+    `Mounting custom adapter module for world "${world.id}" (kind: ${world.kind}, worlds path)`,
+    'adapter',
+  );
+
+  const w = gameContainer.clientWidth || 800;
+  const h = gameContainer.clientHeight || 600;
+  const { session, specs } = await mountModuleWorldRuntime(
+    manifest,
+    world,
+    projectRoot,
+    gameContainer,
+    w,
+    h,
+  );
+
+  const worldInstance = session.game.worlds[0]!;
+  const mounted = worldInstance.mounted;
+  const adapterId = specs[0]!.adapter.id;
+
+  _session = { store, stop: () => session.stop() };
+
+  let activeAuthoring: AuthoringAdapter;
+  if (mounted.authoring) {
+    activeAuthoring = withStoreSelection(mounted.authoring, store);
+  } else {
+    // Honest floor for a module adapter that declares no authoring surface at
+    // all — same embed-only ceiling the legacy path (and ingest) uses.
+    activeAuthoring = makeEmbedOnlyAdapter(store, `${adapterId} (no authoring surface)`);
+  }
+  setActiveAuthoring(activeAuthoring);
+  setActiveSystems(mounted.systems ?? {});
+  store.setActiveViewportTab('game');
+  store.notifyIngestEdit();
+  setMountFailureReport(null); // D-W3: mount succeeded
+
+  const achievedTier = computeAchievedTier(mounted);
+  const shortfall: TierShortfallReport | null = computeTierShortfall(
+    world.id,
+    world.capabilities.local,
+    achievedTier,
+  );
+  // Belt-and-suspenders: resolveWorldAdapter's own wrapping already warned once
+  // via editorConsole (T3.4 slice 1) — this does not warn again, only formats
+  // the SAME message onto the structured dev/e2e hook below for assertions.
+  if (shortfall) {
+    editorConsole.log(
+      `(already warned by the resolver) ${formatTierShortfallMessage(shortfall)}`,
+      'adapter',
+    );
+  }
+
+  (window as unknown as Record<string, unknown>)['__vgaiModule'] = {
+    worldId: world.id,
+    adapterId,
+    declaredTier: world.capabilities.local,
+    achievedTier,
+    ...(shortfall ? { tierShortfall: shortfall } : {}),
+    ...(import.meta.env.DEV ? { adapter: activeAuthoring, store } : {}),
+  };
+}
+
+/**
+ * Route 0 of `ingest-mode.ts`'s `autoLaunchIngestFromURL` (checked before the
+ * ingest routes — see that function's doc comment): a manifest-backed project
+ * whose FIRST world declares a `{ module }` adapter auto-mounts it. Same
+ * "applied or not" contract as `tryManifestIngestRoute`.
+ *
+ * D-Y1: dispatches on `firstWorld.kind` — threejs keeps calling
+ * `enterModuleModeFromManifestWorld` byte-for-byte (its own D-X6 guard stays
+ * as the backstop for any OTHER path that might still funnel a non-three
+ * mount into it); `pixijs`/`react` route through the new
+ * `enterModuleModeWorldsPath` above instead.
+ *
+ * D-V2 (docs/WAVE5-MULTIWORLD-INGEST-DESIGN.md, F24 composite): if the
+ * manifest declares ANY `{ ingest }` world (anywhere in `worlds`, not just
+ * first), this route declines — composites are owned by the ingest routes
+ * (`ingest-mode.ts`'s `tryManifestIngestRoute*`), which mount the one ingest
+ * world through their own enter path and any `{ module }` SIBLING through
+ * the scoped runtime (`ingest-siblings.ts`, D-V4) instead of this
+ * single-world route's global-side-effect-laden mount. Without this guard, a
+ * composite whose FIRST world happens to be a `{ module }` sibling (array
+ * order is manifest order, independent of which world is the primary
+ * ingest) would be mis-mounted here as if it were a standalone module world.
+ * This route's own `firstWorld.adapter.type !== 'module'` behavior for a
+ * non-composite manifest is otherwise untouched.
+ */
+export async function tryManifestModuleRoute(store: EditorStore): Promise<boolean> {
+  if (getEditorMode() === 'browser') return false; // no dev server to serve /vgai.game.json / /@fs/ from
+  const manifest = await fetchGameManifest().catch(() => null);
+  if (manifest?.worlds.some((w) => w.adapter.type === 'ingest')) return false;
+  const firstWorld = manifest?.worlds[0];
+  if (firstWorld === undefined || firstWorld.adapter.type !== 'module') return false;
+
+  const project = getCurrentProject();
+  if (!project) {
+    editorConsole.error(
+      'Manifest declares a { module } world but no project is open — cannot auto-mount',
+      'adapter',
+    );
+    return true;
+  }
+  const ready = await waitForGameContainer();
+  if (!ready) {
+    editorConsole.error(
+      'Game container never mounted — cannot auto-mount module adapter',
+      'adapter',
+    );
+    return true;
+  }
+  try {
+    if (firstWorld.kind === 'pixijs' || firstWorld.kind === 'react') {
+      await enterModuleModeWorldsPath(store, manifest!, firstWorld, project.rootPath);
+    } else {
+      await enterModuleModeFromManifestWorld(store, firstWorld, project.rootPath);
+    }
+  } catch (err) {
+    editorConsole.error(`Manifest { module } auto-mount failed: ${err}`, 'adapter');
+    // D-W3 (docs/WAVE4-FTUE-HARDENING-DESIGN.md §D-W3, F9) — the fourth of the
+    // four manifest-route catch blocks (three/pixi/react in ingest-mode.ts,
+    // this one for `{ module }` worlds); same loud-banner-slot population.
+    setMountFailureReport({
+      worldId: firstWorld.id,
+      kind: firstWorld.kind,
+      identity: firstWorld.adapter.identity,
+      message: formatMountFailureMessage(err),
+    });
+  }
+  return true;
+}

package/src/navmesh-handler.ts

@@ -0,0 +1,94 @@
+import { initNavigation, NavMeshManager } from '@engine/ai/navigation';
+import type * as THREE from 'three';
+import { saveFile } from './editor-api';
+import { editorConsole } from './editor-console';
+import type { EditorStore } from './editor-store';
+import type { EditorViewport } from './editor-viewport';
+
+/**
+ * Set up navmesh bake/clear event listeners. Returns a dispose function.
+ */
+export function setupNavMeshHandlers(
+  store: EditorStore,
+  viewport: EditorViewport,
+  scene: THREE.Scene,
+): () => void {
+  let navMeshManager: NavMeshManager | null = null;
+
+  function collectNavigationIds(role: 'walkable' | 'obstacle'): Set<string> {
+    const ids = new Set<string>();
+    for (const e of store.allEntities()) {
+      if (e.navigation?.role === role && e.id) ids.add(e.id);
+    }
+    return ids;
+  }
+
+  const onBake = async () => {
+    try {
+      await initNavigation();
+    } catch (err) {
+      editorConsole.error(`Failed to init recast-navigation WASM: ${err}`, 'navigation');
+      return;
+    }
+
+    const walkableIds = collectNavigationIds('walkable');
+    if (walkableIds.size === 0) {
+      editorConsole.warn(
+        'No walkable entities found — tag meshes as "walkable" in the Navigation section',
+        'navigation',
+      );
+      return;
+    }
+
+    const meshes: THREE.Mesh[] = [];
+    for (const id of walkableIds) {
+      const obj = store.objectMap.get(id);
+      if (!obj) continue;
+      obj.traverse((child) => {
+        if ((child as THREE.Mesh).isMesh) meshes.push(child as THREE.Mesh);
+      });
+    }
+    if (meshes.length === 0) return;
+
+    if (!navMeshManager) navMeshManager = new NavMeshManager();
+    const envNav = store.environment?.navigation;
+    const success = navMeshManager!.buildFromMeshes(meshes, envNav);
+    if (!success) {
+      editorConsole.error('NavMesh bake failed', 'navigation');
+      return;
+    }
+
+    const debugMesh = navMeshManager!.getDebugMesh(scene);
+    if (debugMesh) viewport.setNavMeshHelper(debugMesh);
+
+    store.markNavMeshBaked();
+
+    if (store.savePath) {
+      const navmeshPath = store.savePath.replace('.vscn.json', '.navmesh');
+      const data = navMeshManager!.exportData();
+      let binary = '';
+      for (let i = 0; i < data.length; i++) binary += String.fromCharCode(data[i]!);
+      const base64 = btoa(binary);
+      saveFile(navmeshPath, base64, 'base64').then((ok) => {
+        if (!ok) editorConsole.error('Failed to save .navmesh file', 'navigation');
+      });
+    }
+  };
+
+  const onClear = () => {
+    if (navMeshManager) {
+      navMeshManager.dispose(scene);
+      navMeshManager = null;
+    }
+    viewport.setNavMeshHelper(null);
+  };
+
+  window.addEventListener('editor:bake-navmesh', onBake);
+  window.addEventListener('editor:clear-navmesh', onClear);
+
+  return () => {
+    window.removeEventListener('editor:bake-navmesh', onBake);
+    window.removeEventListener('editor:clear-navmesh', onClear);
+    if (navMeshManager) navMeshManager.dispose(scene);
+  };
+}

package/src/packaged-runtime.ts

@@ -0,0 +1,49 @@
+/**
+ * Runtime detection of the PACKAGED editor server (`packages/editor/server/
+ * packaged.ts` — a `@vgai/editor` npm package with NO monorepo checkout on
+ * disk) from editor CLIENT code. Needed because a react world's mount
+ * (`adapter-resolver.ts`'s `resolveReactWorldMountRuntime`) must resolve its
+ * `react`/`react-dom/client`/`GameProvider`-fallback wrapper from the
+ * PROJECT's own module graph ONLY under this runtime — see that function's
+ * doc comment, and `packaged.ts`'s header doc comment ("React-world OID
+ * authoring parity"), for the dual-React-instance bug this closes. Under
+ * dev/Electron, this must resolve `false` so the existing static-import path
+ * stays byte-unchanged (one shared Vite instance already collapses both
+ * react copies via `resolve.dedupe`).
+ *
+ * Reads the server's own `packaged` flag off `/__editor/project`'s response
+ * (computed server-side via `isMonorepoScaffoldRoot`, `server-utils.ts`)
+ * rather than probing a URL that only resolves in packaged mode: an
+ * unconditional dynamic `import()` probe would 404 (and log an
+ * unsuppressible browser console error) on EVERY react-world mount under
+ * dev/Electron — the exact reasoning `adapter-resolver.ts`'s
+ * `loadProjectUIRegistry` doc comment already recorded for `hasUiRegistry`
+ * ("the client must not probe /@fs for it").
+ *
+ * Memoized for the session (module-level, not per-call): the runtime a
+ * server process is running under cannot change without a restart, so this
+ * fetches `/__editor/project` at most once per page load.
+ *
+ * A plain inline `fetch()`, not `editor-api.ts`'s `getCurrentServerProject`
+ * — same reasoning `loadProjectUIRegistry` documents: this module (via
+ * `adapter-resolver.ts`) must stay importable by headless Node/vitest
+ * suites, and `editor-api.ts`'s module top level pulls in `./storage`.
+ */
+
+let cachedIsPackaged: Promise<boolean> | null = null;
+
+export function isPackagedRuntime(): Promise<boolean> {
+  if (!cachedIsPackaged) {
+    cachedIsPackaged = fetch('/__editor/project')
+      .then((res) => res.json())
+      .then((data: { project?: { packaged?: boolean } | null }) => Boolean(data.project?.packaged))
+      .catch(() => false);
+  }
+  return cachedIsPackaged;
+}
+
+/** Test-only: reset the memoized result between tests (mirrors
+ *  `setCachedProjectUIRegistry`'s test-seam shape). */
+export function resetPackagedRuntimeCacheForTest(): void {
+  cachedIsPackaged = null;
+}