@vgai/engine 0.2.0 → 0.3.0

package/dist/runtime/game.js

@@ -0,0 +1,569 @@
+/**
+ * Game root — T7.1 slice 1 ("introduce Game internally") + slice 2 ("world
+ * registry + ordered frame algorithm"), extended in T7.3 slice 1 with real
+ * `'pixijs'`-kind `WorldInstance` support (`stage`/`physics2d`/`collisions2d`,
+ * a real `pixiRoot()`) so `world2d/pixi-game-adapter.ts` can register its
+ * world onto a real `Game` instead of driving its own loop, and in T7.3
+ * slice 2 with a construction-time stage check (symmetric with the
+ * threejs/scene check) and the two-world (threejs + pixijs) proof
+ * (`test/game-three-plus-pixi.test.ts`). T6.2 slice 1 adds real `'react'`-kind
+ * `WorldInstance` support (`container`, a real `reactRoot()`) — the DOM-root
+ * world surface `runtime/create-runtime.ts`'s worlds path now mounts (see
+ * `docs/REACT-WORLD-DESIGN.md` §1.B); react worlds host no `ComponentManager`
+ * (D8 — components attaching to a react-kind manager already throw,
+ * `ecs/component-manager.ts`), so `physics`/`collisions`/`camera`/`frame`
+ * stay `undefined` for them exactly like an opaque/foreign mount.
+ *
+ * See `docs/GAME-ROOT-DESIGN.md` (D6), particularly §4 (the frame algorithm)
+ * and §8 stage 2, for the full target shape. This file holds the Game/
+ * WorldInstance shell, the NEW game-scoped `SystemRunner`, and the
+ * host-facing `runFrame` frame executor. The public surface is NOT frozen
+ * yet — do not add these exports to a barrel/index; only the in-scope
+ * runtime/adapter files import this module directly. The `gpu` per-world
+ * cache is the one remaining slice-1 omission.
+ */
+import { formatAudioGateMessage, formatLoopGateMessage } from '../adapter/loop-gate-report';
+import { createSystemRunner } from '../core/system-runner';
+import { PHASE_ORDER, SystemPhase } from '../core/types';
+import { createStateBridge } from './state-bridge';
+/**
+ * Build a `WorldInstance` whose kind-narrowed accessors throw descriptively
+ * on kind mismatch (GAME-ROOT-DESIGN §3). This is the one place that builds
+ * `threeRoot`/`pixiRoot`, so every world (however it's constructed, in this
+ * slice or later ones) gets identical throw behavior.
+ */
+export function createWorldInstance(init) {
+    const { id, kind, pausable = true, adapter, mounted, scene, stage, container, physics, collisions, physics2d, collisions2d, camera, frame, } = init;
+    // A threejs world with no scene has nothing for `threeRoot()` to return —
+    // fail loudly HERE, at construction, rather than letting `threeRoot()`
+    // throw its generic "not a threejs world" message later for a world whose
+    // kind IS threejs (checklist item 5; a misleading error for this case).
+    if (kind === 'threejs' && !scene) {
+        throw new Error(`WorldInstance "${id}" (kind: threejs): a threejs world requires a scene — ` +
+            'pass `scene` in WorldInstanceInit.');
+    }
+    // Symmetric check for pixijs (T7.3 slice 2) — a pixijs world with no stage
+    // has nothing for `pixiRoot()` to return; fail loudly here, at
+    // construction, same as the threejs/scene check above.
+    if (kind === 'pixijs' && !stage) {
+        throw new Error(`WorldInstance "${id}" (kind: pixijs): a pixijs world requires a stage — ` +
+            'pass `stage` in WorldInstanceInit.');
+    }
+    // Symmetric check for react (T6.2 slice 1, docs/REACT-WORLD-DESIGN.md
+    // §1.B) — a react world with no container has nothing for `reactRoot()`
+    // to return; fail loudly here, at construction, same as the two checks
+    // above.
+    if (kind === 'react' && !container) {
+        throw new Error(`WorldInstance "${id}" (kind: react): a react world requires a container — ` +
+            'pass `container` in WorldInstanceInit.');
+    }
+    // Disposed-world guard (GAME-ROOT-DESIGN §8 stage 3 / T7.1 slice 3). There
+    // is no `unregisterWorld` (decision 4 — worlds are manifest-declared; a
+    // whole Game is disposed, not one world out of its registry), so a caller
+    // that disposes ONE world's `mounted` directly (e.g. ending a sub-session)
+    // leaves that `WorldInstance` sitting in `Game.worlds` — and `runFrame`
+    // would otherwise keep invoking its (now-torn-down) frame hooks every
+    // subsequent frame. `MountedGame` has no public "am I disposed" flag to
+    // read, so this wraps `mounted.dispose` in place (mutating the SAME mount
+    // object every holder of `mounted` shares — calling `mounted.dispose()`
+    // directly, exactly like calling `world.mounted.dispose()`, trips this)
+    // to flip a private flag, and wraps the frame hooks so they silently no-op
+    // once that flag is set. `runFrame` itself needs no knowledge of disposal
+    // — a disposed world is skipped by construction from the next call
+    // onward. (The opaque-world `mounted.update` fallback path is unaffected
+    // by this guard — no opaque-mount two-world scenario exists yet to need it.)
+    let disposed = false;
+    const originalDispose = mounted.dispose.bind(mounted);
+    mounted.dispose = () => {
+        disposed = true;
+        originalDispose();
+    };
+    const guardedFrame = frame
+        ? {
+            runPhase(phase, dt) {
+                if (disposed)
+                    return;
+                frame.runPhase(phase, dt);
+            },
+            endFrame() {
+                if (disposed)
+                    return;
+                frame.endFrame?.();
+            },
+        }
+        : undefined;
+    return {
+        id,
+        kind,
+        pausable,
+        adapter,
+        mounted,
+        physics,
+        collisions,
+        physics2d,
+        collisions2d,
+        camera,
+        frame: guardedFrame,
+        threeRoot() {
+            if (kind !== 'threejs' || !scene) {
+                throw new Error(`WorldInstance "${id}" (kind: ${kind}): threeRoot() requested but this world is not ` +
+                    'a threejs world');
+            }
+            return scene;
+        },
+        pixiRoot() {
+            // The `!stage` branch a pixijs world could hit here is now unreachable
+            // (T7.3 slice 2): construction above throws for `kind === 'pixijs'`
+            // with no `stage`, symmetric with `threeRoot()`'s `scene` guard.
+            if (kind !== 'pixijs' || !stage) {
+                throw new Error(`WorldInstance "${id}" (kind: ${kind}): pixiRoot() requested but this world is not ` +
+                    'a pixijs world');
+            }
+            return stage;
+        },
+        reactRoot() {
+            // The `!container` branch a react world could hit here is now
+            // unreachable (T6.2 slice 1): construction above throws for
+            // `kind === 'react'` with no `container`, symmetric with
+            // `threeRoot()`/`pixiRoot()`'s guards.
+            if (kind !== 'react' || !container) {
+                throw new Error(`WorldInstance "${id}" (kind: ${kind}): reactRoot() requested but this world is not ` +
+                    'a react world');
+            }
+            return container;
+        },
+    };
+}
+/**
+ * Type guard for whether a `MountedGame` is a first-party
+ * `VgaiSceneGameAdapter` mount (has a live `GameContext` at `.ctx`). Used to
+ * decide whether a world's `physics`/`collisions`/`camera` (and, on `Game`,
+ * `components`/`input`/`audio`) can be populated from it — an external
+ * adapter's mount has none of these first-party handles.
+ *
+ * Checks the `firstParty: true` brand (checklist item 1), NOT `'ctx' in
+ * mounted` — world2d's `MountedGame2D` (`world2d/pixi-game-adapter.ts`) also
+ * has a `ctx` key (a `World2DContext`, unrelated to `GameContext`), so a
+ * structural `'ctx' in mounted` check would misfire once T7.3 registers 2D
+ * worlds onto the same `Game`. The probe is a plain property read, not an
+ * `instanceof`/value import of `vgai-scene-game-adapter.ts` — the
+ * `VgaiMountedGame` import above stays type-only.
+ */
+export function isFirstPartyMounted(mounted) {
+    return mounted.firstParty === true;
+}
+function describeMismatch(handle, world) {
+    return (`Game.${handle}: default world "${world.id}" (kind: ${world.kind}) is not a first-party ` +
+        "mount — hoisting these to true Game ownership is a later slice's work; available only " +
+        'via a first-party default world today');
+}
+/**
+ * Construct the (host-internal) Game shell. Callers: `createGameRuntime`
+ * builds this BEFORE mounting its one adapter, then registers the default
+ * threejs world once mount resolves (see `registerDefaultThreeWorld` in
+ * `create-runtime.ts`).
+ */
+export function createGame(opts) {
+    const worlds = [];
+    const systems = createSystemRunner();
+    const stateBridge = createStateBridge();
+    function requireDefaultWorld() {
+        if (worlds.length === 0) {
+            throw new Error('Game.defaultWorld: no worlds registered yet');
+        }
+        return worlds.find((w) => w.kind === 'threejs') ?? worlds[0];
+    }
+    function requireFirstPartyCtx(handle) {
+        const world = requireDefaultWorld();
+        if (!isFirstPartyMounted(world.mounted)) {
+            throw new Error(describeMismatch(handle, world));
+        }
+        return world.mounted.ctx;
+    }
+    // --- Game.systemAdapters aggregation (§7.1-3, probe1) --------------------
+    // Warn-once-per-colliding-key state, scoped to this Game instance (a fresh
+    // Game gets a fresh warn history) — deliberately NOT reset by anything
+    // short of a new `createGame` call, matching `reportedGateShortfalls`
+    // above's "once per game instance" idiom.
+    const warnedSystemAdapterKeys = new Set();
+    // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: one cohesive merge-with-collision-report walk (per-world × per-key); splitting the collision-warn branch out would obscure that it's part of the same pass, not reduce real complexity
+    function computeSystemAdapters() {
+        const result = {};
+        const ownerWorldId = new Map();
+        for (const world of worlds) {
+            const adapters = world.mounted.systems;
+            if (!adapters)
+                continue;
+            for (const key of Object.keys(adapters)) {
+                if (adapters[key] === undefined)
+                    continue;
+                const existingOwner = ownerWorldId.get(key);
+                if (existingOwner !== undefined) {
+                    if (!warnedSystemAdapterKeys.has(key)) {
+                        warnedSystemAdapterKeys.add(key);
+                        // biome-ignore lint/suspicious/noConsole: structured, greppable — mirrors this file's own reportGateShortfallOnce's deliberate direct console.warn just above
+                        console.warn(`[game] systemAdapters: "${key}" is registered by both world "${existingOwner}" and ` +
+                            `world "${world.id}" — the FIRST registration ("${existingOwner}") wins; the later ` +
+                            'one is shadowed (docs/GAME-ROOT-DESIGN.md §3: game-scoped system adapters).');
+                    }
+                    continue;
+                }
+                // biome-ignore lint/suspicious/noExplicitAny: SystemAdapters is a plain optional-field record; the per-key copy is correct by construction (same key on both sides), just not expressible without a cast
+                result[key] = adapters[key];
+                ownerWorldId.set(key, world.id);
+            }
+        }
+        return result;
+    }
+    // --- D10/T7.6 play-state (Game.play) -------------------------------------
+    let paused = false;
+    // Dedupe loop-gate/audio-gate shortfall warnings to ONCE per (world, kind)
+    // — `pause()` fans out over every world every call; without this a
+    // multi-second play session would re-log the same "can't gate" shortfall
+    // every time the user hits Pause.
+    const reportedGateShortfalls = new Set();
+    function reportGateShortfallOnce(kind, worldId, reason) {
+        const key = `${kind}:${worldId}`;
+        if (reportedGateShortfalls.has(key))
+            return;
+        reportedGateShortfalls.add(key);
+        const message = kind === 'loop'
+            ? formatLoopGateMessage({ worldId, reason })
+            : formatAudioGateMessage({ worldId, reason });
+        // Other native `console.warn`/`console.error` call sites in this file are
+        // unsuppressed and already counted in the lint baseline (see `runFrame`'s
+        // impl below); this one is a NEW site, so it's suppressed to keep this
+        // task's diff at zero NEW warnings (same reasoning as `overlay-report.ts`'s
+        // identical suppression).
+        // biome-ignore lint/suspicious/noConsole: see comment above
+        console.warn(message);
+    }
+    /** Fan out a loop-gate (self-driven worlds) + audio-gate call over every
+     *  `pausable` world, reporting honestly (once) wherever the capability is
+     *  absent — shared by `pause()`/`resume()` below (same fan-out, opposite
+     *  boolean). */
+    // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: fans out TWO independent capability gates (loop, audio) with the same "call it, else report once" shape per world — splitting the two gates into separate loops would duplicate the fan-out, not reduce real complexity
+    function setWorldGates(next) {
+        for (const world of worlds) {
+            if (!world.pausable)
+                continue; // pausable:false worlds are untouched by design
+            if (world.mounted.drivesOwnLoop) {
+                if (world.mounted.setPaused) {
+                    world.mounted.setPaused(next);
+                }
+                else if (next) {
+                    reportGateShortfallOnce('loop', world.id, 'self-driven world, adapter declares no setPaused capability');
+                }
+            }
+            const audio = world.mounted.systems?.audio;
+            if (audio) {
+                audio.setMuted(next);
+            }
+            else if (next) {
+                reportGateShortfallOnce('audio', world.id, 'no SystemAdapters.audio on this world');
+            }
+        }
+    }
+    // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: the frame algorithm (GAME-ROOT-DESIGN §4, now with D10's per-world pause gate + the onlyFrozen step()-only mode) is one cohesive nested loop over phases/worlds — splitting it would obscure the ordering contract documented on GameInternal.runFrame
+    function runFrameImpl(dt, frameOpts) {
+        const ignorePause = frameOpts?.ignorePause ?? false;
+        // `onlyFrozen` is internal-only (not part of the public `GameInternal.runFrame`
+        // signature — no external caller sets it) — `Game.play.step()` below is the
+        // one and only caller. It ticks EXACTLY the currently-frozen set (host-driven,
+        // `pausable`, and `paused`) through every phase + `endFrame`, with the REAL
+        // `dt` (not the render-phase's forced `0`), and touches no other world at all
+        // — §7.1-2 fix, probe4: the previous `ignorePause` full-frame re-run ticked
+        // EVERY host-driven world, double-ticking every already-running
+        // `pausable: false` world (D10's ordinary loop never stops ticking them).
+        const onlyFrozen = frameOpts?.onlyFrozen ?? false;
+        // Checklist item 7: snapshot the world count ONCE at entry and iterate
+        // by index in both loops below. A world registered mid-frame (e.g. from
+        // a game-scoped system's side effect) joins at the NEXT `runFrame` call,
+        // not this one — `for (const world of worlds)` would otherwise pick up
+        // a world pushed during this very frame. This also drops the two
+        // per-phase `for...of` iterator allocations.
+        const n = worlds.length;
+        // §7.1-11 fix (probe5): `stateBridge.bump()` must fire iff at least one
+        // world actually advanced this call — not unconditionally. `advanced`
+        // covers rule (a) below (host-driven worlds this call actually ticked);
+        // rule (b): a self-driven world that is RUNNING — which is every
+        // self-driven world while not paused, and, while paused, the ones the
+        // gate can't reach (`pausable: false`, or no `setPaused` capability) —
+        // checked once, up front, over the same `worlds` array (no extra
+        // allocation, matching every other loop here). Rule (b) is skipped in
+        // `onlyFrozen` mode: a `step()` call bumps iff it ticked a frozen world
+        // — self-driven notifications belong to the loop's own `runFrame`s.
+        let advanced = false;
+        if (!onlyFrozen) {
+            for (let i = 0; i < n; i++) {
+                const world = worlds[i];
+                if (!world.mounted.drivesOwnLoop)
+                    continue;
+                if (!paused || !world.pausable || !world.mounted.setPaused) {
+                    advanced = true;
+                    break;
+                }
+            }
+        }
+        if (onlyFrozen) {
+            // step(): the frozen set is host-driven + pausable + currently paused.
+            // While NOT paused this set is empty by construction, so this whole
+            // branch is a natural no-op — `Game.play.step()`'s "no-op while
+            // running" behavior falls straight out of this, no separate guard
+            // needed.
+            for (const phase of PHASE_ORDER) {
+                for (let i = 0; i < n; i++) {
+                    const world = worlds[i];
+                    if (world.mounted.drivesOwnLoop)
+                        continue;
+                    if (!(paused && world.pausable))
+                        continue; // only the frozen set
+                    try {
+                        world.frame?.runPhase(phase, dt);
+                    }
+                    catch (err) {
+                        console.error(`[game] world "${world.id}" (kind: ${world.kind}) runPhase("${phase}") threw ` +
+                            '(step()):', err);
+                    }
+                }
+            }
+            for (let i = 0; i < n; i++) {
+                const world = worlds[i];
+                if (world.mounted.drivesOwnLoop)
+                    continue;
+                if (!(paused && world.pausable))
+                    continue;
+                advanced = true;
+                if (world.frame) {
+                    try {
+                        world.frame.endFrame?.();
+                    }
+                    catch (err) {
+                        console.error(`[game] world "${world.id}" (kind: ${world.kind}) endFrame() threw (step()):`, err);
+                    }
+                }
+                else {
+                    try {
+                        world.mounted.update?.(dt);
+                    }
+                    catch (err) {
+                        console.error(`[game] world "${world.id}" (kind: ${world.kind}) update() threw (step()):`, err);
+                    }
+                }
+            }
+        }
+        else {
+            for (const phase of PHASE_ORDER) {
+                systems.runPhase(phase, dt);
+                for (let i = 0; i < n; i++) {
+                    const world = worlds[i];
+                    if (world.mounted.drivesOwnLoop)
+                        continue;
+                    // D10/T7.6: a `pausable` world under an active (non-ignored) pause
+                    // skips every phase except `render` — its render still runs, every
+                    // substep, but with `dt` forced to `0` (deterministic: no
+                    // time-based render effect silently keeps animating a "frozen"
+                    // scene). A `pausable: false` world (or any world while
+                    // `ignorePause`) is unaffected.
+                    const frozen = !ignorePause && paused && world.pausable;
+                    if (frozen && phase !== SystemPhase.RENDER)
+                        continue;
+                    const phaseDt = frozen ? 0 : dt;
+                    // Checklist item 2: isolate each world's per-phase work — one
+                    // world's `runPhase` throwing must not starve sibling worlds still
+                    // due this phase, nor abort the frame. Mirrors `runOne`'s style in
+                    // `core/system-runner.ts` (loud console.error, never swallowed).
+                    try {
+                        world.frame?.runPhase(phase, phaseDt);
+                    }
+                    catch (err) {
+                        console.error(`[game] world "${world.id}" (kind: ${world.kind}) runPhase("${phase}") threw:`, err);
+                    }
+                }
+            }
+            for (let i = 0; i < n; i++) {
+                const world = worlds[i];
+                if (world.mounted.drivesOwnLoop)
+                    continue;
+                // A fully-frozen world gets no `endFrame`/opaque-`update` call either —
+                // there is nothing to "end the frame" of when nothing ran this substep.
+                const frozen = !ignorePause && paused && world.pausable;
+                if (frozen)
+                    continue;
+                advanced = true;
+                if (world.frame) {
+                    try {
+                        world.frame.endFrame?.();
+                    }
+                    catch (err) {
+                        console.error(`[game] world "${world.id}" (kind: ${world.kind}) endFrame() threw:`, err);
+                    }
+                }
+                else {
+                    // Checklist item 2: same isolation for the opaque-world fallback —
+                    // one foreign mount's `update` throwing must not starve its
+                    // siblings' `endFrame`/`update` calls this same loop.
+                    try {
+                        world.mounted.update?.(dt);
+                    }
+                    catch (err) {
+                        console.error(`[game] world "${world.id}" (kind: ${world.kind}) update() threw:`, err);
+                    }
+                }
+            }
+        }
+        // T7.4 slice 1 (REACT-STATE-BRIDGE.md §2): bump + notify LAST, after
+        // every phase of every world and every world's endFrame/update above —
+        // subscribers must only ever observe post-frame state. Bumped at most
+        // once per completed `runFrame`/`step()` call, never per phase/world —
+        // and, per §7.1-11's fix, only when `advanced` (see above) is true: a
+        // fully-gated paused game produces no notifications at all.
+        if (advanced)
+            stateBridge.bump();
+    }
+    return {
+        loop: opts.loop,
+        assets: opts.assets,
+        systems,
+        get worlds() {
+            return worlds;
+        },
+        world(id) {
+            return worlds.find((w) => w.id === id) ?? null;
+        },
+        get defaultWorld() {
+            return requireDefaultWorld();
+        },
+        get systemAdapters() {
+            return computeSystemAdapters();
+        },
+        get components() {
+            return requireFirstPartyCtx('components').components;
+        },
+        get input() {
+            return requireFirstPartyCtx('input').input;
+        },
+        get audio() {
+            return requireFirstPartyCtx('audio').audio;
+        },
+        state: stateBridge,
+        play: {
+            get paused() {
+                return paused;
+            },
+            pause() {
+                if (paused)
+                    return;
+                paused = true;
+                setWorldGates(true);
+            },
+            resume() {
+                if (!paused)
+                    return;
+                paused = false;
+                setWorldGates(false);
+            },
+            step(dt = 1 / 60) {
+                // Self-driven pausable worlds advance via their adapter's `step()`
+                // capability — but only the ones that are actually FROZEN: the game
+                // must be paused, and the world must have been gate-able in the
+                // first place (`setPaused` present — a world the gate couldn't reach
+                // never stopped, so "stepping" it would double-tick a still-running
+                // loop, the same §7.1-2 class as the host-driven fix below). While
+                // not paused, nothing here runs — step() is a whole-call no-op.
+                if (paused) {
+                    for (const world of worlds) {
+                        if (!world.pausable || !world.mounted.drivesOwnLoop)
+                            continue;
+                        if (!world.mounted.setPaused)
+                            continue; // never gated — still running
+                        if (world.mounted.step) {
+                            world.mounted.step();
+                        }
+                        else {
+                            reportGateShortfallOnce('loop', world.id, 'self-driven world, adapter declares no step capability');
+                        }
+                    }
+                }
+                // §7.1-2 fix (probe4): tick EXACTLY the frozen (host-driven, pausable,
+                // paused) set — not `{ ignorePause: true }`, which re-ran a FULL
+                // extra frame for every host-driven world (including already-running
+                // `pausable: false` ones — a double-tick, since D10's ordinary loop
+                // never stops ticking them). See `runFrameImpl`'s `onlyFrozen` mode.
+                runFrameImpl(dt, { onlyFrozen: true });
+            },
+        },
+        queryByComponent(cls, opts) {
+            // Checklist item 8a: a `worldId` naming a world that doesn't exist is a
+            // caller error (typo'd id, wrong manifest) — degrade loudly, matching
+            // repo habit, rather than silently returning `[]`. A worldId that DOES
+            // exist but isn't first-party legitimately answers "no components"
+            // below (the loop's `!isFirstPartyMounted` `continue`), which stays
+            // silent — that's a real, not a mistaken, empty result.
+            if (opts?.worldId !== undefined && !worlds.some((w) => w.id === opts.worldId)) {
+                throw new Error(`Game.queryByComponent: unknown worldId "${opts.worldId}"`);
+            }
+            const result = [];
+            for (const world of worlds) {
+                if (!isFirstPartyMounted(world.mounted))
+                    continue;
+                if (opts?.worldId !== undefined && world.id !== opts.worldId)
+                    continue;
+                if (opts?.kind !== undefined && world.kind !== opts.kind)
+                    continue;
+                // Checklist item 8b: a plain for-loop push instead of
+                // `result.push(...arr)` — spread-as-arguments can hit engine/runtime
+                // argument-count limits once a world's instance count gets large.
+                const instances = world.mounted.ctx.components.queryByComponent(cls);
+                for (const inst of instances)
+                    result.push(inst);
+            }
+            return result;
+        },
+        registerWorld(world) {
+            if (worlds.some((w) => w.id === world.id)) {
+                throw new Error(`Game.registerWorld: duplicate world id "${world.id}"`);
+            }
+            // Checklist item 6: the SAME `mounted` object registered under two
+            // world ids would be double-ticked by `runFrame` (its `frame.runPhase`/
+            // `endFrame` called once per registration) and double-dispose-wrapped
+            // (`createWorldInstance` wraps `mounted.dispose` in place — a second
+            // wrap would flip `disposed` and call through on ITS OWN wrapped
+            // `originalDispose`, which is harmless today only by accident of
+            // `VgaiSceneGameAdapter.dispose` being idempotent; a foreign adapter
+            // has no such guarantee). Reject it outright instead.
+            if (worlds.some((w) => w.mounted === world.mounted)) {
+                throw new Error(`Game.registerWorld: world "${world.id}" shares its \`mounted\` object with an ` +
+                    `already-registered world ("${worlds.find((w) => w.mounted === world.mounted).id}") — ` +
+                    'the same mount cannot be registered twice.');
+            }
+            worlds.push(world);
+            // T7.4 slice 2 (REACT-STATE-BRIDGE.md §4): a NON-first-party mount
+            // (an ingested/foreign world — first-party mounts are exempt, they're
+            // observed via `Game.state`/`useGameState` instead) with no `observe`
+            // has no state bridge at all — react HUDs cannot subscribe to it, and
+            // silently returning `undefined` forever would hide that. Report ONCE
+            // per mount, at registration time, matching this file's existing
+            // `[game] world "<id>" (kind: <kind>) ...` console idiom (see
+            // `runFrame` below).
+            //
+            // §7.1-15: a `kind: 'react'` world is ALSO exempt — it has no `observe`
+            // BY DESIGN (D8/REACT-WORLD-DESIGN.md: a react world's own mounted tree
+            // reads state via `Game.state`/`useGameState`, the SAME first-party
+            // bridge a threejs/pixijs world's HUD uses, never `WorldStateObserver`
+            // — that hook is scoped to the ingested/foreign-world case). Without
+            // this exemption every production react world logged a false-positive
+            // "no state bridge" warning at registration (probe: every real react
+            // world mount), eroding the signal for a genuinely un-observable
+            // ingested world.
+            if (!isFirstPartyMounted(world.mounted) && world.kind !== 'react' && !world.mounted.observe) {
+                console.warn(`[game] world "${world.id}" (kind: ${world.kind}, adapter: "${world.adapter.id}"): ` +
+                    'no state bridge — this mounted game has no `observe` (WorldStateObserver); ' +
+                    'react HUDs/useWorldObservation cannot subscribe to its state (docs/REACT-STATE-BRIDGE.md §4).');
+            }
+        },
+        runFrame(dt, frameOpts) {
+            runFrameImpl(dt, frameOpts);
+        },
+    };
+}

