@vgai/engine 0.5.21 → 0.5.23

package/src/runtime/create-runtime.ts

@@ -1,5 +1,6 @@
 import * as THREE from 'three';
 import { assertNever } from '../adapter/adapter-surface';
+import { createRootBinding, type RootBinding, type RootDeclaration } from '../adapter/binding';
 import type { CanvasHostContext, DomHostContext, ThreeHostContext } from '../adapter/host-context';
 import type {
   MountedPixiRoot,
@@ -7,10 +8,12 @@ import type {
   MountedRoot,
   MountedThreeRoot,
   RootAdapter,
+  SurfaceAdapter,
 } from '../adapter/root-adapter';
 import { createAssetCache } from '../assets';
 import { createGameLoop } from '../core/game-loop';
 import { createHostRenderer } from '../setup/setup-renderer';
+import { getDebugRegistry } from './debug-registry';
 // TYPE-ONLY: `create-runtime.ts` must never value-import `pixi.js` — a canvas
 // `RootMountSpec`'s `adapter` is supplied ALREADY-CONSTRUCTED by the caller, so
 // the host only ever needs the seam's types.
@@ -19,36 +22,11 @@ import {
   createRootInstance,
   type Game,
   type GameInternal,
-  isFirstPartyMounted,
   type RootInstance,
 } from './game';
 import { createInputRouter, type RouterAdapterRoot, stackOrder } from './input-router';
+import type { PlaytestContext } from './playtest';
 import { installRenderControlHarness, isRenderModeRequested } from './render-control';
-import type { PlaytestContext } from './types';
-
-/**
- * Register a three world for a freshly-mounted game onto the Game shell. Shared
- * by `createGameRuntime` and every headless test harness
- * (`test/game-root.test.ts`, `test/frame-order.test.ts`,
- * `test/game-two-roots.test.ts`) so there is exactly one code path for this
- * wiring. `physics`/`collisions`/`camera`/`frame` are populated from the mount's
- * first-party `GameContext`/ `MountedSetupThreeRoot` when available, left
- * `undefined` otherwise (an external adapter's mount has none of these
- * first-party handles — `frame` in particular is what makes
- * `GameInternal.runFrame` fall back to a single opaque
- * `mounted.update` call per substep for such a world).
- */
-function firstPartyExtras(
-  mounted: MountedRoot,
-): Pick<Parameters<typeof createRootInstance>[0], 'physics' | 'collisions' | 'camera' | 'frame'> {
-  if (!isFirstPartyMounted(mounted)) return {};
-  return {
-    physics: mounted.ctx.physics,
-    collisions: mounted.ctx.collisions,
-    camera: mounted.ctx.camera,
-    frame: mounted.frame,
-  };
-}
 
 /**
  * Register a three world onto the Game shell. `opts.id` defaults to
@@ -59,21 +37,68 @@ export function registerThreeRoot(
   game: GameInternal,
   adapter: RootAdapter,
   mounted: MountedThreeRoot,
-  opts?: { id?: string | undefined; pausable?: boolean | undefined },
+  opts?: RegisterRootOptions,
 ): RootInstance {
+  const pausable = opts?.pausable ?? true;
   const world = createRootInstance({
     id: opts?.id ?? 'main',
     kind: 'three',
-    pausable: opts?.pausable ?? true,
+    pausable,
     adapter,
     mounted,
     scene: mounted.scene as THREE.Scene,
-    ...firstPartyExtras(mounted),
+    binding: bindRoot(
+      game,
+      opts?.declaration,
+      {
+        surface: 'three',
+        adapter: adapter as RootAdapter<'three'>,
+      },
+      mounted,
+      pausable,
+    ),
   });
   game.registerRoot(world);
   return world;
 }
 
+/** What every `register<Surface>Root` takes beyond the mount itself. */
+export interface RegisterRootOptions {
+  readonly id?: string | undefined;
+  readonly pausable?: boolean | undefined;
+  /**
+   * The DECLARATION half of this root's binding, from the resolver that
+   * produced `adapter` (`adapter/binding.ts`). Absent for a bare harness
+   * registration or a `mountManifestRoots` caller who supplied an
+   * already-constructed adapter — see `RootInstance.binding` for why that
+   * legitimately yields `null` rather than a fabricated binding.
+   */
+  readonly declaration?: RootDeclaration | undefined;
+}
+
+/**
+ * Complete the root's binding at the first moment it CAN be completed: the
+ * declaration is what the resolver knew, `mounted`/`adapter`/`pausable` are
+ * what mounting produced, and the debug registry is the game's own. Nothing
+ * here loads or fabricates — see `createRootBinding`.
+ */
+function bindRoot(
+  game: GameInternal,
+  declaration: RootDeclaration | undefined,
+  adapter: SurfaceAdapter,
+  mounted: MountedRoot,
+  pausable: boolean,
+): RootBinding | null {
+  if (!declaration) return null;
+  return createRootBinding({
+    ...declaration,
+    adapter,
+    mounted,
+    pausable,
+    debugRegistry: getDebugRegistry(game),
+  });
+}
+
 /**
  * Register a canvas world onto the Game shell — the pixi analog of
  * {@link registerThreeRoot}. `adapter` is the seam's own
@@ -85,16 +110,18 @@ export function registerPixiRoot(
   game: GameInternal,
   adapter: RootAdapter<'canvas'>,
   mounted: MountedPixiRoot,
-  opts?: { id?: string | undefined; pausable?: boolean | undefined },
+  opts?: RegisterRootOptions,
 ): RootInstance {
   const id = opts?.id ?? 'main';
+  const pausable = opts?.pausable ?? true;
   const world = createRootInstance({
     id,
     kind: 'canvas',
-    pausable: opts?.pausable ?? true,
+    pausable,
     adapter,
     mounted,
     stage: mounted.stage,
+    binding: bindRoot(game, opts?.declaration, { surface: 'canvas', adapter }, mounted, pausable),
   });
   game.registerRoot(world);
   return world;
@@ -116,15 +143,17 @@ export function registerReactRoot(
   adapter: RootAdapter<'dom'>,
   mounted: MountedReactRoot,
   container: HTMLElement,
-  opts?: { id?: string | undefined; pausable?: boolean | undefined },
+  opts?: RegisterRootOptions,
 ): RootInstance {
+  const pausable = opts?.pausable ?? true;
   const world = createRootInstance({
     id: opts?.id ?? 'main',
     kind: 'dom',
-    pausable: opts?.pausable ?? true,
+    pausable,
     adapter,
     mounted,
     container,
+    binding: bindRoot(game, opts?.declaration, { surface: 'dom', adapter }, mounted, pausable),
   });
   game.registerRoot(world);
   return world;
@@ -156,6 +185,14 @@ export interface RootMountSpecBase {
    * `input-router.ts`'s `resolveClaimingRoot`.
    */
   readonly hitTest?: ((x: number, y: number) => boolean) | undefined;
+  /**
+   * The DECLARATION half of this root's binding, from whoever resolved
+   * `adapter` — see `adapter/binding.ts`'s {@link RootDeclaration}. Carried on
+   * the spec because the resolver knows it and the host is the only one who
+   * can complete the binding (it needs `mounted`, which does not exist until
+   * this spec is mounted).
+   */
+  readonly declaration?: RootDeclaration | undefined;
 }
 
 export interface ThreeRootMountSpec extends RootMountSpecBase {
@@ -185,9 +222,8 @@ export interface PixiRootMountSpec extends RootMountSpecBase {
  * opaque mount with nothing to tick).
  *
  * Deliberately carries NO `firstParty: true` brand: that brand specifically
- * means "has a `.ctx: GameContext`" (`isFirstPartyMounted`,
- * `runtime/game.ts`) — a react world has no Rapier/ComponentManager/
- * GameContext at all, so branding it first-party would be a type lie.
+ * a react world has no physics or component runtime at all, so branding it
+ * first-party would be a type lie.
  * `Game.registerRoot`'s "no state bridge" console warning explicitly exempts
  * `kind: 'dom'` (§7.1-15): a react world has no `observe` BY DESIGN — that
  * hook is scoped to `useRootObservation` (the ingested/foreign-world case),
@@ -223,7 +259,7 @@ export interface ReactRootAdapter extends RootAdapter<'dom'> {
   mount(host: DomHostContext): Promise<MountedReactGame>;
 }
 
-/** WO-34, same reasoning as {@link PixiRootMountSpec} above: the seam's
+/** Same reasoning as {@link PixiRootMountSpec} above: the seam's
  *  `RootAdapter<'dom'>` is what a DOM root actually guarantees. */
 export interface ReactRootMountSpec extends RootMountSpecBase {
   readonly kind: 'dom';
@@ -249,9 +285,8 @@ export interface RootsRuntimeConfig {
   /**
    * Mirrors `ThreeHostContext.headless` (Node conformance tests — no GPU): skips
    * real `WebGLRenderer` construction for every three world in this
-   * session (a stand-in renderer is used instead, exactly as
-   * `SetupThreeRootAdapter.mount` already special-cases `host.headless`
-   * internally). Pixijs roots are unaffected — Pixi already falls back to
+   * session (a stand-in renderer is used instead; adapters special-case
+   * `host.headless` themselves). Pixijs roots are unaffected — Pixi already falls back to
    * a 2D canvas renderer with no GPU. Never set `true` in a real host.
    */
   headless?: boolean | undefined;
@@ -301,11 +336,9 @@ export interface RootsRuntimeConfig {
 /**
  * Handle returned by createGameRuntime() for controlling the running game.
  *
- * This is the GENERIC host handle — it has no first-party concepts (no
- * `GameContext`, no `GameSetupFn`). First-party features (the live `GameContext`,
- * warm-restart hot reload) are reached through `game.defaultRoot.mounted`
- * and narrowed to `MountedSetupThreeRoot`
- * (the editor does this for HMR/physics-sync — those are inherently first-party).
+ * This is the GENERIC host handle — it has no first-party concepts. A
+ * root's own surface is reached through `game.defaultRoot.mounted`, typed
+ * as the mounted-root contract (`MountedRoot`).
  *
  * Root access is explicit through `game.roots`, `game.world(id)`, and
  * `game.defaultRoot`; the session does not project a surface-specific alias.
@@ -341,9 +374,8 @@ export async function createGameRuntime(config: RootsRuntimeConfig): Promise<Gam
 // ---------------------------------------------------------------------------
 
 /** A stand-in `THREE.WebGLRenderer` for headless (`headless:true`) three
- *  roots — mirrors `SetupThreeRootAdapter.mount`'s own `headlessComposer`
- *  pattern (`adapter/setup-three-root-adapter.ts`): a headless first-party
- *  mount never calls a render-phase method on `host.renderer` at all, so
+ *  roots: a headless mount never calls a render-phase method on
+ *  `host.renderer` at all, so
  *  this only needs to satisfy the handful of calls THIS file itself makes
  *  (`setPixelRatio`/`setClearColor`/`setSize` at mount, `dispose`/
  *  `forceContextLoss` at teardown) — never a real GL call. Node conformance
@@ -372,6 +404,45 @@ interface MountedAdapterRoot {
   readonly renderer: THREE.WebGLRenderer | undefined;
 }
 
+/**
+ * Reclaim ONE mounted root: its adapter, the renderer this file constructed for
+ * it (including the WebGL context — a browser keeps only a handful alive, so
+ * `dispose()` alone is not enough), and its stacked surface element.
+ *
+ * ONE body, TWO callers, deliberately: the session's `fullCleanup` (a normal
+ * stop) and `mountAllRootSpecs`'s partial-mount ROLLBACK (a later root's mount
+ * rejected, so the roots that already mounted must not survive the rejection).
+ * Those two must never drift — a rollback that reclaims less than a stop is how
+ * a failed play leaves a live renderer and a lost GL context behind with no
+ * handle anywhere able to reach it.
+ *
+ * Throws only what the adapter's own `dispose()` throws; every caller wraps it
+ * per entry so one bad root cannot abort the rest of the teardown.
+ */
+function disposeMountedRoot(entry: MountedAdapterRoot, container: HTMLElement): void {
+  try {
+    entry.mounted.dispose();
+  } finally {
+    // Renderer + surface release run even when the adapter's dispose threw:
+    // the GL context is the scarce resource, and the caller still sees the
+    // error (this rethrows through the `finally`).
+    entry.renderer?.dispose();
+    entry.renderer?.forceContextLoss();
+    // Remove from the element's CURRENT parent, not the mount-time
+    // `container`: the editor's Game panel re-parents the live surfaces
+    // when its mount element swaps (fill <-> device preset, W2c), and
+    // `container.removeChild` would throw NotFoundError after such a move.
+    // `container` remains the fallback for hosts whose element stand-ins
+    // never wire `parentNode` (headless unit fixtures); an element already
+    // detached by such a host is a no-op via the catch.
+    try {
+      (entry.element.parentNode ?? container).removeChild(entry.element);
+    } catch {
+      /* already detached — nothing to remove */
+    }
+  }
+}
+
 interface OneRootResult {
   readonly mountedEntry: MountedAdapterRoot;
   readonly routerEntry: RouterAdapterRoot;
@@ -456,7 +527,11 @@ async function mountOneThreeRoot(
     game,
   };
   const mounted = await spec.adapter.mount(host);
-  registerThreeRoot(game, spec.adapter, mounted, { id: spec.id, pausable: spec.pausable });
+  registerThreeRoot(game, spec.adapter, mounted, {
+    id: spec.id,
+    pausable: spec.pausable,
+    declaration: spec.declaration,
+  });
   return {
     mountedEntry: { id: spec.id, kind: 'three', element: canvas, mounted, renderer },
     routerEntry: { id: spec.id, zOrder: spec.zOrder ?? 0, canvas, hitTest: spec.hitTest },
@@ -468,7 +543,7 @@ async function mountOneThreeRoot(
  *  `mountOneThreeRoot` above.
  *
  *  Unlike `mountOneThreeRoot`, this needs no explicit `canvas.style.width`/
- *  `.height` re-assertion (E4.R1). `pixi-surface.ts` constructs its
+ *  `.height` re-assertion. The canvas surface constructs its
  *  `Application` with `autoDensity: true`, which makes PIXI ITSELF re-stamp
  *  `canvas.style.width`/`.height` (real CSS px, matching the LOGICAL
  *  width/height passed to `resize()`) on every `app.renderer.resize()` call —
@@ -500,6 +575,7 @@ async function mountOnePixiRoot(
   registerPixiRoot(game, spec.adapter, mounted, {
     id: spec.id,
     pausable: spec.pausable,
+    declaration: spec.declaration,
   });
   return {
     mountedEntry: {
@@ -560,6 +636,7 @@ async function mountOneReactRoot(
   registerReactRoot(game, spec.adapter, mounted, layer, {
     id: spec.id,
     pausable: spec.pausable,
+    declaration: spec.declaration,
   });
   return {
     mountedEntry: {
@@ -579,8 +656,8 @@ async function mountOneReactRoot(
  * per D5 §1, z-order/ties exactly matching
  * `manifest/load.ts`'s sort, ONE `Game`, and registers every world onto it
  * via `registerThreeRoot`/`registerPixiRoot`/`registerReactRoot` — the
- * SAME wiring `test/game-three-plus-pixi.test.ts` proves by hand for the
- * three/pixi pair. Worlds MOUNT in `roots` ARRAY order ("manifest
+ * SAME wiring `test/create-runtime-worlds.test.ts` proves for the
+ * three/canvas pair. Worlds MOUNT in `roots` ARRAY order ("manifest
  * declaration order" — the frame/registration axis), independent of
  * `zOrder` (the canvas-stacking/rendering axis) — the two orders can differ
  * and both are honored correctly.
@@ -628,6 +705,10 @@ function installDefaultRootDevGlobals(game: GameInternal): () => void {
  *  `isBottom`, plus the surface lookup and bottom-id needed to derive them. */
 interface MountAllRootsInputs extends Omit<OneRootContext, 'canvas' | 'isBottom'> {
   readonly surfacesById: Map<string, HTMLElement>;
+  /** The host element the surfaces were stacked into — needed only by the
+   *  partial-mount rollback, which reclaims them through the same
+   *  {@link disposeMountedRoot} body a normal stop uses. */
+  readonly container: HTMLElement;
 }
 
 interface MountAllRootsResult {
@@ -650,36 +731,60 @@ async function mountAllRootSpecs(
   bottomId: string | undefined,
   inputs: MountAllRootsInputs,
 ): Promise<MountAllRootsResult> {
-  const { surfacesById, ...shared } = inputs;
+  const { surfacesById, container, ...shared } = inputs;
   const mountedEntries: MountedAdapterRoot[] = [];
   const routerEntries: RouterAdapterRoot[] = [];
 
-  for (const spec of mountSpecs) {
-    const isBottom = spec.id === bottomId;
-    if (spec.kind === 'dom') {
-      const layer = surfacesById.get(spec.id)!;
-      const { mountedEntry } = await mountOneReactRoot(spec, shared.game, layer);
+  try {
+    for (const spec of mountSpecs) {
+      const isBottom = spec.id === bottomId;
+      if (spec.kind === 'dom') {
+        const layer = surfacesById.get(spec.id)!;
+        const { mountedEntry } = await mountOneReactRoot(spec, shared.game, layer);
+        mountedEntries.push(mountedEntry);
+        continue;
+      }
+      const canvas = surfacesById.get(spec.id)! as HTMLCanvasElement;
+      const oneCtx: OneRootContext = { ...shared, canvas, isBottom };
+      let mountedEntry: MountedAdapterRoot;
+      let routerEntry: RouterAdapterRoot;
+      if (spec.kind === 'three') {
+        ({ mountedEntry, routerEntry } = await mountOneThreeRoot(spec, oneCtx));
+      } else if (spec.kind === 'canvas') {
+        ({ mountedEntry, routerEntry } = await mountOnePixiRoot(spec, oneCtx));
+      } else {
+        // Exhaustiveness guard (§7.4-2): 'react' was already handled by the
+        // early `continue` above, so only a hypothetical 4th `AdapterSurface` can
+        // reach here — fail loudly rather than silently defaulting. `spec`
+        // itself (not `spec.kind`) is what TS has narrowed to `never`, since
+        // `RootMountSpec` is a discriminated union at the object level.
+        assertNever(spec, 'create-runtime mount loop');
+      }
       mountedEntries.push(mountedEntry);
-      continue;
+      routerEntries.push(routerEntry);
     }
-    const canvas = surfacesById.get(spec.id)! as HTMLCanvasElement;
-    const oneCtx: OneRootContext = { ...shared, canvas, isBottom };
-    let mountedEntry: MountedAdapterRoot;
-    let routerEntry: RouterAdapterRoot;
-    if (spec.kind === 'three') {
-      ({ mountedEntry, routerEntry } = await mountOneThreeRoot(spec, oneCtx));
-    } else if (spec.kind === 'canvas') {
-      ({ mountedEntry, routerEntry } = await mountOnePixiRoot(spec, oneCtx));
-    } else {
-      // Exhaustiveness guard (§7.4-2): 'react' was already handled by the
-      // early `continue` above, so only a hypothetical 4th `AdapterSurface` can
-      // reach here — fail loudly rather than silently defaulting. `spec`
-      // itself (not `spec.kind`) is what TS has narrowed to `never`, since
-      // `RootMountSpec` is a discriminated union at the object level.
-      assertNever(spec, 'create-runtime mount loop');
+  } catch (err) {
+    // PARTIAL MOUNT ROLLBACK. Roots mount sequentially, so a rejection from
+    // root N leaves roots 1..N-1 fully live — renderer, WebGL context, R3F
+    // tree, adapter registrations — and NOTHING ever gets a handle to them:
+    // this function throws instead of returning, so no `GameSession` (and
+    // therefore no `stop()`) is ever constructed. Reclaim them here, in
+    // REVERSE mount order (the inverse of the order they were built in), then
+    // rethrow the ORIGINAL error — the mount failure is what the caller must
+    // see, never a teardown error raised while cleaning up after it.
+    for (let i = mountedEntries.length - 1; i >= 0; i--) {
+      const entry = mountedEntries[i]!;
+      try {
+        disposeMountedRoot(entry, container);
+      } catch (disposeErr) {
+        // biome-ignore lint/suspicious/noConsole: a rollback failure must be visible; the original mount error is still what we rethrow
+        console.error(
+          `createGameRuntime: rolling back root "${entry.id}" after a mount failure threw:`,
+          disposeErr,
+        );
+      }
     }
-    mountedEntries.push(mountedEntry);
-    routerEntries.push(routerEntry);
+    throw err;
   }
   return { mountedEntries, routerEntries };
 }
@@ -735,6 +840,37 @@ function installSessionRenderHarness(
   };
 }
 
+/**
+ * Reclaim what `createRootsGameRuntime` built for ITSELF when the mount
+ * rejects. `mountAllRootSpecs` has already rolled back every root that DID
+ * mount, so what is left is the Game shell (holding whatever registrations
+ * those roots made into it) and the stacked surface elements of the roots that
+ * never got to mount. Neither is reachable afterwards: the mount throws instead
+ * of returning, so no `GameSession` — and therefore no `stop()` — ever exists.
+ *
+ * Never throws: the MOUNT error is what the caller must see, so a failure while
+ * cleaning up after it is reported and swallowed.
+ */
+function reclaimAfterMountFailure(
+  game: GameInternal,
+  surfaces: Iterable<HTMLElement>,
+  container: HTMLElement,
+): void {
+  try {
+    game.dispose();
+  } catch (disposeErr) {
+    // biome-ignore lint/suspicious/noConsole: a failed rollback must be visible; the original mount error is what the caller gets
+    console.error('createGameRuntime: disposing the game after a mount failure threw:', disposeErr);
+  }
+  for (const surface of surfaces) {
+    try {
+      (surface.parentNode ?? container).removeChild(surface);
+    } catch {
+      /* already detached by the per-root rollback */
+    }
+  }
+}
+
 async function createRootsGameRuntime(config: RootsRuntimeConfig): Promise<GameSession> {
   const { container, roots: specs, width, height, headless = false, seed, playtest } = config;
   if (specs.length === 0) {
@@ -836,14 +972,14 @@ async function createRootsGameRuntime(config: RootsRuntimeConfig): Promise<GameS
     // host's explicit `simulateSubsteps`/`renderOnce` calls — wall-clock time
     // passing while a screenshot is taken must not move the world.
     externalDrive: renderMode,
-    // WO-P13 — sim and presentation are wired to different callbacks here:
+    // Sim and presentation are wired to different callbacks here:
     // `update` runs the gameplay phases once per consumed fixed substep with
     // `preRender`/`render` withheld, and `render` runs those two once per real
     // display frame with the interpolation alpha. Both closures are invoked
     // only from the loop's own rAF arm, which `externalDrive` never arms — so
     // a capture/offline-export page (`renderMode`) reaches neither, and its
     // `simulateSubsteps` → `game.runFrame(fixedDt)` path stays frame-exact,
-    // rendering inside the substep exactly as it did before this flip.
+    // rendering inside the substep.
     update: (dt) => {
       if (started) game.runFrame(dt, { skipRenderPhases: true });
     },
@@ -858,16 +994,24 @@ async function createRootsGameRuntime(config: RootsRuntimeConfig): Promise<GameS
   // `createRootsGameRuntime`'s own cyclomatic complexity down (E4) — same
   // reason `mountOneThreeRoot`/`mountOnePixiRoot` are already split out
   // below.
-  const { mountedEntries, routerEntries } = await mountAllRootSpecs(mountSpecs, bottomId, {
-    game,
-    surfacesById,
-    w,
-    h,
-    dpr,
-    headless,
-    assets,
-    antialias: config.antialias,
-  });
+  let mounted: MountAllRootsResult;
+  try {
+    mounted = await mountAllRootSpecs(mountSpecs, bottomId, {
+      game,
+      surfacesById,
+      container,
+      w,
+      h,
+      dpr,
+      headless,
+      assets,
+      antialias: config.antialias,
+    });
+  } catch (err) {
+    reclaimAfterMountFailure(game, surfacesById.values(), container);
+    throw err;
+  }
+  const { mountedEntries, routerEntries } = mounted;
 
   // --- Delegating input router (D5 §2a) ---
   const router = createInputRouter(container, routerEntries);
@@ -894,37 +1038,55 @@ async function createRootsGameRuntime(config: RootsRuntimeConfig): Promise<GameS
   });
   let stopping = false;
 
+  /**
+   * Reclaim EVERYTHING this session owns, and let no single failure stop that.
+   *
+   * Teardown used to be one `try` over the whole body, so a throwing
+   * `entry.mounted.dispose()` on root 1 skipped root 2's disposal, both
+   * renderers' `forceContextLoss`, `game.dispose()` and the two global
+   * retractions — while `stopComplete` still resolved and the editor still
+   * reported the instance reclaimed. Every step is now isolated: a failure is
+   * COLLECTED and reported, never allowed to abort the steps after it.
+   */
   function fullCleanup(): void {
     if (stopping) return;
     stopping = true;
+    const failures: { readonly step: string; readonly error: unknown }[] = [];
+    /** Run one teardown step; record its failure and keep going. */
+    const step = (name: string, run: () => void): void => {
+      try {
+        run();
+      } catch (error) {
+        failures.push({ step: name, error });
+      }
+    };
     try {
-      loop.stop();
-      router.dispose();
+      step('loop.stop', () => loop.stop());
+      step('router.dispose', () => router.dispose());
       for (const entry of mountedEntries) {
-        entry.mounted.dispose();
-        entry.renderer?.dispose();
-        entry.renderer?.forceContextLoss();
-        // Remove from the element's CURRENT parent, not the mount-time
-        // `container`: the editor's Game panel re-parents the live surfaces
-        // when its mount element swaps (fill <-> device preset, W2c), and
-        // `container.removeChild` would throw NotFoundError after such a move.
-        // `container` remains the fallback for hosts whose element stand-ins
-        // never wire `parentNode` (headless unit fixtures); an element already
-        // detached by such a host is a no-op via the catch.
-        try {
-          (entry.element.parentNode ?? container).removeChild(entry.element);
-        } catch {
-          /* already detached — nothing to remove */
-        }
+        step(`root "${entry.id}"`, () => disposeMountedRoot(entry, container));
       }
-      game.dispose();
-      retractDevGlobals();
-      retractRenderHarness?.();
+      step('game.dispose', () => game.dispose());
+      step('dev globals', () => retractDevGlobals());
+      step('render harness', () => retractRenderHarness?.());
     } finally {
       void Promise.allSettled(
         mountedEntries.map((entry) => entry.mounted.disposeComplete ?? Promise.resolve()),
       ).then(() => resolveStopComplete());
     }
+    if (failures.length > 0) {
+      // LOUD, and after everything else has been reclaimed. `stop()` is called
+      // from hosts that must not be left half-torn-down by an early throw, so
+      // the report comes last — but it IS a report: a silent partial teardown
+      // is the failure this whole restructure exists to end. The editor's
+      // `exitPlayMode` catches it and prints it to the editor console.
+      throw new AggregateError(
+        failures.map((f) => f.error),
+        `Game session teardown failed in ${failures.length} step(s): ${failures
+          .map((f) => f.step)
+          .join(', ')}. Every other step still ran.`,
+      );
+    }
   }
 
   return {