@vgai/engine 0.5.2 → 0.5.3

package/src/runtime/debug-registry.ts

@@ -1,22 +1,21 @@
 /**
- * The game-scoped debug/synthetic-player registry (`docs/SYNTHETIC-PLAYER-SPEC.md`
- * §3.1). ONE registry per `Game` root — every world's `ctx.debug` (see
- * `DebugCtxSurface`, `runtime/types.ts`) feeds the SAME registry via
- * {@link DebugRegistry.forWorld}, so a name a game registers is visible (and
- * name-collision-checked) across every world, not just the one that
+ * The game-scoped debug/synthetic-player registry. ONE registry per `Game` root —
+ * every world's `ctx.debug` (see `DebugCtxSurface`, `runtime/types.ts`) feeds the
+ * SAME registry via {@link DebugRegistry.forRoot}, so a name a game registers is
+ * visible (and name-collision-checked) across every world, not just the one that
  * registered it. `createGame` (`runtime/game.ts`) constructs the registry
- * alongside the state bridge and files it in the `Game -> DebugRegistry`
- * WeakMap this module owns; later consumers (the react `useDebugProvider`/
+ * alongside the state bridge and files it in the `Game -> DebugRegistry` WeakMap
+ * this module owns; later consumers (the react `useDebugProvider`/
  * `useDebugCommand` hooks, editor panels) reach it via {@link getDebugRegistry}
  * rather than threading it through every call site.
  *
  * Provenance note: a registration's "world" is the MOUNT's adapter id (the
- * `fromSetup(id, ...)` / `VgaiSceneConfig.id` a project already names each
- * world's entry with) rather than the `WorldInstance.id` `registerThreeWorld`
+ * `fromSetup(id, ...)` / `SetupThreeRootConfig.id` a project already names each
+ * world's entry with) rather than the `RootInstance.id` `registerThreeRoot`
  * assigns — that id isn't known until AFTER `mount()` resolves (`create-
- * runtime.ts` calls `registerThreeWorld` with it only once `mount()` returns),
+ * runtime.ts` calls `registerThreeRoot` with it only once `mount()` returns),
  * which is after every `setup()`-time registration has already run. For the
- * single-world case (nearly every project today) this is simply `'vgai-scene'`;
+ * single-world case (nearly every project today) this is simply `'setup-three'`;
  * a multi-world manifest names each world's adapter to match its declared id
  * by convention, so collision messages stay meaningful in practice.
  */
