@vgai/sdk 0.5.13 → 0.5.15

package/package.json

@@ -2,7 +2,7 @@
   "name": "@vgai/sdk",
   "author": "Volter AI, Inc.",
   "license": "Apache-2.0",
-  "version": "0.5.13",
+  "version": "0.5.15",
   "type": "module",
   "repository": {
     "type": "git",
@@ -30,7 +30,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
-    "@vgai/engine": "0.5.13",
+    "@vgai/engine": "0.5.15",
     "playwright": "^1.58.2",
     "zod": "^4.3.6"
   }

package/src/cinematic/theatre-operations.ts

@@ -31,7 +31,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import { isAbsolute, join } from 'node:path';
 import { z } from 'zod';
 import { ToolError } from '../errors.js';
-import { listProjectFiles } from '../project/shared.js';
+import { isTheatreProjectPath, listProjectFiles } from '../project/shared.js';
 import { defineTool, type ToolErrorDefinition, type ToolRegistry } from '../registry.js';
 import type { ToolContext } from '../types.js';
 
@@ -153,7 +153,7 @@ export const cinematicProjectList = defineTool({
   permission: { risk: 'read', summary: 'Walks a file tree; no writes.' },
   async impl(input, ctx) {
     const root = resolveRoot(input.root, ctx);
-    const theatreProjectFiles = listProjectFiles(root, (p) => p.endsWith('theatre-project.json'));
+    const theatreProjectFiles = listProjectFiles(root, isTheatreProjectPath);
     return { root, theatreProjectFiles };
   },
 });

package/src/mcp/mcp-server.ts

@@ -159,7 +159,7 @@ export function createMcpServer(options: CreateMcpServerOptions = {}): VgaiMcpSe
       request.params.name === 'discover-project'
         ? 'Call project.discover, project.status, and project.manifest.read. Summarize each adapter root and then call editor.session.list. Do not write files.'
         : request.params.name === 'bring-existing-game'
