@vgai/sdk 0.4.0-canary.20260715.0

package/src/editor/index.ts

@@ -0,0 +1,62 @@
+/**
+ * B3 — `editor.*` operations
+ * (docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md §8 B3). Registered
+ * separately from B1's `registerBuiltinOperations` (`../operations.ts`) and
+ * B2's `registerProjectOperations` (`../project/index.ts`) — the default
+ * `operations` singleton (`../index.ts`) calls all three.
+ */
+
+export * from './camera-operations.js';
+export * from './console-operations.js';
+export * from './hierarchy-operations.js';
+export * from './open-operations.js';
+export * from './screenshot-operations.js';
+export * from './selection-operations.js';
+export * from './session-operations.js';
+export * from './source-location-operations.js';
+export type {
+  CameraPose,
+  CameraSetRequest,
+  ConsoleSubscriptionMetadata,
+  EditorCommandResult,
+  EditorSessionInfo,
+  EditorTransport,
+  HierarchyNodeInfo,
+  HierarchySummary,
+  OidSourceEntry,
+  ScreenshotResult,
+} from './transport.js';
+export {
+  EDITOR_COMMAND_TIMEOUT_MS,
+  EDITOR_NOT_RUNNING_ERROR,
+  EDITOR_PROBE_TIMEOUT_MS,
+  EDITOR_READ_TIMEOUT_MS,
+  EDITOR_SESSION_DISCOVERY_TIMEOUT_MS,
+  EditorTimeoutError,
+  getTransport,
+  HttpEditorTransport,
+  resolveEditorSession,
+  withTimeout,
+} from './transport.js';
+
+import type { OperationRegistry } from '../registry.js';
+import { registerCameraOperations } from './camera-operations.js';
+import { registerConsoleOperations } from './console-operations.js';
+import { registerHierarchyOperations } from './hierarchy-operations.js';
+import { registerOpenOperations } from './open-operations.js';
+import { registerScreenshotOperations } from './screenshot-operations.js';
+import { registerSelectionOperations } from './selection-operations.js';
+import { registerSessionOperations } from './session-operations.js';
+import { registerSourceLocationOperations } from './source-location-operations.js';
+
+/** Register every B3 `editor.*` operation onto `registry`. */
+export function registerEditorOperations(registry: OperationRegistry): void {
+  registerSessionOperations(registry);
+  registerSelectionOperations(registry);
+  registerHierarchyOperations(registry);
+  registerCameraOperations(registry);
+  registerSourceLocationOperations(registry);
+  registerOpenOperations(registry);
+  registerScreenshotOperations(registry);
+  registerConsoleOperations(registry);
+}

package/src/editor/open-operations.ts