package/dist/runtime/input-router.d.ts

@@ -0,0 +1,78 @@
+/**
+ * The delegating input router (COMPOSITION-DESIGN.md D5 §2a) —
+ * `createGameRuntime`'s worlds path (T6.1 slice 1,
+ * docs/MULTI-WORLD-DESIGN.md §1.C) uses this to route pointer input across
+ * N stacked world canvases with exactly ONE root listener.
+ *
+ * Split into two layers so the decision logic is unit-testable with plain
+ * fake worlds — no real DOM/canvas needed:
+ *
+ *  - `stackOrder` / `resolveClaimingWorld`: pure functions over
+ *    `{id, zOrder, hitTest?}` — "who claims this point".
+ *  - `applyPointerEventsStacking` / `createInputRouter`: the DOM wiring —
+ *    sets `pointer-events` CSS per D5 §2a and forwards a claimed event to
+ *    the claiming world's own canvas.
+ *
+ * Per-event fall-through (D5 §2b — the sanctioned mechanism for an
+ * authoring surface's own interior drag affordances, e.g. the world2d
+ * editor's gizmos) is explicitly NOT this file's job (MULTI-WORLD-DESIGN.md
+ * task 4) — it stays inside whatever authoring surface needs it.
+ */
+/** The pure decision inputs — no DOM. */
+export interface ClaimEntry {
+    readonly id: string;
+    readonly zOrder: number;
+    /**
+     * Optional claim predicate over a point RELATIVE TO THE CONTAINER. Absent
+     * means: "this world claims only if it is the bottom (lowest zOrder)
+     * world" — D5 §2a's stated default ("transparent upper worlds do not
+     * claim, the bottom world claims everything").
+     */
+    readonly hitTest?: ((x: number, y: number) => boolean) | undefined;
+}
+/** The DOM-wiring inputs — one real canvas per world. */
+export interface RouterWorldEntry extends ClaimEntry {
+    readonly canvas: HTMLCanvasElement;
+}
+/**
+ * Bottom-to-top paint order: ascending `zOrder`, ties -> original array
+ * order — the SAME rule `manifest/load.ts`'s `loadGameManifest` sorts
+ * worlds by, so a world's DOM stacking position always matches its
+ * manifest-resolved zOrder. The last element is the topmost (visually on
+ * top / highest z-index).
+ */
+export declare function stackOrder<T extends ClaimEntry>(entries: readonly T[]): T[];
+/**
+ * Resolve which world's id claims a container-relative point `(x, y)` — D5
+ * §2a: walk top-down (topmost first); the first world whose `hitTest`
+ * returns true wins ("topmost-claim wins"). A world with no `hitTest` never
+ * claims UNLESS it is the bottom-most world, which claims unconditionally
+ * (or via its own `hitTest`, if it declares one) — "no-claim falls to
+ * bottom". Returns `null` only when `entries` is empty.
+ */
+export declare function resolveClaimingWorld(entries: readonly ClaimEntry[], x: number, y: number): string | null;
+/**
+ * Sets `canvas.style.pointerEvents` per D5 §1/§2a: the bottom (lowest
+ * zOrder) world's canvas is `'auto'` (real user input DOM-hit-tests it by
+ * default); every canvas above it is `'none'` (real user input never
+ * DOM-hit-tests it — the router's JS-level `hitTest` is what still lets it
+ * claim a point via `createInputRouter`'s forwarding).
+ */
+export declare function applyPointerEventsStacking(entries: readonly RouterWorldEntry[]): void;
+export interface InputRouterHandle {
+    /** Resolve which world claims a container-relative point right now — the
+     *  pure decision, exposed for callers/tests that don't want to simulate a
+     *  real DOM event. */
+    resolveClaim(x: number, y: number): string | null;
+    /** Detach the container listener(s). Idempotent. */
+    dispose(): void;
+}
+/**
+ * Wire the delegating router onto `container` for `entries` (D5 §2a): apply
+ * the pointer-events stacking, then attach ONE capture-phase listener per
+ * routed event type that resolves the claiming world and forwards the event
+ * to ITS canvas when that world isn't already the natural DOM target (the
+ * bottom world, whose canvas is the only one with `pointer-events:auto`).
+ */
+export declare function createInputRouter(container: HTMLElement, entries: readonly RouterWorldEntry[]): InputRouterHandle;
+//# sourceMappingURL=input-router.d.ts.map

package/dist/runtime/input-router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"input-router.d.ts","sourceRoot":"","sources":["../../src/runtime/input-router.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,yCAAyC;AACzC,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,GAAG,SAAS,CAAC;CACpE;AAED,yDAAyD;AACzD,MAAM,WAAW,gBAAiB,SAAQ,UAAU;IAClD,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;CACpC;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,UAAU,EAAE,OAAO,EAAE,SAAS,CAAC,EAAE,GAAG,CAAC,EAAE,CAK3E;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,SAAS,UAAU,EAAE,EAC9B,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,GACR,MAAM,GAAG,IAAI,CAWf;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,SAAS,gBAAgB,EAAE,GAAG,IAAI,CAKrF;AAyED,MAAM,WAAW,iBAAiB;IAChC;;0BAEsB;IACtB,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAClD,oDAAoD;IACpD,OAAO,IAAI,IAAI,CAAC;CACjB;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,WAAW,EACtB,OAAO,EAAE,SAAS,gBAAgB,EAAE,GACnC,iBAAiB,CA8BnB"}