@vgai/sdk 0.5.21 → 0.5.23

package/src/project/session-journal.ts

@@ -35,6 +35,7 @@
 import { appendFileSync, mkdirSync, readdirSync, readFileSync, unlinkSync } from 'node:fs';
 import { join } from 'node:path';
 import type { TripwireTier } from './build-discipline';
+import type { RecordedTabCensus } from './tab-census';
 
 /** `editor-` + an ISO instant with `:`/`.` flattened + `.jsonl` — the same
  *  lexicographic-order-is-chronological-order shape `play-*.jsonl` uses. */
@@ -64,6 +65,37 @@ export type SessionJournalEvent =
     }
   /** The session is going down (best-effort: a SIGKILL logs nothing). */
   | { readonly kind: 'session-shutdown' }
+  /**
+   * WHERE EDITOR BOOT TIME WENT — written ONCE, when the first page proves it
+   * is RUNNING the editor document (its command listener attaches), which is
+   * the honest end of the wait `vgai edit` narrates as "Vite cold start".
+   *
+   * The gap between "Editor ready at …" and that line is the largest stage of
+   * opening a project and nothing used to record it: on an imported Unity port
+   * it measured 83–139s against a template's 5s, and finding out why took a
+   * hand-rolled request trace plus a V8 CPU profile of the dev server. Every
+   * field here is a fact the host already had.
+   *
+   * READ `loopDelayP99Ms` FIRST. It is what separates "the server was busy" —
+   * where every slow response in the window is queueing, not work — from "the
+   * server was idle and the browser was the wait". See
+   * `packages/editor/server/boot-timings.ts`.
+   */
+  | {
+      readonly kind: 'boot';
+      /** Process start → Vite's `createServer` resolved. */
+      readonly viteMs: number;
+      /** …→ the dependency scan settled. */
+      readonly depScanMs: number;
+      /** …→ HTTP listening (what "Editor ready at" announces). */
+      readonly listenMs: number;
+      /** Listening → the first page running the editor document. */
+      readonly boundMs: number;
+      /** Process start → the declared world warmup finished; `null` if none ran. */
+      readonly worldWarmupDoneMs: number | null;
+      readonly loopDelayP99Ms: number;
+      readonly loopDelayMaxMs: number;
+    }
   /** A save-validation verdict — the same facts `runFileValidation` reports. */
   | {
       readonly kind: 'validation';
@@ -102,6 +134,26 @@ export type SessionJournalEvent =
       readonly name: string | null;
       readonly logFile: string | null;
     }
+  /**
+   * A play run's VIDEO evidence opened or landed.
+   *
+   * Every `vgai play` records — there is no flag — so this row is the answer
+   * to "where is the footage of that run", and it has to be in the journal
+   * rather than only in a terminal ack: the runs whose footage matters most
+   * are the unattended ones, whose ack nobody read.
+   *
+   * `reason` is what ENDED the recording (`'idle-autostop'`, `'stop'`), null
+   * on the `started` row. `rotates` says whether the next play overwrites this
+   * file — the unnamed clip does, a `--record <name>` keepsake does not.
+   */
+  | {
+      readonly kind: 'play-recording';
+      readonly action: 'started' | 'finalized';
+      /** Basename under the project's `.vgai/recordings/`. */
+      readonly file: string;
+      readonly rotates: boolean;
+      readonly reason: string | null;
+    }
   /**
    * A relayed command ran out of budget, and WHICH PLAY-BOOT STEP the page was
    * inside when it did.
@@ -243,17 +295,10 @@ export type SessionJournalEvent =
       /** The abnormal close code that triggered the line. */
       readonly code: number;
       readonly censusAgeMs: number | null;
-      readonly census: {
-        readonly heapUsedMB: number | null;
-        readonly heapLimitMB: number | null;
-        /** Absent on journal lines written before the mount census existed. */
-        readonly mountEpochs?: number;
-        readonly canvases: number;
-        readonly canvasMB: number;
-        readonly textures?: number;
-        readonly geometries?: number;
-        readonly programs?: number;
-      } | null;
+      /** {@link RecordedTabCensus} rather than `TabCensus`: the writer files a
+       *  full census, but a line READ back may have been written before the
+       *  mount census existed. */
+      readonly census: RecordedTabCensus | null;
     }
   /** Two epochs beating under one tabId — "Duplicate Tab" copied sessionStorage. */
   | { readonly kind: 'tab-duplicated'; readonly tabId8: string }