@@ -0,0 +1,209 @@
+/**
+ * `editor.scene.open` / `editor.asset.open` / `editor.story.open`
+ * (B3, §8 B3 "open scene/asset/story").
+ *
+ * scene/asset open are genuinely wired end to end: `{type:'open-scene'}` /
+ * `{type:'open-asset-tab'}` are existing, already-handled cases in the
+ * browser's `handleCommand` switch (`command-listener.ts`).
+ *
+ * story open remains an HONEST GAP (see `./transport.ts` module jsdoc), and
+ * still does after the B3-followup false-ack fix: the editor has no
+ * Storybook/CSF story-preview surface at all today (no story runner, no
+ * `*.stories.tsx` mount path anywhere in `packages/editor/src`) — there is
+ * nothing for a browser-side command handler to open. Sending the command
+ * anyway would previously have fallen through `handleCommand`'s switch to a
+ * silent `{ok:true}` (a LIE — the editor did nothing); that fallthrough is
+ * now a `default:` case returning a structured `{ok:false}` instead, so even
+ * an accidental send would fail loudly rather than lie. This op still never
+ * sends the command at all, on principle: `HttpEditorTransport.openStory`
+ * always returns `undefined` and the op throws the declared
+ * `STORY_OPEN_UNSUPPORTED` error. A test transport can implement `openStory`
+ * for real, proving the success path/schema round-trips.
+ */
+
+import { z } from 'zod';
+import { OperationError } from '../errors.js';
+import { defineOperation, type OperationRegistry } from '../registry.js';
+import {
+  EDITOR_COMMAND_TIMEOUT_MS,
+  EDITOR_NOT_RUNNING_ERROR,
+  getTransport,
+  resolveEditorSession,
+  withTimeout,
+} from './transport.js';
+
+const COMMAND_FAILED_ERROR = {
+  code: 'COMMAND_FAILED',
+  summary: 'The connected editor rejected or failed to execute the relayed open command.',
+  data: z.object({ message: z.string() }),
+} as const;
+
+const STORY_OPEN_UNSUPPORTED_ERROR = {
+  code: 'STORY_OPEN_UNSUPPORTED',
+  summary:
+    'The connected editor has no wire-level command to open a CSF story today (a documented ' +
+    'gap — see transport.ts). Never silently reported as success.',
+  data: z.object({}),
+} as const;
+
+const OkResult = z.object({ ok: z.literal(true) });
+
+// ---------------------------------------------------------------------------
+// editor.scene.open
+// ---------------------------------------------------------------------------
+
+const EditorSceneOpenInput = z.object({
+  path: z
+    .string()
+    .describe('Project-relative path to a .vscn.json scene file to open in the editor.'),
+});
+
+export const editorSceneOpen = defineOperation({
+  name: 'editor.scene.open',
+  summary: 'Open a scene file in a connected editor session.',
+  description:
+    'Relays {type:"open-scene", path} through POST /__editor/command — an existing, already-handled case.',
+  input: EditorSceneOpenInput,
+  result: OkResult,
+  errors: [EDITOR_NOT_RUNNING_ERROR, COMMAND_FAILED_ERROR],
+  requires: { editor: true },
+  host: 'editor-browser',
+  mutates: true,
+  supportsDryRun: false,
+  permission: { risk: 'write', summary: 'Changes which scene the live editor has loaded.' },
+  async impl(input, ctx) {
+    const transport = getTransport(ctx);
+    const session = await resolveEditorSession(ctx, transport);
+    const result = await withTimeout(
+      transport.sendCommand(
+        session,
+        { type: 'open-scene', path: input.path },
+        EDITOR_COMMAND_TIMEOUT_MS,
+      ),
+      EDITOR_COMMAND_TIMEOUT_MS,
+      'editor.scene.open',
+    ).catch((err: unknown) => ({
+      ok: false,
+      error: err instanceof Error ? err.message : String(err),
+    }));
+    if (!result.ok) {
+      throw new OperationError('COMMAND_FAILED', result.error ?? 'open-scene command failed', {
+        message: result.error ?? 'open-scene command failed',
+      });
+    }
+    return { ok: true as const };
+  },
+});
+
+// ---------------------------------------------------------------------------
+// editor.asset.open
+// ---------------------------------------------------------------------------
+
+const AssetKindSchema = z.enum([
+  'model',
+  'image',
+  'audio',
+  'animation',
+  'json',
+  'scene',
+  'prefab',
+  'material',
+]);
+
+const EditorAssetOpenInput = z.object({
+  path: z.string().describe('Project-relative asset path to open as an editor tab.'),
+  kind: AssetKindSchema,
+});
+
+export const editorAssetOpen = defineOperation({
+  name: 'editor.asset.open',
+  summary: 'Open an asset as a tab in a connected editor session.',
+  description:
+    'Relays {type:"open-asset-tab", path, kind} through POST /__editor/command — an existing, already-handled case.',
+  input: EditorAssetOpenInput,
+  result: OkResult,
+  errors: [EDITOR_NOT_RUNNING_ERROR, COMMAND_FAILED_ERROR],
+  requires: { editor: true },
+  host: 'editor-browser',
+  mutates: true,
+  supportsDryRun: false,
+  permission: { risk: 'write', summary: 'Opens an asset tab in the live editor.' },
+  async impl(input, ctx) {
+    const transport = getTransport(ctx);
+    const session = await resolveEditorSession(ctx, transport);
+    const result = await withTimeout(
+      transport.sendCommand(
+        session,
+        { type: 'open-asset-tab', path: input.path, kind: input.kind },
+        EDITOR_COMMAND_TIMEOUT_MS,
+      ),
+      EDITOR_COMMAND_TIMEOUT_MS,
+      'editor.asset.open',
+    ).catch((err: unknown) => ({
+      ok: false,
+      error: err instanceof Error ? err.message : String(err),
+    }));
+    if (!result.ok) {
+      throw new OperationError('COMMAND_FAILED', result.error ?? 'open-asset-tab command failed', {
+        message: result.error ?? 'open-asset-tab command failed',
+      });
+    }
+    return { ok: true as const };
+  },
+});
+
+// ---------------------------------------------------------------------------
+// editor.story.open
+// ---------------------------------------------------------------------------
+
+const EditorStoryOpenInput = z.object({
+  path: z.string().describe('Project-relative path to a *.stories.tsx/*.stories.ts module.'),
+});
+
+export const editorStoryOpen = defineOperation({
+  name: 'editor.story.open',
+  summary: 'Open a Storybook CSF story in a connected editor session.',
+  description:
+    'The live editor has no wire-level command for this today (see module jsdoc) — this always ' +
+    'throws the declared STORY_OPEN_UNSUPPORTED error against the real transport rather than ' +
+    'reporting a fabricated success; a test transport can implement it for real.',
+  input: EditorStoryOpenInput,
+  result: OkResult,
+  errors: [EDITOR_NOT_RUNNING_ERROR, STORY_OPEN_UNSUPPORTED_ERROR],
+  requires: { editor: true },
+  host: 'editor-browser',
+  mutates: true,
+  supportsDryRun: false,
+  permission: {
+    risk: 'write',
+    summary: 'Would open a story tab in the live editor, when supported.',
+  },
+  async impl(input, ctx) {
+    const transport = getTransport(ctx);
+    const session = await resolveEditorSession(ctx, transport);
+    const result = await withTimeout(
+      transport.openStory(session, input.path, EDITOR_COMMAND_TIMEOUT_MS),
+      EDITOR_COMMAND_TIMEOUT_MS,
+      'editor.story.open',
+    ).catch(() => undefined);
+    if (!result) {
+      throw new OperationError(
+        'STORY_OPEN_UNSUPPORTED',
+        'The connected editor has no wire-level command to open a story today.',
+        {},
+      );
+    }
+    if (!result.ok) {
+      throw new OperationError('COMMAND_FAILED', result.error ?? 'open-story command failed', {
+        message: result.error ?? 'open-story command failed',
+      });
+    }
+    return { ok: true as const };
+  },
+});
+
+export function registerOpenOperations(registry: OperationRegistry): void {
+  registry.register(editorSceneOpen);
+  registry.register(editorAssetOpen);
+  registry.register(editorStoryOpen);
+}

