@vgai/engine 0.5.5 → 0.5.6

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

@@ -0,0 +1,65 @@
+/**
+ * Pure, react-free frame-version cache (T7.4 slice 1).
+ * `useWorldState` (`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 `useWorldState` 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,576 @@
+/**
+ * Game root — T7.1 slice 1 ("introduce Game internally") + slice 2 ("world
+ * registry + ordered frame algorithm"), extended in T7.3 slice 1 with real
+ * `'canvas'`-kind `RootInstance` support (`stage`/`physics2d`, a real
+ * `pixiStage()`) so a canvas adapter 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 three/scene check).
+ * T6.2 slice 1 adds real `'react'`-kind
+ * `RootInstance` support (`container`, a real `reactRoot()`) — the DOM-root
+ * world surface `runtime/create-runtime.ts`'s roots path now mounts, with
+ * `physics`/`collisions`/`camera`/`frame` `undefined` for them exactly
+ * like an opaque/foreign mount.
+ *
+ * (D6), particularly §4 (the frame algorithm) and §8 stage 2, for the full
+ * target shape. This file holds the Game/ RootInstance 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 { AdapterSurface as AdapterSurfaceLeaf } from '../adapter/adapter-surface';
+import type { MountedRoot } from '../adapter/root-adapter';
+import type { MountedSetupThreeRoot } from '../adapter/setup-three-root-adapter';
+import type { SystemAdapters } from '../adapter/system-adapter';
+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 PerformanceProfiler } from '../dev/performance-profiler';
+import { InputManager } from '../input/input-manager';
+import type { CollisionSystem } from '../physics/collision-system';
+import type { PhysicsRegistry } from '../physics/physics-registry';
+import type { Physics2DRegistry } from '../pixi/physics-registry';
+import type { AudioContext as GameAudio } from '../setup/setup-audio';
+import { type RunTicksOptions } from './debug-registry';
+import { type GameStateBridge } from './state-bridge';
+import type { GameContext, PlaytestContext } from './types';
+/** The one loop type — `createGameLoop`'s return shape (fixed-step sim,
+ *  display-rate presentation since WO-P13). */
+export type GameLoop = ReturnType<typeof createGameLoop>;
+/**
+ * Game-level play-state control surface (D10, T7.6): pause/resume/step as ONE
+ * control surface on the running game, with PER-WORLD `pausable` semantics
+ * (`RootInstance.pausable`) — a menu/HUD world declaring `pausable: false` keeps
+ * ticking (input, physics) while every `pausable: true` world
+ * freezes. A paused-and-pausable world's `render` phase still runs (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. WO-P13 changed only the
+ * CADENCE of that: once per display frame under a host that drives
+ * `runRenderFrame`, once per substep under one that still renders inside
+ * `runFrame`. `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, which is what makes
+ * "paused still renders" possible (the previous `GameSession.pause()`
+ * implementation set `loop.timeScale = 0`, which starves the accumulator — and,
+ * before WO-P13, stopped rendering with it; 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).
+     * 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 roots by one fixed substep: the
+     * `pausable`, host-driven (`!drivesOwnLoop`) roots 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. `'three'` and `'canvas'`
+ * roots are both real; `'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/adapter-surface.ts` (T7.5) — moved there so
+ * `adapter/root-adapter.ts`'s kind-tagged `MountedRoot` types can name it
+ * without an import cycle back to this file. This re-export keeps every
+ * existing `import type { AdapterSurface } from '../runtime/game'` call site
+ * (`ecs/behavior.ts`, `ecs/component-manager.ts`) compiling unchanged.
+ */
+export type AdapterSurface = AdapterSurfaceLeaf;
+/**
+ * A world's per-phase frame hooks (T7.1 slice 2).
+ * Populated on a `RootInstance` 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 RootFrameHooks {
+    /** 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 roots 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.
+ * Slice-1 subset — `gpu` (per-world GPU resource cache, §6.2) is omitted
+ * until the slice that builds it.
+ */
+export interface RootInstance {
+    /** Manifest id (T3.1). Slice 1 always registers exactly one: `'main'`. */
+    readonly id: string;
+    readonly kind: AdapterSurface;
+    /** Per-world play/pause semantics (D10, T7.6). Slice 1 always `true`. */
+    readonly pausable: boolean;
+    /** The RootAdapter that produced `mounted` — first-party or external.
+     *  Deliberately narrower than `RootAdapter<K>` (T7.5): this field is only
+     *  ever read for `.id` (`Game.registerRoot`'s diagnostic message below) —
+     *  never re-invoked — and `RootAdapter<K>`'s `mount` signature legitimately
+     *  differs per kind's host CONTEXT (`HostContextFor<K>`, P-8: a canvas
+     *  adapter's `CanvasHostContext`, a react adapter's `DomHostContext`, vs a
+     *  three adapter's `ThreeHostContext`), so requiring the FULL interface here
+     *  would force each registration site to name its own `K` for no behavioral
+     *  gain — see `AdapterHandle` below. */
+    readonly adapter: AdapterHandle;
+    /** The live mounted surface — one of `MountedRoot`'s kind-tagged shapes
+     *  (T7.5; `MountedThreeRoot` for a three world, `MountedPixiRoot` for
+     *  canvas, `MountedReactRoot` for react). */
+    readonly mounted: MountedRoot;
+    /** Kind-narrowed accessor: throws a descriptive error when this world is
+     *  not a three world. */
+    threeScene(): THREE.Scene;
+    /** Kind-narrowed accessor for canvas roots (T7.3): returns the stage
+     *  passed to `createRootInstance` for a `'canvas'`-kind world. Throws
+     *  descriptively for a non-pixijs world, or a canvas world built without
+     *  a `stage` (see `RootInstanceInit.stage`). */
+    pixiStage(): PIXI.Container;
+    /** Kind-narrowed accessor for react roots (T6.2 slice 1): returns the
+     *  DOM-root layer `<div>` the host mounted this world's react tree into
+     *  (the SAME element passed as `container` to `createRootInstance` —
+     *  identity matters, mirroring `threeScene()`/`pixiStage()`'s "same
+     *  instance the adapter mounted" contract). Throws descriptively for a
+     *  non-react world, or a react world built without a `container` (see
+     *  `RootInstanceInit.container`). */
+    reactRoot(): HTMLElement;
+    /** Present only when the world's mount is first-party (Rapier3D for
+     *  three roots). */
+    readonly physics?: PhysicsRegistry | undefined;
+    readonly collisions?: CollisionSystem | undefined;
+    /** Present only when the world's mount owns a Rapier-2D world — the 2D
+     *  analog of `physics` above. Kept as a separate field (not folded into
+     *  `physics` as a union) so 3D call sites keep their non-union
+     *  `PhysicsRegistry` typing unchanged. */
+    readonly physics2d?: Physics2DRegistry | 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?: RootFrameHooks | undefined;
+}
+/**
+ * Minimal identity surface `RootInstance.adapter` needs (T7.5) — see that
+ * field's doc comment for why it's narrower than `RootAdapter<K>`. Any real
+ * adapter object (a NAMED type, not a fresh object literal) — `RootAdapter<K>`,
+ * `Pixi2DRootAdapter`, `ReactRootAdapter`, 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 `createRootInstance`/`registerXRoot` call site needs an intermediate
+ * `const` (excess-property checking only special-cases fresh literals).
+ */
+export interface AdapterHandle {
+    readonly id: string;
+}
+/** Inputs to {@link createRootInstance}. */
+export interface RootInstanceInit {
+    readonly id: string;
+    readonly kind: AdapterSurface;
+    /** Defaults to `true` (D10's per-world default). */
+    readonly pausable?: boolean;
+    readonly adapter: AdapterHandle;
+    readonly mounted: MountedRoot;
+    /** Required when `kind === 'three'` — backs `threeScene()`. */
+    readonly scene?: THREE.Scene | undefined;
+    /** Required when `kind === 'canvas'` — backs `pixiStage()` (T7.3 slice 2,
+     *  symmetric with `scene` for three above). */
+    readonly stage?: PIXI.Container | undefined;
+    /** Required when `kind === 'dom'` — 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 camera?: unknown;
+    readonly frame?: RootFrameHooks | undefined;
+}
+/**
+ * Build a `RootInstance` whose kind-narrowed accessors throw descriptively
+ * on kind mismatch. This is the one place that builds
+ * `threeScene`/`pixiStage`, so every world (however it's constructed, in this
+ * slice or later ones) gets identical throw behavior.
+ */
+export declare function createRootInstance(init: RootInstanceInit): RootInstance;
+/**
+ * Type guard for whether a `MountedThreeRoot` is a first-party
+ * `SetupThreeRootAdapter` mount (has a live `GameContext` at `.ctx`). Used to
+ * decide whether a world's `physics`/`collisions`/`camera` (and, on `Game`,
+ * `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` — a foreign mount may carry an unrelated `ctx` key, so a
+ * structural `'ctx' in mounted` check would misfire. The probe is a plain property read, not an
+ * `instanceof`/value import of `setup-three-root-adapter.ts` — the
+ * `MountedSetupThreeRoot` import above stays type-only.
+ */
+export declare function isFirstPartyMounted(mounted: MountedRoot): mounted is MountedSetupThreeRoot;
+/**
+ * One world's half of a debris disposal, as {@link disposeDebrisSubtree} needs
+ * it. A first-party `GameContext` satisfies this structurally.
+ *
+ * `physics`/`rapierWorld` are OPTIONAL: an owner that builds no first-party
+ * Rapier runtime (an R3F world) carries neither, and {@link
+ * disposeDebrisSubtree} reads them behind `readRapierHandles` rather than
+ * unconditionally.
+ */
+export interface DebrisOwner {
+    readonly physics?: GameContext['physics'];
+    readonly rapierWorld?: GameContext['rapierWorld'];
+}
+/**
+ * P3 — what `SimClock.disposeAfter` actually does. `core/sim-clock.ts` knows
+ * only *when*; this is the *what*, and it lives here because it is the runtime
+ * that knows about Rapier and shared geometry.
+ *
+ * The order mirrors `adapter/setup-three-root-adapter.ts`'s world teardown for
+ * ONE subtree. Within the physics step,
+ * `rapierWorld.removeRigidBody(body)` comes BEFORE `physics.remove(node)`: the
+ * registry's `remove()` only drops index entries, so reversing the two leaks
+ * the Rapier body.
+ *
+ * `owners` is every world that could own part of the subtree — `createGame`
+ * passes all of its first-party three roots as their `GameContext`, a bare
+ * adapter mount passes its own ctx. `physics.get` is a no-op for a node the
+ * owner does not own, so offering the subtree to each is safe.
+ *
+ * Safe on an object already removed or already disposed: `removeFromParent` on
+ * a parentless `Object3D` is a no-op and three's `dispose()` calls are
+ * idempotent.
+ */
+export declare function disposeDebrisSubtree(obj: THREE.Object3D, owners: ReadonlyArray<DebrisOwner>): void;
+/**
+ * The Game root. Owns the one loop, the raw-asset
+ * cache, the world registry, and (T7.1 slice 2) the game-scoped
+ * `SystemRunner`. `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 (the target shape) is a later slice's
+ * work, not this one's.
+ */
+export interface Game {
+    readonly loop: GameLoop;
+    readonly assets: AssetCache;
+    /** Host identity for this private play run or coordinated Team Test. */
+    readonly playtest?: PlaytestContext | null;
+    /** Per-game diagnostic store. Disabled by default; the editor enables it on demand. */
+    readonly profiler: PerformanceProfiler;
+    /**
+     * The game-scoped `SystemRunner` (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
+     *  three world) — this is the SAME array reference `registerRoot`
+     *  mutates, not a snapshot, so holders (e.g. `GameContext.roots`) observe
+     *  later registrations. */
+    readonly roots: ReadonlyArray<RootInstance>;
+    world(id: string): RootInstance | null;
+    /** First three world, else first world. Throws descriptively when no
+     *  world has been registered yet. */
+    readonly defaultRoot: RootInstance;
+    /**
+     * Game-scoped aggregation of every world's `SystemAdapters` (§7.1-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
+     * `roots` REGISTRATION order, first registration wins per key. A later
+     * world registering the SAME kind (e.g. two roots 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 `registerRoot` 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
+     * `registerRoot` 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;
+    /** Subscribe when a mounted root registers or replaces a system adapter. */
+    subscribeSystemAdapters?(listener: () => void): () => void;
+    /** The one game-owned `InputManager`, shared by every first-party root. */
+    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). Bumped once per completed
+     * `runFrame`, after all phases of all roots and all `endFrame` hooks (see
+     * `runFrame`'s tail below). This is the ONE subscription surface
+     * `useWorldState` (`@vgai/engine/react/world-state`) — 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;
+    /**
+     * WO-P13 — the interpolation alpha the most recent display frame presented
+     * at: `accumulator / fixedDt`, in `[0, 1]`. `0` means "exactly on the last
+     * completed fixed state", `0.5` means "halfway to the next one".
+     *
+     * Read it to interpolate your own transforms between the last two fixed
+     * states; it is the same number `onRenderStep` hands its callbacks, exposed
+     * here for code that renders from somewhere other than a callback. Stays
+     * `0` for a Game whose host never wired a display-rate render pass (see
+     * {@link onRenderStep}).
+     */
+    readonly renderAlpha: number;
+    /**
+     * WO-P13 — the `RenderStepped`-shaped host: register a callback that runs
+     * ONCE PER DISPLAY FRAME, before that frame's `preRender`/`render` phases,
+     * with `(alpha, displayDt)`.
+     *
+     * This is the seam for presentation-only work whose natural rate is the
+     * monitor's, not the simulation's — camera polish/smoothing, procedural
+     * sway, a cosmetic bob. It is NOT a gameplay hook: it can fire twice
+     * between two fixed substeps (120 Hz display, 60 Hz sim) and zero times
+     * across a `runTicks` fast-forward, so anything that must be deterministic
+     * belongs in a fixed phase (`ctx.systems.add`, a `useFrame` hook, a
+     * `useFrame`) instead.
+     *
+     * Reached from game code as `ctx.game?.onRenderStep(...)`. Returns an
+     * unsubscribe function; pass `opts.signal` to unsubscribe with the same
+     * `AbortSignal` a `setup()` already uses for its listeners and sim timers
+     * (`core/sim-clock.ts`'s ownership section — cancelling what you registered
+     * is the game's job, and a stale render-step closure is the same hazard
+     * class as a stale event listener).
+     *
+     * Silent-no-op honesty: a callback registered on a Game whose host wired no
+     * display-rate render pass (a bare test harness, a `drivesOwnLoop`-only
+     * mount, an `externalDrive` capture page) never fires, because nothing
+     * drives it. That is the same shape as `ctx.clock` on a Game-less mount.
+     */
+    onRenderStep(fn: (alpha: number, displayDt: number) => void, opts?: {
+        signal?: AbortSignal | undefined;
+    }): () => void;
+}
+/**
+ * Host-internal extension of {@link Game}: adds `registerRoot` (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 never call either directly; the host loop
+ * (`createGameRuntime`) and `GameSession.step()` are the only callers of
+ * `runFrame`.
+ */
+export interface GameInternal extends Game {
+    /** Host-side signal used by root contexts after `registerSystemAdapter`. */
+    notifySystemAdaptersChanged(): void;
+    /** Append a world in declaration order. Throws on a duplicate id. */
+    registerRoot(world: RootInstance): void;
+    /**
+     * Run ONE fixed substep across every phase and every world:
+     *
+     * ```
+     * for phase in PHASE_ORDER:
+     *   game.systems.runPhase(phase, dt)        // game-scoped, first
+     *   for world in roots (declaration order):
+     *     if world.mounted.drivesOwnLoop: continue
+     *     world.frame?.runPhase(phase, dt)
+     * for world in roots:                       // 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.
+     *
+     * WO-P13 addendum: `opts.skipRenderPhases` omits `preRender`+`render` from
+     * the pass — every other phase, and `endFrame`, run exactly as always. A
+     * host that drives presentation at DISPLAY rate sets it on every substep
+     * and calls {@link runRenderFrame} once per real frame instead
+     * (`create-runtime.ts`). A host that does
+     * not set it keeps the pre-WO-P13 shape verbatim — which is why
+     * `externalDrive` capture (`render-control.ts`'s `simulateSubsteps`, which
+     * calls `runFrame(fixedDt)` with no opts) is frame-exact and unchanged.
+     * `runTicks` sets it per tick for its `render: 'none' | 'last'` modes.
+     */
+    runFrame(dt: number, opts?: {
+        ignorePause?: boolean;
+        skipRenderPhases?: boolean;
+    }): void;
+    /**
+     * WO-P13 — run ONE display frame's presentation pass: the registered
+     * `onRenderStep` callbacks, then the `preRender` and `render` phases across
+     * game-scoped systems and every host-driven world, in the same
+     * game-systems-then-worlds order {@link runFrame} uses.
+     *
+     * ```
+     * for cb in onRenderStep callbacks: cb(alpha, displayDt)
+     * for phase in [preRender, render]:
+     *   game.systems.runPhase(phase, displayDt)
+     *   for world in roots (declaration order):
+     *     if world.mounted.drivesOwnLoop: continue
+     *     world.frame?.runPhase(phase, frozen ? 0 : displayDt)
+     * ```
+     *
+     * Advances NOTHING: no `tick`, no `simT`, no sim-clock flush, no state-bridge
+     * bump, no `endFrame`. It is presentation only, which is what makes calling
+     * it at a rate the simulation does not share safe in the first place.
+     *
+     * D10's pause rule carries over unchanged in substance: a frozen world
+     * (paused + `pausable`) still RENDERS — that is what keeps a paused editor
+     * viewport painted — but with `dt` forced to `0`, so no time-based render
+     * effect animates a frozen scene. What changes is only the cadence: once per
+     * display frame instead of once per fixed substep.
+     */
+    runRenderFrame(alpha: number, displayDt: number): void;
+    /**
+     * D15/T-D15.3-.4 — a deterministic fast-forward primitive: synchronously
+     * call the SAME per-tick pipeline `runFrame` uses, `n` times in a tight
+     * loop, with `dt` fixed to the host loop's own fixed timestep
+     * (`this.loop.fixedDt` — `core/game-loop.ts`). This generalizes
+     * `render-control.ts`'s proven `VgaiRenderHarness. simulateSubsteps` from
+     * the capture-only door (`?vgai-render=1`) to a Game-level primitive every
+     * door can reach (the bridge's `window.__vgai.runTicks`, the editor relay's
+     * `run-ticks` case → `play.runTicks`) — `simulateSubsteps` itself is
+     * UNTOUCHED by this addition (it may later delegate to this method; not
+     * this unit's job).
+     *
+     * Semantics:
+     * - **Decoupled from wall clock and the accumulator.** `runTicks` drives
+     *   `runFrame` DIRECTLY — it never goes through `GameLoop`'s own
+     *   accumulator/spiral-of-death drop path, so `n` ticks always advance
+     *   `tick`/`simT` by exactly `n`/`n * fixedDt`, on any hardware, regardless
+     *   of how slow or fast the call actually took wall-clock-wise. Single-
+     *   threaded-burst note: because JS has one thread, this synchronous burst
+     *   can never interleave with a real rAF frame — but if the host's own
+     *   loop is still running (`loop.start()`), wall-clock time keeps accruing
+     *   in ITS accumulator while this call executes; the NEXT rAF frame after
+     *   the burst sees that gap and the loop's existing `maxAccumulator` clamp
+     *   absorbs it exactly as it would absorb any other slow-frame gap (up to
+     *   8 substeps, additional time dropped) — `runTicks` does not need to
+     *   (and does not) touch the accumulator itself to make this safe.
+     * - **`opts.render`** (default `'last'`): `'last'` skips the `preRender`/
+     *   `render` phases for ticks `0..n-2` and runs the full phase list
+     *   (including `preRender`/`render`) on the final tick only — the GGPO
+     *   tick-without-render pattern. `'all'` renders every tick. `'none'`
+     *   never renders, not even the last tick. `tick`/`simT`/
+     *   `stateBridge.bump()`/the debug event ring advance identically on
+     *   EVERY tick regardless of `render` — only the paint-affecting phases
+     *   are skipped, so state watchers (`useWorldState`, debug state providers)
+     *   stay correct even when fast-forwarding with no visible output.
+     * - **Refuses while paused.** Throws a structured `DebugError`
+     *   (`code: 'RUN_TICKS_PAUSED'`) if `Game.play.paused` is true —
+     *   `Game.play.step()` owns stepping the frozen set; `runTicks` is a
+     *   running-game primitive, not a paused-world stepper, and silently
+     *   no-op-ing or silently ignoring pause would violate the "byte-identical
+     *   across doors" contract this primitive exists to provide.
+     * - **Does not bypass the input focus gate.** Every tick's `input` phase
+     *   runs through the SAME `InputManager` every other call to `runFrame`
+     *   does — a gated virtual actuation (page unfocused, Game tab inactive)
+     *   still reports `{delivered: false, reason}` exactly as it would under
+     *   normal play; `runTicks` has no special-cased "force focus" behavior.
+     */
+    runTicks(n: number, opts?: RunTicksOptions): void;
+    /**
+     * ADAPTER-MOUNT surface, not game-facing: an adapter's `mount()` calls
+     * this (via `host.game` — the classic `SetupThreeRootAdapter` and the R3F
+     * `createR3FRootContext` both do) to load the game-owned input map ONCE,
+     * even when several roots ask for the same path; competing paths throw
+     * (input is game-owned, so roots cannot load competing maps). GAME code
+     * never calls this — a project's map loads automatically at mount from
+     * the conventional `/inputmaps/default.inputmap.json` (or the adapter's
+     * configured `inputMapPath`); runtime additions go through
+     * `ctx.input.registerAction` instead.
+     */
+    loadInputMap(path: string): Promise<void>;
+    /** Release game-owned resources after every mounted root has disposed. */
+    dispose(): void;
+}
+/**
+ * Construct the (host-internal) Game shell. Callers: `createGameRuntime`
+ * builds this BEFORE mounting its one adapter, then registers the default
+ * three world once mount resolves (see `registerThreeRoot` in
+ * `create-runtime.ts`).
+ */
+export declare function createGame(opts: {
+    loop: GameLoop;
+    assets: AssetCache;
+    playtest?: PlaytestContext | null | undefined;
+    /** D15 (T-D15.1) — the root seed `ctx.random` boots from, on every world
+     *  mounted onto this Game. Defaults to `DEFAULT_SEEDED_RANDOM_SEED` (a
+     *  fixed, non-wall-clock constant — `ctx.random` is always reproducible
+     *  on its own terms, whether or not the project's manifest DECLARES that
+     *  reproducibility as a contract). The manifest-aware boot path
+     *  (`mount-manifest.ts`'s `mountManifestRoots`) is what actually resolves
+     *  `manifest.determinism.defaultSeed`/`?vgai-seed=`/explicit config and
+     *  passes the result here, BEFORE any world's `mount()`/`setup()` runs —
+     *  `createGameRuntime` always constructs the Game (this call) first (see
+     *  this function's own doc comment below). */
+    seed?: number | undefined;
+}): 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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"}