@vgai/engine 0.5.8 → 0.5.10

package/src/adapter/ingest/contract-debug-adapter.ts

@@ -0,0 +1,110 @@
+/**
+ * Projects a game's DECLARED system surface (`window.vgaiGame.systems`, see
+ * `game-contract.ts`) onto the host's existing {@link DebugAdapter} — the one
+ * seam `game.commands()` / `game.state()` / `game.providers()` already read
+ * through for first-party content (`command-listener.ts`'s
+ * `dispatchBridgeMethod` → `getActiveSystems().debug`).
+ *
+ * Why a projection rather than a second door: an agent driving an ingested
+ * game must not have to learn a parallel vocabulary. A first-party game
+ * registers verbs with `ctx.debug.registerCommand`; an ingested game declares
+ * them in its entry shim. Both arrive at the SAME `DebugAdapter`, so every
+ * consumer downstream — the CLI's `vgai eval`, `@vgai/e2e`'s `GameClient`, the
+ * editor's Debug Console and State Watch panels — works unchanged and unaware
+ * of the provenance.
+ *
+ * What this deliberately does NOT do:
+ * - **Validate arguments.** The first-party path validates against a declared
+ *   Zod tuple; a shim beside a foreign game is plain JS and has none. A verb
+ *   validates itself and throws its own error, which surfaces wrapped as
+ *   `DEBUG_COMMAND_FAILED` — the host never invents a schema to check against.
+ * - **Fabricate an event ring.** There is no tick loop behind an ingested
+ *   game's declarations, so `events()` is empty. That is accurate (nothing was
+ *   emitted), not a stub standing in for a missing feature.
+ */
+
+import { DebugError } from '../../runtime/debug-registry';
+import type { DebugAdapter, DebugCommandInfo, TickStampedEvent } from '../system-adapter';
+import type { VgaiGameSystems } from './game-contract';
+
+/**
+ * Build a {@link DebugAdapter} over a declared system surface, or `null` when
+ * the game declared no verbs and no state. `null` is the honest floor: the
+ * bridge then reports `DEBUG_ADAPTER_UNAVAILABLE` exactly as it did before,
+ * rather than serving an empty adapter that reads as "this game has no state"
+ * when the truth is "this game declared nothing".
+ */
+export function createContractDebugAdapter(
+  systems: VgaiGameSystems | undefined | null,
+): DebugAdapter | null {
+  const commandList = systems?.commands ?? [];
+  const providerList = systems?.state ?? [];
+  if (commandList.length === 0 && providerList.length === 0) return null;
+
+  // Snapshot into name-keyed maps once. A later duplicate shadows an earlier
+  // one and the listing de-duplicates with it, so `commands()` can never
+  // advertise a name `invoke()` would resolve differently.
+  const byCommand = new Map(commandList.map((c) => [c.name, c]));
+  const byProvider = new Map(providerList.map((p) => [p.name, p]));
+
+  return {
+    providers: () =>
+      [...byProvider.values()].map((p) => ({ name: p.name, tier: p.tier ?? 'observable' })),
+
+    state: (name: string): unknown => {
+      const provider = byProvider.get(name);
+      if (!provider) {
+        throw new DebugError(
+          'STATE_PROVIDER_NOT_FOUND',
+          `No state provider named "${name}" is declared by this game.`,
+          { registered: [...byProvider.keys()] },
+        );
+      }
+      return provider.read();
+    },
+
+    stateAll: (): Record<string, unknown> => {
+      const out: Record<string, unknown> = {};
+      for (const [name, provider] of byProvider) {
+        // One throwing provider must not cost the caller every other reading —
+        // the same per-key isolation the first-party registry gives.
+        try {
+          out[name] = provider.read();
+        } catch (err) {
+          out[name] = { __error: String(err) };
+        }
+      }
+      return out;
+    },
+
+    commands: (): DebugCommandInfo[] =>
+      [...byCommand.values()].map((c) => ({
+        name: c.name,
+        description: c.description,
+        argsJsonSchema: c.argsJsonSchema,
+        // An ingested game runs entirely in the browser realm the host mounted
+        // it in; there is no server leg for its verbs to route to.
+        locus: 'client' as const,
+      })),
+
+    invoke: async (name: string, args: unknown[]): Promise<unknown> => {
+      const command = byCommand.get(name);
+      if (!command) {
+        throw new DebugError(
+          'DEBUG_COMMAND_NOT_REGISTERED',
+          `No command named "${name}" is declared by this game.`,
+          { registered: [...byCommand.keys()] },
+        );
+      }
+      try {
+        return await command.run(...args);
+      } catch (err) {
+        throw new DebugError('DEBUG_COMMAND_FAILED', `Command "${name}" threw: ${String(err)}`, {
+          name,
+        });
+      }
+    },
+
+    events: (): TickStampedEvent[] => [],
+  };
+}

