@vgai/engine 0.2.0 → 0.3.0

package/dist/runtime/frame-selector-cache.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Pure, react-free frame-version cache (T7.4 slice 1 — `docs/
+ * REACT-STATE-BRIDGE.md` §3). `useGameState` (`packages/editor/template/src/
+ * ui/game-state.tsx`) is a thin `useSyncExternalStore` wrapper
+ * around this: `getSnapshot` re-runs the selector once per `frameVersion`
+ * bump (`GameStateBridge`, `runtime/state-bridge.ts`), caches by version,
+ * and returns the PREVIOUS reference when `equals` holds against the fresh
+ * result — that reference stability is what lets `useSyncExternalStore`
+ * (and thus React) bail out of a re-render.
+ *
+ * Extracted to its own react-free module (no react import here, or anywhere
+ * under `runtime/`) so this cache/equality logic — the part of the hook
+ * that has real branching to get wrong — is unit-testable headlessly under
+ * `packages/engine/test/`, without needing a react test harness (none
+ * exists in this repo today; see `test/frame-selector-cache.test.ts`).
+ */
+/** Equality comparator for `FrameSelectorCache`/`useGameState`. Defaults to
+ *  `Object.is` (T7.4 §3); pass {@link shallow} for tuples/plain objects. */
+export type Equals<T> = (a: T, b: T) => boolean;
+/**
+ * One-level shallow-equality helper (own enumerable keys, `Object.is` per
+ * value) — the opt-in equality for selectors that return a fresh
+ * object/array/tuple every call. Two non-object values fall back to
+ * `Object.is`; a non-object compared against an object is never equal.
+ */
+export declare function shallow<T>(a: T, b: T): boolean;
+export interface FrameSelectorCache<T> {
+    /**
+     * Return the cached value for `frameVersion` if it's the SAME version as
+     * the last call (selector not re-run at all). Otherwise call `compute()`
+     * once: if the fresh result is `equals` to the previously cached value,
+     * the PREVIOUS reference is returned (and re-tagged with this
+     * `frameVersion`, so the next same-version call also short-circuits);
+     * otherwise the fresh value is cached and returned.
+     */
+    get(frameVersion: number, compute: () => T): T;
+}
+/** Construct a fresh per-subscriber cache. One per `useGameState` call site
+ *  (a fresh cache each mount — see the hook). */
+export declare function createFrameSelectorCache<T>(equals?: Equals<T>): FrameSelectorCache<T>;
+//# sourceMappingURL=frame-selector-cache.d.ts.map

package/dist/runtime/frame-selector-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame-selector-cache.d.ts","sourceRoot":"","sources":["../../src/runtime/frame-selector-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH;4EAC4E;AAC5E,MAAM,MAAM,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,OAAO,CAAC;AAEhD;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,OAAO,CAa9C;AAED,MAAM,WAAW,kBAAkB,CAAC,CAAC;IACnC;;;;;;;OAOG;IACH,GAAG,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;CAChD;AAED;iDACiD;AACjD,wBAAgB,wBAAwB,CAAC,CAAC,EAAE,MAAM,GAAE,MAAM,CAAC,CAAC,CAAa,GAAG,kBAAkB,CAAC,CAAC,CAAC,CAwBhG"}

package/dist/runtime/frame-selector-cache.js