-          ? 'Call project.inspect before writing anything. Use its detected technologies, entry candidates, and blockers to identify Three.js/R3F, PixiJS, or React by renderer; explain the honest adapter tier and obtain consent before metadata or source writes.'
+          ? 'Call project.inspect before writing anything. Use its detected technologies, entry candidates, and blockers to identify Three.js/R3F, PixiJS, or React by renderer; name any capability the adapter has not yet reached and obtain consent before metadata or source writes.'
           : `Implement only this requested outcome: ${task}. Discover the project first, preserve unrelated work, use dryRun for file mutations when available, then verify through the exact matching editor with Play, status/logs, and a legible capture.`;
     return {
       description: requested.description,

package/src/project/discovery-operations.ts

@@ -9,7 +9,8 @@
  *  - Stories (CSF) are ordinary `.tsx`/`.ts` modules (§5.2/C3) — VGAI stores
  *    no duplicate story registry, so there is nothing to mutate here; listing
  *    `*.stories.tsx`/`*.stories.ts` is the whole B2 surface.
- *  - Theatre project state (`*.theatre-project.json`) is a real, versioned,
+ *  - Theatre project state (`theatre-project.json` or `*.theatre-project.json`)
+ *    is a real, versioned,
  *    proprietary Theatre.js format this repo does not own (§3.2/§5.3 — "the
  *    committed Theatre project state is authoritative authored data"). B2
  *    validates only the OUTER shape (`sheetsById`/`definitionVersion`/
@@ -29,6 +30,7 @@ import { z } from 'zod';
 import { ToolError } from '../errors.js';
 import { defineTool, type ToolRegistry } from '../registry.js';
 import {
+  isTheatreProjectPath,
   listProjectFiles,
   NO_PROJECT_ROOT_ERROR,
   PATH_OUTSIDE_PROJECT_ERROR,
@@ -71,7 +73,7 @@ export const projectStoryDiscover = defineTool({
 export const projectTheatreDiscover = defineTool({
   name: 'project.theatre.discover',
   summary:
-    'List every committed Theatre project-state file (*.theatre-project.json) in the project.',
+    'List every committed Theatre project-state file (theatre-project.json or *.theatre-project.json) in the project.',
   description:
     'List-only (§3.2/§5.3: the committed Theatre project state is authoritative authored data VGAI does not own the internal format of).',
   input: z.object({}),
@@ -86,9 +88,7 @@ export const projectTheatreDiscover = defineTool({
   permission: { risk: 'read', summary: 'Walks the project file tree; no writes.' },
   async impl(_input, ctx) {
     const projectRoot = requireProjectRoot(ctx);
-    const theatreProjectFiles = listProjectFiles(projectRoot, (p) =>
-      p.endsWith('.theatre-project.json'),
-    );
+    const theatreProjectFiles = listProjectFiles(projectRoot, isTheatreProjectPath);
     return { theatreProjectFiles };
   },
 });

package/src/project/manifest-operations.ts

@@ -22,6 +22,7 @@ import {
   checkNotStale,
   DryRunField,
   FILE_NOT_FOUND_ERROR,
+  isTheatreProjectPath,
   listProjectFiles,
   mutationResultSchema,
   NO_PROJECT_ROOT_ERROR,
@@ -65,7 +66,7 @@ const ProjectDiscoverResult = z
       .describe('Every *.stories.tsx / *.stories.ts found under the project.'),
     theatreProjectFiles: z
       .array(z.string())
-      .describe('Every *.theatre-project.json found under the project.'),
+      .describe('Every theatre-project.json / *.theatre-project.json found under the project.'),
   })
   .describe('A one-call survey of the project at ctx.projectRoot.');
 
@@ -115,9 +116,7 @@ export const projectDiscover = defineTool({
         projectRoot,
         (p) => p.endsWith('.stories.tsx') || p.endsWith('.stories.ts'),
       ),
-      theatreProjectFiles: listProjectFiles(projectRoot, (p) =>
-        p.endsWith('.theatre-project.json'),
-      ),
+      theatreProjectFiles: listProjectFiles(projectRoot, isTheatreProjectPath),
     };
   },
 });

package/src/project/session-journal.ts

@@ -235,16 +235,78 @@ export type SessionJournalEvent =
   /** Two epochs beating under one tabId — "Duplicate Tab" copied sessionStorage. */
   | { readonly kind: 'tab-duplicated'; readonly tabId8: string }
   /**
-   * The tab is present (its worker is beating) but its PAGE has never opened
-   * a command channel this page-load. A heartbeat proves the tab exists, not
-   * that the document works — a main thread that died after the inline
-   * bootstrap beats forever and can run nothing. Such a tab is passed over
-   * for blessing and named in the refusal.
+   * The tab is present but its PAGE never came up this page-load. Presence
+   * proves the tab exists, not that the document works — a main thread that
+   * died after the inline bootstrap keeps beating and holding its control
+   * connection, and can run nothing. Such a tab is passed over for blessing
+   * and named in the refusal.
+   *
+   * `reason` says which stage it is stuck at: `'no-channel'` (the page never
+   * opened a control connection at all) or `'no-command-listener'` (it did,
+   * and the module graph behind it never produced a listener).
    */
   | {
       readonly kind: 'tab-unresponsive';
       readonly tabId8: string;
-      readonly noChannelForMs: number;
+      readonly reason: 'no-channel' | 'no-command-listener';
+      readonly unresponsiveForMs: number;
+    }
+  /**
+   * An uncaught error or unhandled rejection in a tab's PAGE, captured by
+   * `index.html`'s inline bootstrap — before the module graph, so it is
+   * recorded even when the boot that would have reported it is the thing that
+   * died. This is the line that says WHY a `tab-unresponsive` tab is
+   * unresponsive.
+   */
+  | {
+      readonly kind: 'page-error';
+      readonly tabId8: string;
+      readonly message: string;
+    }
+  /**
+   * One batch of occurrences of ONE console error/warning condition, as the
+   * server's unresolved-console ledger recorded it
+   * (`packages/editor/server/console-ledger.ts`).
+   *
+   * This is the DURABLE half of the loudness convention, and the reason it is
+   * a row per observation rather than a row per distinct message: `count` is
+   * the running total after this batch, so the file answers "how many times
+   * did this actually fire, and when did it stop" long after the ledger (and
+   * the tab, and the server) are gone. A repeat is never filtered out here —
+   * deduping repeats to silence is precisely the failure that made a session's
+   * eleven errors read as one line and then nothing.
+   */
+  | {
+      readonly kind: 'console-entry';
+      readonly id: string;
+      readonly severity: 'error' | 'warn';
+      readonly source: string | null;
+      /** Occurrences in THIS batch. */
+      readonly added: number;
+      /** Running total for this condition, across every page-load. */
+      readonly count: number;
+      readonly message: string;
+    }
+  /** A condition cleared by the honest re-test: the page reloaded and it did
+   *  not recur. `count` is what it reached before it stopped. */
+  | {
+      readonly kind: 'console-retired';
+      readonly id: string;
+      readonly severity: 'error' | 'warn';
+      readonly count: number;
+      readonly message: string;
+    }
+  /** A condition waved through BY NAME (`vgai console ack`). The audit row is
+   *  the whole point: an acknowledgment records who and why, and never erases
+   *  what was acknowledged. */
+  | {
+      readonly kind: 'console-ack';
+      readonly id: string;
+      readonly severity: 'error' | 'warn';
+      readonly count: number;
+      readonly by: string;
+      readonly reason: string;
+      readonly message: string;
     };
 
 /** A parsed journal line: the event plus when it was appended. */
@@ -449,9 +511,22 @@ export function formatJournalLine(line: SessionJournalLine): string {
     case 'tab-duplicated':
       return `journal: ${at} tab-duplicated ${line.tabId8}`;
     case 'tab-unresponsive':
-      return `journal: ${at} tab-unresponsive ${line.tabId8} no channel for ${Math.round(line.noChannelForMs / 1000)}s`;
+      return `journal: ${at} tab-unresponsive ${line.tabId8} ${line.reason} for ${Math.round(line.unresponsiveForMs / 1000)}s`;
+    case 'page-error':
+      return `journal: ${at} page-error ${line.tabId8} ${line.message}`;
     case 'tab-death-profile':
       return `journal: ${at} tab-death-profile ${line.tabId8} code ${line.code} — ${tabDeathProfileBody(line)}`;
+    // The CONSOLE arm. `count` is the running total for that condition, so a
+    // reader scanning the column sees a repeat climbing rather than the same
+    // line over and over with nothing to distinguish the fiftieth from the
+    // first. Every line leads with the ack id, because that is what a reader
+    // types next.
+    case 'console-entry':
+      return `journal: ${at} console-${line.severity} ${line.id} +${line.added} (total ${line.count}) ${line.source === null ? '' : `[${line.source}] `}${line.message.split('\n')[0]}`;
+    case 'console-retired':
+      return `journal: ${at} console-retired ${line.id} after ${line.count} — did not recur after reload`;
+    case 'console-ack':
+      return `journal: ${at} console-ack ${line.id} (×${line.count}) by ${line.by}: ${line.reason}`;
   }
 }
 

package/src/project/shared.ts

@@ -44,6 +44,12 @@ import { ToolError } from '../errors.js';
 import type { ToolErrorDefinition } from '../registry.js';
 import type { ToolContext } from '../types.js';
 
+/** Both Theatre project-state names already established in shipped projects. */
+export function isTheatreProjectPath(path: string): boolean {
+  const filename = path.slice(Math.max(path.lastIndexOf('/'), path.lastIndexOf('\\')) + 1);
+  return filename === 'theatre-project.json' || filename.endsWith('.theatre-project.json');
+}
+
 // ---------------------------------------------------------------------------
 // Project-root resolution
 // ---------------------------------------------------------------------------

package/src/render/render-cinematic.ts

@@ -245,7 +245,7 @@ function keepFramesOverride(signal: AbortSignal | undefined): boolean | undefine
 }
 
 const DEFAULT_SEED = 0x5eed_c0de;
-/** Only actually used when `entry` is an http(s) URL (no dev server spawn — see {@link resolveEffectivePort}) or as this pure function's own documented default before that override applies. */
+/** Only actually used when `entry` is an http(s) URL (no preview server spawn — see {@link resolveEffectivePort}) or as this pure function's own documented default before that override applies. */
 const DEFAULT_PORT = 5799;
 
 /**
@@ -282,7 +282,7 @@ export function findFreeRenderPort(): Promise<number> {
 
 /**
  * I7 fold-in (#9b): when the caller didn't pin an explicit `port`, resolve a
- * genuinely free one right before spawning the dev server, overriding the
+ * genuinely free one right before spawning the preview server, overriding the
  * resolved request's `DEFAULT_PORT` placeholder. Checked against the
  * ORIGINAL (unresolved) `request.port`, not `resolved.port` — the latter
  * already has `DEFAULT_PORT` filled in by {@link resolveRenderCinematicRequest}
@@ -471,7 +471,7 @@ export function resolveRenderCinematicRequest(
     keepFrames: req.keepFrames ?? false,
     // I7 fold-in #9b: this DEFAULT_PORT fallback is only actually used when
     // `resolveEffectivePort` (below) doesn't override it — i.e. `entry` is
-    // an already-serving http(s) URL (no dev server is ever spawned, so no
+    // an already-serving http(s) URL (no preview server is ever spawned, so no
     // port collision is possible). Every Vite-config `entry` gets a REAL
     // free port at launch time instead — see `resolveEffectivePort`.
     port: req.port ?? DEFAULT_PORT,
@@ -607,23 +607,23 @@ async function waitForHttpOk(url: string, timeoutMs: number, signal?: AbortSigna
   const deadline = Date.now() + timeoutMs;
   let lastErr: unknown;
   while (Date.now() < deadline) {
-    // I7 fold-in (#9a): don't keep polling a dev server that's booting for a
+    // I7 fold-in (#9a): don't keep polling a preview server that's booting for a
     // render that was already cancelled — return promptly so the caller's
     // own catch path (`launchEntryServer`) can group-kill the half-started
     // vite process right away instead of waiting out the full 30s timeout.
     if (signal?.aborted) {
-      throw new Error('Render cancelled while waiting for the dev server to become ready.');
+      throw new Error('Render cancelled while waiting for the preview server to become ready.');
     }
     try {
       const res = await fetch(url);
-      if (res.ok || res.status === 404) return; // dev server answering is enough; 404 still proves it's up
+      if (res.ok || res.status === 404) return; // a preview response is enough; 404 still proves it's up
     } catch (err) {
       lastErr = err;
     }
     await new Promise((r) => setTimeout(r, 200));
   }
   throw new Error(
-    `Dev server at ${url} did not become ready within ${timeoutMs}ms` +
+    `Preview server at ${url} did not become ready within ${timeoutMs}ms` +
       (lastErr instanceof Error ? ` (last error: ${lastErr.message})` : ''),
   );
 }
@@ -633,16 +633,56 @@ export interface LaunchedServer {
   stop(): Promise<void>;
 }
 
-/** Resolve `entry` into a running dev server: reuse a URL as-is, or spawn `npx vite --config <entry>` (mirrors `run-doctor.ts`/`runConformance`'s `npx tsx <runner>` spawn idiom, `packages/vgai-cli/src/index.ts`). */
+/** Build one Vite config as an exported artifact. A dev-served standalone game
+ * is intentionally trapped by `unexported-game-trap.ts`; render tooling must
+ * exercise either the editor or the export, never invent a bypass query. */
+async function buildExportedEntry(
+  configPath: string,
+  cwd: string,
+  outDir: string,
+  signal?: AbortSignal,
+): Promise<string> {
+  const child = spawn('npx', ['vite', 'build', '--config', configPath, '--outDir', outDir], {
+    cwd,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    detached: true,
+  });
+  let output = '';
+  child.stdout?.on('data', (data) => {
+    output += String(data);
+  });
+  child.stderr?.on('data', (data) => {
+    output += String(data);
+  });
+
+  const abort = () => void stopServerProcess(child);
+  signal?.addEventListener('abort', abort, { once: true });
+  try {
+    const code = await new Promise<number>((resolve, reject) => {
+      child.once('error', reject);
+      child.once('close', (exitCode) => resolve(exitCode ?? 1));
+    });
+    if (signal?.aborted) throw new Error('Render cancelled while building the exported game.');
+    if (code !== 0) {
+      throw new Error(`Vite production build failed (exit ${code}).\nOutput:\n${output}`);
+    }
+    return output;
+  } finally {
+    signal?.removeEventListener('abort', abort);
+  }
+}
+
+/** Resolve `entry` into a running exported page: reuse a URL as-is, or build
+ * the Vite config and spawn `vite preview`. */
 export async function launchEntryServer(
   entry: string,
   port: number,
-  engineRoot: string,
+  _engineRoot: string,
   onProgress: ((e: RenderCinematicProgress) => void) | undefined,
   signal?: AbortSignal,
   options?: {
     /**
-     * Extra args appended to the `npx vite` spawn (G3 fold-in). Motivating
+     * Extra args appended to the `npx vite preview` spawn (G3 fold-in). Motivating
      * case: the render-mode e2e fixtures all pin `server.host: '127.0.0.1'`
      * in their own vite configs, but a real project's config (an
      * `examples/<id>/vite.config.ts`) typically leaves `host` at Vite's
@@ -668,6 +708,15 @@ export async function launchEntryServer(
   }
   const baseUrl = `http://127.0.0.1:${port}`;
   onProgress?.({ phase: 'server-launch', url: baseUrl });
+  const projectDir = dirname(configPath);
+  const exportDir = await mkdtemp(join(tmpdir(), 'vgai-render-export-'));
+  let buildOutput: string;
+  try {
+    buildOutput = await buildExportedEntry(configPath, projectDir, exportDir, signal);
+  } catch (error) {
+    await rm(exportDir, { recursive: true, force: true });
+    throw error;
+  }
 
   // `detached: true` makes this child the leader of its OWN process group —
   // required for `stopServerProcess`'s `process.kill(-pid, sig)` group-kill
@@ -682,14 +731,17 @@ export async function launchEntryServer(
     'npx',
     [
       'vite',
+      'preview',
       '--config',
       configPath,
+      '--outDir',
+      exportDir,
       '--port',
       String(port),
       '--strictPort',
       ...(options?.extraViteArgs ?? []),
     ],
-    { cwd: engineRoot, stdio: ['ignore', 'pipe', 'pipe'], detached: true },
+    { cwd: projectDir, stdio: ['ignore', 'pipe', 'pipe'], detached: true },
   );
   let serverOutput = '';
   child.stdout?.on('data', (d) => {
@@ -708,10 +760,14 @@ export async function launchEntryServer(
     await waitForHttpOk(`${baseUrl}/`, 30_000, signal);
   } catch (err) {
     await stopServerProcess(child);
-    throw new Error(`${(err as Error).message}\nVite dev server output:\n${serverOutput}`);
+    await rm(exportDir, { recursive: true, force: true });
+    throw new Error(
+      `${(err as Error).message}\nVite build output:\n${buildOutput}\nVite preview output:\n${serverOutput}`,
+    );
   }
   if (exited) {
-    throw new Error(`Vite dev server exited before becoming ready.\nOutput:\n${serverOutput}`);
+    await rm(exportDir, { recursive: true, force: true });
+    throw new Error(`Vite preview exited before becoming ready.\nOutput:\n${serverOutput}`);
   }
 
   onProgress?.({ phase: 'server-ready', url: baseUrl });
@@ -719,8 +775,8 @@ export async function launchEntryServer(
   return {
     baseUrl,
     async stop() {
-      if (exited) return;
-      await stopServerProcess(child);
+      if (!exited) await stopServerProcess(child);
+      await rm(exportDir, { recursive: true, force: true });
     },
   };
 }
@@ -729,7 +785,7 @@ export async function launchEntryServer(
  * Terminate `proc` AND its whole process group (see the `detached: true`
  * comment at its call site above) — a plain `proc.kill()` leaves the real
  * `vite` node process (an `npx` grandchild) running, which both leaks a
- * port-bound dev server across renders and keeps THIS process's event loop
+ * port-bound preview server across renders and keeps THIS process's event loop
  * alive via the still-open stdout/stderr pipes, hanging `renderCinematic`'s
  * caller indefinitely after the render itself has already finished. Mirrors
  * `packages/editor/e2e/helpers/server.ts`'s `stopProcess` (POSIX process-
@@ -757,7 +813,7 @@ function stopServerProcess(proc: ChildProcess): Promise<void> {
       return;
     }
     const timer = setTimeout(() => {
-      signalGroup('SIGKILL'); // belt and braces — don't hang the render on a stuck dev server
+      signalGroup('SIGKILL'); // belt and braces — don't hang the render on a stuck preview server
       resolvePromise();
     }, 5_000);
     proc.on('exit', () => {
@@ -1450,12 +1506,12 @@ async function openRenderPage(
 export interface RenderCinematicPageSession {
   readonly page: Page;
   readonly resolved: ResolvedRenderCinematicRequest;
-  /** Closes the page/context, the browser, and stops the spawned dev server (if any). */
+  /** Closes the page/context, the browser, and stops the spawned preview server (if any). */
   close(): Promise<void>;
 }
 
 /**
- * Open a live render-mode page — preflight, dev-server launch, headless
+ * Open a live render-mode page — preflight, production build/preview launch, headless
  * Chromium launch, DOM/CSS-animation freeze, navigate, and wait for
  * `__vgaiRender.ready()` — WITHOUT running {@link renderCinematic}'s own
  * frame-capture/encode loop. This exposes the raw Playwright `Page` for a
@@ -1723,13 +1779,13 @@ export async function renderCinematic(
     // I7 fold-in (#9a — cancellation race): this is the EARLIEST possible
     // cancellation point — `preparePipelineOutputs` (immediately above)
     // already created `framesDir` on disk, so throwing here without cleanup
-    // leaked it (reproduced by a real abort landing before the dev server
+    // leaked it (reproduced by a real abort landing before the preview server
     // even starts, not merely a hypothetical). `cleanupAfterFailure` is a
     // no-op on everything else at this point (no `outAbs` output could
     // possibly exist yet), so this is just the framesDir removal, done
     // explicitly rather than pulled into a broader try/catch this early.
     const err = new RenderCinematicCancelledError(
-      'Render cancelled before the dev server launched.',
+      'Render cancelled before the preview server launched.',
       keepFramesOverride(signal),
     );
     await cleanupAfterFailure(err, resolved, outAbs, framesDir, signal);
@@ -1742,7 +1798,7 @@ export async function renderCinematic(
   // cancellation-driven failure — `waitForHttpOk`'s own `signal?.aborted`
   // check inside `launchEntryServer` throws a plain `Error` (wrapped again
   // by `launchEntryServer`'s own catch, losing any `RenderCinematicCancelledError`-
-  // ness entirely) if `signal` aborts while still waiting for the dev server
+  // ness entirely) if `signal` aborts while still waiting for the preview server
   // to come up. Without this try/catch, THAT throw skipped
   // `cleanupAfterFailure` completely (it's outside the main try block) and
   // leaked the temp frames dir `preparePipelineOutputs` already created
@@ -1765,7 +1821,7 @@ export async function renderCinematic(
   let browser: Browser | undefined;
   const warnings: string[] = [];
   // I7 fold-in (#9a — cancellation/orphan): tear down the browser AND the
-  // vite dev server's WHOLE PROCESS GROUP the INSTANT `signal` aborts,
+  // Vite preview server's WHOLE PROCESS GROUP the INSTANT `signal` aborts,
   // rather than waiting for the next cooperative per-frame check
   // (`captureFrames`'s `signal?.aborted` guard) to be reached. This is what
   // makes a slow/hung in-flight `page.evaluate`/`page.screenshot` call, or a