@vgai/engine 0.5.5 → 0.5.7

package/dist/runtime/create-runtime.js

@@ -0,0 +1,666 @@
+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';
+// 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.
+import { createGame, createRootInstance, isFirstPartyMounted, } from './game';
+import { createInputRouter, stackOrder } from './input-router';
+import { installRenderControlHarness, isRenderModeRequested } from './render-control';
+/**
+ * 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 (T7.1 slice 1, id-generalized in slice 3 for the two-world proof — stage
+ * 3) — `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` (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 three 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 three world, whatever its id.
+ */
+export function registerThreeRoot(game, adapter, mounted, opts) {
+    const world = createRootInstance({
+        id: opts?.id ?? 'main',
+        kind: 'three',
+        pausable: opts?.pausable ?? true,
+        adapter,
+        mounted,
+        scene: mounted.scene,
+        ...firstPartyExtras(mounted),
+    });
+    game.registerRoot(world);
+    return world;
+}
+/**
+ * Register a canvas world onto the Game shell — the pixi analog of
+ * {@link registerThreeRoot}. `adapter` is the seam's own
+ * `RootAdapter<'canvas'>`; `RootInstance.adapter` itself only needs `.id`
+ * (`AdapterHandle`, `runtime/game.ts`), so this passes through with zero cast.
+ * `stage` is the one field every `MountedPixiRoot` actually carries.
+ */
+export function registerPixiRoot(game, adapter, mounted, opts) {
+    const id = opts?.id ?? 'main';
+    const world = createRootInstance({
+        id,
+        kind: 'canvas',
+        pausable: opts?.pausable ?? true,
+        adapter,
+        mounted,
+        stage: mounted.stage,
+    });
+    game.registerRoot(world);
+    return world;
+}
+/**
+ * Register a react world onto the Game shell (T6.2 slice 1) — the react
+ * analog of {@link registerThreeRoot}/{@link registerPixiRoot}. A react
+ * world has 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
+ * `registerPixiRoot`'s doc comment above) — `RootInstance.adapter` only
+ * needs `.id`, so this passes through with zero cast.
+ */
+export function registerReactRoot(game, adapter, mounted, container, opts) {
+    const world = createRootInstance({
+        id: opts?.id ?? 'main',
+        kind: 'dom',
+        pausable: opts?.pausable ?? true,
+        adapter,
+        mounted,
+        container,
+    });
+    game.registerRoot(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 createRootsGameRuntime(config);
+}
+// ---------------------------------------------------------------------------
+// Worlds path (T6.1 slice 1)
+// ---------------------------------------------------------------------------
+/** 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
+ *  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() { },
+    };
+}
+/** Mount one three `RootMountSpec` (canvas + renderer construction, per
+ *  D5 §1/§4, then `registerThreeRoot`). Split out of
+ *  `createRootsGameRuntime` purely to keep that function's own branching
+ *  simple — see `mountOnePixiRoot` for the canvas sibling. */
+async function mountOneThreeRoot(spec, ctx) {
+    const { game, canvas, w, h, dpr, isBottom, headless, 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 three 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,
+        assets,
+        headless,
+        game,
+    };
+    const mounted = await spec.adapter.mount(host);
+    registerThreeRoot(game, spec.adapter, mounted, { id: spec.id, pausable: spec.pausable });
+    return {
+        mountedEntry: { id: spec.id, kind: 'three', element: canvas, mounted, renderer },
+        routerEntry: { id: spec.id, zOrder: spec.zOrder ?? 0, canvas, hitTest: spec.hitTest },
+    };
+}
+/** Mount one canvas `RootMountSpec` (via its own `CanvasHostContext`, per D5
+ *  §1/§3/§4, then `registerPixiRoot`) — the pixi sibling of
+ *  `mountOneThreeRoot` above.
+ *
+ *  Unlike `mountOneThreeRoot`, 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 three, 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 three' buffer-only resize
+ *  did (never self-healing, by design — see above). */
+async function mountOnePixiRoot(spec, ctx) {
+    const { game, canvas, w, h, dpr, headless, isBottom } = ctx;
+    const pixiHost = {
+        canvas,
+        width: w,
+        height: h,
+        game,
+        headless,
+        dpr,
+        transparent: !isBottom,
+        preserveDrawingBuffer: true,
+    };
+    const mounted = await spec.adapter.mount(pixiHost);
+    registerPixiRoot(game, spec.adapter, mounted, {
+        id: spec.id,
+        pausable: spec.pausable,
+    });
+    return {
+        mountedEntry: {
+            id: spec.id,
+            kind: 'canvas',
+            element: canvas,
+            mounted,
+            renderer: undefined,
+        },
+        routerEntry: {
+            id: spec.id,
+            zOrder: spec.zOrder ?? 0,
+            canvas,
+            hitTest: spec.hitTest,
+        },
+    };
+}
+/**
+ * Mount one react `RootMountSpec` (T6.2 slice 1) — the react sibling of
+ * `mountOneThreeRoot`/`mountOnePixiRoot`. 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 `createRootsGameRuntime`'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 mountOneReactRoot(spec, game, 
+/** The ALREADY-created, already-stacked (position/z-index set, appended to
+ *  `container`) DOM-root layer for this world — see
+ *  `createRootsGameRuntime`'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 `RootInstance.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);
+    registerReactRoot(game, spec.adapter, mounted, layer, {
+        id: spec.id,
+        pausable: spec.pausable,
+    });
+    return {
+        mountedEntry: {
+            id: spec.id,
+            kind: 'dom',
+            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 three/canvas, a DOM-root `<div>` layer for react — stacked
+ * 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
+ * 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 `createRootsGameRuntime` 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 three world, else none" default-world rule the
+ * `GameSession.scene`/`.camera` getters alias (`Game.defaultRoot`): 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 installDefaultRootDevGlobals(game) {
+    if (!import.meta.env?.DEV)
+        return () => { };
+    const defaultMounted = game.defaultRoot.mounted;
+    if (defaultMounted.kind !== 'three')
+        return () => { };
+    const scene = defaultMounted.scene;
+    const w = window;
+    w['__vgaiScene'] = scene;
+    // An ACCESSOR, not a value read once: a world may replace its camera after
+    // mount (fiber's `set({ camera })` — drei's `makeDefault`, or a translated
+    // Godot world installing the camera its `.tscn` authors), and a snapshot
+    // here reads as authoritative to the probe that reaches for it while naming
+    // a camera the frame no longer uses. The retraction guard compares the
+    // GETTER's identity, which is the same "don't clobber a newer session"
+    // rule the value comparison was.
+    const readCamera = () => defaultMounted.camera;
+    Object.defineProperty(w, '__vgaiCamera', {
+        get: readCamera,
+        configurable: true,
+        enumerable: true,
+    });
+    return () => {
+        if (w['__vgaiScene'] === scene)
+            delete w['__vgaiScene'];
+        if (Object.getOwnPropertyDescriptor(w, '__vgaiCamera')?.get === readCamera)
+            delete w['__vgaiCamera'];
+    };
+}
+/**
+ * Mount + register every world spec, in ARRAY (declaration) order — split
+ * out of `createRootsGameRuntime` purely to keep that function's own
+ * cyclomatic complexity down (E4, same reason `mountOneThreeRoot`/
+ * `mountOnePixiRoot` are already split out). React roots contribute NO
+ * router entry ("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 `mountOneReactRoot`'s doc
+ * comment).
+ */
+async function mountAllRootSpecs(mountSpecs, bottomId, inputs) {
+    const { surfacesById, ...shared } = inputs;
+    const mountedEntries = [];
+    const routerEntries = [];
+    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);
+        const oneCtx = { ...shared, canvas, isBottom };
+        let mountedEntry;
+        let routerEntry;
+        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);
+        routerEntries.push(routerEntry);
+    }
+    return { mountedEntries, routerEntries };
+}
+/**
+ * G3/FT-11 — publish the render-control harness (`render-control.ts`) for a
+ * live session, returning its retraction (wired into the session's own
+ * `stop()`, same leave-nothing-live rule as the debug bridge's `uninstall()`
+ * in mount-manifest.ts — render-control has no uninstall surface of its own,
+ * a render page being a single-load host by design, so the retraction is
+ * the publication's inverse). Split out of `createRootsGameRuntime` purely
+ * to keep that function's cyclomatic complexity down (the same reason
+ * `mountAllRootSpecs`/`installDefaultRootDevGlobals` are split out).
+ *
+ * The clock is a documented no-op: a manifest-mounted game has no global
+ * cinematic AnimationClock to seek (a cinematic fixture that HAS one
+ * installs its own harness with the real clock, e.g.
+ * packages/engine/e2e/render-cinematic/main.ts) — the meaningful advance
+ * path for a plain game is `simulateSubsteps` (I5 `--simulate`), which
+ * drives `game.runFrame`.
+ */
+function installSessionRenderHarness(game, location, targetOverride) {
+    const target = targetOverride ??
+        (typeof window !== 'undefined' ? window : undefined);
+    if (target === undefined)
+        return undefined;
+    installRenderControlHarness({
+        game,
+        clock: {
+            seek() {
+                /* no global cinematic clock on a manifest-mounted game — see above */
+            },
+            seekFrame() {
+                /* intentional no-op, as seek() */
+            },
+        },
+        readiness: {
+            // Mount is complete by the time this harness exists (the install site
+            // in `createRootsGameRuntime` is after `mountAllRootSpecs`
+            // resolved) — the hook resolving immediately IS the readiness
+            // statement, not an assumption.
+            scene() { },
+        },
+        location,
+        target,
+    });
+    return () => {
+        delete target['__vgaiRender'];
+    };
+}
+async function createRootsGameRuntime(config) {
+    const { container, roots: specs, width, height, headless = false, seed, playtest } = 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 — "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). ---
+    // Dev layers sit TOPMOST, above every non-dev root, whatever zOrder either
+    // declares: a dev GUI the game can paint over is not a dev GUI. Expressed as
+    // two independent `stackOrder` passes concatenated rather than a magic
+    // zOrder value, so `stackOrder`'s one rule (ascending zOrder, ties -> array
+    // order) still governs WITHIN each band and nothing has to reason about what
+    // number is "high enough".
+    const claimEntries = mountSpecs.map((spec) => ({
+        id: spec.id,
+        zOrder: spec.zOrder ?? 0,
+        hitTest: spec.hitTest,
+        dev: spec.dev === true,
+    }));
+    const stacked = [
+        ...stackOrder(claimEntries.filter((e) => !e.dev)),
+        ...stackOrder(claimEntries.filter((e) => e.dev)),
+    ];
+    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) === 'dom';
+        const surface = document.createElement(isReact ? 'div' : 'canvas');
+        surface.dataset['vgaiRootSurface'] = 'true';
+        // The capture's marker (`composite-screenshot.ts` reads exactly this
+        // attribute): a dev layer is excluded from a play capture unless the
+        // capture asks for it, because a contaminated "does the game look right"
+        // frame is worthless.
+        if (entry.dev)
+            surface.dataset['vgaiDevLayer'] = 'true';
+        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`, `mountOneThreeRoot` 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 `mountOneThreeRoot`) 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();
+    // Every manifest/host-mounted game is a deterministic-capture candidate —
+    // the render-control seam (`?vgai-render=1`, render-control.ts) is wired
+    // HERE, at the one host every boot path shares (mountGameFromManifest,
+    // mountManifestRoots, and direct createGameRuntime callers all reach this
+    // function), instead of asking every project's entry page to install it
+    // the way the e2e fixtures do. Production-protected twice over:
+    // `isRenderModeRequested` gates on the query param, and
+    // `installRenderControlHarness` re-checks it internally (its AC 4), so a
+    // normal gameplay page sees zero change.
+    const renderModeLocation = config.renderControl?.location ?? (typeof window !== 'undefined' ? window.location : undefined);
+    const renderMode = renderModeLocation !== undefined && isRenderModeRequested(renderModeLocation);
+    let started = false;
+    const loop = createGameLoop({
+        fixedTimestep: 1 / 60,
+        maxSubSteps: 8,
+        // Render mode runs the loop in EXTERNAL-DRIVE mode (game-loop.ts, I2):
+        // no RAF is ever armed, so nothing advances gameplay between the capture
+        // 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:
+        // `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.
+        update: (dt) => {
+            if (started)
+                game.runFrame(dt, { skipRenderPhases: true });
+        },
+        render: (alpha, displayDt) => {
+            if (started)
+                game.runRenderFrame(alpha, displayDt);
+        },
+    });
+    const game = createGame({ loop, assets, seed, playtest });
+    // --- Mount + register every world, in ARRAY (declaration) order. ---
+    // Split out into its own top-level function purely to keep
+    // `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,
+    });
+    // --- 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): `mountGameFromManifest`/
+    // `mountManifestRoots` 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 = installDefaultRootDevGlobals(game);
+    // G3/FT-11 — publish `window.__vgaiRender` for the deterministic capture
+    // host. Installed at the TAIL of the mount (same position as
+    // mount-manifest.ts's debug bridge): every world's `mount()`/`setup()` has
+    // resolved by now, so the harness's `scene` readiness hook reporting ready
+    // is truthful. See `installSessionRenderHarness` below.
+    const retractRenderHarness = renderMode && renderModeLocation !== undefined
+        ? installSessionRenderHarness(game, renderModeLocation, config.renderControl?.target)
+        : undefined;
+    function fullCleanup() {
+        loop.stop();
+        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 */
+            }
+        }
+        game.dispose();
+        retractDevGlobals();
+        retractRenderHarness?.();
+    }
+    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, pixelRatio) {
+            const safeWidth = Math.max(1, rw);
+            const safeHeight = Math.max(1, rh);
+            for (const entry of mountedEntries) {
+                // W2c device preview: re-pin DPR before setSize so the drawing
+                // buffer (and the first-party composer, whose `mounted.resize` reads
+                // `getDrawingBufferSize`) picks it up in this same pass. Pixi/react
+                // worlds have no `entry.renderer` and keep their own resolution.
+                if (pixelRatio !== undefined)
+                    entry.renderer?.setPixelRatio(pixelRatio);
+                entry.renderer?.setSize(safeWidth, safeHeight, false);
+                entry.mounted.resize?.(safeWidth, safeHeight);
+            }
+        },
+        // `GameSession.scene`/`.camera`/`.mounted` alias `Game.defaultRoot` (T6.1
+        // slice 1's "first three 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
+        // three — real per-world surface routing for that case is T7.6's).
+        get scene() {
+            const m = game.defaultRoot.mounted;
+            return (m.kind === 'three' ? m.scene : undefined);
+        },
+        get camera() {
+            const m = game.defaultRoot.mounted;
+            return (m.kind === 'three' ? m.camera : undefined);
+        },
+        get mounted() {
+            return game.defaultRoot.mounted;
+        },
+        game,
+    };
+}