@@ -0,0 +1,65 @@
+/**
+ * Pure, react-free frame-version cache (T7.4 slice 1 — `docs/
+ * REACT-STATE-BRIDGE.md` §3). `useGameState` (`packages/editor/template/src/
+ * ui/game-state.tsx`) is a thin `useSyncExternalStore` wrapper
+ * around this: `getSnapshot` re-runs the selector once per `frameVersion`
+ * bump (`GameStateBridge`, `runtime/state-bridge.ts`), caches by version,
+ * and returns the PREVIOUS reference when `equals` holds against the fresh
+ * result — that reference stability is what lets `useSyncExternalStore`
+ * (and thus React) bail out of a re-render.
+ *
+ * Extracted to its own react-free module (no react import here, or anywhere
+ * under `runtime/`) so this cache/equality logic — the part of the hook
+ * that has real branching to get wrong — is unit-testable headlessly under
+ * `packages/engine/test/`, without needing a react test harness (none
+ * exists in this repo today; see `test/frame-selector-cache.test.ts`).
+ */
+/**
+ * One-level shallow-equality helper (own enumerable keys, `Object.is` per
+ * value) — the opt-in equality for selectors that return a fresh
+ * object/array/tuple every call. Two non-object values fall back to
+ * `Object.is`; a non-object compared against an object is never equal.
+ */
+export function shallow(a, b) {
+    if (Object.is(a, b))
+        return true;
+    if (typeof a !== 'object' || a === null || typeof b !== 'object' || b === null) {
+        return false;
+    }
+    const aKeys = Object.keys(a);
+    const bKeys = Object.keys(b);
+    if (aKeys.length !== bKeys.length)
+        return false;
+    const bRecord = b;
+    for (const key of aKeys) {
+        if (!Object.is(a[key], bRecord[key]))
+            return false;
+    }
+    return true;
+}
+/** Construct a fresh per-subscriber cache. One per `useGameState` call site
+ *  (a fresh cache each mount — see the hook). */
+export function createFrameSelectorCache(equals = Object.is) {
+    let hasValue = false;
+    let cachedVersion = -1;
+    let cachedValue;
+    return {
+        get(frameVersion, compute) {
+            if (hasValue && frameVersion === cachedVersion) {
+                return cachedValue;
+            }
+            const next = compute();
+            if (hasValue && equals(cachedValue, next)) {
+                // Bail-out: keep the PREVIOUS reference, but remember we're current
+                // as of this frameVersion so a repeat call at the same version
+                // doesn't even re-run `compute`.
+                cachedVersion = frameVersion;
+                return cachedValue;
+            }
+            cachedValue = next;
+            cachedVersion = frameVersion;
+            hasValue = true;
+            return cachedValue;
+        },
+    };
+}

package/dist/runtime/game.d.ts

