@vgai/engine 0.2.0 → 0.4.0-canary.20260715.0

package/src/runtime/debug-bridge.ts

@@ -0,0 +1,483 @@
+/**
+ * The standalone in-page debug bridge (`docs/SYNTHETIC-PLAYER-SPEC.md` §3.4,
+ * D17/D18; Task 2.1 of `docs/ACCEPTANCE-DRIVER-BUILD-PLAN.md`). Query-gated
+ * `window.__vgai`, the same production-protection-lives-in-the-installer
+ * pattern `render-control.ts`'s `installRenderControlHarness` established for
+ * `?vgai-render=1` (production protection lives HERE, not just at whatever
+ * call site invokes this — a caller that calls
+ * {@link maybeInstallDebugBridge} unconditionally on every boot still only
+ * ever gets a handle when the gate below actually passes).
+ *
+ * D17: this is door (a) of the seam's three doors — the SAME `DebugAdapter`
+ * names/JSON the editor relay (door b) and `@vgai/probe` (door c, which
+ * drives door (a) itself over Playwright) all read. D18: the bridge installs
+ * only when the page opts in (`?vgai-debug=1`) AND is either a dev build
+ * (`import.meta.env.DEV`) or the project's manifest explicitly opts a
+ * production build in (`manifest.debug.allowInProduction`, the described
+ * field whose runtime reader THIS module is).
+ */
+
+import type { DebugAdapter, TickStampedEvent } from '../adapter/system-adapter';
+import type { GameLoopLiveness } from '../core/types';
+import { DebugError, type DebugRegistry, type RunTicksOptions } from './debug-registry';
+
+/** Query-param name that opts a standalone page into the debug bridge (D18) —
+ *  mirrors `render-seed.ts`'s `RENDER_MODE_QUERY_PARAM` naming/shape, own
+ *  const because this is a different call site with a different flag. */
+export const DEBUG_MODE_QUERY_PARAM = 'vgai-debug';
+
+/** The subset of `ResolvedGameManifest` the D18 gate reads — typed narrowly
+ *  (not imported from `manifest/load.ts`) so this module doesn't need the
+ *  full manifest shape, just the one described field it is the runtime
+ *  reader for. */
+export interface DebugBridgeManifest {
+  readonly debug?: { readonly allowInProduction: boolean } | undefined;
+}
+
+/** The bridge's actuation surface — byte-identical method names to
+ *  `InputManager`'s virtual-action primitives (Task 1.4), reached through
+ *  `DebugRegistry.getVirtualInputTarget(worldId?)` rather than a direct
+ *  import. Every method takes an optional trailing `worldId` (D15/T-D15.5,
+ *  the review-objection-2 fix): omitted, it resolves to the SAME default
+ *  world the editor relay's `inject-input` case resolves to (one shared
+ *  resolution function, `debug-registry.ts`'s `resolveInputWorldId`) — never
+ *  "whichever world's `InputManager` happened to register last". An
+ *  explicit `worldId` reaches that world's `InputManager` specifically. */
+export interface VgaiDebugInputHandle {
+  setVirtualAction(
+    action: string,
+    value: boolean | number | { x: number; y: number },
+    worldId?: string,
+  ): { delivered: boolean; reason?: string };
+  tapVirtualAction(action: string, worldId?: string): { delivered: boolean; reason?: string };
+  clearVirtualActions(worldId?: string): void;
+  /**
+   * D15/T-D15.5 (`docs/D15-DETERMINISM-DESIGN.md` §2.c): schedule a virtual
+   * actuation for a specific tick — applied at the START of that tick's
+   * input phase, composing with `runTicks` (a schedule for tick 500 fires
+   * exactly once the sim has been driven through tick 500, regardless of
+   * burst size). A digital `true` produces a genuine `isJustPressed` edge
+   * exactly at the target tick. Throws `INPUT_ACTION_NOT_FOUND`/a valueType
+   * mismatch (same as `setVirtualAction`) or `TICK_ALREADY_PASSED`
+   * (`data.currentTick`, the NEXT tick to be serviced) for a tick that
+   * already elapsed.
+   *
+   * A scheduled tick whose input phase never runs at all (that world
+   * paused/frozen, or skipped by a multi-tick gap, when the target tick
+   * would have been serviced) DROPS the actuation rather than applying it
+   * late — it is never delivered, and there is no `{delivered: false,
+   * reason}`-shaped result to read here (the call already returned, long
+   * before the drop happens). The only observable trace is an
+   * `'input.schedule.dropped'` debug event (`{tick, action}`), readable via
+   * `state()`/`stateAll()`'s `events` or `snapshot().events`.
+   */
+  scheduleActionAtTick(
+    tick: number,
+    action: string,
+    value: boolean | number | { x: number; y: number },
+    worldId?: string,
+  ): void;
+  /** Start (or restart) recording the post-gate action-delta trace, readable
+   *  back via `state('input.trace')`/`stateAll()` (a built-in provider —
+   *  itself resolved against the DEFAULT world only; see that provider's own
+   *  doc comment in `debug-registry.ts`). */
+  startRecording(worldId?: string): void;
+  /** Stop recording — the trace accumulated so far stays readable. */
+  stopRecording(worldId?: string): void;
+  /** Whether a recording is currently active. */
+  isRecording(worldId?: string): boolean;
+  /** Accumulate a synthetic pointer delta for a named test source — mirrors
+   *  `InputManager.injectPointerDelta` (the "injected test input" seam):
+   *  multiple calls within the same frame SUM, and the accumulator clears
+   *  each frame (`endFrame`). Bindings with `valueType: 'pointerDelta'`
+   *  reading this source (`{ type: 'test_pointer_delta', sourceId }`) see the
+   *  accumulated value via `getPointerDelta`. */
+  injectPointerDelta(sourceId: string, delta: { x: number; y: number }, worldId?: string): void;
+  /** Set a synthetic absolute pointer position for a named test source —
+   *  mirrors `InputManager.injectPointerPosition`: LAST-WRITE-WINS across
+   *  contributing sources on read, and persists until changed. Bindings with
+   *  `valueType: 'pointerPosition'` reading this source (`{ type:
+   *  'test_pointer_position', sourceId }`) see it via `getPointerPosition`. */
+  injectPointerPosition(sourceId: string, value: { x: number; y: number }, worldId?: string): void;
+}
+
+/** `snapshot()`'s return shape — ONE synchronous pass over the registry, so
+ *  every field reflects the exact same instant (AC-B1.2's batched-read
+ *  primitive: a probe polling this never sees `time` from one tick and
+ *  `state` from another). */
+export interface VgaiDebugSnapshot {
+  /** `loopLiveness` (issue #175): the REAL `GameLoop.liveness` behind this
+   *  session — `'hidden-paused'` while the T2.1 idle throttle has stopped
+   *  the loop (tab hidden), `null` only when no loop is wired at all (a
+   *  bare debug-registry test stand-in with no real `Game`). Never a
+   *  fabricated `'running'`. */
+  time: { simSeconds: number; tick: number; loopLiveness: GameLoopLiveness | null };
+  state: Record<string, unknown>;
+  events: TickStampedEvent[];
+  pageErrors: string[];
+}
+
+/** The frozen `window.__vgai` shape (D18/spec §3.4) — version it if it ever
+ *  needs a breaking change; `providers`/`state`/`stateAll`/`commands`/`events`
+ *  are straight off the game's `DebugAdapter`, `invoke` re-checks D18 gating
+ *  (belt-and-braces, AC-A1.7), and `input`/`snapshot` are bridge-only. */
+export interface VgaiDebugHandle {
+  readonly version: 1;
+  providers: DebugAdapter['providers'];
+  state: DebugAdapter['state'];
+  stateAll: DebugAdapter['stateAll'];
+  commands: DebugAdapter['commands'];
+  invoke(name: string, args: unknown[]): Promise<unknown>;
+  events: DebugAdapter['events'];
+  input: VgaiDebugInputHandle;
+  /** See `DebugAdapter.events`'s doc comment for `sinceTick`/`sinceSeq`'s
+   *  contract (run-4 friction #5) — `snapshot`'s `events` member is filtered
+   *  the exact same way, just batched with `time`/`state`/`pageErrors` into
+   *  one synchronous read. */
+  snapshot(sinceTick?: number, sinceSeq?: number): VgaiDebugSnapshot;
+  /**
+   * D15/T-D15.4 door (a) (`docs/D15-DETERMINISM-DESIGN.md` §2.b): synchronously
+   * drive `n` fixed gameplay ticks via the live `Game`'s `GameInternal.runTicks`
+   * (`runtime/game.ts`) — reached through `DebugRegistry.getRunTicksTarget()`,
+   * the SAME target the editor relay's `run-ticks` case (→ `play.runTicks`,
+   * door b) calls, so behavior is byte-identical across every door (D17).
+   * Throws `DEBUG_RUN_TICKS_UNAVAILABLE` if no `Game` has wired a target yet
+   * (no world mounted); throws whatever `runTicks` itself throws otherwise
+   * (e.g. `RUN_TICKS_PAUSED`) — never a silent no-op.
+   */
+  runTicks(n: number, opts?: RunTicksOptions): void;
+  /**
+   * Collapses `input.setVirtualAction(action, true)` → wait `simSeconds` of
+   * REAL sim time (real ticks — deliberately NOT `runTicks`/fast-forward;
+   * this is the honest human-input-path proof) → `input.clearVirtualActions()`
+   * into ONE async bridge call, as a TOP-LEVEL method (not under `input`)
+   * because it needs the sim clock, not just the input target. Was 15+
+   * transport round trips over the editor relay (`@vgai/probe`'s old
+   * `GameInput.hold`: set → a 150ms-interval `waitSimTime` snapshot poll loop
+   * → clear); now one `page.evaluate`/relay call that runs the wait
+   * in-process on the page.
+   *
+   * Resolves the world's input target exactly like the other `input.*`
+   * methods (`worldId` omitted → the same default-world resolution every
+   * door on this seam shares). A gated actuation (the initial
+   * `setVirtualAction` reports `delivered:false`) clears immediately and
+   * resolves that SAME `{delivered:false, reason}` shape WITHOUT waiting —
+   * matching `setVirtualAction`'s own gated-result contract. If the live
+   * game's sim clock stalls while waiting (play stopped/paused mid-hold),
+   * the action is still cleared (never left stuck) and this resolves
+   * `{delivered:false, reason:'play stopped during hold'}` instead of
+   * hanging forever. Throws `DEBUG_INPUT_UNAVAILABLE`/
+   * `DEBUG_INPUT_WORLD_NOT_FOUND` up front, same as `input.setVirtualAction`,
+   * when no target is wired/resolvable at all.
+   */
+  holdFor(
+    action: string,
+    simSeconds: number,
+    worldId?: string,
+  ): Promise<{ delivered: boolean; reason?: string }>;
+  /**
+   * Defect 5 fix — undo everything THIS install did: remove the
+   * `error`/`unhandledrejection` window listeners it added, and delete
+   * `window.__vgai` so the registry is no longer reachable from the page.
+   * Idempotent (a second call is a harmless no-op). `mountManifestWorlds`
+   * wires this into its session's `stop()`; a caller mounting more
+   * directly (a hand-rolled host) should call it on its own teardown path.
+   */
+  uninstall(): void;
+}
+
+/** Structural `window` surface this module needs — just enough to publish
+ *  the handle and listen for page errors, typed narrowly (no `any`, no DOM
+ *  lib dependency beyond what every other runtime module already assumes). */
+export interface DebugBridgeWindowTarget {
+  addEventListener?(
+    type: 'error' | 'unhandledrejection',
+    listener: (event: { message?: string; error?: unknown; reason?: unknown }) => void,
+  ): void;
+  /** Defect 5 fix — the installer's `uninstall()` calls this (when present)
+   *  to remove the exact listener references it added via `addEventListener`
+   *  above. Optional, like `addEventListener`, so a minimal test/host stub
+   *  that never needs to uninstall can omit it. */
+  removeEventListener?(
+    type: 'error' | 'unhandledrejection',
+    listener: (event: { message?: string; error?: unknown; reason?: unknown }) => void,
+  ): void;
+  [key: string]: unknown;
+}
+
+export interface MaybeInstallDebugBridgeOptions {
+  /** The game-scoped registry (`getDebugRegistry(session.game)`) — its
+   *  `.adapter` backs every read/invoke method on the published handle, and
+   *  its `getVirtualInputTarget()` backs `input.*`. */
+  readonly registry: DebugRegistry;
+  readonly manifest: DebugBridgeManifest;
+  /** Where to read `?vgai-debug=1` from. Defaults to `window.location` when a
+   *  real `window` exists; a headless caller with no `window` at all (and no
+   *  override) gets no bridge — there's nowhere to read a URL from. */
+  readonly url?: { readonly search: string } | undefined;
+  /** Where to publish the handle and install the page-error listeners.
+   *  Defaults to the real `window`; override in a unit test to avoid
+   *  touching (or requiring) the global object. */
+  readonly window?: DebugBridgeWindowTarget | undefined;
+}
+
+const PAGE_ERROR_CAP = 100;
+
+/** `holdFor`'s in-process poll interval — this loop never leaves the page
+ *  (no transport round trip per poll, unlike `@vgai/probe`'s old
+ *  `waitSimTime`), so it can afford to be tighter than that loop's 150ms. */
+const HOLD_FOR_POLL_MS = 50;
+
+/** Consecutive `HOLD_FOR_POLL_MS` polls with the tick unchanged before
+ *  `holdFor` gives up waiting and treats the game as stopped — mirrors
+ *  `@vgai/probe`'s `WAIT_FOR_STALL_POLL_LIMIT` reasoning (`wait-for.ts`:
+ *  a genuinely frozen sim clock must never poll forever), scaled to this
+ *  faster in-process interval so the wall-clock grace period (~5s) lands in
+ *  the same neighborhood. */
+const HOLD_FOR_STALL_POLL_LIMIT = 100;
+
+/** Resolves once `simSeconds` of sim time has elapsed since the call (normal
+ *  host-loop ticks while visible; deterministic `runTicks` through the same
+ *  game phases when the host loop reports `hidden-paused`), or once the tick
+ *  has stopped changing for
+ *  `HOLD_FOR_STALL_POLL_LIMIT` consecutive polls (`stalled: true` — the loop
+ *  driving ticks stopped, e.g. play was stopped/paused). Never rejects.
+ *  Exported (not just used by `holdFor` below) so the editor relay's
+ *  `command-listener.ts` `holdFor` case can share the EXACT same
+ *  poll/stall/hidden-drive logic against its own `DebugAdapter` (reached via
+ *  `getActiveSystems().debug` rather than a `DebugRegistry`) — D17:
+ *  byte-identical behavior across doors, not two hand-copies that can
+ *  silently drift apart. */
+export function waitForHoldBudget(
+  adapter: DebugAdapter,
+  simSeconds: number,
+  driveHiddenTicks?: (n: number) => void,
+): Promise<{ stalled: boolean }> {
+  return new Promise((resolve) => {
+    const start = adapter.state('time') as {
+      simSeconds: number;
+      tick: number;
+      loopLiveness?: GameLoopLiveness | null;
+    };
+    let lastTick = start.tick;
+    let stalledPolls = 0;
+    const poll = () => {
+      const current = adapter.state('time') as {
+        simSeconds: number;
+        tick: number;
+        loopLiveness?: GameLoopLiveness | null;
+      };
+      if (current.simSeconds - start.simSeconds >= simSeconds) {
+        resolve({ stalled: false });
+        return;
+      }
+      if (current.loopLiveness === 'hidden-paused' && driveHiddenTicks) {
+        // One poll represents HOLD_FOR_POLL_MS of requested simulation
+        // progress. Keep this deterministic instead of translating scheduler
+        // jitter through a wall-clock read into a different tick count.
+        const ticks = Math.max(1, Math.round(HOLD_FOR_POLL_MS / (1000 / 60)));
+        driveHiddenTicks(ticks);
+        setTimeout(poll, HOLD_FOR_POLL_MS);
+        return;
+      }
+      stalledPolls = current.tick === lastTick ? stalledPolls + 1 : 0;
+      lastTick = current.tick;
+      if (stalledPolls >= HOLD_FOR_STALL_POLL_LIMIT) {
+        resolve({ stalled: true });
+        return;
+      }
+      setTimeout(poll, HOLD_FOR_POLL_MS);
+    };
+    setTimeout(poll, HOLD_FOR_POLL_MS);
+  });
+}
+
+function hasRealWindow(): boolean {
+  return typeof window !== 'undefined';
+}
+
+function isDebugModeRequested(url: { readonly search: string }): boolean {
+  return new URLSearchParams(url.search).get(DEBUG_MODE_QUERY_PARAM) === '1';
+}
+
+/** D18's gate: a dev build, or a production build the manifest explicitly
+ *  opted in. Read fresh on every call (not cached at install time) so
+ *  `invoke()`'s belt-and-braces re-check (AC-A1.7) is a genuine second
+ *  evaluation, not a rubber stamp of a value computed once at install. */
+function isDebugAllowed(manifest: DebugBridgeManifest): boolean {
+  return Boolean(import.meta.env?.DEV) || manifest.debug?.allowInProduction === true;
+}
+
+function buildDebugHandle(opts: {
+  registry: DebugRegistry;
+  manifest: DebugBridgeManifest;
+  window: DebugBridgeWindowTarget;
+}): VgaiDebugHandle {
+  const { registry, manifest } = opts;
+  const adapter = registry.adapter;
+
+  const pageErrors: string[] = [];
+  function pushPageError(message: string): void {
+    pageErrors.push(message);
+    if (pageErrors.length > PAGE_ERROR_CAP) pageErrors.shift();
+  }
+  // Named (not inline-anonymous) so `uninstall()` below can pass the exact
+  // same reference to `removeEventListener` (Defect 5 fix).
+  const onWindowError = (event: { message?: string; error?: unknown }) => {
+    pushPageError(event.message || String(event.error));
+  };
+  const onWindowRejection = (event: { reason?: unknown }) => {
+    pushPageError(`Unhandled promise rejection: ${String(event.reason)}`);
+  };
+  opts.window.addEventListener?.('error', onWindowError);
+  opts.window.addEventListener?.('unhandledrejection', onWindowRejection);
+
+  function requireInputTarget(method: string, worldId?: string) {
+    const target = registry.getVirtualInputTarget(worldId);
+    if (!target) {
+      throw new DebugError(
+        'DEBUG_INPUT_UNAVAILABLE',
+        `debug bridge: ${method}() has no virtual-input target wired — no default threejs ` +
+          "world has mounted yet, or this project's mount path never wired one",
+      );
+    }
+    return target;
+  }
+
+  return {
+    version: 1,
+    // None of these `DebugAdapter` methods reference `this` (they close over
+    // the registry's own private maps) — passing the references directly is
+    // safe and avoids five redundant wrapper closures.
+    providers: adapter.providers,
+    state: adapter.state,
+    stateAll: adapter.stateAll,
+    commands: adapter.commands,
+    events: adapter.events,
+    async invoke(name, args) {
+      // Belt-and-braces D18 re-check (AC-A1.7): the outer install gate
+      // already required this to be true, but a caller could hold onto this
+      // handle across an environment/manifest change — refuse loudly rather
+      // than trust a decision made once at install time.
+      if (!isDebugAllowed(manifest)) {
+        throw new DebugError(
+          'DEBUG_COMMANDS_UNSUPPORTED',
+          `debug: command "${name}" invocation refused — production build without ` +
+            'debug.allowInProduction (D18)',
+          { name },
+        );
+      }
+      return adapter.invoke(name, args);
+    },
+    input: {
+      setVirtualAction: (action, value, worldId) =>
+        requireInputTarget('setVirtualAction', worldId).setVirtualAction(action, value),
+      tapVirtualAction: (action, worldId) =>
+        requireInputTarget('tapVirtualAction', worldId).tapVirtualAction(action),
+      clearVirtualActions: (worldId) =>
+        requireInputTarget('clearVirtualActions', worldId).clearVirtualActions(),
+      scheduleActionAtTick: (tick, action, value, worldId) =>
+        requireInputTarget('scheduleActionAtTick', worldId).scheduleActionAtTick(
+          tick,
+          action,
+          value,
+        ),
+      startRecording: (worldId) =>
+        requireInputTarget('startRecording', worldId).startInputRecording(),
+      stopRecording: (worldId) => requireInputTarget('stopRecording', worldId).stopInputRecording(),
+      isRecording: (worldId) => requireInputTarget('isRecording', worldId).isInputRecording(),
+      injectPointerDelta: (sourceId, delta, worldId) =>
+        requireInputTarget('injectPointerDelta', worldId).injectPointerDelta(sourceId, delta),
+      injectPointerPosition: (sourceId, value, worldId) =>
+        requireInputTarget('injectPointerPosition', worldId).injectPointerPosition(sourceId, value),
+    },
+    snapshot(sinceTick, sinceSeq) {
+      // One synchronous pass — see VgaiDebugSnapshot's doc comment.
+      return {
+        time: adapter.state('time') as {
+          simSeconds: number;
+          tick: number;
+          loopLiveness: GameLoopLiveness | null;
+        },
+        state: adapter.stateAll(),
+        events: adapter.events(sinceTick, sinceSeq),
+        pageErrors: pageErrors.slice(),
+      };
+    },
+    runTicks(n, runTicksOpts) {
+      const target = registry.getRunTicksTarget();
+      if (!target) {
+        throw new DebugError(
+          'DEBUG_RUN_TICKS_UNAVAILABLE',
+          'debug bridge: runTicks() has no run-ticks target wired — no Game has mounted yet',
+        );
+      }
+      target.runTicks(n, runTicksOpts);
+    },
+    async holdFor(action, simSeconds, worldId) {
+      const target = requireInputTarget('holdFor', worldId);
+      const setResult = target.setVirtualAction(action, true);
+      if (!setResult.delivered) {
+        target.clearVirtualActions();
+        // `exactOptionalPropertyTypes`: don't write an explicit `reason:
+        // undefined` when the gate itself didn't supply one — omit the key
+        // entirely rather than assign `undefined` into an optional `string`
+        // property.
+        return setResult.reason !== undefined
+          ? { delivered: false, reason: setResult.reason }
+          : { delivered: false };
+      }
+      const runTicksTarget = registry.getRunTicksTarget();
+      const { stalled } = await waitForHoldBudget(
+        adapter,
+        simSeconds,
+        runTicksTarget ? (n) => runTicksTarget.runTicks(n, { render: 'last' }) : undefined,
+      );
+      target.clearVirtualActions();
+      return stalled
+        ? { delivered: false, reason: 'play stopped during hold' }
+        : { delivered: true };
+    },
+    uninstall() {
+      opts.window.removeEventListener?.('error', onWindowError);
+      opts.window.removeEventListener?.('unhandledrejection', onWindowRejection);
+      delete opts.window['__vgai'];
+    },
+  };
+}
+
+/**
+ * Install `window.__vgai` iff the page opted in (`?vgai-debug=1`) AND D18's
+ * gate passes (dev build, or manifest `debug.allowInProduction`). When the
+ * param is present but the gate fails, warns once (this single call IS the
+ * "once" — there is exactly one install attempt per boot) and installs
+ * nothing. Returns the installed handle (mostly useful for tests), or
+ * `undefined` when nothing was installed.
+ */
+export function maybeInstallDebugBridge(
+  opts: MaybeInstallDebugBridgeOptions,
+): VgaiDebugHandle | undefined {
+  const url = opts.url ?? (hasRealWindow() ? window.location : undefined);
+  if (!url) return undefined;
+  if (!isDebugModeRequested(url)) return undefined;
+
+  const windowTarget =
+    opts.window ?? (hasRealWindow() ? (window as unknown as DebugBridgeWindowTarget) : undefined);
+  if (!windowTarget) return undefined;
+
+  if (!isDebugAllowed(opts.manifest)) {
+    // biome-ignore lint/suspicious/noConsole: structured, greppable D18 signal — mirrors debug-registry.ts's own console.warn idiom.
+    console.warn(
+      '[debug] ?vgai-debug=1 ignored: production build without debug.allowInProduction (D18)',
+    );
+    return undefined;
+  }
+
+  const handle = buildDebugHandle({
+    registry: opts.registry,
+    manifest: opts.manifest,
+    window: windowTarget,
+  });
+  windowTarget['__vgai'] = handle;
+  return handle;
+}