@vgai/editor-sdk 0.1.0 → 0.4.0-canary.20260715.0

package/README.md

@@ -24,7 +24,10 @@ One export, `EditorClient`, plus its types (`EditorState`, `ProjectInfo`,
 
 - Play control: `play`, `stop`, `pause`, `resume`, `step`
 - Selection: `select(id | null)`, `selectMultiple`, `selectAll`
-- Viewport: `focusEntity`, `focusSelection`, `viewPreset`
+- Viewport: `focusEntity`, `focusSelection`, `viewPreset`, `setCamera`,
+  `captureViewport`
+- Asset preview: `captureAssetPreview` for deterministic front, right, top,
+  and three-quarter captures of a project model or authored entity hierarchy
 - Panels: `showViewport('scene'|'game')`, `showInspector`, `openAsset`,
   `closeAsset`, `toggleConsole`, `toggleCommandPalette`, `showBuild`
 - Display: `setGrid`, `setHelpers`, `setStats`, `setShadingMode`,
@@ -38,9 +41,36 @@ One export, `EditorClient`, plus its types (`EditorState`, `ProjectInfo`,
 Commands throw on `{ ok: false }` responses, including the server's timeout
 when no browser editor is connected — failures are never silently swallowed.
 
+### Asset Lab capture
+
+`captureAssetPreview` accepts exactly one source: an authored entity hierarchy
+already loaded in the editor, or a same-origin project `.glb`/`.gltf` path.
+Rendering happens in an isolated native editor scene and returns deterministic
+front, right, top, and three-quarter PNGs plus a labeled contact sheet:
+
+```ts
+const sketch = await editor.captureAssetPreview(
+  { entityId: 'storefront-sketch' },
+  { width: 768, height: 768, background: 'neutral' },
+);
+
+const model = await editor.captureAssetPreview(
+  { assetPath: '/models/storefront.glb' },
+  { background: 'transparent' },
+);
+```
+
+Project model input is bounded to 64 MiB and 25 seconds. External `.gltf`
+buffers and images must resolve on the same project origin. The thin CLI
+equivalent writes the four views and contact sheet to disk:
+
+```bash
+vgai asset-preview --asset /models/storefront.glb --out artifacts/storefront
+```
+
 ## Limitations
 
-- Exports raw TypeScript (`exports: "./src/index.ts"`); consumable only inside
-  this monorepo under tsx/vite. It is not built or published.
+- The published package exports raw TypeScript (`exports: "./src/index.ts"`),
+  so consumers need a TypeScript-aware runner/bundler such as tsx or Vite.
 - Requires the editor dev server (`npm run dev` or `vgai edit`); there is no
   offline mode.

package/package.json

@@ -2,8 +2,16 @@
   "name": "@vgai/editor-sdk",
   "author": "Volter AI, Inc.",
   "license": "Apache-2.0",
-  "version": "0.1.0",
+  "version": "0.4.0-canary.20260715.0",
   "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/volter-ai/vgai-engine.git",
+    "directory": "packages/editor-sdk"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "files": [
     "src"
   ],

package/src/client.ts

@@ -1,4 +1,23 @@
-import type { AssetKind, EditorState, ProjectInfo, ProjectTemplate, RecentProject, ShadingMode, TransformMode, TransformSpace, ViewPreset } from './types.js';
+import type {
+  AssetKind,
+  AssetPreviewCapture,
+  AssetPreviewOptions,
+  AssetPreviewSource,
+  EditorState,
+  GameCapture,
+  HelperVisibility,
+  ProjectInfo,
+  ProjectOperationCatalog,
+  ProjectOperationOutcome,
+  ProjectTemplate,
+  RecentProject,
+  ShadingMode,
+  TransformMode,
+  TransformSpace,
+  Vec3Value,
+  ViewPreset,
+  ViewportCapture,
+} from './types.js';
 
 const DEFAULT_URL = 'http://localhost:5173';
 
@@ -9,22 +28,30 @@ export class EditorClient {
     this.baseUrl = (opts?.url ?? DEFAULT_URL).replace(/\/$/, '');
   }
 
-  private async command(body: Record<string, unknown>): Promise<void> {
+  private async command<T extends object = Record<string, never>>(
+    body: Record<string, unknown>,
+  ): Promise<T> {
     const res = await fetch(`${this.baseUrl}/__editor/command`, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify(body),
     });
-    const data = (await res.json()) as { ok: boolean; error?: string };
+    const data = (await res.json()) as { ok: boolean; error?: string } & T;
     if (!data.ok) {
       throw new Error(data.error ?? `Editor command failed: ${res.status}`);
     }
+    return data;
   }
 
   // --- Play control ---
 
-  async play(): Promise<void> {
-    await this.command({ type: 'play' });
+  /** `opts.seed` (D15/T-D15.6, objection-4 fix) — `vgai play --seed <n>`'s
+   *  explicit config leg, relayed as `cmd['seed']`; `handleCommand`'s
+   *  `'play'` case threads it into `enterPlayMode`'s highest-precedence seed
+   *  argument (beats manifest.determinism.defaultSeed/?vgai-seed=). Omitted,
+   *  boot seeding falls back to that precedence unchanged. */
+  async play(opts?: { seed?: number }): Promise<void> {
+    await this.command({ type: 'play', ...(opts?.seed !== undefined ? { seed: opts.seed } : {}) });
   }
 
   async stop(): Promise<void> {
@@ -71,6 +98,74 @@ export class EditorClient {
     await this.command({ type: 'view-preset', preset });
   }
 
+  async setCamera(position: Vec3Value, target: Vec3Value, fov?: number): Promise<void> {
+    await this.command({
+      type: 'set-camera',
+      position,
+      target,
+      ...(fov === undefined ? {} : { fov }),
+    });
+  }
+
+  async captureViewport(size?: number): Promise<ViewportCapture> {
+    const data = await this.command<ViewportCapture>({
+      type: 'capture-viewport',
+      ...(size === undefined ? {} : { size }),
+    });
+    return { base64: data.base64, mimeType: data.mimeType };
+  }
+
+  /**
+   * Unit 4 (live-front-door wave) — capture the RUNNING GAME (`vgai
+   * screenshot`'s wire leg). Sends the SAME `bridge-screenshot` relay op
+   * `@vgai/probe`'s `RelayTransport.screenshot` (and therefore
+   * `game.screenshot()` on the relay path) already sends, so all three
+   * surfaces composite the identical full game stack — canvas(es) plus the
+   * HUD/react DOM layers — rather than any of them inventing a second,
+   * subtly-different capture path. Contrast {@link captureViewport}, which
+   * captures the EDITOR viewport's canvas and would silently hand back an
+   * editor-only (HUD-less, possibly not-even-playing) image.
+   *
+   * Rejects — loudly, via `command`'s own `{ok:false}` unwrap — when play
+   * mode isn't running ("not in play mode — start play before using the
+   * debug seam") or no game canvas is mounted yet. Never returns a blank or
+   * editor-only frame as a stand-in.
+   */
+  async captureGame(): Promise<GameCapture> {
+    const data = await this.command<GameCapture>({ type: 'bridge-screenshot' });
+    const layers = data.layers;
+    return {
+      base64: data.base64,
+      mimeType: data.mimeType,
+      composite: data.composite === true,
+      ...(layers && Number.isInteger(layers.canvases) && Number.isInteger(layers.domOverlays)
+        ? { layers }
+        : {}),
+    };
+  }
+
+  /**
+   * Capture an isolated, deterministic four-view preview through the editor's
+   * native Asset Lab. The SDK delegates rendering to the editor; it never
+   * loads, clones, or interprets Three.js assets itself.
+   */
+  async captureAssetPreview(
+    source: AssetPreviewSource,
+    options: AssetPreviewOptions = {},
+  ): Promise<AssetPreviewCapture> {
+    const data = await this.command<AssetPreviewCapture>({
+      type: 'capture-asset-preview',
+      ...source,
+      ...options,
+    });
+    return {
+      width: data.width,
+      height: data.height,
+      views: data.views,
+      contactSheet: data.contactSheet,
+    };
+  }
+
   // --- Panels ---
 
   async showViewport(tab: 'scene' | 'game'): Promise<void> {
@@ -119,7 +214,7 @@ export class EditorClient {
     await this.command({ type: 'set-shading-mode', mode });
   }
 
-  async setHelperType(helperType: string, enabled: boolean): Promise<void> {
+  async setHelperType(helperType: keyof HelperVisibility, enabled: boolean): Promise<void> {
     await this.command({ type: 'set-helper-type', helperType, enabled });
   }
 
@@ -145,7 +240,12 @@ export class EditorClient {
 
   // --- Project management ---
 
-  async createProject(name: string, location: string, template: ProjectTemplate = 'starter', exampleId?: string): Promise<ProjectInfo> {
+  async createProject(
+    name: string,
+    location: string,
+    template: ProjectTemplate = 'default',
+    exampleId?: string,
+  ): Promise<ProjectInfo> {
     const res = await fetch(`${this.baseUrl}/__editor/create-project`, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
@@ -185,12 +285,46 @@ export class EditorClient {
     return data.projects;
   }
 
+  // --- Project operations ---
+
+  /** List live project-local operation definitions below `src/operations/`.
+   * The editor server loads metadata in Node; operation modules never enter the
+   * editor browser merely because they were listed. */
+  async listProjectOperations(): Promise<ProjectOperationCatalog> {
+    const res = await fetch(`${this.baseUrl}/__editor/project-operations`);
+    if (!res.ok) throw new Error(`Failed to list project operations: ${res.status}`);
+    return (await res.json()) as ProjectOperationCatalog;
+  }
+
+  /** Execute one Node-hosted project operation through the existing validated
+   * operation registry. Write/destructive operations require `confirm:true`. */
+  async runProjectOperation(
+    name: string,
+    input: unknown = {},
+    options: { confirm?: boolean } = {},
+  ): Promise<ProjectOperationOutcome> {
+    const res = await fetch(`${this.baseUrl}/__editor/project-operations/run`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ name, input, confirm: options.confirm === true }),
+    });
+    const body = (await res.json()) as ProjectOperationOutcome;
+    if (!body || typeof body !== 'object' || typeof body.ok !== 'boolean') {
+      throw new Error(`Project operation returned an invalid response (${res.status}).`);
+    }
+    return body;
+  }
+
   // --- Logs ---
 
-  async getLogEntries(): Promise<Array<{ t: number; level: string; msg: string; source?: string }>> {
+  async getLogEntries(): Promise<
+    Array<{ t: number; level: string; msg: string; source?: string }>
+  > {
     const res = await fetch(`${this.baseUrl}/__editor/log-entries`);
     if (!res.ok) return [];
-    const data = (await res.json()) as { entries: Array<{ t: number; level: string; msg: string; source?: string }> };
+    const data = (await res.json()) as {
+      entries: Array<{ t: number; level: string; msg: string; source?: string }>;
+    };
     return data.entries;
   }
 

package/src/index.ts

@@ -1,13 +1,26 @@
 export { EditorClient } from './client.js';
 export type {
   AssetKind,
+  AssetPreviewBackground,
+  AssetPreviewCapture,
+  AssetPreviewOptions,
+  AssetPreviewSource,
+  AssetPreviewView,
+  EditorCameraState,
+  EditorEntitySummary,
   EditorState,
+  GameCapture,
   HelperVisibility,
   ProjectInfo,
+  ProjectOperationCatalog,
+  ProjectOperationCatalogEntry,
+  ProjectOperationOutcome,
   ProjectTemplate,
   RecentProject,
   ShadingMode,
   TransformMode,
   TransformSpace,
+  Vec3Value,
   ViewPreset,
+  ViewportCapture,
 } from './types.js';

package/src/types.ts

@@ -15,10 +15,87 @@ export interface HelperVisibility {
   audio: boolean;
   splines: boolean;
   navmesh: boolean;
+  skeletons: boolean;
+}
+
+export interface Vec3Value {
+  x: number;
+  y: number;
+  z: number;
+}
+
+export interface EditorCameraState {
+  position: Vec3Value;
+  target: Vec3Value;
+  fov?: number;
+}
+
+export interface EditorEntitySummary {
+  id: string;
+  name: string;
+  childIds: string[];
+}
+
+export interface ViewportCapture {
+  base64: string;
+  mimeType: 'image/png';
+}
+
+/**
+ * Unit 4 (live-front-door wave) — the RUNNING GAME's pixels, as captured by
+ * the `bridge-screenshot` relay op (`command-listener.ts`'s
+ * `handleBridgeScreenshot`): the full play-mode game stack — canvas(es) PLUS
+ * the DOM adapter layers (for example React roots) composited by
+ * `capturePlayComposite`. Distinct from {@link ViewportCapture}, which is the
+ * EDITOR viewport's own canvas (`capture-viewport`) and knows nothing about
+ * play mode or the HUD.
+ *
+ * `composite` reports honestly whether the DOM-layer composite leg actually
+ * ran, or whether the capture degraded to a canvas-only `toDataURL` frame (no
+ * container, no DOM `Image`/`XMLSerializer`, or a rasterization failure) —
+ * never a silently HUD-less image passed off as the whole game. `layers` is
+ * only present on the composite leg.
+ */
+export interface GameCapture {
+  base64: string;
+  mimeType: 'image/png';
+  composite: boolean;
+  layers?: { canvases: number; domOverlays: number };
+}
+
+export type AssetPreviewView = 'front' | 'right' | 'top' | 'perspective';
+export type AssetPreviewBackground = 'neutral' | 'transparent';
+
+export type AssetPreviewSource =
+  | { assetPath: string; entityId?: never }
+  | { entityId: string; assetPath?: never };
+
+export interface AssetPreviewOptions {
+  width?: number;
+  height?: number;
+  background?: AssetPreviewBackground;
+}
+
+export interface AssetPreviewCapture {
+  width: number;
+  height: number;
+  views: Array<ViewportCapture & { view: AssetPreviewView }>;
+  contactSheet: ViewportCapture & { width: number; height: number };
 }
 
 export interface EditorState {
   playState: 'stopped' | 'playing' | 'paused';
+  /**
+   * Issue #175 — the REAL engine `GameLoop.liveness` behind the current play
+   * session, distinct from `playState` above (editor UI state — a store
+   * flag that never reflected whether the loop was actually ticking).
+   * `'hidden-paused'` means the T2.1 idle throttle stopped the loop because
+   * the editor tab is backgrounded — deliberate and reversible, but the
+   * game is advancing ZERO ticks right now even though `playState` still
+   * reads `'playing'`. `null` while not in play mode (no loop to report on)
+   * or against an older server that predates this field.
+   */
+  loopLiveness?: 'running' | 'hidden-paused' | 'stopped' | null;
   selectedEntityId: string | null;
   selectedEntityIds: string[];
   activeViewportTab: 'scene' | 'game';
@@ -33,6 +110,12 @@ export interface EditorState {
   snapEnabled: boolean;
   entityCount: number;
   savePath: string | null;
+  /** Live editor persistence state. Wait for `saved` before an external scene-file write. */
+  saveState: 'saved' | 'unsaved' | 'failed';
+  /** Current editor camera pose when the viewport has bound a camera. */
+  camera?: EditorCameraState;
+  /** Flattened live authoring hierarchy, useful for agent entity discovery. */
+  entities?: EditorEntitySummary[];
   /**
    * Live count of editor browser tabs holding an SSE connection right now.
    * The rest of this object is the last snapshot a browser POSTed and persists
@@ -43,6 +126,44 @@ export interface EditorState {
   editorsConnected?: number;
   /** Convenience: `editorsConnected > 0`. */
   connected?: boolean;
+  /**
+   * Epoch ms when the server last received a state POST from a browser tab —
+   * i.e. the age of the cached snapshot above. Omitted if no tab has ever
+   * posted state this server lifetime (or since the last project switch,
+   * which clears the cache). Present regardless of `connected`, but only
+   * meaningful for interpreting staleness when `connected` is `false`.
+   */
+  stateUpdatedAt?: number;
+  /**
+   * Validate-on-change (#103): per-file validation status for every
+   * `*.vscn.json`/`*.prefab.json`/`vgai.game.json` the dev server has seen
+   * change since it booted (or since the last project switch). Server-
+   * computed — unlike the rest of `EditorState`, it is NOT part of the
+   * browser-POSTed snapshot, so it is always current. A file appears here
+   * ONLY while it is currently failing; a clean write removes its entry
+   * (absence means "not known to be invalid", not "never checked"). Always
+   * present (`{}` when nothing is failing) so `vgai status` consumers can
+   * read it unconditionally.
+   */
+  projectValidation?: Record<string, { errors: string[]; at: number }>;
+  /**
+   * #124: the absolute path of the project this editor server currently has
+   * open — server-computed (never part of the browser-POSTed snapshot,
+   * exactly like `projectValidation` above), so it is always current. Added
+   * so a watcher/relay holding only a port number (e.g. an agent that
+   * printed a `vgai edit` URL earlier and lost track of which project it
+   * belongs to) can identify which project that port serves without also
+   * reading the `~/.vgai/editor-sessions.json` registry file. `null` when no
+   * project is open (the in-repo "no project selected" default server
+   * state — mirrors `/__editor/project`'s own `{ project: null }` shape).
+   */
+  projectRoot?: string | null;
+  /**
+   * #124: the open project's declared name, alongside `projectRoot` above
+   * (`vgai.game.json`'s `name`). `null` when no project is open, or the open
+   * project has no readable manifest name.
+   */
+  projectName?: string | null;
 }
 
 export type ViewPreset = 'top' | 'front' | 'right' | 'perspective';
@@ -50,7 +171,8 @@ export type ShadingMode = 'solid' | 'wireframe' | 'unlit';
 export type TransformMode = 'translate' | 'rotate' | 'scale';
 export type TransformSpace = 'world' | 'local';
 
-export type ProjectTemplate = 'starter' | 'empty' | 'example';
+/** Template ids accepted by the editor's create-project endpoint. */
+export type ProjectTemplate = 'default' | '2d' | 'react' | 'example';
 
 export interface ProjectInfo {
   path: string;
@@ -63,3 +185,36 @@ export interface RecentProject {
   lastOpened: string;
   thumbnail?: string;
 }
+
+export interface ProjectOperationCatalogEntry {
+  name: string;
+  summary: string;
+  description: string;
+  sourcePath: string;
+  inputSchema: unknown;
+  resultSchema: unknown;
+  errors: Array<{ code: string; summary: string; dataSchema?: unknown }>;
+  requires: Record<string, boolean | undefined>;
+  host: 'node' | 'editor-browser' | 'runtime-page';
+  mutates: boolean;
+  supportsDryRun: boolean;
+  longRunning: boolean;
+  permission: { risk: 'read' | 'write' | 'destructive'; summary: string };
+}
+
+export interface ProjectOperationCatalog {
+  operations: ProjectOperationCatalogEntry[];
+  loadErrors: Array<{ sourcePath: string; message: string }>;
+}
+
+export type ProjectOperationOutcome =
+  | { ok: true; data: unknown }
+  | {
+      ok: false;
+      error: {
+        code: string;
+        message: string;
+        data?: unknown;
+        issues?: Array<{ path?: PropertyKey[]; message?: string; [key: string]: unknown }>;
+      };
+    };