package/src/editor/screenshot-operations.ts

@@ -0,0 +1,99 @@
+/**
+ * `editor.viewport.screenshot.capture` (B3, §8 B3 "capture viewport screenshot").
+ *
+ * B3-followup: wired to a REAL on-demand capture. `HttpEditorTransport.getScreenshot`
+ * now tries the `capture-viewport` relay command first — a real, already-handled
+ * case in the browser's `command-listener.ts` `handleCommand` switch that renders
+ * the LIVE viewport (via `EditorStore.captureViewportImage`, the same offscreen
+ * render-target technique the periodic autosave thumbnail already used) and
+ * returns fresh PNG bytes through the command-result payload. This only fails to
+ * be "fresh" when no browser tab is attached to answer the relay, or the viewport
+ * hasn't bound a renderer/scene/camera yet (e.g. immediately after page load) —
+ * in that case it falls back to `GET /__editor/project-thumbnail?path=<project>`,
+ * the LAST-SAVED thumbnail PNG (`editor-server.ts`'s `/__editor/save-thumbnail`/
+ * `/__editor/project-thumbnail` pair). The result schema's `fresh` field names
+ * which path answered — never silently presented as equivalent.
+ */
+
+import { z } from 'zod';
+import { OperationError } from '../errors.js';
+import { defineOperation, type OperationRegistry } from '../registry.js';
+import {
+  EDITOR_NOT_RUNNING_ERROR,
+  EDITOR_READ_TIMEOUT_MS,
+  getTransport,
+  resolveEditorSession,
+  withTimeout,
+} from './transport.js';
+
+const SCREENSHOT_UNAVAILABLE_ERROR = {
+  code: 'SCREENSHOT_UNAVAILABLE',
+  summary:
+    'Neither a fresh on-demand capture nor a saved thumbnail is available for this session ' +
+    "(no browser tab attached to answer the relay, the viewport hasn't bound a renderer/scene/" +
+    'camera yet, and no thumbnail has been saved), or the read timed out.',
+  data: z.object({}),
+} as const;
+
+const EditorViewportScreenshotCaptureInput = z
+  .object({})
+  .describe(
+    'No input — captures a fresh viewport image for the target editor session, falling back to ' +
+      'its last-saved thumbnail when a fresh capture is unavailable.',
+  );
+
+const EditorViewportScreenshotCaptureResult = z
+  .object({
+    base64: z.string().describe('Base64-encoded image bytes.'),
+    mimeType: z.string().describe('Image MIME type.'),
+    fresh: z
+      .boolean()
+      .describe(
+        'True when this is an on-demand capture of the CURRENT viewport (the `capture-viewport` ' +
+          'relay command); false when it is the last-saved thumbnail fallback (the editor UI ' +
+          "saves one on its own cadence — this project's most recent one, not necessarily current).",
+      ),
+  })
+  .describe('A viewport image — fresh when possible, the last-saved thumbnail otherwise.');
+
+export const editorViewportScreenshotCapture = defineOperation({
+  name: 'editor.viewport.screenshot.capture',
+  summary: "Capture the target editor session's live viewport (falls back to its saved thumbnail).",
+  description:
+    'Relays {type:"capture-viewport"} through POST /__editor/command for a fresh render of the ' +
+    'live viewport; falls back to GET /__editor/project-thumbnail?path=<project> (the last-saved ' +
+    'snapshot) when no browser tab can answer the relay or the viewport has not bound a camera ' +
+    'yet. The result schema names which path answered via `fresh`.',
+  input: EditorViewportScreenshotCaptureInput,
+  result: EditorViewportScreenshotCaptureResult,
+  errors: [EDITOR_NOT_RUNNING_ERROR, SCREENSHOT_UNAVAILABLE_ERROR],
+  requires: { editor: true },
+  host: 'editor-browser',
+  mutates: false,
+  supportsDryRun: false,
+  permission: {
+    risk: 'read',
+    summary: "Reads the live editor viewport (render only) or the project's saved thumbnail file.",
+  },
+  async impl(_input, ctx) {
+    const transport = getTransport(ctx);
+    const session = await resolveEditorSession(ctx, transport);
+    const shot = await withTimeout(
+      transport.getScreenshot(session, EDITOR_READ_TIMEOUT_MS),
+      EDITOR_READ_TIMEOUT_MS,
+      'editor.viewport.screenshot.capture',
+    ).catch(() => undefined);
+    if (!shot) {
+      throw new OperationError(
+        'SCREENSHOT_UNAVAILABLE',
+        'No fresh capture or saved thumbnail is available for this session, or the read timed out.',
+        {},
+      );
+    }
+    return shot;
+  },
+});
+
+export function registerScreenshotOperations(registry: OperationRegistry): void {
+  registry.register(editorViewportScreenshotCapture);
+}