@@ -46,6 +45,26 @@ export class DebugError extends Error {
 const REGISTRATION_HINT =
   'ctx.debug.registerStateProvider(name, fn) — see the template example component';
 
+/** A thrown value flattened to JSON-SAFE fields. Every caller of a debug
+ *  command is on the far side of a JSON boundary — the editor session relay
+ *  (`POST /__editor/command`) and `page.evaluate` both serialize the error's
+ *  `data` bag — and an `Error` stringifies to `{}` there, so a command's own
+ *  refusal text ("no such waypoint") vanished and the developer at
+ *  `vgai eval` saw only `debug: command "x" threw`. The text has to travel as
+ *  plain strings, and in the `message` above all: that is the one field every
+ *  client (`SessionError`, the CLI's own error print) actually surfaces. */
+function describeCause(cause: unknown): {
+  causeName: string;
+  causeMessage: string;
+  causeStack?: string;
+} {
+  if (cause instanceof Error) {
+    const described = { causeName: cause.name, causeMessage: cause.message };
+    return cause.stack === undefined ? described : { ...described, causeStack: cause.stack };
+  }
+  return { causeName: typeof cause, causeMessage: String(cause) };
+}
+
 /** Task 2.2 — how long `invoke()` waits for a `locus: 'server'` command's
  *  `__vgai:debugCommandResult` reply before failing loudly. */
 const SERVER_COMMAND_TIMEOUT_MS = 10_000;
@@ -54,7 +73,7 @@ const SERVER_COMMAND_TIMEOUT_MS = 10_000;
  *  actuates through — the SAME three methods `InputManager` exposes
  *  (`setVirtualAction`/`tapVirtualAction`/`clearVirtualActions`, Task 1.4),
  *  typed narrowly here so this module never imports `InputManager` itself.
- *  Wired once by the hosting adapter (`vgai-scene-game-adapter.ts`, at the
+ *  Wired once by the hosting adapter (`setup-three-root-adapter.ts`, at the
  *  same seed spot as `setInputActionsSource`) — absent until then. */
 export interface DebugVirtualInputTarget {
   setVirtualAction(
@@ -63,9 +82,9 @@ export interface DebugVirtualInputTarget {
   ): { delivered: boolean; reason?: string };
   tapVirtualAction(action: string): { delivered: boolean; reason?: string };
   clearVirtualActions(): void;
-  /** D15/T-D15.5 (`docs/D15-DETERMINISM-DESIGN.md` §2.c) — schedule a virtual
-   *  actuation for a specific future (or current) tick, applied at the start
-   *  of that tick's input phase (composes with `runTicks`). */
+  /** D15/T-D15.5 — schedule a virtual actuation for a specific future (or
+   *  current) tick, applied at the start of that tick's input phase (composes
+   *  with `runTicks`). */
   scheduleActionAtTick(
     tick: number,
     action: string,
@@ -85,8 +104,8 @@ export interface DebugVirtualInputTarget {
 }
 
 /**
- * D15/T-D15.5 — the `input.trace` builtin provider's shape (docs/D15-
- * DETERMINISM-DESIGN.md §2.c's format sketch). `seed`/`fixedDt` are
+ * D15/T-D15.5 — the `input.trace` builtin provider's shape.
+ * `seed`/`fixedDt` are
  * replay-critical metadata a future SP5 consumer needs BESIDE the raw
  * per-tick action deltas (`ticks`, straight off `InputManager.getInputTrace()`)
  * to know what to replay the trace AGAINST — recording deltas alone is not
@@ -132,12 +151,12 @@ interface PendingServerCommand {
  *  (spec §3.1's "react-world registration door" paragraph), so all of them
  *  share this one provenance string; a name collision between two DIFFERENT
  *  react components is therefore the same-world "replace + warn once" case,
- *  never the cross-world throw (which is reserved for a GameComponent world
+ *  never the cross-world throw (which is reserved for a first-party world
  *  vs. the react door genuinely disagreeing about a name).
  *
  *  Defect 7 fix: this used to be the bare string `'react'`, which collided in
  *  provenance with a manifest world literally named `'react'` (e.g. a
- *  `kind: 'react'` world whose `id` is `"react"`) — `forWorld('react')` and
+ *  `kind: 'dom'` world whose `id` is `"react"`) — `forRoot('react')` and
  *  the react door would then be treated as the SAME world for collision
  *  purposes, which is wrong (they are genuinely different registrants that
  *  happen to share a display name). Namespaced like `'__engine__'` so no
@@ -167,14 +186,14 @@ interface CommandEntry {
 
 /** What {@link createDebugRegistry} returns — the adapter half (`DebugAdapter`,
  *  for `SystemAdapters.debug`) plus the registration/lifecycle surface the
- *  hosting adapter (`vgai-scene-game-adapter.ts`) and `createGame` drive. */
+ *  hosting adapter (`setup-three-root-adapter.ts`) and `createGame` drive. */
 export interface DebugRegistry {
   /** The `SystemAdapters.debug` implementer — one shared instance, seeded
    *  onto every world's adapter bag. */
   readonly adapter: DebugAdapter;
   /** Build the `ctx.debug` surface for one world/mount — registrations made
    *  through it carry `worldId` as their provenance for collision messages. */
-  forWorld(worldId: string): DebugCtxSurface;
+  forRoot(worldId: string): DebugCtxSurface;
   /** Emit from a React root through the same tick-stamped event ring as
    *  `ctx.debug.emit`. React roots have no setup context, so
    *  `useDebugEmit()` calls this dedicated door instead of reaching through
@@ -208,7 +227,7 @@ export interface DebugRegistry {
    *  exist yet when the registry is constructed (`createGame`, before any
    *  world mounts). Before ANY source is set, `input.actions` reads `[]`;
    *  once one or more roots have registered, the built-in `input.actions`
-   *  provider reads the DEFAULT world's (see {@link resolveInputWorldId}) —
+   *  provider reads the DEFAULT world's (see {@link resolveInputRootId}) —
    *  same resolution every other per-world seam on this interface uses. */
   setInputActionsSource(worldId: string, fn: () => { name: string; valueType: string }[]): void;
   /** D15/T-D15.5 — wire the built-in `input.trace` provider to a live
@@ -218,7 +237,7 @@ export interface DebugRegistry {
    *  `{version: 1, seed: null, fixedDt: null, ticks: []}`. `seed`/`fixedDt`
    *  are the two replay-critical metadata fields the design doc's format
    *  sketch (§2.c) calls for beside the raw per-tick deltas — the wiring
-   *  adapter (`vgai-scene-game-adapter.ts`) assembles them from
+   *  adapter (`setup-three-root-adapter.ts`) assembles them from
    *  `getSeededRandom(game)?.seed`/`host.game?.loop.fixedDt` alongside
    *  `InputManager.getInputTrace()`'s own `{version, ticks}`. An `engine`
    *  (package version) stamp remains a KNOWN GAP — no build-time version
@@ -239,14 +258,14 @@ export interface DebugRegistry {
    * multi-world project — the bridge always got whichever world mounted
    * LAST, the relay always got the FIRST/default world. Now every world's
    * target is kept, keyed by `worldId`, and {@link getVirtualInputTarget}
-   * resolves ONE of them via {@link resolveInputWorldId} — the SAME
+   * resolves ONE of them via {@link resolveInputRootId} — the SAME
    * resolution the bridge and the relay both call through, so they can never
    * disagree again. An explicit `worldId` reaches that world specifically. */
   setVirtualInputTarget(worldId: string, target: DebugVirtualInputTarget): void;
   /**
    * Resolve and return a virtual-input target: `worldId` given and
    * registered → that world's; omitted → the DEFAULT world's (per
-   * {@link resolveInputWorldId} — the manifest's first/default world when a
+   * {@link resolveInputRootId} — the manifest's first/default world when a
    * `Game` is behind this registry, else the single registered world, else
    * whichever registered first), consistently, for every caller (the debug
    * bridge and the editor relay both call this — see this interface's own
@@ -277,13 +296,13 @@ export interface DebugRegistry {
   /** D15/T-D15.3/.5 — the CURRENT shared game tick (the same counter the
    *  built-in `time` provider's `tick` field reads), for a per-world
    *  `InputManager.poll(tick)` call to key its `scheduleActionAtTick`
-   *  numbering off — see `vgai-scene-game-adapter.ts`'s `systems.add('input',
+   *  numbering off — see `setup-three-root-adapter.ts`'s `systems.add('input',
    *  ...)` wiring. `0` for a bare `createDebugRegistry()` test stand-in with
    *  no real `Game`/tick counter behind it (matching `getTick`'s own
    *  constructor-supplied default in that case). */
   getGameTick(): number;
   /** React-door registration (Task 1.5, spec §3.1's "react-world
-   *  registration door") — same accumulator as `forWorld(...)
+   *  registration door") — same accumulator as `forRoot(...)
    *  .registerStateProvider`, provenance `'__react__'` (see {@link REACT_WORLD_ID}),
    *  but returns a disposer instead of requiring a separate unregister call.
    *  Calling the disposer removes the registration ONLY if it is still the
@@ -322,13 +341,13 @@ function warnOnce(
  * Construct a fresh game-scoped debug registry. `getTick`/`getSimT` are
  * suppliers (not values) so the built-in `time` provider always reads the
  * CURRENT counters — `createGame` passes closures over its own mutable
- * `tick`/`simT`, incremented in `runFrame`'s tail (T1.2). `getDefaultWorldId`
+ * `tick`/`simT`, incremented in `runFrame`'s tail (T1.2). `getDefaultRootId`
  * (D15/T-D15.5, optional) resolves the manifest's first/default world id —
- * `createGame` passes `() => (roots.length ? requireDefaultWorld().id :
+ * `createGame` passes `() => (roots.length ? requireDefaultRoot().id :
  * null)`; a bare `createDebugRegistry()` test stand-in with no `Game` behind
  * it omits it (per-world resolution then falls back to "the single
  * registered world" or "whichever registered first" — see
- * `resolveInputWorldId`). `getLoopLiveness` (issue #175, optional) supplies
+ * `resolveInputRootId`). `getLoopLiveness` (issue #175, optional) supplies
  * the REAL `GameLoop.liveness` — `createGame` passes `() => opts.loop.
  * liveness`; a bare `createDebugRegistry()` test stand-in with no loop
  * behind it omits it, and the built-in `time` provider reports `null`
@@ -338,7 +357,7 @@ function warnOnce(
 export function createDebugRegistry(opts: {
   getTick(): number;
   getSimT(): number;
-  getDefaultWorldId?(): string | null;
+  getDefaultRootId?(): string | null;
   getLoopLiveness?(): GameLoopLiveness;
 }): DebugRegistry {
   const providers = new Map<string, ProviderEntry>();
@@ -356,8 +375,8 @@ export function createDebugRegistry(opts: {
 
   let roomDeclared = false;
   // D15/T-D15.5 — per-world maps (Map preserves insertion order, which
-  // `resolveInputWorldId`'s "whichever registered first" fallback relies on
-  // when no `getDefaultWorldId` is available to disambiguate).
+  // `resolveInputRootId`'s "whichever registered first" fallback relies on
+  // when no `getDefaultRootId` is available to disambiguate).
   const inputActionsSources = new Map<string, () => { name: string; valueType: string }[]>();
   const inputTraceSources = new Map<string, () => InputTraceSnapshot>();
   const virtualInputTargets = new Map<string, DebugVirtualInputTarget>();
@@ -375,7 +394,7 @@ export function createDebugRegistry(opts: {
    *   `DEBUG_INPUT_WORLD_NOT_FOUND` (a caller mistake — distinct from
    *   "nothing mounted yet", which returns `null` below instead of throwing).
    * - `explicit` omitted: the manifest's first/default world id
-   *   (`opts.getDefaultWorldId()`) iff that world has actually registered —
+   *   (`opts.getDefaultRootId()`) iff that world has actually registered —
    *   else (no `Game`/no default resolvable, or the default world never
    *   wired one — e.g. a foreign/opaque mount) the single registered world,
    *   or, with more than one and no resolvable default, whichever registered
@@ -384,7 +403,7 @@ export function createDebugRegistry(opts: {
    *   instead of "whichever mounted last".
    * - Nothing registered at all: `null`.
    */
-  function resolveInputWorldId(explicit?: string): string | null {
+  function resolveInputRootId(explicit?: string): string | null {
     if (explicit !== undefined) {
       if (!virtualInputTargets.has(explicit)) {
         throw new DebugError(
@@ -396,11 +415,11 @@ export function createDebugRegistry(opts: {
       }
       return explicit;
     }
-    return resolveWorldForSource(virtualInputTargets.keys());
+    return resolveRootForSource(virtualInputTargets.keys());
   }
 
   /** The same "default world, else the one registered, else whichever
-   *  registered first" fallback {@link resolveInputWorldId} uses for the
+   *  registered first" fallback {@link resolveInputRootId} uses for the
    *  ACTUATION target, generalized over any per-world registration set
    *  (`inputActionsSources`/`inputTraceSources` included) — every one of
    *  these maps is keyed by the same world ids, populated at the same
@@ -408,10 +427,10 @@ export function createDebugRegistry(opts: {
    *  for all of them. Never throws (no explicit-id case here — the two
    *  builtin providers that call this have no way to accept a caller-chosen
    *  worldId today; see their own doc comments). */
-  function resolveWorldForSource(registered: IterableIterator<string>): string | null {
+  function resolveRootForSource(registered: IterableIterator<string>): string | null {
     const ids = [...registered];
     if (ids.length === 0) return null;
-    const defaultId = opts.getDefaultWorldId?.() ?? null;
+    const defaultId = opts.getDefaultRootId?.() ?? null;
     if (defaultId !== null && ids.includes(defaultId)) return defaultId;
     return ids[0]!;
   }
@@ -431,11 +450,11 @@ export function createDebugRegistry(opts: {
     builtin: true,
   });
   providers.set('input.actions', {
-    // Resolves to the DEFAULT world's action list (see `resolveInputWorldId`)
+    // Resolves to the DEFAULT world's action list (see `resolveInputRootId`)
     // — deterministic across every world that registers, rather than the
     // pre-D15.5 "whichever mounted last" behavior.
     fn: () => {
-      const worldId = resolveWorldForSource(inputActionsSources.keys());
+      const worldId = resolveRootForSource(inputActionsSources.keys());
       return (worldId ? inputActionsSources.get(worldId) : undefined)?.() ?? [];
     },
     tier: 'observable',
@@ -448,7 +467,7 @@ export function createDebugRegistry(opts: {
   // `input.actions` immediately above.
   providers.set('input.trace', {
     fn: () => {
-      const worldId = resolveWorldForSource(inputTraceSources.keys());
+      const worldId = resolveRootForSource(inputTraceSources.keys());
       return (
         (worldId ? inputTraceSources.get(worldId) : undefined)?.() ?? {
           version: 1,
@@ -544,12 +563,11 @@ export function createDebugRegistry(opts: {
   }
 
   /** See `DebugAdapter.events`'s doc comment (`adapter/system-adapter.ts`)
-   *  for the full contract — `sinceSeq` (when given) wins over `sinceTick`,
-   *  since it's the unambiguous one. */
-  function events(sinceTick?: number, sinceSeq?: number): TickStampedEvent[] {
-    if (sinceSeq !== undefined) return ring.filter((e) => e.seq > sinceSeq);
-    if (sinceTick === undefined) return ring.slice();
-    return ring.filter((e) => e.tick > sinceTick);
+   *  for the full contract — `seq` is the ONLY fence (the defective
+   *  `sinceTick` filter was removed). */
+  function events(sinceSeq?: number): TickStampedEvent[] {
+    if (sinceSeq === undefined) return ring.slice();
+    return ring.filter((e) => e.seq > sinceSeq);
   }
 
   /**
@@ -728,17 +746,24 @@ export function createDebugRegistry(opts: {
       try {
         return await entry.fn(...parsedArgs);
       } catch (cause) {
-        throw new DebugError('DEBUG_COMMAND_FAILED', `debug: command "${name}" threw`, { cause });
+        // `cause` stays for in-process readers; the flattened fields are what
+        // survive the wire (see `describeCause`).
+        const described = describeCause(cause);
+        throw new DebugError(
+          'DEBUG_COMMAND_FAILED',
+          `debug: command "${name}" threw: ${described.causeMessage}`,
+          { cause, ...described },
+        );
       }
     },
-    events(sinceTick?: number, sinceSeq?: number) {
-      return events(sinceTick, sinceSeq);
+    events(sinceSeq?: number) {
+      return events(sinceSeq);
     },
   };
 
   return {
     adapter,
-    forWorld(worldId: string): DebugCtxSurface {
+    forRoot(worldId: string): DebugCtxSurface {
       return {
         registerStateProvider(name, fn, providerOpts) {
           registerStateProvider(worldId, name, fn, providerOpts?.tier ?? 'observable');
@@ -796,7 +821,7 @@ export function createDebugRegistry(opts: {
       virtualInputTargets.set(worldId, target);
     },
     getVirtualInputTarget(worldId?: string) {
-      const resolved = resolveInputWorldId(worldId);
+      const resolved = resolveInputRootId(worldId);
       return resolved !== null ? (virtualInputTargets.get(resolved) ?? null) : null;
     },
     setRunTicksTarget(target: RunTicksTarget) {
@@ -821,7 +846,7 @@ export function createDebugRegistry(opts: {
     },
     registerReactCommand(name, spec, fn) {
       const token = Symbol(name);
-      // See the `forWorld().registerCommand` cast above — same reason.
+      // See the `forRoot().registerCommand` cast above — same reason.
       registerCommand(
         REACT_WORLD_ID,
         name,

package/src/runtime/dev-layers.ts

@@ -0,0 +1,40 @@
+/**
+ * THE one owner of "are dev layers enabled" (`vgai.project.json`'s `dev: true`
+ * root flag). Every reader that has to answer that question calls
+ * {@link devLayersEnabled}; there is deliberately NO second source of truth —
+ * not a module-level cached boolean, not a `globalThis` flag, not a per-host
+ * copy of the `import.meta.env` read below. A dev GUI that ships to players
+ * because two places disagreed about what "dev" means is exactly the failure
+ * this single owner exists to make impossible.
+ *
+ * Ownership, stated in one place (the build rule):
+ *  - OWNER: this function. It resolves the answer; nothing else derives it.
+ *  - SHARERS: `mountManifestRoots` (the ship gate — a dev root only mounts
+ *    when this returns true). Any future host that mounts manifest roots
+ *    itself calls this too, with its own `override`.
+ *  - TEARDOWN: none. This is a pure predicate over build config and one
+ *    caller-supplied argument — it owns no resource, allocates nothing, and
+ *    has no lifecycle to end.
+ *
+ * The three inputs, highest precedence first:
+ *  1. `override` — the explicit per-mount answer. A headless test, a capture
+ *     harness, or a host that knows better passes `true`/`false` and gets
+ *     exactly that. Passing `undefined` (or omitting it) means "decide for
+ *     me" and falls through.
+ *  2. A dev build — `import.meta.env.DEV`. The ordinary local/editor case:
+ *     dev layers are on.
+ *  3. A production build's EXPLICIT opt-in — `VITE_VGAI_DEV_LAYERS=true`.
+ *     Shipping the dev GUI in a production bundle is a real, legitimate
+ *     choice (an internal playtest build, a QA build), and it must be an
+ *     opt-in someone had to type, never something a default drifts into.
+ *
+ * Anything else — a production build with no opt-in — is `false`.
+ */
+export function devLayersEnabled(override?: boolean | undefined): boolean {
+  if (override !== undefined) return override;
+  const env = import.meta.env as
+    | { DEV?: boolean | undefined; VITE_VGAI_DEV_LAYERS?: string | undefined }
+    | undefined;
+  if (env?.DEV === true) return true;
+  return env?.VITE_VGAI_DEV_LAYERS === 'true';
+}

package/src/runtime/frame-selector-cache.ts

@@ -1,6 +1,6 @@
 /**
- * Pure, react-free frame-version cache (T7.4 slice 1 — `docs/
- * REACT-STATE-BRIDGE.md` §3). `useGameState` (`packages/editor/template/src/
+ * 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,
@@ -15,7 +15,7 @@
  * exists in this repo today; see `test/frame-selector-cache.test.ts`).
  */
 
-/** Equality comparator for `FrameSelectorCache`/`useGameState`. Defaults to
+/** Equality comparator for `FrameSelectorCache`/`useWorldState`. Defaults to
  *  `Object.is` (T7.4 §3); pass {@link shallow} for tuples/plain objects. */
 export type Equals<T> = (a: T, b: T) => boolean;
 
@@ -52,7 +52,7 @@ export interface FrameSelectorCache<T> {
   get(frameVersion: number, compute: () => T): T;
 }
 
-/** Construct a fresh per-subscriber cache. One per `useGameState` call site
+/** Construct a fresh per-subscriber cache. One per `useWorldState` call site
  *  (a fresh cache each mount — see the hook). */
 export function createFrameSelectorCache<T>(equals: Equals<T> = Object.is): FrameSelectorCache<T> {
   let hasValue = false;