@vgai/engine 0.5.14 → 0.5.16

package/src/runtime/game.ts

@@ -1,25 +1,11 @@
 /**
- * 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.
+ * The surface-neutral Game root and its declaration-ordered root registry.
+ * Three, Canvas, and DOM roots share one game-scoped loop, input manager,
+ * system runner, state bridge, debug registry, clock, and seeded RNG. Each
+ * RootInstance retains its own mounted surface and optional capabilities.
  */
 
-// TYPE-ONLY pixi import (T7.3 slice 1): `game.ts` must never value-import
+// TYPE-ONLY pixi import: `game.ts` must never value-import
 // `pixi.js` — a value import would pull the Pixi runtime into 3D-only
 // bundles that never touch a canvas root. Every pixi-typed field below is erased
 // at compile time; nothing here constructs or calls into Pixi.
@@ -48,7 +34,6 @@ import type { PhysicsRegistry } from '../physics/physics-registry';
 // TYPE-ONLY (same rule as the pixi import above): this lives under `pixi/`,
 // but `game.ts` only ever names its TYPE.
 import type { Physics2DRegistry } from '../pixi/physics-registry';
-import type { AudioContext as GameAudio } from '../setup/setup-audio';
 import {
   createDebugRegistry,
   DebugError,
@@ -89,10 +74,7 @@ const DISPLAY_RATE_PHASES: readonly SystemPhaseName[] = PHASE_ORDER.filter(
  * `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).
+ * "paused still renders" possible.
  */
 export interface PlayState {
   /** Whether the game is currently paused (game-level — see the per-world
@@ -131,11 +113,9 @@ export interface PlayState {
 
 /**
  * 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.
+ * roots are canvas-backed; `'dom'` roots own a DOM layer.
  *
- * Re-exported from `adapter/adapter-surface.ts` (T7.5) — moved there so
+ * Re-exported from `adapter/adapter-surface.ts` 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
@@ -144,7 +124,7 @@ export interface PlayState {
 export type AdapterSurface = AdapterSurfaceLeaf;
 
 /**
- * A world's per-phase frame hooks (T7.1 slice 2).
+ * A world's per-phase frame hooks.
  * 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
@@ -153,7 +133,7 @@ export type AdapterSurface = AdapterSurfaceLeaf;
 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. */
+   *  same `SystemRunner.runPhase` as its direct `mounted.update` entry. */
   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
@@ -164,14 +144,12 @@ export interface RootFrameHooks {
 
 /**
  * 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'`. */
+  /** Manifest root id. */
   readonly id: string;
   readonly kind: AdapterSurface;
-  /** Per-world play/pause semantics (D10, T7.6). Slice 1 always `true`. */
+  /** Per-world play/pause semantics. */
   readonly pausable: boolean;
   /** The RootAdapter that produced `mounted` — first-party or external.
    *  Deliberately narrower than `RootAdapter<K>` (T7.5): this field is only
@@ -195,7 +173,7 @@ export interface RootInstance {
    *  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
+  /** Kind-narrowed accessor for DOM roots: 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
@@ -214,7 +192,7 @@ export interface RootInstance {
   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
+  /** Phase-partitioned frame entry point — 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
@@ -399,8 +377,8 @@ export 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
+ * decide whether a world's `physics`/`collisions`/`camera` 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
@@ -505,13 +483,9 @@ function debrisOwnersOf(world: RootInstance): DebrisOwner[] {
 }
 
 /**
- * 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.
+ * The Game root. Owns the loop, raw-asset cache, world registry, input,
+ * and game-scoped `SystemRunner`. Surface-specific capabilities remain on
+ * their mounted roots or in the aggregated `SystemAdapters` contract.
  */
 export interface Game {
   readonly loop: GameLoop;
@@ -521,18 +495,16 @@ export interface Game {
   /** 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,
+   * The game-scoped `SystemRunner`, 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.
+   * against it), so an empty runner has no frame cost beyond dispatch.
    */
   readonly systems: SystemRunner;
-  /** Declaration-ordered. Slice 1 registers exactly one (the default
-   *  three world) — this is the SAME array reference `registerRoot`
+  /** Declaration-ordered. This is the same array reference `registerRoot`
    *  mutates, not a snapshot, so holders (e.g. `GameContext.roots`) observe
    *  later registrations. */
   readonly roots: ReadonlyArray<RootInstance>;
@@ -568,9 +540,6 @@ export interface Game {
   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
@@ -653,28 +622,18 @@ export interface GameInternal extends Game {
    *   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.
+   * A single first-party world and its direct `mounted.update(dt)` entry run
+   * the same `SystemRunner` and `postFrame` work. A `drivesOwnLoop` world is
+   * never ticked here. An opaque host-driven world (no `frame`) gets exactly
+   * one `update(dt)` call per substep, after the phase loop.
    *
    * 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
+   * is completely unaffected. `Game.play.step()` drives this function via the
+   * internal-only `onlyFrozen` mode (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
@@ -690,7 +649,7 @@ export interface GameInternal extends Game {
    * 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;
+  runFrame(dt: number, opts?: { skipRenderPhases?: boolean }): void;
   /**
    * WO-P13 — run ONE display frame's presentation pass: the registered
    * `onRenderStep` callbacks, then the `preRender` and `render` phases across
@@ -781,14 +740,6 @@ export interface GameInternal extends Game {
   dispose(): void;
 }
 
-function describeMismatch(handle: 'input' | 'audio', world: RootInstance): string {
-  return (
-    `Game.${handle}: default world "${world.id}" (kind: ${world.kind}) is not a first-party ` +
-    "mount — hoisting these to true Game ownership is a later slice's work; available only " +
-    'via a first-party default world today'
-  );
-}
-
 /**
  * Construct the (host-internal) Game shell. Callers: `createGameRuntime`
  * builds this BEFORE mounting its one adapter, then registers the default
@@ -879,7 +830,7 @@ export function createGame(opts: {
     getTick: () => tick,
     getSimT: () => simT,
     // D15/T-D15.5 — "the manifest's first/default world" for the debug
-    // registry's world-addressed input-target compatibility surface. Every
+    // registry's world-addressed input-target surface. Every
     // first-party root now registers the SAME game-owned InputManager, but the
     // stable default id still keeps explicit/implicit debug routing coherent.
     // Use the SAME "first three world, else first world" rule
@@ -913,14 +864,6 @@ export function createGame(opts: {
     return roots.find((w) => w.kind === 'three') ?? roots[0]!;
   }
 
-  function requireFirstPartyCtx(handle: 'input' | 'audio') {
-    const world = requireDefaultRoot();
-    if (!isFirstPartyMounted(world.mounted)) {
-      throw new Error(describeMismatch(handle, world));
-    }
-    return world.mounted.ctx;
-  }
-
   // --- Game.systemAdapters aggregation (§7.1-3, probe1) --------------------
   // Warn-once-per-colliding-key state, scoped to this Game instance (a fresh
   // Game gets a fresh warn history) — deliberately NOT reset by anything
@@ -1023,7 +966,7 @@ export function createGame(opts: {
   // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: the frame algorithm (now with D10's per-world pause gate + the onlyFrozen step()-only mode) is one cohesive nested loop over phases/roots — splitting it would obscure the ordering contract documented on GameInternal.runFrame
   function runFrameImpl(
     dt: number,
-    frameOpts?: { ignorePause?: boolean; onlyFrozen?: boolean; skipRenderPhases?: boolean },
+    frameOpts?: { onlyFrozen?: boolean; skipRenderPhases?: boolean },
   ): void {
     // D15 (T-D15.3) — brackets the ENTIRE frame body (every phase, every
     // world, both the `onlyFrozen` and normal branches below converge on the
@@ -1033,7 +976,6 @@ export function createGame(opts: {
     // declare `determinism.seededRandom`).
     if (rngTrapEnabled) rngTrap.enable();
     profiler.beginFrame();
-    const ignorePause = frameOpts?.ignorePause ?? false;
     // D15/T-D15.4 + WO-P13: the render-phase skip. Two callers set it, for the
     // same reason — this substep is not the thing that paints. `runTicks`'s
     // `render: 'none'|'last'` fast-forward sets it on every tick it doesn't
@@ -1048,9 +990,6 @@ export function createGame(opts: {
     // one and only caller. It ticks EXACTLY the currently-frozen set (host-driven,
     // `pausable`, and `paused`) through every phase + `endFrame`, with the REAL
     // `dt` (not the render-phase's forced `0`), and touches no other world at all
-    // — §7.1-2 fix, probe4: the previous `ignorePause` full-frame re-run ticked
-    // EVERY host-driven world, double-ticking every already-running
-    // `pausable: false` world (D10's ordinary loop never stops ticking them).
     const onlyFrozen = frameOpts?.onlyFrozen ?? false;
     // Checklist item 7: snapshot the world count ONCE at entry and iterate
     // by index in both loops below. A world registered mid-frame (e.g. from
@@ -1068,10 +1007,9 @@ export function createGame(opts: {
           break;
         }
       } else if (
-        ignorePause ||
-        (world.mounted.drivesOwnLoop
+        world.mounted.drivesOwnLoop
           ? !paused || !world.pausable || !world.mounted.setPaused
-          : !paused || !world.pausable)
+          : !paused || !world.pausable
       ) {
         inputFrameActive = true;
         break;
@@ -1169,13 +1107,12 @@ export function createGame(opts: {
           for (let i = 0; i < n; i++) {
             const world = roots[i]!;
             if (world.mounted.drivesOwnLoop) continue;
-            // D10/T7.6: a `pausable` world under an active (non-ignored) pause
+            // D10/T7.6: a `pausable` world under an active pause
             // skips every phase except `render` — its render still runs, every
             // substep, but with `dt` forced to `0` (deterministic: no
             // time-based render effect silently keeps animating a "frozen"
-            // scene). A `pausable: false` world (or any world while
-            // `ignorePause`) is unaffected.
-            const frozen = !ignorePause && paused && world.pausable;
+            // scene). A `pausable: false` world is unaffected.
+            const frozen = paused && world.pausable;
             if (frozen && phase !== SystemPhase.RENDER) continue;
             const phaseDt = frozen ? 0 : dt;
             // Checklist item 2: isolate each world's per-phase work — one
@@ -1199,7 +1136,7 @@ export function createGame(opts: {
         if (world.mounted.drivesOwnLoop) continue;
         // A fully-frozen world gets no `endFrame`/opaque-`update` call either —
         // there is nothing to "end the frame" of when nothing ran this substep.
-        const frozen = !ignorePause && paused && world.pausable;
+        const frozen = paused && world.pausable;
         if (frozen) continue;
         advanced = true;
         if (world.frame) {
@@ -1346,9 +1283,6 @@ export function createGame(opts: {
       for (const listener of systemAdapterListeners) listener();
     },
     input,
-    get audio() {
-      return requireFirstPartyCtx('audio').audio;
-    },
     state: stateBridge,
     play: {
       get paused() {
@@ -1387,11 +1321,7 @@ export function createGame(opts: {
             }
           }
         }
-        // §7.1-2 fix (probe4): tick EXACTLY the frozen (host-driven, pausable,
-        // paused) set — not `{ ignorePause: true }`, which re-ran a FULL
-        // extra frame for every host-driven world (including already-running
-        // `pausable: false` ones — a double-tick, since D10's ordinary loop
-        // never stops ticking them). See `runFrameImpl`'s `onlyFrozen` mode.
+        // Tick exactly the frozen (host-driven, pausable, paused) set.
         runFrameImpl(dt, { onlyFrozen: true });
       },
     },
@@ -1486,7 +1416,7 @@ export function createGame(opts: {
         );
       }
     },
-    runFrame(dt: number, frameOpts?: { ignorePause?: boolean; skipRenderPhases?: boolean }): void {
+    runFrame(dt: number, frameOpts?: { skipRenderPhases?: boolean }): void {
       runFrameImpl(dt, frameOpts);
     },
     runRenderFrame(alpha: number, displayDt: number): void {

package/src/runtime/mount-game.ts

@@ -17,6 +17,11 @@
 // even the 'three' convenience export is a plain function the CALLER
 // registers, not something this module wires up automatically.
 
+import {
+  installNativeDebugBindings,
+  type NativeDebugBinding,
+  nativeDebugBindingFromEntryModule,
+} from '../adapter/native-debug-module';
 import type { RootAdapter } from '../adapter/root-adapter';
 import type { ResolvedAdapterRoot } from '../manifest/load';
 import type { GameSession } from './create-runtime';
@@ -209,6 +214,15 @@ function worldIsSelfSufficient(_world: ResolvedAdapterRoot): boolean {
   return false;
 }
 
+function nativeDebugForEntry(
+  world: ResolvedAdapterRoot,
+  entryModule: unknown,
+): NativeDebugBinding[] {
+  if (entryModule === undefined || world.adapter.type !== 'builtin') return [];
+  const binding = nativeDebugBindingFromEntryModule(world.id, entryModule);
+  return binding ? [binding] : [];
+}
+
 /**
  * Mount every world declared by a `vgai.project.json` manifest onto `host
  * .container`, resolving each world's kind through the `registerAdapter`
@@ -240,6 +254,7 @@ export async function mountGameFromManifest(
   assertExportedOrInEditor();
   const manifest = resolveManifest(manifestInput);
   const entries: Record<string, MountEntry> = { ...opts.entries };
+  const nativeDebug: NativeDebugBinding[] = [];
 
   for (const world of manifest.roots) {
     if (entries[world.id] !== undefined) continue; // explicit entry always wins
@@ -250,6 +265,7 @@ export async function mountGameFromManifest(
         world.entry !== undefined && host.loadEntryModule
           ? await host.loadEntryModule(world.entry)
           : undefined;
+      nativeDebug.push(...nativeDebugForEntry(world, entryModule));
       entries[world.id] = await factory(world, { host, entryModule });
       continue;
     }
@@ -265,7 +281,7 @@ export async function mountGameFromManifest(
     );
   }
 
-  return mountManifestRoots({
+  const session = await mountManifestRoots({
     manifest,
     container: host.container,
     entries,
@@ -273,4 +289,6 @@ export async function mountGameFromManifest(
     height: host.height,
     headless: host.headless,
   });
+  installNativeDebugBindings(session.game, nativeDebug);
+  return session;
 }

package/src/runtime/mount-manifest.ts

@@ -20,8 +20,7 @@
 // `entries[id].adapter` (the caller's own module graph built it). Threejs is
 // different: `three`/
 // `SetupThreeRootAdapter` are already unconditional dependencies of every
-// caller of `createGameRuntime`'s legacy path (this same file's sibling,
-// immediately below in this directory), so wrapping a `setup` with
+// caller of `createGameRuntime`, so wrapping a `setup` with
 // `fromSetup` here adds no NEW bundle weight — only pixi/react are avoided.
 
 import { assertNever } from '../adapter/adapter-surface';
@@ -275,8 +274,9 @@ function resolveThreeAdapter(
   if (world.adapter.type === 'ingest') {
     throw new Error(
       `mountManifestRoots: world "${world.id}" (three) declares an { ingest } adapter — ` +
-        "ingest roots require the editor's dev-server-backed mount machinery (an EditorStore " +
-        "plus in-realm scene capture, see adapter-resolver.ts's resolveIngestThreeAdapter) and are " +
+        "captured ingest roots require the editor's dev-server-backed mount machinery (an EditorStore " +
+        'plus in-realm scene capture, see resolveIngestDescriptor + ' +
+        'mountThreeIngestRootFromManifest) and are ' +
         'not supported by mountManifestRoots (no porting aids, no hosted ingest routes).',
     );
   }
@@ -347,7 +347,6 @@ function buildRootMountSpec(
     zOrder: world.zOrder,
     pausable: world.pausable,
     dev: world.dev,
-    loop: world.loop,
   };
 
   // `entry`'s `kind` is guaranteed to agree with `world.kind` past the guard

package/src/runtime/types.ts

@@ -259,6 +259,28 @@ export interface GameContext {
   playtest?: PlaytestContext | null | undefined;
 }
 
+/**
+ * Services shared by component-authored roots, independent of their render
+ * surface. This is deliberately an explicit pick from {@link GameContext}:
+ * adding a subsystem to the imperative Three setup context never silently
+ * exposes it to R3F or Canvas components.
+ *
+ * `input` is nullable because it belongs to the optional `Game` host. Normal
+ * vgai project mounts always provide it; bare harnesses and foreign hosts do
+ * not. Component code therefore sees the absence in its type instead of a
+ * getter that first throws from inside a frame callback.
+ *
+ * `clock` is surface-specific and intentionally absent here. The imperative
+ * and R3F clocks can dispose `THREE.Object3D` debris; a Canvas context narrows
+ * that Three-only operation away.
+ */
+export type ComponentContextBase = Pick<
+  GameContext,
+  'systems' | 'debug' | 'random' | 'game' | 'roots' | 'playtest' | 'registerSystemAdapter'
+> & {
+  readonly input: InputManager | null;
+};
+
 /** Return value from a game setup function. */
 export interface GameCleanup {
   dispose: () => void;

package/src/setup/setup-renderer.ts

@@ -79,10 +79,9 @@ export function applyRendererSettings(
  * reload-only `antialias` option at construction and the live shadow/resolution
  * settings (via {@link applyRendererSettings}). Absent → registry defaults.
  *
- * `opts` is additive (T6.1 slice 1, D5 §1/§4): omitted
- * entirely, construction is byte-identical to before (no `alpha`/
- * `preserveDrawingBuffer` keys at all) — the legacy single-canvas host never
- * passes it. The roots path passes `alpha:true` for every stacked canvas
+ * When `opts` is omitted, construction leaves `alpha` and
+ * `preserveDrawingBuffer` at their renderer defaults. The host passes
+ * `alpha:true` for every stacked canvas
  * above the bottom one (so its clear-alpha-0 shows the layer below through
  * it) and `preserveDrawingBuffer:true` for every stacked canvas (the
  * recorded capture-tier cost, paid once here rather than re-derived later).

package/src/world3d-react/engine-bridge.ts

@@ -39,7 +39,7 @@ export const EngineBridge = createContext<EngineBridgeValue | null>(null);
  * function Player({ speed = 4.5 }) {
  *   const { input } = useGameContext();
  *   const ref = useRef<THREE.Group>(null);
- *   useFrame((_, dt) => { if (input.isPressed('move_forward')) … });
+ *   useFrame((_, dt) => { if (input?.isPressed('move_forward')) … });
  *   return <group ref={ref}><PlayerCharacter /></group>;
  * }
  * ```