package/src/editor/selection-operations.ts

@@ -0,0 +1,144 @@
+/**
+ * `editor.selection.get` / `editor.selection.set` (B3, §8 B3 "selection read/set").
+ *
+ * Both genuinely wired end to end against the real editor:
+ *  - get: `GET /__editor/state`'s `selectedEntityId`/`selectedEntityIds` —
+ *    always populated by the browser's `collectState` (`command-listener.ts`).
+ *  - set: `POST /__editor/command` with `{type:'select', id}` or
+ *    `{type:'select-multiple', ids}` — existing, already-handled cases in
+ *    the browser's `handleCommand` switch.
+ */
+
+import { z } from 'zod';
+import { OperationError } from '../errors.js';
+import { defineOperation, type OperationRegistry } from '../registry.js';
+import {
+  EDITOR_COMMAND_TIMEOUT_MS,
+  EDITOR_NOT_RUNNING_ERROR,
+  EDITOR_READ_TIMEOUT_MS,
+  getTransport,
+  resolveEditorSession,
+  withTimeout,
+} from './transport.js';
+
+const SELECTION_UNAVAILABLE_ERROR = {
+  code: 'SELECTION_UNAVAILABLE',
+  summary: 'A session is connected but did not answer the selection-state read in time.',
+  data: z.object({}),
+} as const;
+
+const COMMAND_FAILED_ERROR = {
+  code: 'COMMAND_FAILED',
+  summary: 'The connected editor rejected or failed to execute the relayed command.',
+  data: z.object({ message: z.string() }),
+} as const;
+
+// ---------------------------------------------------------------------------
+// editor.selection.get
+// ---------------------------------------------------------------------------
+
+const EditorSelectionGetInput = z
+  .object({})
+  .describe('No input — reads the current selection from the target editor session.');
+
+const EditorSelectionGetResult = z
+  .object({
+    selectedEntityId: z
+      .string()
+      .nullable()
+      .describe('Primary selected entity id, or null when none.'),
+    selectedEntityIds: z.array(z.string()).describe('Every currently selected entity id.'),
+  })
+  .describe('Live selection snapshot from the resolved editor session.');
+
+export const editorSelectionGet = defineOperation({
+  name: 'editor.selection.get',
+  summary: 'Read the current entity selection from a connected editor session.',
+  description:
+    'Resolves a target session (deterministic multi-session rule — see resolveEditorSession) ' +
+    "then reads GET /__editor/state's selectedEntityId/selectedEntityIds. Fails " +
+    'EDITOR_NOT_RUNNING (never hangs — bounded by a named timeout) when no session is available.',
+  input: EditorSelectionGetInput,
+  result: EditorSelectionGetResult,
+  errors: [EDITOR_NOT_RUNNING_ERROR, SELECTION_UNAVAILABLE_ERROR],
+  requires: { editor: true },
+  host: 'editor-browser',
+  mutates: false,
+  supportsDryRun: false,
+  permission: { risk: 'read', summary: 'Reads live editor selection state only.' },
+  async impl(_input, ctx) {
+    const transport = getTransport(ctx);
+    const session = await resolveEditorSession(ctx, transport);
+    const selection = await withTimeout(
+      transport.getSelection(session, EDITOR_READ_TIMEOUT_MS),
+      EDITOR_READ_TIMEOUT_MS,
+      'editor.selection.get',
+    ).catch(() => undefined);
+    if (!selection) {
+      throw new OperationError(
+        'SELECTION_UNAVAILABLE',
+        'The connected editor session did not answer the selection-state read in time.',
+        {},
+      );
+    }
+    return selection;
+  },
+});
+
+// ---------------------------------------------------------------------------
+// editor.selection.set
+// ---------------------------------------------------------------------------
+
+const EditorSelectionSetInput = z
+  .object({
+    ids: z.array(z.string()).describe('Entity ids to select. Empty array clears the selection.'),
+  })
+  .describe('Set the editor selection to exactly these entity ids.');
+
+const EditorSelectionSetResult = z.object({ ok: z.literal(true) });
+
+export const editorSelectionSet = defineOperation({
+  name: 'editor.selection.set',
+  summary: 'Set the entity selection in a connected editor session.',
+  description:
+    'Relays {type:"select"} (single id) or {type:"select-multiple"} (0 or many ids) through ' +
+    "POST /__editor/command — existing, already-handled cases in the browser's command listener.",
+  input: EditorSelectionSetInput,
+  result: EditorSelectionSetResult,
+  errors: [EDITOR_NOT_RUNNING_ERROR, COMMAND_FAILED_ERROR],
+  requires: { editor: true },
+  host: 'editor-browser',
+  mutates: true,
+  supportsDryRun: false,
+  permission: {
+    risk: 'write',
+    summary: 'Changes the live editor selection only (no file/document writes).',
+  },
+  async impl(input, ctx) {
+    const transport = getTransport(ctx);
+    const session = await resolveEditorSession(ctx, transport);
+    const command =
+      input.ids.length === 1
+        ? { type: 'select', id: input.ids[0] }
+        : { type: 'select-multiple', ids: input.ids };
+    const result = await withTimeout(
+      transport.sendCommand(session, command, EDITOR_COMMAND_TIMEOUT_MS),
+      EDITOR_COMMAND_TIMEOUT_MS,
+      'editor.selection.set',
+    ).catch((err: unknown) => ({
+      ok: false,
+      error: err instanceof Error ? err.message : String(err),
+    }));
+    if (!result.ok) {
+      throw new OperationError('COMMAND_FAILED', result.error ?? 'select command failed', {
+        message: result.error ?? 'select command failed',
+      });
+    }
+    return { ok: true as const };
+  },
+});
+
+export function registerSelectionOperations(registry: OperationRegistry): void {
+  registry.register(editorSelectionGet);
+  registry.register(editorSelectionSet);
+}

