@vgai/engine 0.5.0 → 0.5.2

package/dist/runtime/create-runtime.js

@@ -1,641 +0,0 @@
-import * as THREE from 'three';
-import { assertNever } from '../adapter/adapter-surface';
-import { createAssetCache } from '../assets';
-import { createGameLoop } from '../core/game-loop';
-import { createHostRenderer } from '../setup/setup-renderer';
-import { createGame, createWorldInstance, isFirstPartyMounted, } from './game';
-import { createInputRouter, stackOrder } from './input-router';
-// Re-export the camera-precedence helper from its new home so existing importers
-// (`import { adoptSceneCamera } from '@engine/runtime/create-runtime'`) keep working.
-export { adoptSceneCamera } from '../adapter/vgai-scene-game-adapter';
-/**
- * Register a threejs 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 (T7.1 slice 1, id-generalized in slice 3 for the two-world proof —
- * `docs/GAME-ROOT-DESIGN.md` §8 stage 3) — `physics`/`collisions`/`camera`/
- * `frame` are populated from the mount's first-party `GameContext`/
- * `VgaiMountedGame` 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` (T7.1 slice 2) fall back
- * to a single opaque `mounted.update` call per substep for such a world).
- */
-function firstPartyExtras(mounted) {
-    if (!isFirstPartyMounted(mounted))
-        return {};
-    return {
-        physics: mounted.ctx.physics,
-        collisions: mounted.ctx.collisions,
-        camera: mounted.ctx.camera,
-        frame: mounted.frame,
-    };
-}
-/**
- * Register a threejs world onto the Game shell. `opts.id` defaults to
- * `'main'` — the single-world callers (`createGameRuntime`, slice-1/2 tests)
- * are unaffected; a second/third world (T7.1 slice 3's two-world proof, and
- * real multi-world manifests later) pass an explicit id. This is the ONE
- * registration code path for a threejs world, whatever its id.
- */
-export function registerThreeWorld(game, adapter, mounted, opts) {
-    const world = createWorldInstance({
-        id: opts?.id ?? 'main',
-        kind: 'threejs',
-        pausable: opts?.pausable ?? true,
-        adapter,
-        mounted,
-        scene: mounted.scene,
-        ...firstPartyExtras(mounted),
-    });
-    // T7.2 slice 2 — one-time world-wiring backfill (closes the KNOWN GAP
-    // documented on `resolveWorldInstance` in `ecs/component-manager.ts`):
-    // scene-authored components were attached by the scene loader DURING the
-    // `mount()` call that just returned `mounted`, before this `WorldInstance`
-    // existed — so `instance.world` was left `undefined` for every one of
-    // them. `adoptWorld` backfills it now, once, for every already-attached
-    // instance still missing a world. Attaches made AFTER this point (e.g.
-    // runtime-spawned entities once the game is ticking) still resolve their
-    // world directly at attach time, unaffected by this call.
-    if (isFirstPartyMounted(mounted)) {
-        mounted.ctx.components.adoptWorld(world);
-    }
-    game.registerWorld(world);
-    return world;
-}
-/**
- * Register a pixijs world onto the Game shell — the pixi analog of
- * {@link registerThreeWorld}, mirroring the wiring
- * `world2d/pixi-game-adapter.ts`'s `createWorld2DRuntime` performs for its
- * OWN (separate) Game, and `test/game-three-plus-pixi.test.ts` performs by
- * hand onto a SHARED Game. `createGameRuntime`'s roots path
- * (T6.1 slice 1) is the first PRODUCTION caller that registers a pixijs
- * world alongside other roots on one Game; this is its one wiring code
- * path, so a second/third pixijs world (or a future caller) never
- * re-derives it. `adapter` is typed as the real {@link Pixi2DGameAdapter}
- * shape (T7.5 — previously the generic `GameAdapter`, which forced a cast at
- * every call site since a pixi adapter's `mount` takes a `World2DHost`, not
- * `HostContext`); `WorldInstance.adapter` itself only needs `.id`
- * (`AdapterHandle`, `runtime/game.ts`), so this passes through with zero cast.
- *
- * Section 7.4-5 (design-gap catalog), UPDATED by wave 2 (D-Y1,
- * docs/EXTERNAL-REACT-AND-MODULE-DESIGN.md §1/§4 slice S1): this guard used
- * to THROW for a non-first-party mount, reasoning "today this can never
- * actually fire (Pixi2DGameAdapter.mount is typed to always return a
- * MountedGame2D, whose ctx/physics2d/collisions2d/frame are all REQUIRED
- * fields, so there is no foreign-mount shape that could reach here)". Wave 2
- * proved that reasoning stale: a `kind: 'pixijs'` `{ module }` adapter's mount
- * result IS exactly such a foreign shape — `Pixi2DGameAdapter`'s TYPE promises
- * `MountedGame2D`, but `adapter-resolver.ts`'s `resolveAllWorlds` reaches it
- * only via `adapter as unknown as Pixi2DGameAdapter` (a custom module's actual
- * return value is merely `MountedPixiWorld`-shaped, T7.5's cross-kind union),
- * so the "never actually fire" premise no longer holds the moment a custom
- * pixi module world reaches the roots path. Rather than keep the throw (which
- * would re-create exactly the kind of dead end D-X6 named and D-Y1 exists to
- * remove), this now degrades EXACTLY like `registerThreeWorld`'s own foreign-
- * mount handling above (`firstPartyExtras`): `physics2d`/`collisions2d`/
- * `frame`/component-adoption are omitted for a non-first-party mount instead
- * of read from a `.ctx` that doesn't exist — `stage` (the one field every
- * `MountedPixiWorld`, first-party or not, actually carries) is always real.
- */
-function pixiFirstPartyExtras(mounted) {
-    // Same structural check `firstPartyExtras`/`isFirstPartyMounted` use — see
-    // this function's own doc comment (above `registerPixiWorld`) for why this
-    // stays a plain boolean read rather than a type-guarded `isFirstPartyMounted`
-    // call (that guard's threejs-shaped return type would narrow `mounted` to
-    // `never` here).
-    if (mounted.firstParty !== true)
-        return {};
-    return {
-        physics2d: mounted.ctx.physics2d,
-        collisions2d: mounted.ctx.collisions2d,
-        frame: mounted.frame,
-    };
-}
-export function registerPixiWorld(game, adapter, mounted, opts) {
-    const id = opts?.id ?? 'main';
-    const mountedIsFirstParty = mounted.firstParty === true;
-    const world = createWorldInstance({
-        id,
-        kind: 'pixijs',
-        pausable: opts?.pausable ?? true,
-        adapter,
-        mounted,
-        stage: mounted.stage,
-        ...pixiFirstPartyExtras(mounted),
-    });
-    // Mirrors `registerThreeWorld`'s adoptWorld backfill above — the pixi
-    // world's scene-authored components attach during `mount()`, before this
-    // `WorldInstance` exists. Skipped for a non-first-party mount (a foreign
-    // `{ module }` adapter's `ComponentManager` doesn't exist to adopt into —
-    // same "nothing for a custom adapter to backfill" reasoning
-    // `registerReactWorld`'s doc comment records for react).
-    if (mountedIsFirstParty)
-        mounted.ctx.components.adoptWorld(world);
-    game.registerWorld(world);
-    return world;
-}
-/**
- * Register a react world onto the Game shell (T6.2 slice 1,
- * `docs/REACT-WORLD-DESIGN.md` §1.B) — the react analog of
- * {@link registerThreeWorld}/{@link registerPixiWorld}. A react world has no
- * `ComponentManager` to adopt (D8: react entities host no GameComponents —
- * there is nothing for `adoptWorld` to backfill, unlike the three/pixi
- * siblings above) and no `frame` hooks (react's own `createRoot` schedules
- * its commits; `GameInternal.runFrame` correctly leaves a world with no
- * `frame` untouched by its opaque-`update` fallback too, since
- * `MountedReactGame` declares no `update`). `adapter` is typed as the real
- * {@link ReactRootAdapter} shape (T7.5, same reasoning as
- * `registerPixiWorld`'s doc comment above) — `WorldInstance.adapter` only
- * needs `.id`, so this passes through with zero cast.
- */
-export function registerReactWorld(game, adapter, mounted, container, opts) {
-    const world = createWorldInstance({
-        id: opts?.id ?? 'main',
-        kind: 'react',
-        pausable: opts?.pausable ?? true,
-        adapter,
-        mounted,
-        container,
-    });
-    game.registerWorld(world);
-    return world;
-}
-/**
- * Bootstrap the game host and mount a game adapter.
- *
- * `createGameRuntime` is the universal HOST: it owns the root surfaces,
- * renderers, loop, and asset cache. Every game — including a one-root game —
- * uses the same explicit adapter-root path.
- */
-export async function createGameRuntime(config) {
-    return createWorldsGameRuntime(config);
-}
-// ---------------------------------------------------------------------------
-// Worlds path (T6.1 slice 1 — docs/MULTI-WORLD-DESIGN.md §1.A/B/C)
-// ---------------------------------------------------------------------------
-/** A stand-in `THREE.WebGLRenderer` for headless (`headless:true`) threejs
- *  roots — mirrors `VgaiSceneGameAdapter.mount`'s own `headlessComposer`
- *  pattern (`adapter/vgai-scene-game-adapter.ts`): a headless first-party
- *  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
- *  tests only; never used when `headless` is left `false`/absent. */
-function createHeadlessRendererStub() {
-    return {
-        setPixelRatio() { },
-        setClearColor() { },
-        setSize() { },
-        dispose() { },
-        forceContextLoss() { },
-    };
-}
-/**
- * Derive a REAL default `hitTest` for a pixijs world from its own mounted
- * stage (D5 §2a/COMPOSITION-DESIGN.md proof item 2: "pixi `EventBoundary
- * .hitTest`") — used only when the caller's `WorldMountSpec` didn't declare
- * an explicit `hitTest`. `(x, y)` are container-relative pixels, matching
- * the coordinates the pixi surface renders at (the stage itself carries no
- * pan/zoom — that lives on `pixi-surface.ts`'s child `world` container, per
- * its own doc comment), so this is a correct global hit test with no extra
- * coordinate mapping. Duck-typed against `mounted.ctx.app` (never a
- * value-import of `pixi.js`) so this file stays type-only w.r.t. Pixi;
- * returns `undefined` (no default claim) if the mount's `app`/event
- * boundary isn't shaped as expected — degrade to "does not claim" rather
- * than throw. A non-first-party mount (D-Y1, wave 2 — same finding
- * `registerPixiWorld`'s doc comment records: a `{ module }` adapter's mount
- * has no `.ctx` at all) has nothing to duck-type here either, so this checks
- * the SAME `firstParty` brand FIRST and degrades identically — never claims,
- * never throws.
- */
-function derivePixiHitTest(mounted) {
-    if (mounted.firstParty !== true)
-        return undefined;
-    const app = mounted.ctx.app;
-    const rootBoundary = app?.renderer?.events?.rootBoundary;
-    if (!rootBoundary || typeof rootBoundary.hitTest !== 'function')
-        return undefined;
-    // Pixi assigns `rootTarget` lazily on the first render. Pointer movement
-    // can reach the host router during that small window (or while a world is
-    // tearing down); EventBoundary.hitTest dereferences it unconditionally.
-    // An unready boundary cannot claim input, so degrade to no hit instead of
-    // surfacing Pixi's internal `undefined.eventMode` exception.
-    return (x, y) => rootBoundary.rootTarget != null && rootBoundary.hitTest(x, y) != null;
-}
-/** Mount one threejs `WorldMountSpec` (canvas + renderer construction, per
- *  D5 §1/§4, then `registerThreeWorld`). Split out of
- *  `createWorldsGameRuntime` purely to keep that function's own branching
- *  simple — see `mountOnePixiWorld` for the pixijs sibling. */
-async function mountOneThreeWorld(spec, ctx) {
-    const { game, canvas, w, h, dpr, isBottom, headless, loopHandle, assets } = ctx;
-    const renderer = headless
-        ? createHeadlessRendererStub()
-        : createHostRenderer(canvas, w, h, undefined, {
-            alpha: !isBottom,
-            preserveDrawingBuffer: true,
-        });
-    renderer.setSize(w, h, false); // backing resolution only — CSS stacking owns layout size
-    // Defect E4.R1 (Fable review): `createHostRenderer`'s OWN construction-time
-    // `setSize` call (`setup-renderer.ts`, `updateStyle` defaulting `true` —
-    // unchanged there on purpose, see below) stamps `canvas.style.width`/
-    // `.height` to literal `${w}px`/`${h}px` the moment the renderer is built,
-    // OVERWRITING the container-relative `100%`/`100%` the surface-stacking
-    // loop above just set. The `renderer.setSize(w, h, false)` line right above
-    // this comment does NOT undo that stamp (updateStyle:false only skips
-    // TOUCHING style, it can't un-stamp a previous call) — so without this
-    // re-assertion, every roots-path threejs canvas' on-screen size was
-    // permanently pinned to whatever `w`/`h` it happened to mount at (usually
-    // the manifest's `resolution`, since standalone builds mount before a real
-    // container size is known — see `mount-manifest.ts`). Re-asserting here
-    // makes the CSS layout size and the render-buffer resolution fully
-    // independent, exactly like the react DOM world layer already is: this
-    // fixes the template-standalone bug (broken at any viewport other than the
-    // manifest's `resolution`, which is also Playwright's DEFAULT viewport —
-    // why it went unnoticed) and, for free, tri-world's pre-existing
-    // resize-staleness (the roots-path `resize()` below always calls
-    // `setSize(rw, rh, false)`, so nothing else was ever going to update this
-    // canvas' CSS after mount). `createHostRenderer`'s own default
-    // (`updateStyle:true`) is intentionally left alone — the LEGACY
-    // single-canvas path (editor play-mode's non-multi-world branch) still
-    // relies on that construction-time stamp + its own later `updateStyle:true`
-    // resizes for byte-identical behavior; this fix touches only the
-    // roots-path canvas, after the fact.
-    canvas.style.width = '100%';
-    canvas.style.height = '100%';
-    renderer.setPixelRatio(dpr);
-    if (!isBottom)
-        renderer.setClearColor(0x000000, 0); // D5 §1: alpha-clear above the bottom layer
-    const host = {
-        three: THREE,
-        surface: { canvas, width: w, height: h },
-        renderer,
-        loop: loopHandle,
-        assets,
-        headless,
-        game,
-        requestSystem: () => null,
-    };
-    const mounted = await spec.adapter.mount(host);
-    registerThreeWorld(game, spec.adapter, mounted, { id: spec.id, pausable: spec.pausable });
-    return {
-        mountedEntry: { id: spec.id, kind: 'threejs', element: canvas, mounted, renderer },
-        routerEntry: { id: spec.id, zOrder: spec.zOrder ?? 0, canvas, hitTest: spec.hitTest },
-    };
-}
-/** Mount one pixijs `WorldMountSpec` (via its own `World2DHost`, per D5
- *  §1/§3/§4, then `registerPixiWorld`) — the pixi sibling of
- *  `mountOneThreeWorld` above. Derives a real default `hitTest` from the
- *  mounted stage when the spec didn't declare one (see `derivePixiHitTest`).
- *
- *  Unlike `mountOneThreeWorld`, this needs no explicit `canvas.style.width`/
- *  `.height` re-assertion (E4.R1). `pixi-surface.ts` 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 —
- *  including the one this world's `mounted.resize?.()` triggers from the
- *  roots-path `resize()` below. So while a pixi world's canvas can start
- *  pinned to the mount-time `w`/`h` (same as threejs, until PIXI's own
- *  construction-time resize runs), it self-heals the moment ANY real
- *  `session.resize(rw, rh)` fires — every shipped standalone entry
- *  (`packages/editor/template/src/main.ts`, `examples/tri-world/src/main.ts`)
- *  already calls `session.resize()` unconditionally right after mount, so
- *  this never surfaces as a lasting bug the way threejs' buffer-only resize
- *  did (never self-healing, by design — see above). */
-async function mountOnePixiWorld(spec, ctx) {
-    const { game, canvas, w, h, dpr, isBottom } = ctx;
-    const pixiHost = {
-        canvas,
-        width: w,
-        height: h,
-        game,
-        dpr,
-        transparent: !isBottom,
-        preserveDrawingBuffer: true,
-    };
-    const mounted = await spec.adapter.mount(pixiHost);
-    registerPixiWorld(game, spec.adapter, mounted, {
-        id: spec.id,
-        pausable: spec.pausable,
-    });
-    return {
-        mountedEntry: {
-            id: spec.id,
-            kind: 'pixijs',
-            element: canvas,
-            mounted,
-            renderer: undefined,
-        },
-        routerEntry: {
-            id: spec.id,
-            zOrder: spec.zOrder ?? 0,
-            canvas,
-            hitTest: spec.hitTest ?? derivePixiHitTest(mounted),
-        },
-    };
-}
-/**
- * Mount one react `WorldMountSpec` (T6.2 slice 1, `docs/REACT-WORLD-DESIGN.md`
- * §1.B/§1.C) — the react sibling of `mountOneThreeWorld`/`mountOnePixiWorld`.
- * Unlike its canvas-backed siblings this returns NO `routerEntry`: a react
- * world's DOM-root layer participates in D5's z-order/box stacking (the
- * caller still creates and positions its `<div>` exactly like a canvas — see
- * `createWorldsGameRuntime`'s stack-building loop) but needs no entry in the
- * delegating router's hit-test loop (§1.C — "DOM layers need no entry in the
- * router's hit-test loop"): the layer's own `pointer-events` discipline
- * (this file sets `none` on the layer by default; the mounted React tree opts specific elements back
- * in with `pointer-events:auto`) is what lets its interactive elements claim
- * events NATIVELY, via the real DOM, with zero router involvement — and lets
- * a click over its non-interactive (transparent) area fall through to the
- * canvas below it via the SAME native DOM hit-testing (a `pointer-events:none`
- * element is invisible to hit-testing entirely, so the click lands on
- * whatever real DOM element is beneath it — the router's normal
- * canvas-vs-canvas forwarding, unaffected by this layer's presence).
- */
-async function mountOneReactWorld(spec, game, 
-/** The ALREADY-created, already-stacked (position/z-index set, appended to
- *  `container`) DOM-root layer for this world — see
- *  `createWorldsGameRuntime`'s surface-stack loop, which builds a `<div>`
- *  for every react-kind spec up front, in the SAME pass that builds every
- *  other world's canvas. This function must reuse that exact element (never
- *  create its own) so `WorldInstance.reactRoot()` returns the SAME node
- *  that is actually positioned in the stack. */
-layer) {
-    layer.style.pointerEvents = 'none';
-    // An absolutely-positioned layer with no width/height collapses to zero
-    // content size, so a child's
-    // own position:absolute offsets resolve against a degenerate containing
-    // block (found by the T6.2 slice-3 e2e — clicks landed outside the game).
-    layer.style.width = '100%';
-    layer.style.height = '100%';
-    const reactHost = { container: layer, game };
-    const mounted = await spec.adapter.mount(reactHost);
-    registerReactWorld(game, spec.adapter, mounted, layer, {
-        id: spec.id,
-        pausable: spec.pausable,
-    });
-    return {
-        mountedEntry: {
-            id: spec.id,
-            kind: 'react',
-            element: layer,
-            mounted,
-            renderer: undefined,
-        },
-    };
-}
-/**
- * The roots-path implementer behind {@link createGameRuntime} (T6.1 slice
- * 1; react roots added T6.2 slice 1). Builds ONE surface per world — a
- * canvas for threejs/pixijs, a DOM-root `<div>` layer for react — stacked
- * per COMPOSITION-DESIGN D5 §1, z-order/ties exactly matching
- * `manifest/load.ts`'s sort, ONE `Game`, and registers every world onto it
- * via `registerThreeWorld`/`registerPixiWorld`/`registerReactWorld` — the
- * SAME wiring `test/game-three-plus-pixi.test.ts` proves by hand for the
- * three/pixi pair. Worlds MOUNT in `roots` ARRAY order (GAME-ROOT-DESIGN §4's
- * "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.
- */
-/**
- * Dev/e2e-only `window.__vgaiScene`/`__vgaiCamera` exposure for the roots
- * path's DEFAULT world (E4) — split out of `createWorldsGameRuntime` purely
- * to keep that function's own cyclomatic complexity down. Mirrors the
- * legacy single-world path's identical exposure (above, in this same file),
- * using the SAME "first threejs world, else none" default-world rule the
- * `GameSession.scene`/`.camera` getters alias (`Game.defaultWorld`): a
- * non-threejs default world (or none at all) publishes neither global,
- * exactly like those getters return `undefined` in that case. Returns a
- * retraction callback — identity-guarded (a newer session's globals must
- * never be clobbered by an older session's stop, same reason the legacy
- * path's own cleanup guards it) — that is a no-op when nothing was
- * published (non-DEV build, or non-threejs default world).
- */
-function installDefaultWorldDevGlobals(game) {
-    if (!import.meta.env?.DEV)
-        return () => { };
-    const defaultMounted = game.defaultWorld.mounted;
-    if (defaultMounted.kind !== 'threejs')
-        return () => { };
-    const scene = defaultMounted.scene;
-    const camera = defaultMounted.camera;
-    const w = window;
-    w['__vgaiScene'] = scene;
-    w['__vgaiCamera'] = camera;
-    return () => {
-        if (w['__vgaiScene'] === scene)
-            delete w['__vgaiScene'];
-        if (w['__vgaiCamera'] === camera)
-            delete w['__vgaiCamera'];
-    };
-}
-/**
- * Mount + register every world spec, in ARRAY (declaration) order — split
- * out of `createWorldsGameRuntime` purely to keep that function's own
- * cyclomatic complexity down (E4, same reason `mountOneThreeWorld`/
- * `mountOnePixiWorld` are already split out). React roots contribute NO
- * router entry (docs/REACT-WORLD-DESIGN.md §1.C — "DOM layers need no entry
- * in the router's hit-test loop"): their layer's own `pointer-events`
- * discipline handles claim/fall-through natively, with zero router
- * involvement (see `mountOneReactWorld`'s doc comment).
- */
-async function mountAllWorldSpecs(mountSpecs, bottomId, inputs) {
-    const { surfacesById, ...shared } = inputs;
-    const mountedEntries = [];
-    const routerEntries = [];
-    for (const spec of mountSpecs) {
-        const isBottom = spec.id === bottomId;
-        if (spec.kind === 'react') {
-            const layer = surfacesById.get(spec.id);
-            const { mountedEntry } = await mountOneReactWorld(spec, shared.game, layer);
-            mountedEntries.push(mountedEntry);
-            continue;
-        }
-        const canvas = surfacesById.get(spec.id);
-        const oneCtx = { ...shared, canvas, isBottom };
-        let mountedEntry;
-        let routerEntry;
-        if (spec.kind === 'threejs') {
-            ({ mountedEntry, routerEntry } = await mountOneThreeWorld(spec, oneCtx));
-        }
-        else if (spec.kind === 'pixijs') {
-            ({ mountedEntry, routerEntry } = await mountOnePixiWorld(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
-            // `WorldMountSpec` is a discriminated union at the object level.
-            assertNever(spec, 'create-runtime mount loop');
-        }
-        mountedEntries.push(mountedEntry);
-        routerEntries.push(routerEntry);
-    }
-    return { mountedEntries, routerEntries };
-}
-async function createWorldsGameRuntime(config) {
-    const { container, roots: specs, width, height, headless = false, seed } = config;
-    if (specs.length === 0) {
-        throw new Error('createGameRuntime: `roots` must contain at least one root.');
-    }
-    const mountSpecs = specs;
-    const w = Math.max(1, width ?? container.clientWidth ?? 0);
-    const h = Math.max(1, height ?? container.clientHeight ?? 0);
-    const dpr = headless
-        ? 1
-        : Math.min(typeof window !== 'undefined' ? window.devicePixelRatio || 1 : 1, 2);
-    if (!container.style.position)
-        container.style.position = 'relative';
-    // --- Surface stack (D5 §1): DOM/z-order follows zOrder, ties -> array
-    // order — computed FIRST (bottom -> top) so both the z-index assignment
-    // below and the router's default-claim rule share one definition. A react
-    // world's DOM-root layer shares this SAME stacking pass (T6.2 slice 1,
-    // docs/REACT-WORLD-DESIGN.md §1.B — "one stacking model, no special case")
-    // even though it is a `<div>`, not a canvas, and carries no `hitTest` (the
-    // router never sees react entries at all — see the dispatch loop below). ---
-    const stacked = stackOrder(mountSpecs.map((spec) => ({ id: spec.id, zOrder: spec.zOrder ?? 0, hitTest: spec.hitTest })));
-    const bottomId = stacked[0]?.id;
-    const kindById = new Map(mountSpecs.map((spec) => [spec.id, spec.kind]));
-    const surfacesById = new Map();
-    stacked.forEach((entry, i) => {
-        const isReact = kindById.get(entry.id) === 'react';
-        const surface = document.createElement(isReact ? 'div' : 'canvas');
-        if (!isReact) {
-            const canvas = surface;
-            canvas.width = w;
-            canvas.height = h;
-        }
-        // Defect E4.R1 (Fable review): layout size is ALWAYS container-relative
-        // (`width:100%;height:100%`), fully decoupled from the surface's
-        // intrinsic buffer resolution (`w`/`h`, set on the canvas element's
-        // `width`/`height` ATTRIBUTES above — a device-pixel/render-resolution
-        // concern only). Without this, a canvas with no CSS size falls back to
-        // its `width`/`height` attribute as its CSS layout size too, so whatever
-        // stamped those attributes (`createHostRenderer`'s construction-time
-        // `setSize`, `mountOneThreeWorld` below) pins the ON-SCREEN size — see
-        // that function's doc comment for the concrete bug this caused (template
-        // standalone at any viewport ≠ the manifest resolution). Setting it HERE
-        // too (not just in `mountOneThreeWorld`) means every surface, whatever
-        // kind, starts container-relative from its very first paint, before any
-        // per-kind mount work has even run.
-        // `contain:layout paint` makes each surface the CONTAINING BLOCK for
-        // `position:fixed` descendants (and clips overflow to the world's
-        // rectangle): full-screen game UI written the natural way (`fixed;
-        // inset:0`) then fills the WORLD, not the page. Without it, `fixed` UI
-        // looks correct standalone (surface == window) but escapes over the
-        // editor chrome whenever the surface is a sub-rectangle of the page —
-        // and toggles behavior when any ancestor gains a transform (e.g. the
-        // editor's space-pan). Dogfooded 2026-07-12 via a react shell world.
-        surface.style.cssText = `position:absolute;top:0;left:0;width:100%;height:100%;z-index:${i + 1};contain:layout paint;`;
-        container.appendChild(surface);
-        surfacesById.set(entry.id, surface);
-    });
-    const assets = createAssetCache();
-    const extraUpdaters = new Set();
-    const loopHandle = {
-        onUpdate(fn) {
-            extraUpdaters.add(fn);
-            return () => extraUpdaters.delete(fn);
-        },
-    };
-    let started = false;
-    const loop = createGameLoop({
-        fixedTimestep: 1 / 60,
-        maxSubSteps: 8,
-        update: (dt) => {
-            if (started)
-                game.runFrame(dt);
-            for (const fn of extraUpdaters)
-                fn(dt);
-        },
-    });
-    const game = createGame({ loop, assets, seed });
-    // --- Mount + register every world, in ARRAY (declaration) order. ---
-    // Split out into its own top-level function purely to keep
-    // `createWorldsGameRuntime`'s own cyclomatic complexity down (E4) — same
-    // reason `mountOneThreeWorld`/`mountOnePixiWorld` are already split out
-    // below.
-    const { mountedEntries, routerEntries } = await mountAllWorldSpecs(mountSpecs, bottomId, {
-        game,
-        surfacesById,
-        w,
-        h,
-        dpr,
-        headless,
-        loopHandle,
-        assets,
-    });
-    // --- Delegating input router (D5 §2a) ---
-    const router = createInputRouter(container, routerEntries);
-    started = true;
-    loop.start();
-    // Expose scene & camera for dev tools / e2e tests — mirrors the legacy
-    // single-world path's identical dev-only exposure above, generalized to
-    // the roots path's DEFAULT world (E4, docs/unified-world-editor/
-    // 27-visual-react-editing.md §7 E4): `mountGameFromManifest`/
-    // `mountManifestWorlds` route every caller (including a single-threejs-
-    // world scaffold project) through THIS path, so a caller migrating off
-    // the legacy `{canvas, adapter}` call must not silently lose
-    // `window.__vgaiScene`/`__vgaiCamera` — real e2e/dev tooling depends on
-    // them (`packages/editor/e2e/tests/04-standalone-game.spec.ts`). Split
-    // into its own top-level helper (with its retraction counterpart below)
-    // purely to keep this function's own cyclomatic complexity down.
-    const retractDevGlobals = installDefaultWorldDevGlobals(game);
-    function fullCleanup() {
-        loop.stop();
-        router.dispose();
-        for (const entry of mountedEntries) {
-            entry.mounted.dispose();
-            entry.renderer?.dispose();
-            entry.renderer?.forceContextLoss();
-            container.removeChild(entry.element);
-        }
-        retractDevGlobals();
-    }
-    return {
-        stop: fullCleanup,
-        // D10/T7.6: `Game.play` fans out per-world pausable/loop-gate/audio-gate
-        // semantics itself now (see the legacy path's identical comment above) —
-        // a `pausable: false` world (a menu/HUD world) keeps ticking while every
-        // other world freezes, which the old blind `for (const entry of
-        // mountedEntries) entry.mounted.setPaused?.(true)` fan-out (with no
-        // `pausable` check at all) could never express.
-        pause() {
-            game.play.pause();
-        },
-        resume() {
-            game.play.resume();
-        },
-        step() {
-            game.play.step();
-        },
-        resize(rw, rh) {
-            const safeWidth = Math.max(1, rw);
-            const safeHeight = Math.max(1, rh);
-            for (const entry of mountedEntries) {
-                entry.renderer?.setSize(safeWidth, safeHeight, false);
-                entry.mounted.resize?.(safeWidth, safeHeight);
-            }
-        },
-        // `GameSession.scene`/`.camera`/`.mounted` alias `Game.defaultWorld` (T6.1
-        // slice 1's "first threejs world, else first world" rule) — a legacy
-        // convenience shaped for the threejs-only past. T7.5 narrows the read via
-        // the `kind` discriminant instead of a blind `.scene`/`.camera` cast
-        // through a nonexistent property (identical behavior to before: still
-        // `undefined` for a roots-path session whose default world isn't
-        // threejs — real per-world surface routing for that case is T7.6's).
-        get scene() {
-            const m = game.defaultWorld.mounted;
-            return (m.kind === 'threejs' ? m.scene : undefined);
-        },
-        get camera() {
-            const m = game.defaultWorld.mounted;
-            return (m.kind === 'threejs' ? m.camera : undefined);
-        },
-        get mounted() {
-            return game.defaultWorld.mounted;
-        },
-        game,
-    };
-}