@@ -0,0 +1,433 @@
+/**
+ * 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 type * as PIXI from 'pixi.js';
+import type * as THREE from 'three';
+import type { MountedWorld } from '../adapter/game-adapter';
+import type { SystemAdapters } from '../adapter/system-adapter';
+import type { VgaiMountedGame } from '../adapter/vgai-scene-game-adapter';
+import type { WorldKind as WorldKindLeaf } from '../adapter/world-kind';
+import type { AssetCache } from '../assets';
+import type { createGameLoop } from '../core/game-loop';
+import { type SystemRunner } from '../core/system-runner';
+import { type SystemPhaseName } from '../core/types';
+import type { ComponentManager } from '../ecs/component-manager';
+import type { GameComponent } from '../ecs/game-component';
+import type { InputManager } from '../input/input-manager';
+import type { CollisionSystem } from '../physics/collision-system';
+import type { PhysicsRegistry } from '../physics/physics-registry';
+import type { AudioContext as GameAudio } from '../setup/setup-audio';
+import type { Collision2DSystem } from '../world2d/collision-2d';
+import type { Physics2DRegistry } from '../world2d/physics2d-registry';
+import { type GameStateBridge } from './state-bridge';
+/** The one loop type — `createGameLoop`'s return shape (D1, fixed-step). */
+export type GameLoop = ReturnType<typeof createGameLoop>;
+/**
+ * Game-level play-state control surface (D10, T7.6 — `docs/DECISIONS-PENDING.md`
+ * §D10): pause/resume/step as ONE control surface on the running game, with
+ * PER-WORLD `pausable` semantics (`WorldInstance.pausable`) — a menu/HUD world
+ * declaring `pausable: false` keeps ticking (input, components, physics) while
+ * every `pausable: true` world freezes. Interacts with D1 (deliberate
+ * fixed-rate rendering): a paused-and-pausable world's `render` phase still
+ * runs every substep (with `dt` forced to `0`, so time-based render effects —
+ * e.g. a post-processing pass with its own internal clock — don't silently
+ * keep animating under a "frozen" scene) — simulation freezes, the screen does
+ * not go black. `GameLoop.timeScale` (unaffected by this) remains the
+ * orthogonal "speed up/slow down" axis — pausing never touches it, so the
+ * host's accumulator/rAF loop keeps ticking at its normal cadence and keeps
+ * calling `runFrame`, which is what makes "paused still renders" possible
+ * (the previous `GameSession.pause()` implementation set `loop.timeScale = 0`,
+ * which — per D1 — starves the accumulator and stops rendering too; that was
+ * the bug this control surface replaces, not a compatible behavior to keep).
+ */
+export interface PlayState {
+    /** Whether the game is currently paused (game-level — see the per-world
+     *  `pausable` caveat above: a `pausable: false` world ignores this). */
+    readonly paused: boolean;
+    /**
+     * Freeze every `pausable` world's simulation (idempotent — a second call
+     * while already paused is a no-op) and, for every `pausable`, self-driven
+     * (`drivesOwnLoop`) world, invoke its loop-gate capability
+     * (`mounted.setPaused(true)`) — reporting loudly, once per world, when that
+     * capability is absent (an honest "cannot gate" instead of a silent no-op,
+     * `docs/CAPABILITY-TIERS.md` §d). Also silences every `pausable` world's
+     * audio via its `SystemAdapters.audio` (absent ⇒ the same loud, once-only
+     * report).
+     */
+    pause(): void;
+    /** Resume every `pausable` world — the inverse of `pause()`, same
+     *  idempotency and loop-gate/audio fan-out (no re-reporting; a world that
+     *  couldn't be gated on pause simply never was, so resume has nothing to
+     *  undo for it). */
+    resume(): void;
+    /**
+     * Advance exactly the currently-FROZEN worlds by one fixed substep: the
+     * `pausable`, host-driven (`!drivesOwnLoop`) worlds while `paused` is
+     * true. While NOT paused this is a whole-call no-op — under D10 the loop
+     * never stops, so every non-frozen world is already being ticked; an
+     * unconditional extra tick was the §7.1-2 double-tick bug (probe4). A
+     * `pausable`, self-driven world that was actually gated by `pause()`
+     * (adapter has `setPaused`) steps via its own loop-gate `step()`
+     * capability instead (absent ⇒ the same loud report as `pause()`); a
+     * self-driven world the gate couldn't reach is still running and is left
+     * alone. `dt` defaults to the engine's fixed timestep (1/60s — every real
+     * host constructs its loop with this value; see `create-runtime.ts`).
+     */
+    step(dt?: number): void;
+}
+/**
+ * The kinds of render surface a world can be. `'threejs'` and `'pixijs'`
+ * worlds are real as of T7.3 slice 1 (`create-runtime.ts`'s default threejs
+ * world; `world2d/pixi-game-adapter.ts`'s pixi world); `'react'` is named
+ * here so the type is already shaped for T7.4 and no caller has to widen a
+ * union later.
+ *
+ * Re-exported from `adapter/world-kind.ts` (T7.5) — moved there so
+ * `adapter/game-adapter.ts`'s kind-tagged `MountedWorld` types can name it
+ * without an import cycle back to this file. This re-export keeps every
+ * existing `import type { WorldKind } from '../runtime/game'` call site
+ * (`ecs/game-component.ts`, `ecs/component-manager.ts`) compiling unchanged.
+ */
+export type WorldKind = WorldKindLeaf;
+/**
+ * A world's per-phase frame hooks (GAME-ROOT-DESIGN §4, T7.1 slice 2).
+ * Populated on a `WorldInstance` only for first-party mounts — an opaque/
+ * foreign mount has no phase-partitioned entry point, so it stays
+ * `undefined` and the Game's frame executor (`GameInternal.runFrame`) falls
+ * back to calling its single `mounted.update(dt)` once per substep instead.
+ */
+export interface WorldFrameHooks {
+    /** Run this world's engine systems + component ticks + world-bound game
+     *  systems for one phase. For a first-party world this delegates to the
+     *  SAME `SystemRunner.runPhase` its (legacy) `mounted.update` uses. */
+    runPhase(phase: SystemPhaseName, dt: number): void;
+    /** Run once per substep, after ALL phases have run for ALL worlds this
+     *  substep (mirrors where `mounted.update`'s post-`systems.run` work sat
+     *  today — e.g. `input.endFrame()`). Optional: a world may have nothing
+     *  to do here. */
+    endFrame?(): void;
+}
+/**
+ * A single world instance: the unit of adaptation (GAME-ROOT-DESIGN §3).
+ * Slice-1 subset — `gpu` (per-world GPU resource cache, §6.2) is omitted
+ * until the slice that builds it.
+ */
+export interface WorldInstance {
+    /** Manifest id (T3.1). Slice 1 always registers exactly one: `'main'`. */
+    readonly id: string;
+    readonly kind: WorldKind;
+    /** Per-world play/pause semantics (D10, T7.6). Slice 1 always `true`. */
+    readonly pausable: boolean;
+    /** The GameAdapter that produced `mounted` — first-party or external.
+     *  Deliberately narrower than `GameAdapter<K>` (T7.5): this field is only
+     *  ever read for `.id` (`Game.registerWorld`'s diagnostic message below) —
+     *  never re-invoked — and `GameAdapter<K>`'s `mount` signature legitimately
+     *  differs per kind's host type (a pixijs adapter's `World2DHost`, a react
+     *  adapter's `ReactWorldHost`, vs a threejs adapter's `HostContext`), so
+     *  requiring the FULL interface here would force a cast at every non-
+     *  threejs registration site for no behavioral gain — see `AdapterHandle`
+     *  below. */
+    readonly adapter: AdapterHandle;
+    /** The live mounted surface — one of `MountedWorld`'s kind-tagged shapes
+     *  (T7.5; `MountedThreeWorld` for a threejs world, `MountedPixiWorld` for
+     *  pixijs, `MountedReactWorld` for react). */
+    readonly mounted: MountedWorld;
+    /** Kind-narrowed accessor: throws a descriptive error when this world is
+     *  not a threejs world. */
+    threeRoot(): THREE.Scene;
+    /** Kind-narrowed accessor for pixijs worlds (T7.3): returns the stage
+     *  passed to `createWorldInstance` for a `'pixijs'`-kind world. Throws
+     *  descriptively for a non-pixijs world, or a pixijs world built without
+     *  a `stage` (see `WorldInstanceInit.stage`). */
+    pixiRoot(): PIXI.Container;
+    /** Kind-narrowed accessor for react worlds (T6.2 slice 1,
+     *  `docs/REACT-WORLD-DESIGN.md` §1.B): returns the DOM-root layer
+     *  `<div>` the host mounted this world's react tree into (the SAME
+     *  element passed as `container` to `createWorldInstance` — identity
+     *  matters, mirroring `threeRoot()`/`pixiRoot()`'s "same instance the
+     *  adapter mounted" contract). Throws descriptively for a non-react
+     *  world, or a react world built without a `container` (see
+     *  `WorldInstanceInit.container`). */
+    reactRoot(): HTMLElement;
+    /** Present only when the world's mount is first-party (Rapier3D for
+     *  threejs worlds). */
+    readonly physics?: PhysicsRegistry | undefined;
+    readonly collisions?: CollisionSystem | undefined;
+    /** Present only when the world's mount is a first-party pixijs world
+     *  (Rapier2D, T7.3) — the 2D analog of `physics`/`collisions` above. Kept
+     *  as separate fields (not folded into `physics`/`collisions` as a union)
+     *  so 3D call sites keep their non-union `PhysicsRegistry`/`CollisionSystem`
+     *  typing unchanged. */
+    readonly physics2d?: Physics2DRegistry | undefined;
+    readonly collisions2d?: Collision2DSystem | undefined;
+    /** Kind-typed via `mounted` in T7.5; `unknown` here deliberately. */
+    readonly camera?: unknown;
+    /** Phase-partitioned frame entry point (T7.1 slice 2) — present only for
+     *  first-party mounts. `undefined` for an opaque/foreign mount, which
+     *  `GameInternal.runFrame` drives via its single `mounted.update` call
+     *  instead (unless it `drivesOwnLoop`, in which case it isn't ticked at
+     *  all — see `runFrame`). */
+    readonly frame?: WorldFrameHooks | undefined;
+}
+/**
+ * Minimal identity surface `WorldInstance.adapter` needs (T7.5) — see that
+ * field's doc comment for why it's narrower than `GameAdapter<K>`. Any real
+ * adapter object (a NAMED type, not a fresh object literal) — `GameAdapter<K>`,
+ * `Pixi2DGameAdapter`, `ReactWorldAdapter`, or a project's own custom adapter —
+ * satisfies this trivially (extra members beyond `id` are always fine for a
+ * non-literal source); a bare `{ id, mount }` object literal built INLINE at
+ * a `createWorldInstance`/`registerXWorld` call site needs an intermediate
+ * `const` (excess-property checking only special-cases fresh literals).
+ */
+export interface AdapterHandle {
+    readonly id: string;
+}
+/** Inputs to {@link createWorldInstance}. */
+export interface WorldInstanceInit {
+    readonly id: string;
+    readonly kind: WorldKind;
+    /** Defaults to `true` (D10's per-world default). */
+    readonly pausable?: boolean;
+    readonly adapter: AdapterHandle;
+    readonly mounted: MountedWorld;
+    /** Required when `kind === 'threejs'` — backs `threeRoot()`. */
+    readonly scene?: THREE.Scene | undefined;
+    /** Required when `kind === 'pixijs'` — backs `pixiRoot()` (T7.3 slice 2,
+     *  symmetric with `scene` for threejs above). */
+    readonly stage?: PIXI.Container | undefined;
+    /** Required when `kind === 'react'` — backs `reactRoot()` (T6.2 slice 1,
+     *  symmetric with `scene`/`stage` above): the DOM-root layer `<div>` this
+     *  world's react tree is mounted into. */
+    readonly container?: HTMLElement | undefined;
+    readonly physics?: PhysicsRegistry | undefined;
+    readonly collisions?: CollisionSystem | undefined;
+    readonly physics2d?: Physics2DRegistry | undefined;
+    readonly collisions2d?: Collision2DSystem | undefined;
+    readonly camera?: unknown;
+    readonly frame?: WorldFrameHooks | undefined;
+}
+/**
+ * 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 declare function createWorldInstance(init: WorldInstanceInit): WorldInstance;
+/**
+ * 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 declare function isFirstPartyMounted(mounted: MountedWorld): mounted is VgaiMountedGame;
+/**
+ * The Game root (GAME-ROOT-DESIGN §3). Owns the one loop, the raw-asset
+ * cache, the world registry, and (T7.1 slice 2) the game-scoped
+ * `SystemRunner`. `components`/`input`/`audio` remain slice-1 late
+ * additions: they delegate to the default world's first-party mount so
+ * existing single-world call sites keep working; hoisting them to true
+ * Game ownership (GAME-ROOT-DESIGN §3's target shape) is a later slice's
+ * work, not this one's.
+ */
+export interface Game {
+    readonly loop: GameLoop;
+    readonly assets: AssetCache;
+    /**
+     * The game-scoped `SystemRunner` (GAME-ROOT-DESIGN §4, T7.1 slice 2) — a
+     * NEW bucket, separate from any world's own runner. Within each phase,
+     * `GameInternal.runFrame` runs THIS runner's `runPhase` first, before any
+     * world's engine systems/component ticks/world-bound game systems (e.g.
+     * `ctx.systems.add`, which stays world-bound to the default world — see
+     * `runtime/types.ts`). Empty for every existing game (nothing registers
+     * against it yet), so `runFrame`'s behavior for a single-world game is
+     * unchanged by its presence.
+     */
+    readonly systems: SystemRunner;
+    /** Declaration-ordered. Slice 1 registers exactly one (the default
+     *  threejs world) — this is the SAME array reference `registerWorld`
+     *  mutates, not a snapshot, so holders (e.g. `GameContext.worlds`) observe
+     *  later registrations. */
+    readonly worlds: ReadonlyArray<WorldInstance>;
+    world(id: string): WorldInstance | null;
+    /** First threejs world, else first world. Throws descriptively when no
+     *  world has been registered yet. */
+    readonly defaultWorld: WorldInstance;
+    /**
+     * Game-scoped aggregation of every world's `SystemAdapters` (§7.1-3,
+     * `docs/GAME-ROOT-DESIGN.md` §3: "`registerSystemAdapter` is game-scoped" —
+     * the recorded decision this getter finally implements; probe1). Each
+     * mounted world builds its OWN `mounted.systems` object (a game registers
+     * capabilities like `networking` from ITS OWN `setup()`, via
+     * `ctx.registerSystemAdapter`, per-world) — this merges every world's
+     * `mounted.systems` into ONE `SystemAdapters`, in `worlds` REGISTRATION
+     * order, first registration wins per key. A later world registering the
+     * SAME kind (e.g. two worlds both exposing `networking`) does not
+     * override the first — instead this warns ONCE per (game instance, key)
+     * naming both world ids, matching this file's `[game] world "<id>" …`
+     * console idiom (see `registerWorld` below). NOT to be confused with
+     * `Game.systems` (the game-scoped `SystemRunner` bucket, an entirely
+     * different concept — see that field's doc comment) — this name was
+     * deliberately chosen not to collide with it.
+     *
+     * A plain getter (recomputed on every read, not cached) so a LATER
+     * `registerWorld` call (or a world's setup registering a NEW adapter kind
+     * after this was first read) is always reflected — only the COLLISION
+     * warning is deduped (once per key, for the lifetime of this `Game`).
+     * Includes every world regardless of first-party-ness — `mounted.systems`
+     * is a capability any adapter (first-party or foreign) may expose.
+     */
+    readonly systemAdapters: SystemAdapters;
+    /** Delegates to the default world's first-party `ComponentManager`.
+     *  Throws when the default world is not a first-party mount. */
+    readonly components: ComponentManager;
+    /** Delegates to the default world's first-party `InputManager`. Throws
+     *  when the default world is not a first-party mount. */
+    readonly input: InputManager;
+    /** Delegates to the default world's first-party audio context. Throws
+     *  when the default world is not a first-party mount. */
+    readonly audio: GameAudio;
+    /**
+     * Frame-versioned state bridge (T7.4 slice 1 — `docs/REACT-STATE-BRIDGE.md`
+     * §2). Bumped once per completed `runFrame`, after all phases of all
+     * worlds and all `endFrame` hooks (see `runFrame`'s tail below). This is
+     * the ONE subscription surface `useGameState`
+     * (`packages/editor/template/src/ui/game-state.tsx`) — or any
+     * other frame-versioned consumer — subscribes to; `state-bridge.ts` itself
+     * has no react import, matching the rest of `runtime/`.
+     */
+    readonly state: GameStateBridge;
+    /** Game-level play-state control surface (D10, T7.6) — see {@link PlayState}. */
+    readonly play: PlayState;
+    /**
+     * Cross-world component query (GAME-ROOT-DESIGN §5, T7.1 slice 3) — the
+     * game-level half; `ComponentManager.queryByComponent` (`ecs/
+     * component-manager.ts`) is the per-world half this aggregates.
+     *
+     * Iterates `worlds` in declaration order, skipping any world whose mount
+     * is not first-party (an opaque/foreign mount has no `ComponentManager`
+     * to query), applying `opts.worldId`/`opts.kind` as world-level filters,
+     * and concatenating each remaining world's `queryByComponent(cls)`
+     * result. No filter (`opts` omitted) spans **every** world — that is the
+     * whole point of this API existing (D7's "cross-world flow is ordinary
+     * component access", e.g. a pixi minimap component querying the 3D
+     * world's tank components).
+     *
+     * Returns component **instances**, not nodes — `inst.world`/typed node
+     * accessors (`inst.object3D`, the generic `inst.node`) are T7.2's; this
+     * API's contract freezes HERE. The physical ONE-`ComponentManager`
+     * unification (partitioning one manager by (phase, world) instead of one
+     * manager per world) lands with T7.2/T7.3 — this per-world-aggregation
+     * implementation is the compatible interim: callers written against this
+     * signature keep working unchanged once the manager is unified
+     * underneath.
+     *
+     * `T extends GameComponent<WorldKind>` (not the bare default-`'threejs'`
+     * `GameComponent`, T7.3 slice 2) — the whole point of a CROSS-WORLD query
+     * is spanning every kind in one call (the T7.3 AC,
+     * `test/game-three-plus-pixi.test.ts`), so a `GameComponent<'pixijs'>`
+     * subclass must type-check here exactly like a default-kind one does.
+     */
+    queryByComponent<T extends GameComponent<WorldKind>>(cls: new () => T, opts?: {
+        worldId?: string;
+        kind?: WorldKind;
+    }): T[];
+}
+/**
+ * Host-internal extension of {@link Game}: adds `registerWorld` (the host's
+ * wiring surface for populating the world registry) and `runFrame` (the
+ * frame executor). NEITHER is part of the game-facing `Game` surface —
+ * games/components never call either directly; the host loop
+ * (`createGameRuntime`) and `GameSession.step()` are the only callers of
+ * `runFrame`.
+ */
+export interface GameInternal extends Game {
+    /** Append a world in declaration order. Throws on a duplicate id. */
+    registerWorld(world: WorldInstance): void;
+    /**
+     * Run ONE fixed substep across every phase and every world
+     * (GAME-ROOT-DESIGN §4):
+     *
+     * ```
+     * for phase in PHASE_ORDER:
+     *   game.systems.runPhase(phase, dt)        // game-scoped, first
+     *   for world in worlds (declaration order):
+     *     if world.mounted.drivesOwnLoop: continue
+     *     world.frame?.runPhase(phase, dt)
+     * for world in worlds:                       // after ALL phases
+     *   if world.mounted.drivesOwnLoop: continue
+     *   if world.frame: world.frame.endFrame?.()
+     *   else: world.mounted.update?.(dt)          // opaque world fallback
+     * ```
+     *
+     * For today's single first-party world this is byte-identical to the
+     * legacy `mounted.update(dt)` (`game.systems` is empty; the one world's
+     * `frame.runPhase` delegates to the SAME `SystemRunner.runPhase` its
+     * `update` used; `endFrame` is the same `postFrame` call). A
+     * `drivesOwnLoop` world is never ticked here at all — matching its
+     * exclusion from the legacy `!mountedRef.drivesOwnLoop` guard. An opaque
+     * host-driven world (no `frame`) gets exactly one `update(dt)` call per
+     * substep, after the phase loop — unchanged cadence from today.
+     *
+     * D10/T7.6 play-state addendum: when `Game.play.paused` is true, every
+     * `pausable` (and non-`drivesOwnLoop`) world skips every phase EXCEPT
+     * `render` (still called, every substep, with `dt` forced to `0`) and skips
+     * its `endFrame`/opaque-`update` call entirely — a `pausable: false` world
+     * is completely unaffected. `opts.ignorePause` runs this call as if nothing
+     * were paused, regardless of the live `paused` flag; kept for external
+     * byte-compatibility (no first-party caller passes it today — grep finds
+     * none) but is no longer how `Game.play.step()` works (§7.1-2 fix,
+     * probe4: the old `ignorePause` full-frame re-run double-ticked every
+     * already-running `pausable: false` world, since D10's ordinary loop never
+     * stops ticking them). `Game.play.step()` now drives this function via the
+     * internal-only `onlyFrozen` mode instead (see `runFrameImpl` — not part of
+     * this public, host-facing signature): 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 — a natural no-op while not paused, since
+     * the frozen set is then empty.
+     */
+    runFrame(dt: number, opts?: {
+        ignorePause?: boolean;
+    }): void;
+}
+/**
+ * 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 declare function createGame(opts: {
+    loop: GameLoop;
+    assets: AssetCache;
+}): GameInternal;
+//# sourceMappingURL=game.d.ts.map

package/dist/runtime/game.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"game.d.ts","sourceRoot":"","sources":["../../src/runtime/game.ts"],"names":[],"mappings":"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"}