@vgai/engine 0.5.5 → 0.5.6

package/dist/runtime/render-seed.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Deterministic `Math.random` seeding for render-control mode (I2 AC:
+ * "`Math.random` is deterministically seeded/stubbed page-wide before any
+ * game module executes").
+ *
+ * Deliberately a ZERO-IMPORT module (no `three`, no other engine file) so
+ * its own evaluation is instantaneous — a render-mode entry page loads this
+ * as its FIRST `<script type="module">` tag, before the tag that pulls in
+ * the actual game/runtime modules. Per the HTML module-script ordering
+ * rules, sibling `<script type="module">` tags without `async` execute in
+ * document order, and each one's own dependency graph (here, empty) is
+ * fully evaluated before the browser moves to the next tag — so calling
+ * {@link maybeInstallRenderModeRandom} from this module's importer, in a
+ * script tag placed before the game's own entry tag, guarantees every
+ * subsequent module's top-level code (and everything it does at runtime)
+ * observes the seeded generator, never the platform's real
+ * cryptographically-random `Math.random`.
+ *
+ * This module does not decide WHETHER to seed on its own (importing it has
+ * no side effect) — the caller decides, by calling
+ * {@link maybeInstallRenderModeRandom} (query-param gated) or
+ * {@link installDeterministicRandom} (unconditional) from a tiny bootstrap
+ * entry. See `packages/engine/e2e/fixture/render-seed-entry.ts` for the
+ * worked bootstrap this module is designed to be loaded from.
+ */
+/**
+ * mulberry32 — a small, fast, deterministic 32-bit PRNG. Not cryptographic;
+ * this is explicitly a determinism tool (reproducible capture), not a
+ * security primitive. Returns a function with the same call signature as
+ * `Math.random` (no arguments, `[0, 1)` float).
+ */
+export declare function createMulberry32(seed: number): () => number;
+/**
+ * Replace the global `Math.random` with a seeded, deterministic generator.
+ * Idempotent to call more than once (each call re-seeds from scratch — the
+ * last call wins), which matters for HMR-style re-execution the same way
+ * `main.ts`'s `registerAdapterSurface` guard does elsewhere in this runtime.
+ */
+export declare function installDeterministicRandom(seed: number): void;
+/** Query-param name that opts a page into render-control mode (I2 AC 4: the
+ *  mode must be unavailable/protected in normal production gameplay unless
+ *  explicitly enabled). Shared with `render-control.ts`'s own production
+ *  guard so both checks agree on the same flag. */
+export declare const RENDER_MODE_QUERY_PARAM = "vgai-render";
+/** Optional query param to pin a specific seed (default below when absent). */
+export declare const RENDER_SEED_QUERY_PARAM = "vgai-seed";
+/**
+ * Seed `Math.random` iff the page's URL opts into render mode
+ * (`?vgai-render=1`), reading an optional `?vgai-seed=<int>` override.
+ * Returns whether it seeded, purely for the caller's own diagnostics/log —
+ * the bootstrap entry doesn't need to branch on it.
+ */
+export declare function maybeInstallRenderModeRandom(location?: {
+    search: string;
+}): boolean;
+//# sourceMappingURL=render-seed.d.ts.map

package/dist/runtime/render-seed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-seed.d.ts","sourceRoot":"","sources":["../../src/runtime/render-seed.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,MAAM,CAS3D;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAE7D;AAED;;;mDAGmD;AACnD,eAAO,MAAM,uBAAuB,gBAAgB,CAAC;AACrD,+EAA+E;AAC/E,eAAO,MAAM,uBAAuB,cAAc,CAAC;AAGnD;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAC1C,QAAQ,GAAE;IAAE,MAAM,EAAE,MAAM,CAAA;CAAoB,GAC7C,OAAO,CAOT"}

package/dist/runtime/render-seed.js

@@ -0,0 +1,73 @@
+/**
+ * Deterministic `Math.random` seeding for render-control mode (I2 AC:
+ * "`Math.random` is deterministically seeded/stubbed page-wide before any
+ * game module executes").
+ *
+ * Deliberately a ZERO-IMPORT module (no `three`, no other engine file) so
+ * its own evaluation is instantaneous — a render-mode entry page loads this
+ * as its FIRST `<script type="module">` tag, before the tag that pulls in
+ * the actual game/runtime modules. Per the HTML module-script ordering
+ * rules, sibling `<script type="module">` tags without `async` execute in
+ * document order, and each one's own dependency graph (here, empty) is
+ * fully evaluated before the browser moves to the next tag — so calling
+ * {@link maybeInstallRenderModeRandom} from this module's importer, in a
+ * script tag placed before the game's own entry tag, guarantees every
+ * subsequent module's top-level code (and everything it does at runtime)
+ * observes the seeded generator, never the platform's real
+ * cryptographically-random `Math.random`.
+ *
+ * This module does not decide WHETHER to seed on its own (importing it has
+ * no side effect) — the caller decides, by calling
+ * {@link maybeInstallRenderModeRandom} (query-param gated) or
+ * {@link installDeterministicRandom} (unconditional) from a tiny bootstrap
+ * entry. See `packages/engine/e2e/fixture/render-seed-entry.ts` for the
+ * worked bootstrap this module is designed to be loaded from.
+ */
+/**
+ * mulberry32 — a small, fast, deterministic 32-bit PRNG. Not cryptographic;
+ * this is explicitly a determinism tool (reproducible capture), not a
+ * security primitive. Returns a function with the same call signature as
+ * `Math.random` (no arguments, `[0, 1)` float).
+ */
+export function createMulberry32(seed) {
+    let state = seed >>> 0;
+    return function mulberry32() {
+        state = (state + 0x6d2b79f5) | 0;
+        let t = state;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+/**
+ * Replace the global `Math.random` with a seeded, deterministic generator.
+ * Idempotent to call more than once (each call re-seeds from scratch — the
+ * last call wins), which matters for HMR-style re-execution the same way
+ * `main.ts`'s `registerAdapterSurface` guard does elsewhere in this runtime.
+ */
+export function installDeterministicRandom(seed) {
+    Math.random = createMulberry32(seed);
+}
+/** Query-param name that opts a page into render-control mode (I2 AC 4: the
+ *  mode must be unavailable/protected in normal production gameplay unless
+ *  explicitly enabled). Shared with `render-control.ts`'s own production
+ *  guard so both checks agree on the same flag. */
+export const RENDER_MODE_QUERY_PARAM = 'vgai-render';
+/** Optional query param to pin a specific seed (default below when absent). */
+export const RENDER_SEED_QUERY_PARAM = 'vgai-seed';
+const DEFAULT_RENDER_SEED = 0x9e3779b9; // golden-ratio constant — an arbitrary but fixed default
+/**
+ * Seed `Math.random` iff the page's URL opts into render mode
+ * (`?vgai-render=1`), reading an optional `?vgai-seed=<int>` override.
+ * Returns whether it seeded, purely for the caller's own diagnostics/log —
+ * the bootstrap entry doesn't need to branch on it.
+ */
+export function maybeInstallRenderModeRandom(location = window.location) {
+    const params = new URLSearchParams(location.search);
+    if (params.get(RENDER_MODE_QUERY_PARAM) !== '1')
+        return false;
+    const seedParam = params.get(RENDER_SEED_QUERY_PARAM);
+    const seed = seedParam !== null && seedParam !== '' ? Number(seedParam) : DEFAULT_RENDER_SEED;
+    installDeterministicRandom(Number.isFinite(seed) ? seed : DEFAULT_RENDER_SEED);
+    return true;
+}

package/dist/runtime/state-bridge.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Frame-versioned game state bridge (T7.4 slice 1, the D7 remainder). Components
+ * mutate state on `this` freely during ticks — there is no proxy, no dirty
+ * tracking, no event per mutation (Track A: no mirror, no sync layer). So the
+ * unit of change a subscriber can observe is the FRAME: `GameInternal.runFrame`
+ * bumps `frameVersion` and notifies subscribers at most once, at its tail, AFTER
+ * every phase of every world and every world's `endFrame` hook has run (see the
+ * wiring in `runtime/game.ts`) — mirroring the D7 "from `gameLogic` onward,
+ * every world's post-step state is readable" guarantee, extended to "after the
+ * frame, ALL state is readable".
+ *
+ * This file is plain, react-free TypeScript any consumer could use — no
+ * react import here, or anywhere under `runtime/` (the react-facing
+ * `useWorldState` hook, which DOES import React, lives at
+ * `packages/engine/src/react/world-state.tsx`).
+ *
+ * SECOND trigger for `bump()` (`Game.registerRoot`, `runtime/game.ts`): the
+ * `roots` list is also state a `useWorldState` selector can read
+ * (`g.roots.map(...)`, the T6.2 two-world-compose gate), and it changes
+ * OUTSIDE the frame loop — `registerRoot` is called as each world finishes
+ * mounting, which can happen well before the host's loop has ticked even
+ * once. Without an immediate notification here, a selector that first reads
+ * `g.roots` before every world has registered stays stuck on that stale
+ * snapshot until the next completed frame — which, on a slow/contended host
+ * or a backgrounded tab, may be arbitrarily delayed. See `registerRoot`'s
+ * own doc comment for the concrete CI failure this closes.
+ */
+/** Frame-versioned, react-free subscription surface. */
+export interface GameStateBridge {
+    /** Monotonic; bumped once per completed `runFrame`, AND once per
+     *  `Game.registerRoot` call (world-list changes are observable state too
+     *  — see this file's module doc comment). Starts at 0 before the first of
+     *  either has happened. Never treat this as a literal frame COUNT — only
+     *  "did it change" is a contract any consumer may rely on. */
+    readonly frameVersion: number;
+    /** Notified at most once per frame, after ALL phases of ALL roots (and
+     *  their `endFrame` hooks) have run. Returns an unsubscribe function. */
+    subscribe(onFrame: () => void): () => void;
+}
+/** Host-internal extension of {@link GameStateBridge}: adds `bump`, called
+ *  both by `GameInternal.runFrame` at its tail AND by `Game.registerRoot`
+ *  when the world list changes (see this file's module doc comment). NOT
+ *  part of the game-facing `Game.state` surface (typed as the narrower
+ *  `GameStateBridge` there) — games/components/hooks never call `bump`
+ *  directly; only the frame executor and the world registry do. */
+export interface GameStateBridgeInternal extends GameStateBridge {
+    /** Bump `frameVersion` by one and notify every current subscriber, in
+     *  subscription order. Subscriber errors are isolated (per-subscriber
+     *  try/catch, loud `console.error`, never swallowed silently) — mirrors
+     *  the error-isolation idiom in `ecs/component-manager.ts`'s per-component
+     *  `update()` calls: one offending subscriber must not stop its siblings
+     *  from being notified, and must not break the frame loop. */
+    bump(): void;
+}
+/**
+ * Construct a fresh bridge. One per `Game` (created alongside the other
+ * game-scoped state in `createGame`, `runtime/game.ts`).
+ */
+export declare function createStateBridge(): GameStateBridgeInternal;
+//# sourceMappingURL=state-bridge.d.ts.map

package/dist/runtime/state-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-bridge.d.ts","sourceRoot":"","sources":["../../src/runtime/state-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,wDAAwD;AACxD,MAAM,WAAW,eAAe;IAC9B;;;;kEAI8D;IAC9D,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B;6EACyE;IACzE,SAAS,CAAC,OAAO,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;CAC5C;AAED;;;;;mEAKmE;AACnE,MAAM,WAAW,uBAAwB,SAAQ,eAAe;IAC9D;;;;;kEAK8D;IAC9D,IAAI,IAAI,IAAI,CAAC;CACd;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,uBAAuB,CA8B3D"}

package/dist/runtime/state-bridge.js

@@ -0,0 +1,62 @@
+/**
+ * Frame-versioned game state bridge (T7.4 slice 1, the D7 remainder). Components
+ * mutate state on `this` freely during ticks — there is no proxy, no dirty
+ * tracking, no event per mutation (Track A: no mirror, no sync layer). So the
+ * unit of change a subscriber can observe is the FRAME: `GameInternal.runFrame`
+ * bumps `frameVersion` and notifies subscribers at most once, at its tail, AFTER
+ * every phase of every world and every world's `endFrame` hook has run (see the
+ * wiring in `runtime/game.ts`) — mirroring the D7 "from `gameLogic` onward,
+ * every world's post-step state is readable" guarantee, extended to "after the
+ * frame, ALL state is readable".
+ *
+ * This file is plain, react-free TypeScript any consumer could use — no
+ * react import here, or anywhere under `runtime/` (the react-facing
+ * `useWorldState` hook, which DOES import React, lives at
+ * `packages/engine/src/react/world-state.tsx`).
+ *
+ * SECOND trigger for `bump()` (`Game.registerRoot`, `runtime/game.ts`): the
+ * `roots` list is also state a `useWorldState` selector can read
+ * (`g.roots.map(...)`, the T6.2 two-world-compose gate), and it changes
+ * OUTSIDE the frame loop — `registerRoot` is called as each world finishes
+ * mounting, which can happen well before the host's loop has ticked even
+ * once. Without an immediate notification here, a selector that first reads
+ * `g.roots` before every world has registered stays stuck on that stale
+ * snapshot until the next completed frame — which, on a slow/contended host
+ * or a backgrounded tab, may be arbitrarily delayed. See `registerRoot`'s
+ * own doc comment for the concrete CI failure this closes.
+ */
+/**
+ * Construct a fresh bridge. One per `Game` (created alongside the other
+ * game-scoped state in `createGame`, `runtime/game.ts`).
+ */
+export function createStateBridge() {
+    let frameVersion = 0;
+    const subscribers = new Set();
+    return {
+        get frameVersion() {
+            return frameVersion;
+        },
+        subscribe(onFrame) {
+            subscribers.add(onFrame);
+            return () => {
+                subscribers.delete(onFrame);
+            };
+        },
+        bump() {
+            frameVersion++;
+            // Snapshot before iterating (same idiom as ComponentManager's
+            // per-phase `list = byPhase.get(phase)!.slice()`): a subscriber that
+            // subscribes/unsubscribes from WITHIN a notification must not affect
+            // which of ITS SIBLINGS get notified this same bump.
+            const notified = Array.from(subscribers);
+            for (const onFrame of notified) {
+                try {
+                    onFrame();
+                }
+                catch (err) {
+                    console.error('[state-bridge] subscriber threw:', err);
+                }
+            }
+        },
+    };
+}

package/dist/runtime/types.d.ts

@@ -0,0 +1,285 @@
+import type RAPIER from '@dimforge/rapier3d-compat';
+import type { EffectComposer } from 'postprocessing';
+import type * as THREE from 'three';
+import type { z } from 'zod';
+import type { SystemAdapters } from '../adapter/system-adapter';
+import type { AssetCache } from '../assets';
+import type { SeededRandom } from '../core/seeded-random';
+import type { SimClock } from '../core/sim-clock';
+import type { createSystemRunner } from '../core/system-runner';
+import type { createDebugDraw } from '../dev/debug-draw';
+import type { SceneIndex } from '../ecs/scene-index';
+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 { ParticlesContext } from '../setup/setup-particles';
+import type { Game, RootInstance } from './game';
+/**
+ * The minimal structural shape `ctx.debug.attachRoom` needs from a joined
+ * Colyseus room: just enough to send the reserved `__vgai:debugCommand`
+ * message and listen for its `__vgai:debugCommandResult` reply. Structural,
+ * not a Colyseus type import — the same seam-boundary style every other
+ * `DebugCtxSurface` member uses (no wrapper around Colyseus itself, D2).
+ * `onMessage`'s return type is `unknown` because Colyseus's own return shape
+ * (void in some client versions, an unsubscribe function in others) isn't
+ * load-bearing here: the registry calls it defensively (invokes it on detach
+ * only if it's actually a function).
+ */
+export interface DebugRoomHandle {
+    send(type: string, message?: unknown): void;
+    onMessage(type: string, cb: (message: unknown) => void): unknown;
+}
+/**
+ * Infers a `registerCommand`/`registerReactCommand`/`useDebugCommand`
+ * handler's parameter tuple from its declared Zod `args` tuple (dry-run
+ * finding, ledger — "`registerCommand` fn typing forces `unknown[]` casts"):
+ * a real `z.ZodTuple` infers its element types (`z.tuple([z.number(),
+ * z.string()])` → `(n: number, s: string) => ...`), while omitting `args`
+ * (the generic's `undefined` default) resolves to the original permissive
+ * `(...args: unknown[]) => ...` shape every command had before this generic
+ * existed. That permissive fallback is deliberate, not just a placeholder —
+ * it keeps every existing no-schema registration (including ones whose
+ * handler reads positional args the runtime never validates, since
+ * `invoke()` only parses `args` against a schema when one is declared)
+ * compiling byte-for-byte unchanged.
+ */
+export type DebugCommandArgs<T extends z.ZodTuple | undefined = undefined> = T extends z.ZodTuple ? z.infer<T> : unknown[];
+/**
+ * The authoring half of the debug/synthetic-player seam — the read/actuate half is
+ * `SystemAdapters.DebugAdapter` (`adapter/system-adapter.ts`). Callable from any
+ * `init` (one file per new provider/command), or from a react world's
+ * `useDebugProvider`/`useDebugCommand`/`useDebugEmit` hooks. Every registration feeds the ONE
+ * game-scoped registry (`runtime/debug-registry.ts`) — never a per-world accumulator.
+ */
+export interface DebugCtxSurface {
+    /** Register (or replace) a named, JSON-serializable state read. Duplicate
+     *  names from the SAME world replace + warn once; the SAME name from a
+     *  DIFFERENT world throws (`DebugError` code `DEBUG_NAME_COLLISION`). */
+    registerStateProvider(name: string, fn: () => unknown, opts?: {
+        tier?: 'observable' | 'assisted';
+    }): void;
+    /** Register (or replace) an invokable command. `locus` is REQUIRED once the
+     *  project declares a Colyseus room (`DebugRegistry.setRoomDeclared`) — a
+     *  fixture must say whether it mutates authoritative (server) or predicted
+     *  (client) state.
+     *
+     *  Generic over the declared `args` Zod tuple ({@link DebugCommandArgs}) so
+     *  `fn`'s parameters INFER from it: `registerCommand('setHp', { args:
+     *  z.tuple([z.number()]) }, (hp) => ...)` types `hp` as `number` with no
+     *  cast. Leaving `args` off keeps `fn` typed `(...args: unknown[]) => ...`,
+     *  same as before this generic existed. */
+    registerCommand<T extends z.ZodTuple | undefined = undefined>(name: string, spec: {
+        description?: string;
+        args?: T;
+        locus?: 'client' | 'server';
+    }, fn: (...args: DebugCommandArgs<T>) => unknown | Promise<unknown>): void;
+    /** Push a tick-stamped event onto the debug event ring (spec §3.3) — the
+     *  engine stamps `tick`/`simT` at emission, not at read time. */
+    emit(event: string, detail?: unknown): void;
+    /**
+     * Task 2.2 — server-locus command routing (client leg). Call once your
+     * game code has joined its Colyseus room, so `locus: 'server'` commands
+     * have somewhere to send `__vgai:debugCommand`. Returns a detach function
+     * (call on room leave/dispose) — game-scoped, last-attached room wins.
+     */
+    attachRoom(room: DebugRoomHandle): () => void;
+}
+/**
+ * All engine subsystems, passed to every game `setup(ctx)` and to each
+ * game lifecycle callback.
+ *
+ * The surface is intentionally split in two:
+ *
+ * - **Raw libraries** — the actual Three.js / Rapier / postprocessing objects.
+ *   Call their documented APIs directly; do NOT build wrappers around them.
+ * - **Engine handles** — thin VGAI-owned managers that bridge those libraries
+ *   into the phase-ordered game loop. Reach for these when you need behavior the
+ *   raw library doesn't provide (physics↔Object3D mapping, system phases, etc.).
+ */
+/** Host-supplied identity for one private play run or coordinated team test.
+ * Games may pass `roomKey` as a Colyseus filter/join option; the engine never
+ * joins a room or couples this authoring identity to a networking library. */
+export interface PlaytestContext {
+    readonly mode: 'private' | 'team';
+    readonly id: string;
+    readonly roomKey: string;
+    readonly revision: number | null;
+    readonly participantId: string | null;
+}
+export interface GameContext {
+    /** Three.js scene graph root. Add/remove any `Object3D` (meshes, lights,
+     *  groups) here. This is THE scene — there is no separate engine scene. */
+    scene: THREE.Scene;
+    /** The single render camera. Move/aim it directly, or (preferred) drive it
+     *  from game code — see the camera-precedence note below. */
+    camera: THREE.PerspectiveCamera;
+    /** The Rapier physics `World`. Step/query it, create bodies & colliders via
+     *  `ctx.rapier`. One shared world for the whole scene. */
+    rapierWorld: RAPIER.World;
+    /** The Rapier module namespace itself (`RigidBodyDesc`, `ColliderDesc`,
+     *  `Vector3`, enums, …). Use to construct physics descriptors. */
+    rapier: typeof RAPIER;
+    /** The `postprocessing` EffectComposer driving the final render. Use to
+     *  add/remove passes (bloom, vignette, …) or reach the underlying
+     *  `WebGLRenderer` via `composer.getRenderer()`. */
+    composer: EffectComposer;
+    /** Keyboard/mouse/gamepad input. Polled once per frame in the `input` phase;
+     *  read action/axis state inside your `update`. */
+    input: InputManager;
+    /** Rapier collision-event dispatcher. Register handlers with
+     *  `collisions.onCollision(...)`; it is drained each `postPhysics`. Prefer a
+     *  own handler for per-entity sensor logic. */
+    collisions: CollisionSystem;
+    /** `Object3D ↔ Rapier body/collider` registry (+ collider→Object3D reverse
+     *  index). Use to find an entity's body/collider, or the entity behind a
+     *  raw collision. Inside a component, `this.rigidBody`/`this.collider` are
+     *  pre-resolved from here. */
+    physics: PhysicsRegistry;
+    /** Procedural audio: master gain, listener, and one-shot/impact helpers.
+     *  Use for SFX and music; the listener tracks the camera. */
+    audio: GameAudio;
+    /** three.quarks particle system: the batched renderer + spawn helpers. Use
+     *  to emit runtime particle effects; declarative scene particles register
+     *  here automatically. */
+    particles: ParticlesContext;
+    /** Immediate-mode debug drawing (`line`/`box`/`sphere`/`arrow`). Drawn
+     *  objects persist until you call `debugDraw.clear()` yourself (the
+     *  adapter also clears on scene dispose/hot-reload) — nothing clears it
+     *  automatically per frame. Dev-only visualization — not for shipped
+     *  visuals. */
+    debugDraw: ReturnType<typeof createDebugDraw>;
+    /** Shared GLTF/texture cache. Use `assets.loadGLTF(...)` etc. to load+cache
+     *  models at runtime so repeated loads reuse geometry/material. */
+    assets: AssetCache;
+    /** The phase-ordered system runner. `systems.add(phase, fn)` registers a
+     *  per-frame callback. Reserve this for non-gameplay infra (audio mixers,
+     *  network send); per-entity GAMEPLAY belongs in a `useFrame` hook. */
+    systems: ReturnType<typeof createSystemRunner>;
+    /**
+     * P3 — the SIM-TIME scheduler (`core/sim-clock.ts`). `await ctx.clock.delay(n)`
+     * waits `n` seconds of the fixed loop's own time, so it pauses when the game
+     * pauses, steps when `Game.play.step()` steps, and reproduces exactly in an
+     * offline export; `ctx.clock.after(n, fn)` is the frame-exact synchronous
+     * form, and `ctx.clock.disposeAfter(obj, n)` is debris removal. Cancellation
+     * is `AbortSignal`.
+     *
+     * REQUIRED, unlike `debug`/`random` above: every world has a sim clock. When
+     * a Game hosts the mount it is the ONE game-scoped clock the fixed loop
+     * flushes; a bare harness mount with no Game shell gets a private,
+     * mount-local clock that nothing advances (so `now()` stays 0) rather than an
+     * absent field.
+     *
+     * NOT `AnimationClock` (`animation/animation-clock.ts`) — that one is the
+     * seekable cinematic playhead and runs backwards. This one is monotonic and
+     * never rewinds, which is exactly why a Promise can be bound to it. See
+     * `core/sim-clock.ts`'s header.
+     */
+    clock: SimClock;
+    /** The live scene index for this root (P2 `observe`): tag/entity-id lookup
+     *  that never traverses, plus the change signals — `entityadded`,
+     *  `entityremoved`, `tagadded`, `tagremoved`, `attributechanged` — on a plain
+     *  `EventTarget`, unsubscribed with an `AbortSignal`. Maintained from three's
+     *  own `childadded`/`childremoved` parent events, so it costs nothing on a
+     *  frame where nothing changes. See `ecs/scene-index.ts`; the one-shot
+     *  `ecs/scene-query.ts` walks remain for a single ad-hoc question. */
+    sceneIndex: SceneIndex;
+    /** Register a game-owned `SystemAdapters` capability (networking,
+     *  navigation, …) on the mounted game's adapter surface, so the editor's
+     *  introspection panels (via `getActiveSystems()`) can see it. The engine
+     *  wires the first-party physics/input/assets/audio entries itself;
+     *  capabilities the GAME owns (a Colyseus connection, a NavMeshManager)
+     *  are registered here by the game's setup. Optional capability — absent
+     *  in contexts that expose no adapter surface (some test harnesses);
+     *  call as `ctx.registerSystemAdapter?.(…)`.
+     *
+     *  Ordering contract: **game registrations always win** — the engine seeds
+     *  its first-party entries (physics/input/assets/audio) BEFORE setup()
+     *  runs, so a game that registers any of those same kinds during its own
+     *  setup overrides the engine's entry, not the other way around. This also
+     *  holds across a warm restart (`hotReload`): every kind the outgoing game
+     *  registered is stripped back to the engine's entry (or absent, for
+     *  game-only kinds like networking/navigation) before the incoming game's
+     *  setup runs, so a disposed game's adapter is never left stale on the
+     *  mounted surface. */
+    registerSystemAdapter?<K extends keyof SystemAdapters>(kind: K, adapter: SystemAdapters[K]): void;
+    /** The debug/synthetic-player authoring surface — see {@link DebugCtxSurface}.
+     *  Optional, same absence precedent as `registerSystemAdapter`: present on every
+     *  first-party mount, absent only in bare test harnesses that build a
+     *  hand-rolled `ctx`. */
+    debug?: DebugCtxSurface;
+    /**
+     * D15 (T-D15.1) — the game-scoped, named-stream seeded PRNG. `ctx.random()`
+     * draws from the `'gameplay'` stream; `ctx.random.stream('vfx')` (or any other
+     * name) draws from an INDEPENDENT stream, so a cosmetic/VFX draw can never
+     * shift the gameplay draw sequence. Use this instead of raw `Math.random()` for
+     * anything a project wants to keep reproducible; `ctx.random` itself always
+     * exists and is always internally consistent (same seed ⇒ same sequence)
+     * whether or not the project's manifest declares `determinism.seededRandom` —
+     * that flag only gates the BOOT-TIME seeding from
+     * `manifest.determinism.defaultSeed`/`?vgai-seed=`, the burn-down lint scan,
+     * and the dev-mode `Math.random` phase trap (three separate enforcers,
+     * `test/gameplay-rng-ban.test.ts` + `runtime/gameplay-rng-trap.ts`), never
+     * `ctx.random`'s mere presence. Same absence precedent as `debug` above:
+     * present on every first-party mount, optional only for bare test harnesses
+     * that build a hand-rolled `ctx`. `reseed(seed)` (future draws only) is
+     * `play.seed.set`'s eventual target (T-D15.6, not yet wired).
+     */
+    random?: SeededRandom;
+    /** The Game root — the loop, the world registry, and game-scoped handles.
+     *  Absent only in bare test harnesses that construct a partial context (the
+     *  host always sets it in `createGameRuntime`). Optional so every existing
+     *  harness that builds a hand-rolled `ctx` object keeps compiling
+     *  unmodified — the same precedent as `registerSystemAdapter`. */
+    game?: Game | undefined;
+    /** Alias for `game.roots` — the live, declaration-ordered world registry.
+     *  Same optionality/absence rule as `game` above. */
+    roots?: ReadonlyArray<RootInstance> | undefined;
+    /** The host's current private play or Team Test identity. Optional for
+     * standalone/custom hosts; networking remains game-owned and direct. */
+    playtest?: PlaytestContext | null | undefined;
+}
+/** Return value from a game setup function. */
+export interface GameCleanup {
+    dispose: () => void;
+}
+/** Context passed to setup() when launched from the editor's play mode. */
+export interface EditorPreview {
+    /** Editor viewport camera transform — use this as the initial game camera viewpoint. */
+    viewportCamera?: {
+        position: [number, number, number];
+        quaternion: [number, number, number, number];
+    };
+    /**
+     * Which bundled example the static/browser build's project picker wants to
+     * run (Adjudication H).
+     *
+     * Its one former reader — `browser-play-entry.ts`'s whole-bundle `setup()`,
+     * which dispatched over the generated `SETUP_BY_EXAMPLE_ID` table — is
+     * DELETED. Hosted dispatch is per-root (`ADAPTER_BY_EXAMPLE_ROOT` /
+     * `REACT_BY_EXAMPLE_ROOT`, resolved in `adapter-resolver.ts`) and never
+     * consults this field; `exampleDispatchFor` still sets it as the marker for
+     * "play the project's own shipped game" rather than a `?scene=` override
+     * (which sets `assetPrefix` instead — that one IS read, by
+     * `SetupThreeRootAdapter`). Every `GameSetupFn` consumer ignores it.
+     */
+    exampleId?: string | undefined;
+    /**
+     * Asset prefix for the static/browser build's GENERIC scene-loader fallback,
+     * set INSTEAD of `exampleId` when the editor has a non-default scene of a
+     * bundled example open (hosted `?project=<id>&scene=<project-relative>` —
+     * Track H): the open scene plays via `sceneData`, but its relative asset
+     * refs still live under the example's staged `/examples/<id>/` public root.
+     * Ignored whenever `exampleId` is set; undefined ⇒ root prefix `/`.
+     */
+    assetPrefix?: string | undefined;
+}
+/** A game setup function: receives engine context, returns cleanup.
+ *
+ * This is the MOUNT body of the FIRST-PARTY implementer. The host no longer
+ * depends on it — the host depends on `RootAdapter` (`@engine/adapter`), and
+ * `GameSetupFn` is wrapped into a `SetupThreeRootAdapter` via `fromSetup`.. (The
+ * former `RootAdapter` `{ setup, components }` interface lived here; it is
+ * superseded by the real adapter interfaces in `@engine/adapter`.) */
+export type GameSetupFn = (ctx: GameContext, editor?: EditorPreview) => Promise<GameCleanup>;
+//# sourceMappingURL=types.d.ts.map

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

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

package/dist/runtime/types.js

@@ -0,0 +1 @@
+export {};

package/dist/runtime/unexported-game-trap.d.ts

@@ -0,0 +1,36 @@
+/**
+ * THE UNEXPORTED-GAME TRAP: a dev-served standalone game page REFUSES to boot.
+ *
+ * Owner decision (2026-08-09): until a game is EXPORTED, it is never played
+ * outside the editor. The editor is the one authoring, viewing and
+ * verification surface; the standalone page exists to serve the exported
+ * artifact, not to be a second door during development.
+ *
+ * Why this is a trap in CODE and not a rule in prose: the rule already
+ * existed, and it drifted. When an editor session broke mid-task, an agent
+ * "temporarily" switched to `npm run game`, the fallback fed its whole
+ * feedback loop (pixels for screenshots), nothing broken ever pushed it back,
+ * and hours of verification ran outside the editor without anyone deciding
+ * that. A workaround whose cost lands outside the loop that chose it is
+ * sticky; the only fix that holds is for the workaround PATH ITSELF to fail
+ * immediately, loudly, and with the way back in its hands. That is this file.
+ *
+ * The boundary is DEV-SERVED vs EXPORTED, decided by the bundler: a Vite dev
+ * server strips nothing, so `import.meta.env.DEV` is true; a production build
+ * (`vite build` — what `vgai deploy` runs) compiles it false and this module
+ * costs an exported game nothing. Headless contexts (unit tests, playtest's
+ * node leg) have no real browser page and never trip it — the check requires
+ * a document whose `defaultView` is the window, which no test stub wires up.
+ *
+ * There is deliberately NO opt-out flag, env var, or query param. An escape
+ * hatch an agent can reach for is the workaround again, one hop later.
+ */
+/**
+ * Throws (and paints a full-screen refusal, so a human at the tab sees it as
+ * immediately as a harness watching the console does) when an unexported game
+ * is being mounted on a dev-served page. Called by `mountGameFromManifest`
+ * before any root is resolved; exported builds and headless tests pass
+ * through untouched.
+ */
+export declare function assertExportedOrInEditor(): void;
+//# sourceMappingURL=unexported-game-trap.d.ts.map

package/dist/runtime/unexported-game-trap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unexported-game-trap.d.ts","sourceRoot":"","sources":["../../src/runtime/unexported-game-trap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AA4BH;;;;;;GAMG;AACH,wBAAgB,wBAAwB,IAAI,IAAI,CAoB/C"}