@vgai/engine 0.2.0 → 0.3.0

package/dist/runtime/create-runtime.js

@@ -0,0 +1,795 @@
+import * as THREE from 'three';
+import { VgaiSceneGameAdapter } from '../adapter/vgai-scene-game-adapter';
+import { assertNever } from '../adapter/world-kind';
+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-worlds.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;
+}
+/** Thin alias kept for existing single-world callers (`createGameRuntime`,
+ *  `test/game-root.test.ts`, `test/frame-order.test.ts`) — registers the
+ *  default `'main'` world via the SAME `registerThreeWorld` code path. */
+export function registerDefaultThreeWorld(game, adapter, mounted) {
+    return registerThreeWorld(game, adapter, mounted);
+}
+/**
+ * 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 worlds path
+ * (T6.1 slice 1) is the first PRODUCTION caller that registers a pixijs
+ * world alongside other worlds 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 worlds 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 ReactWorldAdapter} 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;
+}
+function isWorldsConfig(config) {
+    return 'worlds' in config;
+}
+/**
+ * Bootstrap the game host and mount a game adapter.
+ *
+ * `createGameRuntime` is the HOST: it owns the canvas/renderer(s), the loop,
+ * the UI overlay, and the asset cache, and it mounts a {@link GameAdapter}
+ * (or several, via the worlds path — T6.1 slice 1) against that context. It
+ * knows nothing about `.vscn`, `GameComponent`, Rapier, or `GameSetupFn` —
+ * those live inside the first-party {@link VgaiSceneGameAdapter}, which is
+ * the default implementer when no explicit `adapter` is supplied on the
+ * legacy path. Dispatches on `config`'s shape: {@link WorldsRuntimeConfig}
+ * (`worlds` present) goes through {@link createWorldsGameRuntime};
+ * everything else is the byte-compatible legacy single-world path.
+ */
+export async function createGameRuntime(config) {
+    if (isWorldsConfig(config)) {
+        return createWorldsGameRuntime(config);
+    }
+    const { canvas, width, height, adapter, ...sceneConfig } = config;
+    const w = Math.max(1, width ?? canvas.width);
+    const h = Math.max(1, height ?? canvas.height);
+    // --- Host primitives (neutral — no first-party assumptions) ---
+    const renderer = createHostRenderer(canvas, w, h);
+    const assets = createAssetCache();
+    let uiContainer;
+    const existingUi = document.getElementById('example-ui');
+    if (existingUi instanceof HTMLDivElement) {
+        uiContainer = existingUi;
+    }
+    else {
+        uiContainer = document.createElement('div');
+        uiContainer.id = 'example-ui';
+        uiContainer.style.cssText =
+            'position:absolute;top:0;left:0;width:100%;height:100%;pointer-events:none;z-index:2;';
+        (canvas.parentElement ?? document.getElementById('ui-overlay') ?? document.body).appendChild(uiContainer);
+    }
+    const extraUpdaters = new Set();
+    const loopHandle = {
+        onUpdate(fn) {
+            extraUpdaters.add(fn);
+            return () => extraUpdaters.delete(fn);
+        },
+    };
+    // --- Game root (T7.1 slice 1 + slice 2) ---
+    // The loop's update callback used to close directly over `mounted`, which
+    // only exists after `game.mount(host)` resolves. The Game shell (and thus
+    // its `loop`) must exist BEFORE mount so the mount can see `host.game` — so
+    // the callback instead consults a mutable ref, set once mount resolves.
+    // Behavior is identical: `loop.start()` still only runs after mount, same
+    // pause/step/stop semantics below. `drivesOwnLoop` handling now lives
+    // INSIDE `game.runFrame` (T7.1 slice 2) rather than being checked here —
+    // for today's single first-party (or single opaque host-driven) world this
+    // is byte-identical to the old `if (!mountedRef.drivesOwnLoop) mountedRef
+    // .update?.(dt)` guard (see `runFrame`'s doc comment in `runtime/game.ts`).
+    // `game` is referenced here before its `const` below only textually — this
+    // closure isn't invoked until `loop.start()`, well after `game` exists.
+    let mountedRef = null;
+    const loop = createGameLoop({
+        fixedTimestep: 1 / 60,
+        maxSubSteps: 8,
+        update: (dt) => {
+            if (mountedRef)
+                game.runFrame(dt);
+            for (const fn of extraUpdaters)
+                fn(dt);
+        },
+    });
+    const game = createGame({ loop, assets });
+    const host = {
+        three: THREE,
+        surface: { canvas, width: w, height: h },
+        renderer,
+        loop: loopHandle,
+        assets,
+        ui: uiContainer,
+        game,
+        requestSystem: () => null,
+    };
+    // --- Mount the game adapter (first-party default, or an explicit adapter) ---
+    const gameAdapter = adapter ?? new VgaiSceneGameAdapter(sceneConfig);
+    const mounted = await gameAdapter.mount(host);
+    mountedRef = mounted;
+    // Register the default (and, in this slice, only) threejs world now that
+    // mount has produced a MountedGame — the world's `threeRoot()` must return
+    // the SAME scene instance the adapter mounted (identity is the contract).
+    registerDefaultThreeWorld(game, gameAdapter, mounted);
+    // Expose scene & camera for dev tools / e2e tests
+    if (import.meta.env?.DEV) {
+        const w = window;
+        w['__vgaiScene'] = mounted.scene;
+        w['__vgaiCamera'] = mounted.camera;
+    }
+    loop.start();
+    function fullCleanup() {
+        loop.stop();
+        mounted.dispose();
+        renderer.dispose();
+        renderer.forceContextLoss();
+        // Retract the dev/e2e globals THIS session published (identity-guarded so
+        // a newer session's globals are never clobbered by an older session's
+        // stop). Leaving them dangling let e2e waits pass vacuously against a
+        // stopped game's scene/camera.
+        if (import.meta.env?.DEV) {
+            const w = window;
+            if (w['__vgaiScene'] === mounted.scene)
+                delete w['__vgaiScene'];
+            if (w['__vgaiCamera'] === mounted.camera)
+                delete w['__vgaiCamera'];
+        }
+    }
+    return {
+        stop: fullCleanup,
+        // D10/T7.6: `Game.play` (`runtime/game.ts`) is the real control surface —
+        // it fans out over every `pausable` world (just the one default world on
+        // this legacy single-world path) via its loop-gate/audio-gate capability,
+        // reporting honestly wherever a world can't actually be gated, and keeps
+        // `render` running every substep while paused (the old `loop.timeScale =
+        // 0` here starved the accumulator entirely — per D1, zero substeps means
+        // zero renders too — which is the bug this replaces, not a behavior to
+        // preserve).
+        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);
+            renderer.setSize(safeWidth, safeHeight);
+            mounted.resize?.(safeWidth, safeHeight);
+        },
+        get scene() {
+            return mounted.scene;
+        },
+        get camera() {
+            return mounted.camera;
+        },
+        get mounted() {
+            return mounted;
+        },
+        game,
+    };
+}
+// ---------------------------------------------------------------------------
+// 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
+ *  worlds — 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;
+    return (x, y) => 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, uiContainer, 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 worlds-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 worlds-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
+    // worlds-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,
+        ui: uiContainer,
+        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
+ *  worlds-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, uiContainer } = ctx;
+    const pixiHost = {
+        canvas,
+        width: w,
+        height: h,
+        ui: uiContainer,
+        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, mirroring the existing
+ * `uiContainer`/HUD rule; 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';
+    // Size the layer like the shared uiContainer does: 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 worlds-path implementer behind {@link createGameRuntime} (T6.1 slice
+ * 1; react worlds 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 `worlds` 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 worlds
+ * 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 worlds 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 `WorldKind` 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, worlds: specs, width, height, headless = false } = config;
+    if (specs.length === 0) {
+        throw new Error('createGameRuntime: `worlds` must contain at least one world.');
+    }
+    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.
+        surface.style.cssText = `position:absolute;top:0;left:0;width:100%;height:100%;z-index:${i + 1};`;
+        container.appendChild(surface);
+        surfacesById.set(entry.id, surface);
+    });
+    // One shared UI overlay, above every canvas. I8 render-integration seam
+    // (docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md §15 I8, C1 review note):
+    // the legacy single-world path (above) reuses/stamps a stable `#example-ui`
+    // id so a capture host has a reliable selector for "the HUD/letterbox
+    // overlay" — this worlds path had no such id at all, so a render-mode page
+    // built on `createWorldsGameRuntime` (multi-world manifests, including a
+    // react-HUD-over-threejs cinematic) had no stable selector to composite-
+    // screenshot. `vgai-ui-overlay` is deliberately a DIFFERENT id than the
+    // legacy path's `example-ui` (not reused/aliased) — the two runtime paths
+    // mount genuinely different DOM subtrees, and collapsing them onto one id
+    // would make a caller's selector ambiguous about which mount produced it.
+    const uiContainer = document.createElement('div');
+    uiContainer.id = 'vgai-ui-overlay';
+    uiContainer.style.cssText =
+        `position:absolute;top:0;left:0;width:100%;height:100%;pointer-events:none;` +
+            `z-index:${stacked.length + 1};`;
+    container.appendChild(uiContainer);
+    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 });
+    // --- 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,
+        uiContainer,
+        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 worlds 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);
+        }
+        container.removeChild(uiContainer);
+        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 worlds-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,
+    };
+}