@@ -481,6 +526,30 @@ export function readRecentJournalEvents(
  * events already have exactly one wording as data, and a second prose form per
  * caller is how a reader ends up believing there are two records.
  */
+/** Split out of {@link formatJournalLine}'s switch for the same reason as
+ *  {@link playRecordingLine} below. Seconds, because that is the unit the
+ *  reader's complaint is in ("opening this project takes two minutes"), except
+ *  the loop-delay pair — a p99 is a millisecond fact and rounding it to
+ *  seconds would erase the only number that says WHO was waiting. */
+function bootLine(line: Extract<SessionJournalEvent, { kind: 'boot' }>): string {
+  const s = (ms: number): string => `${Math.round(ms / 100) / 10}s`;
+  return (
+    `boot ready ${s(line.listenMs)} (vite ${s(line.viteMs)}, dep-scan ${s(line.depScanMs)}) ` +
+    `→ page bound +${s(line.boundMs)}` +
+    (line.worldWarmupDoneMs === null ? '' : `, world warmup done ${s(line.worldWarmupDoneMs)}`) +
+    ` — loop delay p99 ${line.loopDelayP99Ms}ms / max ${line.loopDelayMaxMs}ms`
+  );
+}
+
+/** Split out of {@link formatJournalLine}'s switch so this row's three
+ *  conditionals do not push that already-long function further over the
+ *  complexity bound. */
+function playRecordingLine(line: Extract<SessionJournalEvent, { kind: 'play-recording' }>): string {
+  const why = line.reason === null ? '' : ` (${line.reason})`;
+  const life = line.rotates ? ' — replaced by the next play' : ' — kept';
+  return `play-recording ${line.action} .vgai/recordings/${line.file}${why}${life}`;
+}
+
 export function formatJournalLine(line: SessionJournalLine): string {
   const at = line.at.slice(11, 19);
   switch (line.kind) {
@@ -492,6 +561,8 @@ export function formatJournalLine(line: SessionJournalLine): string {
       return `journal: ${at} validation ${line.ok ? 'ok' : 'FAILED'} ${line.path}`;
     case 'play':
       return `journal: ${at} play ${line.action}${line.name === null ? '' : ` [${line.name}]`}`;
+    case 'play-recording':
+      return `journal: ${at} ${playRecordingLine(line)}`;
     case 'play-stall':
       return (
         `journal: ${at} play-stall ${line.command} ${line.requestId8} after ` +
@@ -506,6 +577,8 @@ export function formatJournalLine(line: SessionJournalLine): string {
       return `journal: ${at} project-opened ${line.project}`;
     case 'session-shutdown':
       return `journal: ${at} session-shutdown`;
+    case 'boot':
+      return `journal: ${at} ${bootLine(line)}`;
     // The TRANSPORT arm. One short line each, and every one of them names the
     // TAB or the request it is about — a column of ids is how these lines get
     // correlated, and a paragraph per line is how a reader stops reading.
@@ -574,9 +647,7 @@ function tabDeathProfileBody(line: SessionJournalEvent & { kind: 'tab-death-prof
  *  phrasings of the same numbers is how a reader ends up believing there are
  *  two measurements. Renderer counts appear only when the page could read them
  *  (no mounted render-debug adapter = the words are absent, never a zero). */
-export function formatTabCensus(
-  census: (SessionJournalEvent & { kind: 'tab-death-profile' })['census'],
-): string {
+export function formatTabCensus(census: RecordedTabCensus | null): string {
   if (census === null) return 'no resource census';
   const parts = [
     census.heapUsedMB === null

package/src/project/shared.ts

@@ -3,12 +3,9 @@
  *
  * Every `project.*` op is file-native (host: 'node', requires: { project: true })
  * and runs with NO editor process — it resolves `ctx.projectRoot`, reads/writes
- * plain files on disk, and reuses the engine's existing Zod schemas +
- * schemas. (WO-8: this also said it reused the engine's `applyDiff` for anything
- * scene-shaped — `engine/src/scene/scene-apply.ts` and the twelve
- * `project.scene.*` ops that used it are deleted with the `.vscn.json` format.)
+ * plain files on disk, and reuses the engine's existing Zod schemas.
  *
- * Two cross-cutting decisions (pinned by the B2 task brief) live here so every
+ * Two cross-cutting decisions live here so every
  * operation module applies them identically:
  *
  *  - DRY-RUN: every mutation's input carries an optional `dryRun` field

package/src/project/tab-census.ts

@@ -0,0 +1,83 @@
+/**
+ * THE TAB RESOURCE CENSUS — one declaration of the profile a browser tab
+ * reports about itself, for every compilation unit that speaks it.
+ *
+ * WHAT IT IS. What a game tab is holding: JS heap, canvas backing stores,
+ * renderer resource counts, and how many project mount generations the
+ * document has accumulated. Sampled by the page every five seconds and carried
+ * on the heartbeat, so that a browser-level renderer death — which the presence
+ * system recovers from perfectly and would otherwise leave unexplained — has a
+ * number beside it. MEASUREMENT ONLY: nothing anywhere enforces a budget from
+ * these. The page-side sampler and its `why` are
+ * `packages/editor/src/tab-census.ts`.
+ *
+ * WHY IT LIVES HERE. This one shape crosses four compilation units — the page
+ * that samples it (`@vgai/editor`'s browser bundle), the editor server that
+ * files it (`@vgai/editor`'s node half), the editor-extension surface that
+ * describes the status response (`@vgai/editor-sdk`), and the session journal
+ * plus the CLI row that print it (`@vgai/sdk`, `@vgai/cli`). Each of them used
+ * to spell the seven fields out again. `@vgai/sdk` is the only package all four
+ * already depend on: `@vgai/editor-sdk` depends on `@vgai/sdk` and `@vgai/editor`
+ * depends on both, so this cannot live in `@vgai/editor-sdk` without a cycle —
+ * and it does not belong in `@vgai/engine`, whose subject is a running game,
+ * not an editor session's tabs.
+ *
+ * Deliberately import-free so a browser bundle can take it: the census's other
+ * `@vgai/sdk` home, `project/session-journal.ts`, reads `node:fs`.
+ *
+ * ABSENT IS NOT ZERO. `heapUsedMB`/`heapLimitMB` are null off Chromium
+ * (`performance.memory` is non-standard). The renderer counts are ABSENT rather
+ * than zero when no game has registered a render-debug adapter, and `programs`
+ * is absent until a first render: a zero would read as "no textures", which is
+ * a different claim from "nobody measured".
+ */
+
+/**
+ * A census as a CURRENT page produces it and the server files it.
+ *
+ * Every field here is guaranteed by a producer that always writes it, and
+ * `packages/editor/server/tab-heartbeat.ts`'s `parseCensus` is where that is
+ * checked: a beat frame missing `canvases`, `canvasMB` or `mountEpochs` is
+ * rejected outright rather than filed as a partial profile.
+ */
+export interface TabCensus {
+  /** `performance.memory.usedJSHeapSize` in MB; null off Chromium. */
+  readonly heapUsedMB: number | null;
+  /** `performance.memory.jsHeapSizeLimit` in MB; null off Chromium. */
+  readonly heapLimitMB: number | null;
+  /** Distinct project mount generations fetched by this document. */
+  readonly mountEpochs: number;
+  /** How many `<canvas>` elements the document holds. */
+  readonly canvases: number;
+  /** Their total pixel-buffer footprint: Σ width×height×4 bytes, in MB. */
+  readonly canvasMB: number;
+  /** `renderer.info.memory.textures` — absent with no mounted adapter. */
+  readonly textures?: number;
+  /** `renderer.info.memory.geometries` — absent with no mounted adapter. */
+  readonly geometries?: number;
+  /** Compiled programs — absent with no adapter, or before the first render. */
+  readonly programs?: number;
+}
+
+/**
+ * A census read back out of a RECORD, where the writer may predate a field.
+ *
+ * Exactly one field varies, and this is the only place that is said: a session
+ * journal line written before the mount census existed has no `mountEpochs`,
+ * and neither does a status response from an older editor server. The
+ * difference is a property of the READER's input, so it is named on the
+ * reader's type rather than by softening {@link TabCensus} — which is what the
+ * four hand-copied declarations did, and how the producers' own guarantee got
+ * lost on the way to the two SDKs.
+ *
+ * There is no runtime narrowing to point at because neither reader has a parse
+ * step to put one in: the journal is `JSON.parse` per line by recorded design
+ * (`session-journal.ts`: "nothing reads a journal back through a validator"),
+ * and the CLI reads the status body as JSON. So the absence is carried in the
+ * type and handled where it is printed — `formatTabCensus` omits the words
+ * rather than printing a fabricated count. Every {@link TabCensus} is a valid
+ * value of this type; the reverse is not.
+ */
+export type RecordedTabCensus = Omit<TabCensus, 'mountEpochs'> & {
+  readonly mountEpochs?: number;
+};

package/src/project-tool-catalog.ts

@@ -49,6 +49,31 @@ export interface ProjectToolLoadError {
   message: string;
 }
 
+/**
+ * What a host says when it cannot load the project's TypeScript at all.
+ *
+ * ONE owner for the sentence, because two realms reach this state through
+ * different doors and both must say the same true thing rather than fall back
+ * to a fabricated empty catalog:
+ *
+ *  - the NODE side (`packages/editor/server/project-tools.ts`) when a host
+ *    builds the catalog with no `loadModule`; and
+ *  - the BROWSER side (`packages/editor/src/project-tools.ts`) on the hosted
+ *    `--mode web` build, which has no editor server on its origin at all. A
+ *    static host answers `/__editor/project-tools` with the SPA fallback —
+ *    `200` and HTML — so an unguarded fetch that merely checks `response.ok`
+ *    reads a successful page load as a successful catalog, then dies in
+ *    `res.json()`. The panel's empty state ("No project tools registered")
+ *    is a FACT about the project; a host that cannot ask has not learned it.
+ */
+export const NO_PROJECT_MODULE_HOST_MESSAGE =
+  'This editor host cannot load project TypeScript modules. Use the Vite-backed dev or packaged editor.';
+
+/** The catalog row that states {@link NO_PROJECT_MODULE_HOST_MESSAGE}. */
+export function noProjectModuleHostError(): ProjectToolLoadError {
+  return { sourcePath: 'package.json#vgai.tools', message: NO_PROJECT_MODULE_HOST_MESSAGE };
+}
+
 /**
  * Callables and contribution modules are SIBLINGS, not parent and child.
  *