@vgai/editor 0.2.0

package/src/play-mode.ts

@@ -0,0 +1,1148 @@
+/**
+ * Play-mode orchestrator.
+ *
+ * Editor and game are fully isolated — separate canvas, renderer, and scene.
+ * Play mode creates a new game canvas, launches a standalone game session,
+ * and tears it all down on stop. The editor scene is never touched.
+ *
+ * Flow:
+ *   enterPlayMode → create canvas → createGameRuntime() → game loop
+ *   exitPlayMode  → game stop → remove canvas → re-enable editor
+ */
+
+import type { AuthoringAdapter } from '@engine/adapter';
+import type { VgaiMountedGame } from '@engine/adapter/vgai-scene-game-adapter';
+import { assertNever } from '@engine/adapter/world-kind';
+import { _engineLogActive } from '@engine/dev/logger';
+import type { GameComponentClass } from '@engine/ecs/game-component';
+import * as gameComponentModule from '@engine/ecs/game-component';
+import { logHmrSwapMiss } from '@engine/ecs/hmr-swap-report';
+import type { GameSession } from '@engine/runtime/create-runtime';
+import { isFirstPartyMounted, type WorldInstance } from '@engine/runtime/game';
+import { parseSceneFile, SceneParseError } from '@engine/scene/parse';
+import type { Overlay2D } from '@engine/world2d/authoring-2d';
+import { createPhysics2DRegistry } from '@engine/world2d/physics2d-registry';
+import { createPhysicsAdapter2D } from '@engine/world2d/system-adapters-2d';
+import gsap from 'gsap';
+import * as THREE from 'three';
+import { resolveAllWorldEntries, resolveWorldAdapter } from './adapter-resolver';
+import {
+  getActiveAuthoring,
+  getAuthoringOverride,
+  setActiveAuthoring,
+} from './authoring/active-adapter';
+import { setActiveSystems } from './authoring/active-systems';
+import {
+  CompositeAuthoringAdapter,
+  type CompositeChild,
+} from './authoring/composite-authoring-adapter';
+import { createEphemeralPersistence } from './authoring/ephemeral-persistence';
+import { IngestAuthoringAdapter } from './authoring/ingest-authoring-adapter';
+import type { IngestOverlay } from './authoring/ingest-overlay';
+import { ReactWorldAuthoringAdapter } from './authoring/react-world-authoring-adapter';
+import { type UndoAdapter, unregisterUndoAdapter } from './authoring/undo-timeline';
+import { loadWorldOverlay, saveWorldOverlay, worldOverlayPath } from './authoring/world-overlay';
+import { World2DAuthoringAdapter } from './authoring/world2d-authoring-adapter';
+import { importFromSource, registerRuntimeModules } from './browser-transpile';
+import { watchScriptChanges } from './browser-watch-reload';
+import type { LogEntry } from './editor-api';
+import { endLogSession, flushLogEntries, startLogSession } from './editor-api';
+import type { ConsoleEntry } from './editor-console';
+import { editorConsole } from './editor-console';
+import { getEditorMode } from './editor-mode';
+import type { EditorStore } from './editor-store';
+import { installGatedGameGlobals, setGameInputGate } from './gated-globals';
+import { exampleDispatchFor } from './hosted-example';
+import { fetchGameManifest } from './manifest-project';
+import { getCurrentProject } from './project-manager';
+import { loadProjectScripts, type ProjectScripts, reloadProjectScripts } from './script-loader';
+import { createHttpSourceWriteBackend } from './ui-source/source-write-backend';
+
+/** Context needed by the orchestrator (passed from ViewportPanel). */
+export interface PlayModeContext {
+  store: EditorStore;
+  /** Container for the game canvas (the Game tab panel). */
+  gameContainer: HTMLElement;
+  /** Returns the editor viewport camera (for copying viewpoint into game). */
+  getViewportCamera: () => THREE.PerspectiveCamera;
+}
+
+let _gameContainerEl: HTMLElement | null = null;
+let _ctx: PlayModeContext | null = null;
+let _session: GameSession | null = null;
+
+/**
+ * Play-mode generation counter. Bumped on every enterPlayMode and every
+ * exitPlayMode. enterPlayMode captures the value before its async boot and
+ * re-checks it around `createGameRuntime` — if exitPlayMode (Stop/Escape) ran
+ * while the runtime was still booting, the freshly-created session belongs to
+ * an already-exited play and must be stopped and abandoned, NOT adopted.
+ * Without this, a stop-during-boot left the store swapped onto the orphaned
+ * live game scene (empty hierarchy in edit mode) with the session leaked
+ * (RAF loop, Rapier world, WebGL context never released).
+ */
+let _playEpoch = 0;
+
+// T6.3: install the gated window/document proxies once so the dev server's/
+// browser-transpile's GAME_GLOBALS_PRELUDE (prepended to project modules) has
+// something to resolve to. No-op outside a browser (headless unit tests).
+installGatedGameGlobals();
+
+/**
+ * The first-party game runtime behind the current session. HMR (component
+ * hot-swap, warm restart) and physics edit-sync are inherently first-party, so
+ * play-mode reaches the `GameContext` + `hotReload` via the `VgaiMountedGame`
+ * extras on `session.mounted`. The generic host (`createGameRuntime`) no longer
+ * exposes these — that confinement is the adapter inversion.
+ */
+/** e2e counter: proofs read `window.__vgaiHmrCount` to assert HMR fired. */
+function bumpHmrCount(): void {
+  const w = window as unknown as { __vgaiHmrCount?: number };
+  w.__vgaiHmrCount = (w.__vgaiHmrCount ?? 0) + 1;
+}
+
+function firstParty(session: GameSession): VgaiMountedGame {
+  return session.mounted as VgaiMountedGame;
+}
+
+/**
+ * Fan HMR's `hotSwap` out across EVERY first-party world in the session
+ * (§7.1-4, probes 2/2b) — both call sites below used to reach only
+ * `firstParty(_session).ctx.components.hotSwap(...)`, i.e. the DEFAULT
+ * world's `ComponentManager` alone. In a multi-world session (T6.1) a
+ * component living in a second/third world never saw a hot update at all
+ * (probe2), and — worse — a component living ONLY in a non-default world
+ * produced a misleading "no live instance" swap-miss warning (probe2b) even
+ * though the instance was alive the whole time, just in a manager this call
+ * never consulted; structurally identical to "you renamed the class."
+ *
+ * Iterates `session.game.worlds` (declaration order), skipping any
+ * non-first-party mount (`isFirstPartyMounted` — an opaque/foreign or react
+ * mount has no `ComponentManager` to hotSwap against), and calls each
+ * first-party world's OWN `hotSwap` with its own swap-miss warning
+ * suppressed (`{ warnOnMiss: false }`) — a per-world zero-match is
+ * meaningless on its own (the name may simply live in a DIFFERENT world).
+ * The ONE real "nothing anywhere matched this name" warning is emitted HERE,
+ * exactly once, with the SAME message convention every other swap-miss uses
+ * (`logHmrSwapMiss`), only when the total across every first-party world is
+ * zero.
+ *
+ * Returns the total number of live instances swapped, summed across worlds.
+ */
+export function hotSwapAcrossWorlds(
+  session: GameSession,
+  name: string,
+  NewClass: GameComponentClass,
+): number {
+  let total = 0;
+  for (const world of session.game.worlds) {
+    if (!isFirstPartyMounted(world.mounted)) continue;
+    total += world.mounted.ctx.components.hotSwap(name, NewClass, { warnOnMiss: false });
+  }
+  if (total === 0) {
+    logHmrSwapMiss({ key: name, reason: 'no-live-instance' });
+  }
+  return total;
+}
+
+/**
+ * Warm-restart's fan-out investigation (§7.1-4's second half): the
+ * non-component-edit HMR branch below re-runs ONLY the default world's
+ * `hotReload` — it does NOT fan out across `session.game.worlds` the way
+ * {@link hotSwapAcrossWorlds} does for true-HMR component swaps. This is a
+ * STRUCTURAL limitation, not an oversight left for later:
+ *
+ *  1. `hotReload` is a `VgaiMountedGame` (first-party THREEJS mount) extra —
+ *     `world2d/pixi-game-adapter.ts`'s pixi mount and `create-runtime.ts`'s
+ *     react mount expose no such method at all, so there is no capability to
+ *     fan out to on a non-threejs world even in principle.
+ *  2. Even restricted to first-party THREEJS worlds, `reloadProjectScripts`
+ *     (`script-loader.ts`) resolves exactly ONE project entry
+ *     (`src/scripts/main.ts` by default) and returns ONE `setup` function —
+ *     it has no per-world mapping, so there is no way to know which world a
+ *     second/third `hotReload` call should even run against, let alone which
+ *     source file to re-import for it.
+ *
+ * So this reports the limitation loudly instead of silently reloading only
+ * part of a multi-world session — called right after a successful warm
+ * restart, from the `vgai:script-update` handler below.
+ */
+export function warnIfOtherFirstPartyWorldsUnrestarted(session: GameSession): void {
+  const worlds = session.game?.worlds;
+  if (!worlds || worlds.length <= 1) return;
+  const defaultWorldId = session.game?.defaultWorld.id;
+  const otherFirstParty = worlds.some(
+    (w) => w.id !== defaultWorldId && isFirstPartyMounted(w.mounted),
+  );
+  if (otherFirstParty) {
+    editorConsole.warn(
+      'Warm restart applied to the default world only — components in other worlds keep ' +
+        'running old code until play restarts (structural limitation: hotReload is a first-party ' +
+        'threejs-mount-only capability, and reloadProjectScripts resolves a single ' +
+        'src/scripts/main.ts entry with no per-world mapping).',
+      'play-mode',
+    );
+  }
+}
+
+/**
+ * The warm-restart HMR bracket's pause/resume wrapper (§7.1 item 1 /
+ * probe3-warm-restart-unpauses: the bracket used to call
+ * `_session.pause(); await hotReload(...); _session.resume();`
+ * unconditionally, so it silently un-paused a user-paused game — the UI kept
+ * saying "paused" while the simulation resumed running). Fix: capture
+ * whether the game was ALREADY paused from the SAME source of truth
+ * `pause()`/`resume()` drive (`session.game.play.paused`, `game.ts:713`)
+ * BEFORE unconditionally pausing for the reload, and only resume afterward
+ * if it was not already paused — `pause()`/`resume()` are idempotent, so an
+ * unconditional `pause()` up front is always safe. try/finally so a throw
+ * mid-`reload()` still restores the correct pre-bracket state (a throw must
+ * never leave a previously-RUNNING game stuck paused). Exported for direct
+ * unit testing without any `import.meta.hot`/Vite HMR event machinery — see
+ * `packages/editor/test/play-mode-warm-restart-pause.test.ts`.
+ */
+export async function runWarmRestartPauseBracket(
+  session: GameSession,
+  reload: () => Promise<void>,
+): Promise<void> {
+  const wasPaused = session.game.play.paused;
+  session.pause();
+  try {
+    await reload();
+  } finally {
+    if (!wasPaused) session.resume();
+  }
+}
+let _gameCanvas: HTMLCanvasElement | null = null;
+let _resizeObserver: ResizeObserver | null = null;
+let _unsubStore: (() => void) | null = null;
+/** Browser-mode component-source watch (Phase A2); null in server mode / stopped. */
+let _unsubBrowserScriptWatch: (() => void) | null = null;
+/** True for the CURRENT session iff it mounted through the worlds path with
+ *  more than one world — decides which of `installPlayAuthoring` (ephemeral,
+ *  single `.vscn` preview) vs `installMultiWorldAuthoring` (real per-world
+ *  overlay persistence) ran, so `exitPlayMode` tears down the right one. */
+let _isMultiWorldSession = false;
+/**
+ * The authoring override that was active before THIS play session installed its
+ * own (normally `null` — nothing else authors while playing today, but this
+ * restores whatever was there rather than assuming null; see
+ * `installPlayAuthoring`/`restorePriorAuthoring`). `undefined` ⇒ this play
+ * session never installed one (e.g. it bailed before adopting the scene) — exit
+ * must then leave the authoring override untouched.
+ */
+let _priorAuthoringOverride: AuthoringAdapter | null | undefined;
+
+/**
+ * Play adoption drives the SAME authoring adapter the editor already uses for
+ * `store` (first-party today — `getActiveAuthoring` falls back to it absent an
+ * override), just with its `persistence` swapped for the ephemeral provider
+ * (design `docs/PERSISTENCE-PROVIDER-DESIGN.md` §2/§7 slice 1): play-time edits
+ * apply to the live game scene exactly as before, but the store's autosave/
+ * saveNow guards now see `isDirty() → false` / no real destination instead of
+ * relying on the `_playState` flag alone. `undo`/`redo`/`subscribe` are rebound
+ * explicitly (a plain spread would keep them pointing at `base`'s `this`, which
+ * is fine for arrow-function fields but not for prototype methods).
+ */
+function installPlayAuthoring(store: EditorStore): void {
+  _priorAuthoringOverride = getAuthoringOverride();
+  const base = getActiveAuthoring(store);
+  const wrapped: AuthoringAdapter = {
+    ...base,
+    persistence: createEphemeralPersistence(() => store.getDocument()),
+  };
+  // Only rebind when `base` actually implements these (exactOptionalPropertyTypes
+  // rejects assigning `undefined` to an already-optional property explicitly).
+  if (base.subscribe) wrapped.subscribe = base.subscribe.bind(base);
+  if (base.undo) wrapped.undo = base.undo.bind(base);
+  if (base.redo) wrapped.redo = base.redo.bind(base);
+  setActiveAuthoring(wrapped);
+}
+
+/** Restore whatever authoring override (if any) was active before play started. */
+function restorePriorAuthoring(): void {
+  if (_priorAuthoringOverride === undefined) return; // installPlayAuthoring never ran
+  setActiveAuthoring(_priorAuthoringOverride);
+  _priorAuthoringOverride = undefined;
+}
+
+/**
+ * Per-world adapters built for the CURRENT multi-world session, tracked ONLY so
+ * `exitMultiWorldAuthoring` can unregister any that self-registered with the
+ * global undo timeline. As of v4 §7.1-13, `IngestAuthoringAdapter` AND
+ * `World2DAuthoringAdapter` both self-register (the `ReactWorldAuthoringAdapter`
+ * branch does too) — mirrors `ingest-mode.ts`'s teardown of its own single
+ * adapter.
+ */
+let _multiWorldChildren: AuthoringAdapter[] = [];
+
+/**
+ * Build ONE {@link AuthoringAdapter} per mounted world (T6.1 slice 3,
+ * docs/MULTI-WORLD-DESIGN.md §1.F/§3 slice 3) and install the N-ary
+ * {@link CompositeAuthoringAdapter} over all of them as the active authoring
+ * override.
+ *
+ * Study finding (this slice): `resolveAllWorlds`'s own doc comment records that
+ * NO world in a multi-world manifest gets the live editor document/editorPreview
+ * — every world mounts from its own on-disk `scene`/`entry`, single-world OR
+ * not. So there is no "the store's document IS this world's live scene" world
+ * the way `VgaiSceneAuthoringAdapter` assumes for the single-world path — EVERY
+ * world here (including a `kind:'threejs'` world) gets a live-tree REFLECTION
+ * adapter, the same shape `ingest-mode.ts` already uses for an unmodified game's
+ * `Object3D` tree: `IngestAuthoringAdapter` for a threejs world's `threeRoot()`,
+ * `World2DAuthoringAdapter` for a pixijs world's `pixiRoot()`. Persistence is
+ * REAL (not the ephemeral discard-on-stop wrapper `installPlayAuthoring` uses
+ * for the single-world `.vscn` preview path) — each per-world adapter's overlay
+ * (§1.G: `.vgai/overlays/<world-id>.json`, project-root-relative, `authoring/
+ * world-overlay.ts`) is the honest floor a manifest-mounted world has today,
+ * exactly like `ingest-mode.ts`'s own overlay persistence (both its three-side
+ * and — T6.1 slice 4 — pixi-side ingest sessions) —
+ * this is not a "preview of an editable document" session the way single-world
+ * play is, so ephemeral-wrapping it would silently discard the ONLY persistence
+ * mechanism these worlds have.
+ *
+ * `store` is used ONLY as the editor-global selection bag + change-notification
+ * bus (`selectedEntityIds`/`selectMultiple`/`subscribe`/`notifyIngestEdit`) —
+ * neither per-world adapter reads/writes `store`'s document, matching how
+ * `ingest-mode.ts` already uses the SAME store for the same narrow purpose
+ * over a live foreign tree.
+ *
+ * A `kind: 'react'` world (T6.2 slice 2, `docs/REACT-WORLD-DESIGN.md` §1.D/§3
+ * slice 2) gets a {@link ReactWorldAuthoringAdapter} over its `reactRoot()` DOM —
+ * NOT the overlay-file persistence the threejs/pixijs branches use: a react
+ * world's truth is JSX SOURCE (D4), so its persistence is the SAME immediate
+ * source-write seam `UIAuthoringAdapter` already uses
+ * (`../ui-source/source-write-backend.ts`), wired only under the dev server
+ * (`import.meta.env.DEV`) exactly like `edit-mode-authoring.ts`'s scene-UI
+ * child does — a hosted/no-dev-server session degrades to selection/
+ * inspection only, writes reporting unavailable (never silently faked).
+ */
+async function installMultiWorldAuthoring(
+  store: EditorStore,
+  worlds: readonly WorldInstance[],
+): Promise<void> {
+  _priorAuthoringOverride = getAuthoringOverride();
+  const children: CompositeChild[] = [];
+  for (const world of worlds) {
+    if (world.kind === 'threejs') {
+      const overlay = await loadWorldOverlay<IngestOverlay>(world.id);
+      const adapter = new IngestAuthoringAdapter(store, world.threeRoot(), {
+        overlay,
+        persist: (o) => saveWorldOverlay(world.id, o),
+        destination: worldOverlayPath(world.id),
+      });
+      children.push({ worldId: world.id, kind: world.kind, adapter });
+    } else if (world.kind === 'pixijs') {
+      const overlay = await loadWorldOverlay<Overlay2D>(world.id);
+      const physics = createPhysicsAdapter2D(world.physics2d ?? createPhysics2DRegistry());
+      const adapter = new World2DAuthoringAdapter(world.pixiRoot(), physics, store, {
+        overlay,
+        persist: (o) => saveWorldOverlay(world.id, o),
+        destination: worldOverlayPath(world.id),
+      });
+      children.push({ worldId: world.id, kind: world.kind, adapter });
+    } else if (world.kind === 'react') {
+      const adapter = new ReactWorldAuthoringAdapter(world.reactRoot(), store, {
+        // Same dev-server-only gating `edit-mode-authoring.ts`'s scene-UI
+        // child uses for the identical seam: a hosted/production build has
+        // no `/__ui-source` middleware.
+        ...(import.meta.env.DEV ? { writeBackend: createHttpSourceWriteBackend() } : {}),
+      });
+      children.push({ worldId: world.id, kind: world.kind, adapter });
+    } else {
+      // Exhaustiveness guard (§7.4-2): the pre-existing if/else-if chain over
+      // `WorldInstance.kind` had no trailing else — a hypothetical 4th kind
+      // would silently get NO authoring child (no error, just missing
+      // authoring for that world) rather than failing loudly/at compile time.
+      assertNever(world.kind, 'installMultiWorldAuthoring');
+    }
+  }
+  _multiWorldChildren = children.map((c) => c.adapter);
+  const composite = new CompositeAuthoringAdapter(children);
+  setActiveAuthoring(composite);
+  // `setActiveAuthoring` is a plain module-level variable, not React state —
+  // the left hierarchy panel only re-checks `hasAuthoringOverride()` when the
+  // store notifies (same reason `ingest-mode.ts` calls this right after
+  // installing its own override).
+  store.notifyIngestEdit();
+
+  // Dev/e2e diagnostic handle — the SAME pattern `ingest-mode.ts`'s
+  // `window.__vgaiIngest`/`window.__vgaiIngest2D` use:
+  // `store.saveNow()` (Ctrl/Cmd+S) and `_autoSave()` are both structurally
+  // guarded OFF while ANY authoring override is active (`hasAuthoringOverride()`
+  // / the play-state check) — the adapter's OWN `persistence.save()` is the
+  // only way an override session's edits reach disk, so tests/tooling need a
+  // handle to call it directly, exactly as the ingest sessions expose.
+  if (import.meta.env.DEV) {
+    (window as unknown as Record<string, unknown>)['__vgaiMultiWorld'] = {
+      adapter: composite,
+      worldIds: children.map((c) => c.worldId),
+      store,
+    };
+  }
+}
+
+/** Teardown for `installMultiWorldAuthoring` — unregisters any per-world child
+ *  that self-registered with the global undo timeline (mirrors
+ *  `ingest-mode.ts`'s `unregisterUndoAdapter` call on its own adapter). Must
+ *  pass the ORIGINAL adapter instance (not a rebuilt wrapper) — the timeline
+ *  keys registration by object identity (see undo-timeline.ts's doc comment),
+ *  and `registerUndoAdapter(this)` inside each of `IngestAuthoringAdapter`'s,
+ *  `World2DAuthoringAdapter`'s (v4 §7.1-13), and `ReactWorldAuthoringAdapter`'s
+ *  constructors registered exactly that instance. The type guard below is now
+ *  just a defensive narrowing (every current child kind DOES register), kept
+ *  in case a future child kind legitimately has no undo/redo of its own. */
+function exitMultiWorldAuthoring(): void {
+  for (const adapter of _multiWorldChildren) {
+    if (adapter.undo && adapter.redo)
+      unregisterUndoAdapter(adapter as AuthoringAdapter & UndoAdapter);
+  }
+  _multiWorldChildren = [];
+  if (import.meta.env.DEV) {
+    delete (window as unknown as Record<string, unknown>)['__vgaiMultiWorld'];
+  }
+}
+let _escapeListener: ((e: KeyboardEvent) => void) | null = null;
+let _originalConsoleLog: typeof console.log | null = null;
+let _originalConsoleInfo: typeof console.info | null = null;
+let _originalConsoleWarn: typeof console.warn | null = null;
+let _originalConsoleError: typeof console.error | null = null;
+let _logFlushChain: Promise<unknown> = Promise.resolve();
+let _flushInterval: ReturnType<typeof setInterval> | null = null;
+let _pendingEntries: LogEntry[] = [];
+
+// --- Script HMR ---
+if (import.meta.hot) {
+  import.meta.hot.on('vgai:script-update', async (data: { file: string }) => {
+    if (!_session || !_ctx) return;
+    const project = getCurrentProject();
+    if (!project) return;
+    try {
+      const { store } = _ctx;
+
+      // Strategy based on which file changed:
+      // Component source files → true HMR (import only the file, swap prototypes)
+      // Entry point or registry → warm restart (re-import main, re-run setup)
+      const isComponentFile =
+        !data.file.endsWith('/main.ts') && !data.file.endsWith('/registry.ts');
+
+      if (isComponentFile) {
+        // True HMR: import only the changed file to get fresh class definitions.
+        // This avoids re-importing the full module chain which can trigger page reloads.
+        const modulePath = `/@fs/${data.file}?t=${Date.now()}`;
+        const mod = await import(/* @vite-ignore */ modulePath);
+        for (const [key, value] of Object.entries(mod)) {
+          // §7.1-5/probe7: filter to GameComponent subclasses BEFORE ever
+          // calling hotSwap — a plain helper function export sharing a live
+          // component's registry key/name must never reach
+          // `Object.setPrototypeOf`. `gameComponentModule.GameComponent` is
+          // the SAME singleton class the running session's components were
+          // built from — Vite's dev-server module graph resolves
+          // `@engine/ecs/game-component` to one cached instance for both this
+          // file and the `/@fs/`-imported component file (the cache-busting
+          // `?t=` query targets ONLY the edited file's own module id, not its
+          // import specifiers), so `instanceof` here holds across the two
+          // import paths. See `applyBrowserComponentEdit` below for the
+          // in-browser (esbuild-wasm) path's identity guarantee, which is
+          // explicit-by-construction via `registerRuntimeModules`.
+          if (
+            typeof value === 'function' &&
+            value.prototype instanceof gameComponentModule.GameComponent
+          ) {
+            hotSwapAcrossWorlds(_session, key, value as unknown as GameComponentClass);
+          }
+        }
+        bumpHmrCount();
+        editorConsole.log('Hot-swapped component classes (true HMR)', 'play-mode');
+      } else {
+        // Warm restart: re-run setup() with fresh code
+        const scripts = await reloadProjectScripts(project.rootPath);
+        // W1 (docs/R3F-FIRST-PARTY-DESIGN.md §1.A) widened `ProjectScripts` so
+        // `setup` is no longer guaranteed — an entry that exports only
+        // `adapter` has no re-runnable setup() for `hotReload` to call (the
+        // adapter owns its whole mount lifecycle itself; O3 in the design doc
+        // already flags entry-module HMR as unverified for v1). Fail loudly
+        // here instead of handing `hotReload` an `undefined` — the outer
+        // try/catch (below) reports it exactly like any other HMR failure.
+        const reloadedSetup = scripts.setup;
+        if (!reloadedSetup) {
+          throw new Error(
+            'Warm restart failed: the project entry now exports only `adapter`, not `setup` — ' +
+              'hot-reloading a pre-built GameAdapter has no setup() to re-run in v1 ' +
+              '(docs/R3F-FIRST-PARTY-DESIGN.md O3). Restart play instead.',
+          );
+        }
+        const hotViewCam = _ctx.getViewportCamera();
+        // Pause the host loop around the warm restart (the generic host no longer
+        // owns hotReload; gate the loop so it doesn't tick mid-rebuild) — but never
+        // un-pause a game the USER had already paused (§7.1-1, probe3).
+        await runWarmRestartPauseBracket(_session, () =>
+          firstParty(_session as GameSession).hotReload(reloadedSetup, {
+            scenePath: store.savePath,
+            sceneData: store.getDocument(),
+            viewportCamera: {
+              position: hotViewCam.position.toArray() as [number, number, number],
+              quaternion: hotViewCam.quaternion.toArray() as [number, number, number, number],
+            },
+          }),
+        );
+        bumpHmrCount();
+        editorConsole.log('Hot-reloaded game scripts (warm restart)', 'play-mode');
+        warnIfOtherFirstPartyWorldsUnrestarted(_session);
+      }
+    } catch (err) {
+      editorConsole.error(`Script hot-reload failed: ${err}`, 'play-mode');
+    }
+  });
+}
+
+// --- In-browser HMR (no server) ---
+//
+// The `vgai:script-update` handler above relies on the Vite dev server to
+// transpile the changed file and on a filesystem watcher to fire the event.
+// The path below does the same live prototype-swap, but the source comes from
+// the browser and is transpiled in-browser via esbuild-wasm — no Node, no Vite
+// transpile, no file write. This is what makes hot reload possible entirely
+// client-side. The transpiled component shares the running session's THREE and
+// GameComponent singletons (registered below), so prototype chains stay valid.
+
+let _runtimeModulesRegistered = false;
+function ensureRuntimeModulesRegistered(): void {
+  if (_runtimeModulesRegistered) return;
+  registerRuntimeModules({
+    three: THREE as unknown as Record<string, unknown>,
+    gsap: { default: gsap } as Record<string, unknown>,
+    '@engine/ecs/game-component': gameComponentModule as unknown as Record<string, unknown>,
+  });
+  _runtimeModulesRegistered = true;
+}
+
+/**
+ * Apply an in-browser source edit to the running game: transpile the given
+ * component module source with esbuild-wasm and hot-swap every exported class
+ * onto its live instances. Returns the names of the classes that were swapped.
+ *
+ * This is the in-browser analogue of the `vgai:script-update` HMR handler —
+ * same engine `hotSwap`, but driven entirely client-side.
+ */
+export async function applyBrowserComponentEdit(source: string): Promise<string[]> {
+  if (!_session) throw new Error('Not in play mode — enter play mode before editing components.');
+  ensureRuntimeModulesRegistered();
+  const mod = await importFromSource(source);
+  const swapped: string[] = [];
+  for (const [name, value] of Object.entries(mod)) {
+    // §7.1-5/probe7: same GameComponent-subclass filter as the vgai:script-update
+    // handler above — identity here is explicit-by-construction (not merely
+    // module-graph coincidence): `ensureRuntimeModulesRegistered` registers
+    // THIS session's live `gameComponentModule` singleton via
+    // `registerRuntimeModules`, and `importFromSource`'s esbuild-wasm output
+    // has its bare `@engine/ecs/game-component` import rewritten to a blob-URL
+    // shim that re-exports exactly that registered namespace — so a
+    // transpiled component's `class Foo extends GameComponent` extends the
+    // SAME class object checked here.
+    if (
+      typeof value === 'function' &&
+      value.prototype instanceof gameComponentModule.GameComponent
+    ) {
+      hotSwapAcrossWorlds(_session, name, value as GameComponentClass);
+      swapped.push(name);
+    }
+  }
+  if (swapped.length > 0) {
+    const w = window as unknown as Record<string, unknown>;
+    w['__vgaiHmrCount'] = ((w['__vgaiHmrCount'] as number) ?? 0) + 1;
+    editorConsole.log(`In-browser hot-swap: ${swapped.join(', ')}`, 'play-mode');
+  }
+  return swapped;
+}
+
+// Dev-only handle so the editor UI / e2e can drive in-browser component edits.
+if (import.meta.env.DEV) {
+  (window as unknown as Record<string, unknown>)['__vgaiBrowserHmr'] = {
+    applyBrowserComponentEdit,
+  };
+}
+
+/** Set the Game panel container element (called by GamePanel on mount). */
+export function setGameContainer(el: HTMLElement | null): void {
+  _gameContainerEl = el;
+}
+
+/** Get the Game panel container element (shared with ingest-mode). */
+export function getGameContainer(): HTMLElement | null {
+  return _gameContainerEl;
+}
+
+/** Bind the play-mode orchestrator to editor context. Call once at init. */
+export function bindPlayMode(ctx: Omit<PlayModeContext, 'gameContainer'>): void {
+  _ctx = { ...ctx, gameContainer: null! }; // gameContainer set dynamically via setGameContainer
+}
+
+/** True if play mode is currently active (playing or paused). */
+export function isPlayModeActive(): boolean {
+  return _session !== null;
+}
+
+/** Get the running game's audio context (for volume/mute control). */
+export function getGameAudio() {
+  return _session ? firstParty(_session).ctx.audio : null;
+}
+
+/** Get the running game's scene (for editor Scene tab rendering). */
+export function getGameScene(): THREE.Scene | null {
+  return _session?.scene ?? null;
+}
+
+/** Resize the running game to a specific resolution. */
+export function resizeGame(width: number, height: number): void {
+  _session?.resize(width, height);
+}
+
+/**
+ * Enter play mode: create a game canvas, start game, disable editor controls.
+ */
+export async function enterPlayMode(): Promise<void> {
+  if (!_ctx) return;
+  // The play button is only shown while stopped, so a non-null _session here is
+  // stale — a previous play that didn't fully tear down (e.g. a re-entry race).
+  // Clean it up so re-entering play mode always works.
+  if (_session) exitPlayMode();
+  // Capture this play's generation AFTER the stale-session cleanup (which
+  // bumps the epoch via exitPlayMode). Any exitPlayMode — or a newer
+  // enterPlayMode — during the async boot below invalidates this generation.
+  const epoch = ++_playEpoch;
+  const { store } = _ctx;
+
+  // Validate scene before entering play mode
+  try {
+    parseSceneFile(store.getDocument());
+  } catch (err) {
+    const msg = err instanceof SceneParseError ? err.message : `Scene validation failed: ${err}`;
+    editorConsole.error(msg, 'scene');
+    return;
+  }
+
+  // Patch console → editorConsole tagged [game]
+  patchConsole();
+
+  // Start log session and register sink for JSONL persistence
+  await startLogSession();
+  _pendingEntries = [];
+  _logFlushChain = Promise.resolve();
+  editorConsole.setSink((entry: ConsoleEntry) => {
+    _pendingEntries.push({
+      t: entry.timestamp,
+      level: entry.level,
+      msg: entry.message,
+      ...(entry.source ? { source: entry.source } : {}),
+      ...(entry.subsystem ? { sub: entry.subsystem } : {}),
+      ...(entry.metadata ? { meta: entry.metadata } : {}),
+    });
+  });
+  _flushInterval = setInterval(() => {
+    if (_pendingEntries.length > 0) {
+      const batch = _pendingEntries.splice(0);
+      _logFlushChain = _logFlushChain.then(() => flushLogEntries(batch));
+    }
+  }, 200);
+
+  // Register Escape → stop play mode
+  _escapeListener = (e: KeyboardEvent) => {
+    if (e.key === 'Escape') exitPlayMode();
+  };
+  window.addEventListener('keydown', _escapeListener);
+
+  // Create game canvas inside the dedicated game container
+  if (!_gameContainerEl) {
+    editorConsole.error('Game container not mounted', 'play-mode');
+    // Tear down the console patch + flush interval + escape listener set up
+    // above, same as the other failure paths (ED8).
+    exitPlayMode();
+    return;
+  }
+  const gameContainer = _gameContainerEl;
+  const w = gameContainer.clientWidth;
+  const h = gameContainer.clientHeight;
+
+  const gameCanvas = document.createElement('canvas');
+  gameCanvas.style.cssText = 'width:100%;height:100%;display:block;';
+  gameContainer.appendChild(gameCanvas);
+  _gameCanvas = gameCanvas;
+
+  // setPlayState auto-switches to Game tab
+  store.setPlayState('playing');
+  editorConsole.log('Play mode started', 'play-mode');
+
+  try {
+    const sceneData = store.getDocument();
+    const project = getCurrentProject();
+
+    if (!project) {
+      editorConsole.error('No project open — open or create a project first', 'play-mode');
+      exitPlayMode();
+      return;
+    }
+
+    const { createGameRuntime } = await import('@engine/runtime/create-runtime');
+
+    // T3.3 slice 2 part C: a manifest-backed project (vgai.game.json present)
+    // plays through the resolver, against its first world — the manifest
+    // wins for game identity/mounting per docs/CLI-ON-FOLDER-DESIGN.md §1B.
+    // A legacy (project.json-only) project has no `/vgai.game.json` to fetch
+    // (404 -> null below) and falls through to today's scripts-based path,
+    // UNCHANGED. Browser mode (the hosted, no-dev-server build) never has
+    // this route served at all, so it always takes the legacy branch too.
+    const manifest =
+      getEditorMode() === 'browser' ? null : await fetchGameManifest().catch(() => null);
+    const firstWorld = manifest?.worlds[0];
+
+    // E4.R2 (reopen fix) — honest scoping of the three branches below,
+    // replacing the old blanket "editor-side because Vite-coupled" framing
+    // (`mount-manifest.ts`'s header comment, which is true of ADAPTER
+    // CONSTRUCTION generally but was being read as though it explained every
+    // branch here equally). Each branch has its OWN, different reason to
+    // live where it does:
+    //  - The multi-world branch (below) is the one design/26 S-D D2 actually
+    //    names ("editor play mode calls it, adapter-resolver keeps only
+    //    editor-specific concerns: dev-server URLs, ingest session wiring")
+    //    — it migrated onto the engine's `mountManifestWorlds` composer.
+    //  - The single-manifest-world `else if (firstWorld)` branch stays HERE,
+    //    permanently, NOT because of dev-server coupling but because it
+    //    threads `editorPreview` (the live in-memory document + viewport
+    //    camera, so unsaved edits play and the editor's own camera seeds the
+    //    session) — a channel the engine composer must never grow, since it
+    //    is inherently "there is exactly one editable document" (the
+    //    editor's), which stops making sense the moment a manifest declares
+    //    more than one world.
+    //  - The no-manifest `else` branch (project.json-only legacy projects)
+    //    stays HERE because there is no manifest world to resolve AT ALL —
+    //    not a scoping choice, a structural one.
+    //  - `ingest-mode.ts`/`module-mode.ts` (separate files, not this
+    //    dispatch) still call `resolveAllWorlds` un-migrated — genuinely OUT
+    //    of E4's scope (not named by it), left for a follow-on unit; their
+    //    OWN dev-server `/@fs/` coupling for ingest session wiring and
+    //    custom-module loading is real and correctly stays editor-side.
+    let session: GameSession;
+    if (manifest && (manifest.worlds.length > 1 || firstWorld?.kind === 'pixijs')) {
+      // T6.1 slice 2 (docs/MULTI-WORLD-DESIGN.md §3 slice 2): a manifest with
+      // MORE THAN ONE world mounts through the slice-1 worlds path — the
+      // single-canvas legacy path below is three-only (its `createGameRuntime`
+      // call constructs exactly one THREE renderer against one canvas) and
+      // cannot represent N stacked worlds. A LONE pixijs world routes here
+      // too: the legacy path's HostContext is three-shaped (≠ World2DHost),
+      // so it could resolve but never mount a pixi adapter — and lone pixi
+      // had no working legacy behavior to preserve (it THREW pre-slice), so
+      // this is new capability, not a stability break. A single-THREE-world
+      // manifest NEVER reaches this branch (the `else if (firstWorld)`
+      // branch below is BYTE-STABLE — same call shape as before this slice). The
+      // already-created single `gameCanvas` above is unused on this path —
+      // the composer's own host builds its OWN canvas stack directly inside
+      // `gameContainer` (`mountManifestWorlds`'s `MountManifestOptions
+      // .container`), so discard it rather than leave an orphaned extra
+      // canvas in the DOM.
+      gameCanvas.remove();
+      _gameCanvas = null;
+
+      // E4.R2 (reopen fix, design/26 S-D D2 — "editor play mode calls it,
+      // adapter-resolver keeps only editor-specific concerns: dev-server
+      // URLs, ingest session wiring"): per-world adapter construction stays
+      // HERE, editor-side, via `resolveAllWorldEntries` (which is itself just
+      // the scope-checked `resolveWorldAdapter` fan-out — the SAME dev-server
+      // `/@fs/` mechanics `resolveWorldAdapter` always used). What moved OFF
+      // this file is the WorldMountSpec ASSEMBLY (id/zOrder/pausable/loop +
+      // per-kind dispatch) that `resolveAllWorlds` used to hand-build for
+      // this call site — `mountManifestWorlds` below now does that from the
+      // manifest itself (`mount-manifest.ts`'s `buildWorldMountSpec`, the
+      // engine's own single authoritative implementation of that
+      // translation), so it is never duplicated here. `entries` (not the
+      // process-global `registerWorldKind` registry) is the right channel
+      // for an editor session specifically because play mode mounts a FRESH
+      // session on every play — registering into the global registry would
+      // double-register (and throw) on the second play; `entries` carries no
+      // such hazard since it is rebuilt from scratch every `enterPlayMode`.
+      const entries = await resolveAllWorldEntries(manifest, project.rootPath);
+      editorConsole.log(
+        `Resolved ${manifest.worlds.length} manifest worlds via the composer path: ` +
+          manifest.worlds.map((w) => `${w.id} (${w.kind})`).join(', '),
+        'play-mode',
+      );
+      // Play may have been exited while resolving — don't boot a runtime for
+      // a play that is already over.
+      if (epoch !== _playEpoch) return;
+      // Re-read the container's real size instead of the `w`/`h` captured
+      // BEFORE `store.setPlayState('playing')` above (that capture can race
+      // the Game-tab layout switch and read 0x0). This still matters for the
+      // INITIAL render-buffer resolution (`mountManifestWorlds`'s own
+      // `width`/`height` default otherwise falls back to the manifest's
+      // `resolution`) even though it is no longer the ONLY thing standing
+      // between a 0x0 mount and a correctly-laid-out canvas: the worlds-path
+      // canvas's on-screen SIZE is now fully CSS-container-driven
+      // (`create-runtime.ts`'s `mountOneThreeWorld`, E4.R1 reopen fix), not
+      // pinned to whatever it mounted at.
+      const rw = gameContainer.clientWidth || w;
+      const rh = gameContainer.clientHeight || h;
+      const { mountManifestWorlds } = await import('@engine/runtime/mount-manifest');
+      session = await mountManifestWorlds({
+        manifest,
+        container: gameContainer,
+        entries,
+        width: rw,
+        height: rh,
+      });
+    } else if (firstWorld) {
+      // The SAME editorPreview the legacy branch builds below — live in-memory
+      // document (so unsaved edits play), current save path, viewport-camera
+      // spawn. The resolver threads it into whichever default-three branch it
+      // takes (entry -> setup(ctx, editorPreview), byte-equivalent to the
+      // legacy path; scene-only -> mounts sceneData, camera honored).
+      const manifestViewCam = _ctx.getViewportCamera();
+      const adapter = await resolveWorldAdapter(firstWorld, project.rootPath, {
+        editorPreview: {
+          scenePath: store.savePath,
+          sceneData,
+          viewportCamera: {
+            position: manifestViewCam.position.toArray() as [number, number, number],
+            quaternion: manifestViewCam.quaternion.toArray() as [number, number, number, number],
+          },
+        },
+      });
+      editorConsole.log(
+        `Resolved manifest world "${firstWorld.id}" (${firstWorld.adapter.identity})`,
+        'play-mode',
+      );
+      // Play may have been exited while resolving — don't boot a runtime for
+      // a play that is already over.
+      if (epoch !== _playEpoch) return;
+      session = await createGameRuntime({ canvas: gameCanvas, width: w, height: h, adapter });
+    } else {
+      // Load project scripts and run with createGameRuntime.
+      // Server build: dev-server import of the on-disk project entry.
+      // Browser build: no dev server — load the pre-bundled scripts and transpile
+      // them in-browser (same esbuild-wasm path the Playground uses).
+      let scripts: ProjectScripts;
+      if (getEditorMode() === 'browser') {
+        const { loadBrowserProjectScripts } = await import('./browser-project-scripts');
+        scripts = await loadBrowserProjectScripts();
+      } else {
+        scripts = await loadProjectScripts(project.rootPath);
+      }
+      editorConsole.log('Loaded project scripts', 'play-mode');
+
+      const viewCam = _ctx.getViewportCamera();
+      // Play may have been exited while the scripts were loading — don't boot a
+      // runtime for a play that is already over.
+      if (epoch !== _playEpoch) return;
+      // Hosted example project (Track H): route play through the bundled
+      // example's own setup — or, for a `?scene=` override inside the project,
+      // play the open scene generically but keep its asset prefix. Pure
+      // decision in hosted-example.ts; empty object everywhere else.
+      const exampleDispatch =
+        getEditorMode() === 'browser'
+          ? exampleDispatchFor(
+              project.exampleId,
+              store.savePath,
+              new URLSearchParams(window.location.search).has('scene'),
+            )
+          : {};
+      session = await createGameRuntime({
+        canvas: gameCanvas,
+        width: w,
+        height: h,
+        setup: scripts.setup,
+        editorPreview: {
+          scenePath: store.savePath,
+          sceneData,
+          viewportCamera: {
+            position: viewCam.position.toArray() as [number, number, number],
+            quaternion: viewCam.quaternion.toArray() as [number, number, number, number],
+          },
+          ...exampleDispatch,
+        },
+      });
+    }
+
+    // Play was exited (Stop/Escape) — or re-entered — while the runtime was
+    // booting. This session belongs to a play that is already over: stop it
+    // and bail WITHOUT adopting its scene into the store. Adopting here left
+    // the editor showing an empty hierarchy in edit mode and leaked the
+    // session (RAF loop, Rapier world, WebGL context).
+    if (epoch !== _playEpoch) {
+      session.stop();
+      return;
+    }
+    _session = session;
+    // A2: browser mode has no Vite dev server, so no `vgai:script-update` HMR
+    // event ever fires (the `import.meta.hot` handler below is dead in the
+    // hosted build). Drive the SAME in-browser hot-swap from the storage
+    // backend's self-derived write events instead: any component source written
+    // through the backend is transpiled + prototype-swapped onto its live
+    // instances. Subscribed here (not at module load) so it binds the backend
+    // that is actually active by play time — after any File System Access pick
+    // has replaced the boot-default OPFS backend. Torn down in exitPlayMode.
+    if (getEditorMode() === 'browser') {
+      _unsubBrowserScriptWatch = watchScriptChanges(({ path, source }) => {
+        void applyBrowserComponentEdit(source).catch((err) =>
+          editorConsole.error(`In-browser hot-swap failed for ${path}: ${err}`, 'play-mode'),
+        );
+      });
+    }
+    // `session.game.worlds` is always present on a REAL `GameSession` (T6.1
+    // slice 1 — `create-runtime.ts` unconditionally sets `game`); the
+    // optional-chaining guard here is for the LEGACY/single-world play-mode
+    // unit tests (`adapter-resolver-play-path.test.ts`,
+    // `play-mode-multi-world.test.ts`), whose `fakeSession()` fixtures predate
+    // this slice and stub only the fields THEY need — never touch those
+    // pinned files, so this reads defensively instead.
+    _isMultiWorldSession = (session.game?.worlds.length ?? 1) > 1;
+    // Wave 20 (docs/MULTI-WORLD-DESIGN.md §1.F candidate improvement /
+    // MASTER-ARCHITECTURE-REVIEW §7.4 gap 4): surface WHICH persistence regime
+    // this session's edits are under. Derived from the SAME
+    // `_isMultiWorldSession` boolean the branch below uses to pick
+    // `installMultiWorldAuthoring` (overlay, real per-world persistence) vs
+    // `installPlayAuthoring` (ephemeral, discarded on stop) — never a second,
+    // independently-computed condition, so this can't drift from the actual
+    // provider that gets installed.
+    store.setPlayEditRegime(_isMultiWorldSession ? 'overlay' : 'ephemeral');
+
+    // Swap store to game scene so hierarchy/inspector show game entities.
+    // liveHierarchy: first-party play mode is the ONLY adoption path that may
+    // synthesize descriptors for untagged runtime objects (anti-shim rule —
+    // ingest/module mounts adopt foreign scenes and must never fabricate).
+    store.enterPlayScene(session.scene, { liveHierarchy: true });
+    if (_isMultiWorldSession) {
+      // T6.1 slice 3 (docs/MULTI-WORLD-DESIGN.md §1.F/§3 slice 3): N-ary
+      // Composite over one per-world adapter each, REAL (overlay) persistence —
+      // see installMultiWorldAuthoring's doc comment for why this differs from
+      // the ephemeral-wrapped single-world path below.
+      await installMultiWorldAuthoring(store, session.game!.worlds);
+    } else {
+      // Carry an ephemeral persistence provider for the duration of play (design
+      // docs/PERSISTENCE-PROVIDER-DESIGN.md §2/§7 slice 1) — see installPlayAuthoring.
+      installPlayAuthoring(store);
+    }
+
+    // Wire physics sync THROUGH the first-party `RapierPhysicsAdapter` (Phase E):
+    // the gizmo path freezes a Rapier-owned body on beginEdit, commits the edited
+    // pose each frame (the callback below), and unfreezes on release — so the
+    // postPhysics writer doesn't snap the gizmo edit back. The editor speaks only
+    // the `PhysicsAdapter` interface, never Rapier directly.
+    // Install the GAME-scoped System-adapter aggregate (§7.1-3, probe1) — every
+    // world's `mounted.systems` merged (first registration wins per key), NOT
+    // just the default world's own copy (`firstParty(session).systems`, the
+    // pre-fix read) — so a networking/etc. adapter registered from ANY world's
+    // setup is visible to the editor's gizmo path + inspector panels.
+    // `session.game` is absent on the legacy fake-session fixtures some
+    // play-mode unit tests use (predate T6.1's `game` field) — optional-chain
+    // through so those keep passing unmodified, same fallback as before.
+    const systems = session.game?.systemAdapters ?? {};
+    setActiveSystems(systems);
+
+    // T6.3: gate game input (raw `window`/`document` listeners in game code via
+    // gated-globals, AND the default world's first-party InputManager) to only
+    // fire while play is actually running AND the Game tab is the focused
+    // viewport — so keystrokes typed into the editor (Scene tab, inspector
+    // fields) don't leak into the running game. `session.game` is absent on the
+    // legacy fake-session fixtures some play-mode unit tests use (predate T6.1's
+    // `game` field) — optional-chain through so those keep passing unmodified.
+    const gameInputActive = () =>
+      store.playState === 'playing' && store.activeViewportTab === 'game';
+    setGameInputGate(gameInputActive);
+    // `Game.input` is a THROWING getter, not an optional field — it delegates
+    // to the default world's first-party ctx and throws when that mount has
+    // no `firstParty` brand (`game.ts`'s `requireFirstPartyCtx`). Every
+    // scene/setup world mounts through `VgaiSceneGameAdapter` (branded), so
+    // this never fired before W1 — but an `adapter`-export default-three
+    // world (docs/R3F-FIRST-PARTY-DESIGN.md §1.A, e.g. the R3F bridge) owns
+    // its whole mount and correctly has no first-party `InputManager`. There
+    // is nothing to wire in that case: the gated-globals half of T6.3
+    // (`setGameInputGate` above) still fences raw window/document listeners;
+    // only the InputManager half is absent.
+    let gameInput: NonNullable<typeof session.game>['input'] | undefined;
+    try {
+      gameInput = session.game?.input;
+    } catch {
+      gameInput = undefined;
+    }
+    const syncInputEnabled = () => gameInput?.setEnabled(gameInputActive());
+    syncInputEnabled();
+    _unsubStore = store.subscribe(syncInputEnabled);
+
+    const physics = systems.physics;
+    store.setEcsSyncTransform((obj) => {
+      physics?.commit(obj, {
+        position: obj.position.toArray() as [number, number, number],
+        rotation: obj.quaternion.toArray() as [number, number, number, number],
+        scale: obj.scale.toArray() as [number, number, number],
+      });
+    });
+
+    // Container may have been display:none when w/h were read above.
+    // Now that the session exists, do one resize with the actual dimensions.
+    const actualW = gameContainer.clientWidth;
+    const actualH = gameContainer.clientHeight;
+    if (actualW > 0 && actualH > 0 && (actualW !== w || actualH !== h)) {
+      session.resize(actualW, actualH);
+    }
+  } catch (err) {
+    const msg = `Play mode failed to start: ${err}`;
+    editorConsole.error(msg, 'play-mode');
+    // Roll back only if THIS play is still the live generation — if it was
+    // already exited during boot (epoch moved on), a second exitPlayMode here
+    // could tear down a newer play that started in the meantime.
+    if (epoch === _playEpoch) exitPlayMode();
+    throw new Error(msg);
+  }
+}
+
+/**
+ * Exit play mode: stop game, remove canvas, re-enable editor.
+ */
+export function exitPlayMode(): void {
+  if (!_ctx) return;
+  // Invalidate any enterPlayMode still awaiting its runtime boot (see
+  // _playEpoch): its session must be abandoned, not adopted.
+  _playEpoch++;
+  const { store } = _ctx;
+
+  // Restore editor scene before stopping (stop disposes game scene children)
+  store.setEcsSyncTransform(null);
+  setActiveSystems(null);
+  store.exitPlayScene();
+  if (_isMultiWorldSession) exitMultiWorldAuthoring();
+  restorePriorAuthoring();
+  _isMultiWorldSession = false;
+  // Readout-only — clear the regime the moment play is no longer active
+  // (mirrors _isMultiWorldSession's own reset just above). Optional-chained:
+  // some pre-existing play-mode unit tests (e.g. play-mode-teardown.test.ts's
+  // ED8 no-container path) pass a minimal hand-built fake store that predates
+  // this signal and stubs only the methods THEY need — never touch those
+  // pinned fixtures, so this degrades gracefully instead (same convention as
+  // this file's other `session.game?.` guards for legacy fixtures).
+  store.setPlayEditRegime?.(null);
+
+  // Always null _session even if stop() throws — otherwise enterPlayMode's
+  // `if (_session) return` guard would permanently block re-entering play mode.
+  if (_session) {
+    try {
+      _session.stop();
+    } catch (err) {
+      editorConsole.error(`Error stopping play session: ${err}`, 'play-mode');
+    } finally {
+      _session = null;
+    }
+  }
+
+  // Remove game canvas
+  _gameCanvas?.remove();
+  _gameCanvas = null;
+
+  // Cleanup subscriptions
+  _unsubStore?.();
+  _unsubStore = null;
+  _unsubBrowserScriptWatch?.();
+  _unsubBrowserScriptWatch = null;
+
+  // T6.3: no game running — game input (raw window/document listeners AND the
+  // InputManager sync above) should never be suppressed again until the next
+  // play session re-gates it.
+  setGameInputGate(() => true);
+
+  _resizeObserver?.disconnect();
+  _resizeObserver = null;
+
+  if (_escapeListener) {
+    window.removeEventListener('keydown', _escapeListener);
+    _escapeListener = null;
+  }
+
+  // Log before clearing sink so this message gets persisted
+  editorConsole.log('Play mode stopped', 'play-mode');
+
+  // Flush remaining log entries and end session
+  if (_flushInterval) {
+    clearInterval(_flushInterval);
+    _flushInterval = null;
+  }
+  editorConsole.setSink(null);
+  if (_pendingEntries.length > 0) {
+    const batch = _pendingEntries.splice(0);
+    _logFlushChain = _logFlushChain.then(() => flushLogEntries(batch));
+  }
+  // The server has one active log file. End it only after every queued batch
+  // has reached the append endpoint, otherwise Stop can race the final fetch
+  // and silently discard the most useful end-of-run evidence.
+  _logFlushChain = _logFlushChain.then(() => endLogSession());
+
+  unpatchConsole();
+
+  // setPlayState('stopped') auto-switches back to Scene tab
+  store.setPlayState('stopped');
+}
+
+/**
+ * Pause play mode: freeze game, allow editor inspection.
+ */
+export function pausePlayMode(): void {
+  if (!_session || !_ctx) return;
+  _session.pause();
+  _ctx.store.setPlayState('paused');
+
+  editorConsole.log('Play mode paused', 'play-mode');
+}
+
+/**
+ * Resume play mode from pause.
+ */
+export function resumePlayMode(): void {
+  if (!_session || !_ctx) return;
+
+  _session.resume();
+  _ctx.store.setPlayState('playing');
+
+  editorConsole.log('Play mode resumed', 'play-mode');
+}
+
+/**
+ * Step one fixed-timestep frame while paused.
+ */
+export function stepPlayMode(): void {
+  if (!_session) return;
+  _session.step();
+}
+
+// --- Console patching ---
+
+function patchConsole(): void {
+  _originalConsoleLog = console.log;
+  _originalConsoleInfo = console.info;
+  _originalConsoleWarn = console.warn;
+  _originalConsoleError = console.error;
+
+  console.log = (...args: unknown[]) => {
+    _originalConsoleLog?.apply(console, args);
+    if (!_engineLogActive) editorConsole.log(args.map(String).join(' '), 'game');
+  };
+  console.info = (...args: unknown[]) => {
+    _originalConsoleInfo?.apply(console, args);
+    if (!_engineLogActive) editorConsole.log(args.map(String).join(' '), 'game');
+  };
+  console.warn = (...args: unknown[]) => {
+    _originalConsoleWarn?.apply(console, args);
+    if (!_engineLogActive) editorConsole.warn(args.map(String).join(' '), 'game');
+  };
+  console.error = (...args: unknown[]) => {
+    _originalConsoleError?.apply(console, args);
+    if (!_engineLogActive) editorConsole.error(args.map(String).join(' '), 'game');
+  };
+}
+
+function unpatchConsole(): void {
+  if (_originalConsoleLog) console.log = _originalConsoleLog;
+  if (_originalConsoleInfo) console.info = _originalConsoleInfo;
+  if (_originalConsoleWarn) console.warn = _originalConsoleWarn;
+  if (_originalConsoleError) console.error = _originalConsoleError;
+  _originalConsoleLog = null;
+  _originalConsoleInfo = null;
+  _originalConsoleWarn = null;
+  _originalConsoleError = null;
+}