package/src/adapter/ingest/game-contract.ts

@@ -15,7 +15,7 @@
  * endpoint by endpoint: capture infers what it can (the scene), the game
  * declares what inference can't reach (its DOM root, its session lifecycle).
  *
- * Origin (root), F17+F21 (lifecycle).
+ * Origin (root), F17+F21 (lifecycle), WO-SYS1 (systems).
  */
 
 /**
@@ -34,6 +34,62 @@ export interface VgaiGameLifecycle {
   resume?(): void;
 }
 
+/**
+ * One invokable verb the game exposes. Deliberately the SAME listing shape a
+ * first-party game gets from `ctx.debug.registerCommand`
+ * (`DebugCommandInfo`/`DebugAdapter.invoke` in `adapter/system-adapter.ts`) —
+ * an ingested game's verbs must enumerate through `game.commands()` and run
+ * through `game.command(...)` with no second vocabulary for agents to learn.
+ *
+ * `run` receives the positional argument list exactly as invoked. There is no
+ * host-side validation: the contract is plain JS declared beside a foreign
+ * game, so it cannot carry a Zod tuple the way `registerCommand` does.
+ * `argsJsonSchema` is therefore DOCUMENTATION for listing surfaces, not a
+ * gate — a verb validates its own arguments and throws its own errors.
+ */
+export interface VgaiGameCommand {
+  name: string;
+  description?: string;
+  /** JSON-Schema projection of the argument list, when the game declares one. */
+  argsJsonSchema?: unknown;
+  run(...args: unknown[]): unknown | Promise<unknown>;
+}
+
+/**
+ * One named, JSON-serializable state read — the `ctx.debug.registerStateProvider`
+ * shape. `tier` carries the same meaning as the first-party one: `observable`
+ * is a value the game already computes, `assisted` is one the shim derives.
+ */
+export interface VgaiGameStateProvider {
+  name: string;
+  tier?: 'observable' | 'assisted';
+  read(): unknown;
+}
+
+/**
+ * The game's SYSTEM surface: what its content actually IS, as opposed to how
+ * it renders. An ingested game's content is not always its scene graph — in a
+ * system-driven game the authorable content lives in the game's own model and
+ * is reached through the game's own verbs, which `root`/`lifecycle` could not
+ * express.
+ *
+ * Both members are read by exactly one consumer,
+ * `adapter/ingest/contract-debug-adapter.ts`, which projects them onto the
+ * host's ordinary `DebugAdapter` (`adapter/system-adapter.ts`) — so
+ * `game.commands()`/`game.state()` reach an ingested game through the same
+ * bridge first-party content uses, with no second vocabulary for agents to
+ * learn. That is deliberate scope: this
+ * interface describes what a foreign game's entry shim may declare, so every
+ * member here is a promise the host must already keep. A member nothing reads
+ * would be a shim author implementing a hook that is never called.
+ */
+export interface VgaiGameSystems {
+  /** Verbs, enumerated by `game.commands()` and run by `game.command(...)`. */
+  commands?: VgaiGameCommand[];
+  /** State reads, enumerated by `game.providers()` and read by `game.state(...)`. */
+  state?: VgaiGameStateProvider[];
+}
+
 export interface VgaiGameContract {
   /** Bump only on breaking shape changes; additive endpoints keep version 1. */
   contractVersion: 1;
@@ -45,6 +101,12 @@ export interface VgaiGameContract {
    */
   root?: HTMLElement;
   lifecycle?: VgaiGameLifecycle;
+  /**
+   * The game's own systems. Absent means "this game declared no system
+   * surface" — every dependent editor surface then shows a named absence, not
+   * an empty pretend-palette.
+   */
+  systems?: VgaiGameSystems;
 }
 
 /**

package/src/adapter/setup-three-root-adapter.ts

@@ -33,12 +33,14 @@ import {
 import { createSimClock, getSimClock, type SimClockInternal } from '../core/sim-clock';
 import { createSystemRunner } from '../core/system-runner';
 import { createDebugDraw } from '../dev/debug-draw';
+import { type RenderVitalsRegistration, registerRenderVitals } from '../dev/register-render-vitals';
 import {
   createRenderDebugAdapter,
   frameCaptureContextFor,
   type RenderDebugWiring,
 } from '../dev/render-debug-adapter';
 import { collectRenderMemory } from '../dev/render-memory';
+import { RENDER_SUBMIT_PHASE } from '../dev/render-vitals';
 import { createWebGLFrameCapture } from '../dev/webgl-frame-capture';
 import { createWebGLGpuTimer } from '../dev/webgl-gpu-timer';
 import { createSceneIndex } from '../ecs/scene-index';
@@ -61,6 +63,7 @@ import {
   type DebugRegistry,
   getDebugRegistry,
 } from '../runtime/debug-registry';
+import { devLayersEnabled } from '../runtime/dev-layers';
 import { disposeDebrisSubtree, type RootFrameHooks } from '../runtime/game';
 import type { EditorPreview, GameCleanup, GameContext, GameSetupFn } from '../runtime/types';
 import { type AudioContext as GameAudio, setupAudio } from '../setup/setup-audio';
@@ -237,6 +240,10 @@ export class SetupThreeRootAdapter implements RootAdapter {
       : null;
     const viewportShading = new ViewportShadingRenderer();
     let viewportShadingMode: ViewportShadingMode = 'solid';
+    /** Top-level `renderer.render()` calls the last presentation cost — written
+     *  by the render system, read by `postFrame`. See both for why the count is
+     *  latched rather than differenced at report time. */
+    let lastPresentationPasses = 0;
 
     // --- System runner (engine-level systems) ---
     const systems = createSystemRunner(host.game?.profiler.systemObserver, 'three');
@@ -296,7 +303,8 @@ export class SetupThreeRootAdapter implements RootAdapter {
       systems.add(
         'render',
         (dt) => {
-          if (host.game?.profiler.enabled) gpuTimer?.begin();
+          const profiler = host.game?.profiler;
+          if (profiler?.enabled) gpuTimer?.begin();
           if (sparkRenderer) scene.add(sparkRenderer);
           // W4b: arm-gated frame capture wraps the real draw calls. beginPass
           // is a no-op unless a captureFrame() armed it; afterRender delivers
@@ -304,6 +312,21 @@ export class SetupThreeRootAdapter implements RootAdapter {
           // patched context — in the SAME finally as gpuTimer.end(). Spark is
           // added before this so its draws fall inside the captured frame.
           renderDebugWiring?.beforeRender();
+          // Issue #1504: CPU render submission, bracketed as its OWN profiler
+          // phase nested inside the frame's enclosing `render` phase. This is
+          // the frame's only isolated measurement of "how long did it take to
+          // hand the draws to the driver" — the `render` phase around it also
+          // contains physics-debug redraw and every other world's render work,
+          // and a system span would key the reading to this adapter's system
+          // NAME. The profiler's phase clock is a stack precisely so this
+          // bracket cannot truncate its parent (`dev/performance-profiler.ts`).
+          // It is also what makes a frame a PRESENTATION as far as the vitals
+          // fold is concerned: no draw, no bracket, no display frame.
+          profiler?.beginPhase();
+          // `info.render.frame` counts top-level renderer.render() calls and
+          // survives `info.reset()`, so its delta across the draw is how many
+          // passes the composer chain (plus shadows) actually cost.
+          const passesBefore = renderer.info.render.frame;
           try {
             viewportShading.render(
               scene,
@@ -315,6 +338,8 @@ export class SetupThreeRootAdapter implements RootAdapter {
               (mesh) => camera.layers.test(mesh.layers),
             );
           } finally {
+            profiler?.endPhase(RENDER_SUBMIT_PHASE);
+            lastPresentationPasses = renderer.info.render.frame - passesBefore;
             renderDebugWiring?.afterRender();
             sparkRenderer?.removeFromParent();
             gpuTimer?.end();
@@ -336,13 +361,25 @@ export class SetupThreeRootAdapter implements RootAdapter {
 
     const postFrame = () => {
       if (ownsInput) input.endFrame();
-      if (host.game?.profiler.enabled) {
+      // `renderer.info` is checked, not assumed: a headless/stub renderer
+      // supplies only what the runtime needs to mount, and a mount with no
+      // counters must report NOTHING rather than throw once per frame. This
+      // used to be unreachable because only the editor ever enabled the
+      // profiler; the engine enables it itself under the dev gate now (see the
+      // render-vitals seed below), so the assumption has to be paid for.
+      if (host.game?.profiler.enabled && renderer.info) {
         host.game.profiler.reportRender({
           gpuMs: gpuTimer?.poll() ?? null,
           drawCalls: renderer.info.render.calls,
           triangles: renderer.info.render.triangles,
           geometries: renderer.info.memory.geometries,
           textures: renderer.info.memory.textures,
+          // The LAST presentation's pass count, not a delta taken here: under
+          // the display-rate loop this hook runs once per fixed SUBSTEP, so a
+          // delta measured at this point would read as 0 on every substep that
+          // did not draw. Same one-frame-warm semantics as the renderer.info
+          // counters beside it.
+          renderPasses: lastPresentationPasses,
         });
       }
     };
@@ -538,6 +575,59 @@ export class SetupThreeRootAdapter implements RootAdapter {
       (host.game ? getSeededRandom(host.game) : null) ??
       createSeededRandom(DEFAULT_SEEDED_RANDOM_SEED);
 
+    // --- Live render vitals (issue #1504) -------------------------------------
+    // Engine-owned and first-party, seeded HERE like `renderDebug` above: a
+    // running game must be able to explain its own frame cost through the debug
+    // registry, with no capability to install and nothing for a game to write.
+    //
+    // THE GATE, in one place. Three conditions, and the reason for each:
+    //  1. `devLayersEnabled()` — the ONE owner of "is this a dev/editor
+    //     context" (`runtime/dev-layers.ts`). A ship build registers nothing,
+    //     subscribes to nothing, and never enables the profiler.
+    //  2. a `Game` shell exists — the readings are folded out of that game's
+    //     profiler frames, and a bare mount has no profiler to fold.
+    //  3. not headless — a headless mount registers no render system at all,
+    //     so it never brackets a submission and never presents a frame. Its
+    //     vitals could only ever read empty, and registering a door that is
+    //     structurally incapable of answering is worse than not having one.
+    //
+    // The enabled-gating question, resolved: the profiler is AUTO-ENABLED here
+    // rather than given a second, cheaper always-on counter tier. A counter
+    // tier would be a parallel measurement path — exactly the side ledger this
+    // work exists to avoid — and the profiler already has the one property
+    // that made the choice: `enabled` is a plain flag whose cost is per-frame
+    // bookkeeping the editor ALREADY pays (it sets `profiler.enabled = true`
+    // on play, `CenterDocuments.tsx`), so under the dev gate this is not a new
+    // cost, it is the same cost arriving a little earlier. Nothing here ever
+    // turns it OFF: the profiler's other owners (the Performance panel,
+    // `render-control.ts`'s perfSample) save and restore the prior state, so a
+    // dev session that enabled it at mount keeps it enabled.
+    let renderVitals: RenderVitalsRegistration | null = null;
+    const seedRenderVitals = (): void => {
+      // `editorPreview ? true : undefined`: an adapter holding an editor
+      // preview is being authored IN the editor — a dev context by
+      // definition, even when the editor SPA itself is a production build.
+      // The packaged runtime bakes `import.meta.env.DEV = false` into its
+      // prebuilt bundle, which is a fact about how the EDITOR was built, not
+      // about whether this mount is a dev session — found live: a
+      // package-native project's vitals never seeded while its dev menu,
+      // capabilities, and every project-graph dev layer ran fine. The
+      // override argument is dev-layers' own documented seam for exactly
+      // this caller-knows-better case; a standalone/ship mount (no
+      // editorPreview) still resolves purely from the build env.
+      if (!host.game || headless || !devLayersEnabled(editorPreview ? true : undefined)) return;
+      renderVitals?.dispose();
+      host.game.profiler.enabled = true;
+      renderVitals = registerRenderVitals({
+        registry: debugRegistry,
+        worldId: this.id,
+        profiler: host.game.profiler,
+        scene,
+        renderer,
+      });
+    };
+    seedRenderVitals();
+
     // Snapshot of the engine-owned adapter kinds, taken right after seeding
     // and before any setup() has had a chance to run. `hotReload`/`disposeGame`
     // use this to strip every GAME-registered kind (including an override of a
@@ -740,6 +830,13 @@ export class SetupThreeRootAdapter implements RootAdapter {
       safeStep('debugRegistry.strip', () =>
         host.game ? debugRegistry.strip(this.id) : debugRegistry.strip(),
       );
+      // The strip above removes the vitals REGISTRATIONS (their provenance is
+      // this world). This ends the fold's profiler subscription — the one
+      // resource `registerRenderVitals` allocates that a strip cannot reach.
+      safeStep('renderVitals.dispose', () => {
+        renderVitals?.dispose();
+        renderVitals = null;
+      });
 
       // Release analyser taps BEFORE the audio teardown below. A consumer
       // (the editor's meter poll) should dispose its own handle, but Stop must
@@ -855,6 +952,12 @@ export class SetupThreeRootAdapter implements RootAdapter {
       // every react-door registration (whose `useEffect` cleanup never
       // re-fires to restore them after someone else's strip).
       safeStep('debugRegistry.strip', () => debugRegistry.strip(this.id));
+      // The strip above takes the ENGINE's own vitals registrations with it
+      // (they carry this world's provenance, which is what makes the game's
+      // own re-seed silent). Re-seed them before the incoming setup runs, so a
+      // warm restart does not silently cost a game its render vitals — and so
+      // the fold starts clean rather than carrying the outgoing game's frames.
+      safeStep('renderVitals re-seed', seedRenderVitals);
 
       currentCleanup = await newSetup(ctx, newEditorPreview);
     };

package/src/dev/performance-profiler.ts

@@ -35,6 +35,15 @@ export interface PerformanceRenderStats {
   readonly triangles: number;
   readonly geometries: number;
   readonly textures: number;
+  /**
+   * How many top-level `renderer.render()` submissions the last presentation
+   * took (`renderer.info.render.frame`'s delta across one draw) — a composer
+   * chain, a shadow pass and a post stack each cost one. `null` (never a
+   * fabricated 0, same rule as `gpuMs`) when no reporter counted them: a
+   * reporter that omits `renderPasses` is saying it does not know, which is
+   * different from saying nothing was drawn.
+   */
+  readonly renderPasses: number | null;
 }
 
 export interface PerformanceFrame {
@@ -75,13 +84,7 @@ export interface PerformanceSnapshot {
   readonly phases: readonly PerformanceTiming[];
   readonly systems: readonly PerformanceTiming[];
   readonly components: readonly PerformanceTiming[];
-  readonly render: {
-    readonly gpuMs: number | null;
-    readonly drawCalls: number;
-    readonly triangles: number;
-    readonly geometries: number;
-    readonly textures: number;
-  };
+  readonly render: PerformanceRenderStats;
 }
 
 const now = () => globalThis.performance?.now() ?? Date.now();
@@ -110,15 +113,27 @@ export function createPerformanceProfiler(initiallyEnabled = false) {
   let frameId = 0;
   let frameStart = 0;
   let lastFrameStart = 0;
-  let phaseStart = 0;
+  /**
+   * Phase start times, innermost last. A STACK rather than the single slot
+   * this used to be, because phases NEST: the three adapter brackets its CPU
+   * render submission as its own phase (`render.submit`,
+   * `dev/render-vitals.ts`) from inside the frame's enclosing `render` phase.
+   * With one slot the inner `beginPhase()` overwrote the outer's start, so the
+   * outer `endPhase('render')` measured only the tail after the inner phase —
+   * silently under-reporting the very phase the inner one was decomposing.
+   * Balanced callers are unaffected; `endPhase` with an empty stack falls back
+   * to `frameStart` rather than a stale start from a previous frame.
+   */
+  const phaseStack: number[] = [];
   let systemStart = 0;
   let componentStart = 0;
-  let render = {
-    gpuMs: null as number | null,
+  let render: PerformanceRenderStats = {
+    gpuMs: null,
     drawCalls: 0,
     triangles: 0,
     geometries: 0,
     textures: 0,
+    renderPasses: null,
   };
   let snapshot: PerformanceSnapshot = {
     enabled,
@@ -188,15 +203,28 @@ export function createPerformanceProfiler(initiallyEnabled = false) {
       currentComponents.clear();
       frameSystems = [];
       frameComponents = [];
-      render = { gpuMs: null, drawCalls: 0, triangles: 0, geometries: 0, textures: 0 };
+      // A frame that threw mid-phase leaves entries on the stack; a fresh
+      // frame starts from nothing rather than inheriting them.
+      phaseStack.length = 0;
+      render = {
+        gpuMs: null,
+        drawCalls: 0,
+        triangles: 0,
+        geometries: 0,
+        textures: 0,
+        renderPasses: null,
+      };
       frameStart = now();
     },
     beginPhase() {
       if (!enabled) return;
-      phaseStart = now();
+      phaseStack.push(now());
     },
     endPhase(name: string) {
       if (!enabled) return;
+      // See `phaseStack`: pop restores the ENCLOSING phase's own start, so a
+      // nested bracket measures itself without truncating its parent.
+      const phaseStart = phaseStack.pop() ?? frameStart;
       const elapsed = now() - phaseStart;
       const existing = currentPhases.get(name);
       // Accumulate ms across re-entries of the same phase, but keep the FIRST
@@ -247,6 +275,9 @@ export function createPerformanceProfiler(initiallyEnabled = false) {
       triangles: number;
       geometries: number;
       textures: number;
+      /** Omit when this reporter does not count passes — see
+       *  {@link PerformanceRenderStats.renderPasses}. */
+      renderPasses?: number;
     }) {
       if (!enabled) return;
       render = {
@@ -255,6 +286,10 @@ export function createPerformanceProfiler(initiallyEnabled = false) {
         triangles: render.triangles + stats.triangles,
         geometries: render.geometries + stats.geometries,
         textures: render.textures + stats.textures,
+        renderPasses:
+          stats.renderPasses === undefined
+            ? render.renderPasses
+            : (render.renderPasses ?? 0) + stats.renderPasses,
       };
     },
     endFrame() {