package/src/editor/session-operations.ts

@@ -0,0 +1,73 @@
+/**
+ * `editor.session.list` (B3, §8 B3 "session discovery").
+ *
+ * Host is `node`, not `editor-browser` — a deliberate, documented departure
+ * from the task brief's "host editor-browser for every op" default. B1's own
+ * definition of `editor-browser` (`../types.ts`) is "invoked through the
+ * existing POST /__editor/command SSE relay ... which broadcasts to the
+ * browser editor and awaits its callback". Session discovery never
+ * broadcasts anything to a browser tab — it reads the local session
+ * registry file and probes each candidate with a plain `GET
+ * /__editor/project` (answered by the Node dev server itself, live browser
+ * tab or not). That is Node-process-local work, the same shape as B2's
+ * `project.*` discovery ops, so `host: 'node'` is the honest fit; see
+ * `../transport.ts`'s module jsdoc for the full transport inventory.
+ *
+ * Unlike every other `editor.*` op, an EMPTY result is success here (this
+ * IS the discovery operation other ops use to decide EDITOR_NOT_RUNNING) —
+ * so `requires` is `{}` and there is no EDITOR_NOT_RUNNING error declared.
+ */
+
+import { z } from 'zod';
+import { defineOperation, type OperationRegistry } from '../registry.js';
+import { EDITOR_SESSION_DISCOVERY_TIMEOUT_MS, getTransport } from './transport.js';
+
+const EditorSessionListInput = z
+  .object({})
+  .describe('No input — lists every live, probe-verified editor session.');
+
+const EditorSessionListResult = z.object({
+  sessions: z
+    .array(
+      z.object({
+        port: z.number().describe('Port the dev server is bound to.'),
+        project: z.string().nullable().describe('Canonical project root currently open, or null.'),
+        pid: z
+          .number()
+          .nullable()
+          .describe('Dev-server process id, when known from the local session registry.'),
+      }),
+    )
+    .describe('Every live session that answered a liveness probe, in no particular order.'),
+});
+
+export const editorSessionList = defineOperation({
+  name: 'editor.session.list',
+  summary: 'List every live, probe-verified editor dev-server session on this machine.',
+  description:
+    'Reads the local session registry (~/.vgai/editor-sessions.json, the format contract owned ' +
+    'by packages/editor/server/session-registry.ts), PID-liveness-filters it, then probe-' +
+    'verifies each survivor with GET /__editor/project (bounded by a named timeout — see ' +
+    'transport.ts). This is the SAME discovery every other editor.* op uses internally to pick ' +
+    "a target session (see resolveEditorSession's deterministic rule).",
+  input: EditorSessionListInput,
+  result: EditorSessionListResult,
+  errors: [],
+  requires: {},
+  host: 'node',
+  mutates: false,
+  supportsDryRun: false,
+  permission: {
+    risk: 'read',
+    summary: 'Reads the local session registry file + probes localhost ports; no writes.',
+  },
+  async impl(_input, ctx) {
+    const transport = getTransport(ctx);
+    const sessions = await transport.listSessions(EDITOR_SESSION_DISCOVERY_TIMEOUT_MS);
+    return { sessions };
+  },
+});
+
+export function registerSessionOperations(registry: OperationRegistry): void {
+  registry.register(editorSessionList);
+}