@vgai/sdk 0.5.0 → 0.5.2

package/src/project/shared.ts

@@ -40,24 +40,24 @@ import {
 import { dirname, isAbsolute, join, relative, resolve, win32 } from 'node:path';
 import type { SceneEntity } from '@vgai/engine/scene/scene-types';
 import { z } from 'zod';
-import { OperationError } from '../errors.js';
-import type { ErrorDefinition } from '../registry.js';
-import type { OperationContext } from '../types.js';
+import { ToolError } from '../errors.js';
+import type { ToolErrorDefinition } from '../registry.js';
+import type { ToolContext } from '../types.js';
 
 // ---------------------------------------------------------------------------
 // Project-root resolution
 // ---------------------------------------------------------------------------
 
-export const NO_PROJECT_ROOT_ERROR: ErrorDefinition = {
+export const NO_PROJECT_ROOT_ERROR: ToolErrorDefinition = {
   code: 'NO_PROJECT_ROOT',
   summary: 'dispatch() was called without ctx.projectRoot.',
   data: z.object({}).describe('No additional data.'),
 };
 
 /** Every `project.*` op needs `ctx.projectRoot` — this is the one place that enforces it. */
-export function requireProjectRoot(ctx: OperationContext): string {
+export function requireProjectRoot(ctx: ToolContext): string {
   if (!ctx.projectRoot) {
-    throw new OperationError(
+    throw new ToolError(
       'NO_PROJECT_ROOT',
       'dispatch() was called without ctx.projectRoot.',
       {},
@@ -66,7 +66,7 @@ export function requireProjectRoot(ctx: OperationContext): string {
   return ctx.projectRoot;
 }
 
-export const PATH_OUTSIDE_PROJECT_ERROR: ErrorDefinition = {
+export const PATH_OUTSIDE_PROJECT_ERROR: ToolErrorDefinition = {
   code: 'PATH_OUTSIDE_PROJECT',
   summary: 'A given relative path escapes ctx.projectRoot lexically or through a symbolic link.',
   data: z.object({ projectRoot: z.string(), path: z.string() }),
@@ -85,7 +85,7 @@ export function resolveProjectPath(projectRoot: string, relativePath: string): s
   // UNC absolutes even when the SDK process itself is running on POSIX.
   const portablePath = relativePath.replace(/\\/g, '/');
   if (isAbsolute(portablePath) || win32.isAbsolute(relativePath)) {
-    throw new OperationError(
+    throw new ToolError(
       'PATH_OUTSIDE_PROJECT',
       `"${relativePath}" must be project-relative, not absolute.`,
       {
@@ -103,7 +103,7 @@ export function resolveProjectPath(projectRoot: string, relativePath: string): s
     rel.startsWith(`..${'\\'}`) ||
     isAbsolute(rel)
   ) {
-    throw new OperationError(
+    throw new ToolError(
       'PATH_OUTSIDE_PROJECT',
       `"${relativePath}" escapes the project root.`,
       {
@@ -150,7 +150,7 @@ export function resolveProjectPath(projectRoot: string, relativePath: string): s
       // `lstatSync` succeeded but `realpathSync` failed: the path is most
       // commonly a dangling symlink. It must not become a write-through
       // escape when its target later appears.
-      throw new OperationError(
+      throw new ToolError(
         'PATH_OUTSIDE_PROJECT',
         `"${relativePath}" contains an unresolved symbolic link.`,
         { projectRoot, path: relativePath },
@@ -163,7 +163,7 @@ export function resolveProjectPath(projectRoot: string, relativePath: string): s
       physicalRel.startsWith(`..${'\\'}`) ||
       isAbsolute(physicalRel)
     ) {
-      throw new OperationError(
+      throw new ToolError(
         'PATH_OUTSIDE_PROJECT',
         `"${relativePath}" escapes the project root through a symbolic link.`,
         { projectRoot, path: relativePath },
@@ -186,7 +186,7 @@ export interface FileRead {
   hash: string;
 }
 
-export const FILE_NOT_FOUND_ERROR: ErrorDefinition = {
+export const FILE_NOT_FOUND_ERROR: ToolErrorDefinition = {
   code: 'FILE_NOT_FOUND',
   summary: 'The referenced project file does not exist on disk.',
   data: z.object({ path: z.string() }),
@@ -195,7 +195,7 @@ export const FILE_NOT_FOUND_ERROR: ErrorDefinition = {
 /** Read a file's raw text + its content hash. Throws the declared `FILE_NOT_FOUND` shape when absent. */
 export function readFileWithHash(absPath: string): FileRead {
   if (!existsSync(absPath)) {
-    throw new OperationError('FILE_NOT_FOUND', `File not found: ${absPath}`, { path: absPath });
+    throw new ToolError('FILE_NOT_FOUND', `File not found: ${absPath}`, { path: absPath });
   }
   const raw = readFileSync(absPath, 'utf-8');
   return { raw, hash: sha256Hex(raw) };
@@ -210,7 +210,7 @@ export function writeFileAtomic(absPath: string, content: string): void {
   renameSync(tmp, absPath);
 }
 
-export const CONFLICT_ERROR: ErrorDefinition = {
+export const CONFLICT_ERROR: ToolErrorDefinition = {
   code: 'CONFLICT',
   summary:
     'The target file changed on disk since it was last read (baseHash mismatch) — the write ' +
@@ -230,7 +230,7 @@ export function checkNotStale(
   baseHash: string | undefined,
 ): void {
   if (baseHash !== undefined && actualHash !== baseHash) {
-    throw new OperationError(
+    throw new ToolError(
       'CONFLICT',
       `"${path}" changed on disk since it was last read (baseHash mismatch) — refusing to overwrite an external change.`,
       { path, expectedHash: baseHash, actualHash },
@@ -278,7 +278,7 @@ export function mutationResultSchema<T extends z.ZodType>(afterSchema: T) {
 // Scene entity tree walk (read-side helper shared by entity/component ops)
 // ---------------------------------------------------------------------------
 
-export const ENTITY_NOT_FOUND_ERROR: ErrorDefinition = {
+export const ENTITY_NOT_FOUND_ERROR: ToolErrorDefinition = {
   code: 'ENTITY_NOT_FOUND',
   summary: 'No entity with the given id exists in the scene.',
   data: z.object({ id: z.string() }),
@@ -300,7 +300,7 @@ export function findEntityById(entities: SceneEntity[], id: string): SceneEntity
 export function requireEntityById(entities: SceneEntity[], id: string): SceneEntity {
   const found = findEntityById(entities, id);
   if (!found) {
-    throw new OperationError(
+    throw new ToolError(
       'ENTITY_NOT_FOUND',
       `No entity with id "${id}" exists in this scene.`,
       { id },

package/src/project-tool-catalog.ts

@@ -5,10 +5,18 @@ export type ToolContributionPoint =
   | 'generation.result'
   | 'workspace.utility';
 
+/**
+ * One contribution module, FOUND BY SCANNING — never listed anywhere.
+ *
+ * Nothing enumerates these. `src/tools/` in project source and `src/` in every
+ * `vgai`-declaring dependency are walked for the naming convention
+ * (`*.document.tsx`, `*.inspector.tsx`, `*.asset-inspector.tsx`,
+ * `*.result.tsx`, `*.utility.tsx`), and the module itself declares everything
+ * else: `point`, `title` (or `presentations`), and the `tool` it drives, by
+ * name. Its id is derived from this path. A manifest cannot disagree with a
+ * module it does not mention.
+ */
 export interface ProjectToolContribution {
-  id: string;
-  point: ToolContributionPoint;
-  title: string;
   /** Project-relative or package-absolute browser module path. */
   entryPath: string;
 }
@@ -33,8 +41,7 @@ export interface ProjectToolCatalogEntry {
   supportsDryRun: boolean;
   longRunning: boolean;
   permission: { risk: 'read' | 'write' | 'destructive'; summary: string };
-  generation?: { provider: string; role: 'submit' | 'poll' | 'accept' };
-  contributions: ProjectToolContribution[];
+  generation?: { provider: string; role: 'submit' | 'poll' | 'cancel' | 'accept' };
 }
 
 export interface ProjectToolLoadError {
@@ -42,7 +49,16 @@ export interface ProjectToolLoadError {
   message: string;
 }
 
+/**
+ * Callables and contribution modules are SIBLINGS, not parent and child.
+ *
+ * They used to be nested — `tools[].contributions[]` — purely so the browser
+ * loader had a tool to hand the component. A document is not owned by one
+ * callable, and the nesting made project source structurally unable to present
+ * a dependency-provided tool. The module names the tool it drives instead.
+ */
 export interface ProjectToolCatalog {
   tools: ProjectToolCatalogEntry[];
+  contributions: ProjectToolContribution[];
   loadErrors: ProjectToolLoadError[];
 }

package/src/registry.ts

@@ -8,28 +8,28 @@ import {
 import {
   type ExecutionHost,
   type ExecutionRequirements,
-  OPERATION_NAMESPACES,
-  type OperationContext,
-  type OperationNamespace,
+  TOOL_NAMESPACES,
+  type ToolContext,
+  type ToolNamespace,
   type PermissionMetadata,
 } from './types.js';
 
 /** One declared, machine-readable failure mode of an operation (§8 B1: "structured error codes and data schemas"). */
-export interface ErrorDefinition<TCode extends string = string> {
+export interface ToolErrorDefinition<TCode extends string = string> {
   code: TCode;
   /** One-line human summary of when this code fires — for docs/help text, never parsed by callers. */
   summary: string;
-  /** Optional schema for this code's `data` payload. When present, `dispatch()` validates a thrown OperationError's data against it. */
+  /** Optional schema for this code's `data` payload. When present, `dispatch()` validates a thrown ToolError's data against it. */
   data?: z.ZodType;
 }
 
 /**
  * One operation, fully self-describing: identity, both schemas, every
  * declared failure mode, where/how it runs, and its own implementation.
- * Built via `defineOperation` (below), which validates the name shape and
+ * Built via `defineTool` (below), which validates the name shape and
  * error-code uniqueness at definition time.
  */
-export interface OperationDefinition<
+export interface ToolDefinition<
   TInput extends z.ZodType = z.ZodType,
   TResult extends z.ZodType = z.ZodType,
   TErrorCode extends string = string,
@@ -44,8 +44,8 @@ export interface OperationDefinition<
   input: TInput;
   /** Zod schema every `impl` return value is validated against before `dispatch()` succeeds. */
   result: TResult;
-  /** Every structured failure mode this operation may raise via `OperationError`. */
-  errors: ReadonlyArray<ErrorDefinition<TErrorCode>>;
+  /** Every structured failure mode this operation may raise via `ToolError`. */
+  errors: ReadonlyArray<ToolErrorDefinition<TErrorCode>>;
   /** Which live contexts this operation needs (project/editor/play/render). */
   requires: ExecutionRequirements;
   /** Which of the three hosts this operation executes on (node / editor-browser / runtime-page). */
@@ -59,15 +59,15 @@ export interface OperationDefinition<
   /** Coarse permission/risk metadata for gated callers (agents, HTTP/MCP auth). */
   permission: PermissionMetadata;
   /** The actual implementation. Receives already-schema-validated input. */
-  impl: (input: z.infer<TInput>, ctx: OperationContext) => Promise<z.infer<TResult>>;
+  impl: (input: z.infer<TInput>, ctx: ToolContext) => Promise<z.infer<TResult>>;
 }
 
-/** `listOperations()`'s element shape — every field of `OperationDefinition` except `impl`, so enumerating never risks invoking anything. */
-export type OperationSummary<
+/** `listOperations()`'s element shape — every field of `ToolDefinition` except `impl`, so enumerating never risks invoking anything. */
+export type ToolSummary<
   TInput extends z.ZodType = z.ZodType,
   TResult extends z.ZodType = z.ZodType,
   TErrorCode extends string = string,
-> = Omit<OperationDefinition<TInput, TResult, TErrorCode>, 'impl'>;
+> = Omit<ToolDefinition<TInput, TResult, TErrorCode>, 'impl'>;
 
 const NAME_PATTERN = /^[a-z][a-zA-Z0-9]*(\.[a-z][a-zA-Z0-9]*)+$/;
 
@@ -77,9 +77,9 @@ function namespaceOf(name: string): string {
 }
 
 /**
- * Typed helper that builds an `OperationDefinition`. Pure and synchronous —
+ * Typed helper that builds an `ToolDefinition`. Pure and synchronous —
  * it does not touch a registry (so it can never itself throw "duplicate
- * name"; that check happens at `OperationRegistry.register`, which has the
+ * name"; that check happens at `ToolRegistry.register`, which has the
  * cross-operation state to detect it) — but it DOES validate the two things
  * that are decidable from the definition alone: the name is a valid dotted
  * `namespace.rest` string under one of the four operation namespaces
@@ -89,31 +89,31 @@ function namespaceOf(name: string): string {
  * to `z.infer<TInput>` / `z.infer<TResult>` so a mismatched implementation
  * fails to compile rather than failing at runtime.
  */
-export function defineOperation<
+export function defineTool<
   TInput extends z.ZodType,
   TResult extends z.ZodType,
   TErrorCode extends string = string,
 >(
-  def: OperationDefinition<TInput, TResult, TErrorCode>,
-): OperationDefinition<TInput, TResult, TErrorCode> {
+  def: ToolDefinition<TInput, TResult, TErrorCode>,
+): ToolDefinition<TInput, TResult, TErrorCode> {
   if (!NAME_PATTERN.test(def.name)) {
     throw new Error(
-      `defineOperation: "${def.name}" is not a valid dotted operation name ` +
+      `defineTool: "${def.name}" is not a valid dotted operation name ` +
         '(expected e.g. "project.scene.read" — lowercase-leading segments joined by dots).',
     );
   }
   const ns = namespaceOf(def.name);
-  if (!(OPERATION_NAMESPACES as readonly string[]).includes(ns)) {
+  if (!(TOOL_NAMESPACES as readonly string[]).includes(ns)) {
     throw new Error(
-      `defineOperation: "${def.name}" has unknown namespace "${ns}" — expected one of ` +
-        `${OPERATION_NAMESPACES.join(', ')} (§5.7).`,
+      `defineTool: "${def.name}" has unknown namespace "${ns}" — expected one of ` +
+        `${TOOL_NAMESPACES.join(', ')} (§5.7).`,
     );
   }
   const seen = new Set<string>();
   for (const err of def.errors) {
     if (seen.has(err.code)) {
       throw new Error(
-        `defineOperation: "${def.name}" declares duplicate error code "${err.code}".`,
+        `defineTool: "${def.name}" declares duplicate error code "${err.code}".`,
       );
     }
     seen.add(err.code);
@@ -122,25 +122,25 @@ export function defineOperation<
 }
 
 /** `dispatch()`'s result — a discriminated union, never a thrown exception, so every projection (CLI/HTTP/MCP) gets one uniform JSON-able shape for both success and failure. */
-export type OperationOutcome<TResult = unknown> =
+export type ToolOutcome<TResult = unknown> =
   | { ok: true; data: TResult }
   | { ok: false; error: StructuredOperationError };
 
 /**
  * Normalize whatever an `impl` threw into a `StructuredOperationError`.
  * Three cases:
- *  1. A declared `OperationError` whose code IS in `def.errors` and whose
+ *  1. A declared `ToolError` whose code IS in `def.errors` and whose
  *     `data` (if the code declares a schema) validates — forwarded as-is,
  *     `data` replaced by its *parsed* form.
  *  2. A declared code whose `data` fails its own schema — that is itself an
  *     implementation bug, surfaced as INVALID_OUTPUT (never silently
  *     forwarding unvalidated data).
- *  3. Anything else — an `OperationError` with an undeclared code, a plain
+ *  3. Anything else — an `ToolError` with an undeclared code, a plain
  *     `Error`, or a non-Error throw — normalized into INTERNAL_ERROR. The
  *     raw exception/message is tucked into `data.message`, never used as
  *     the identifying `code`.
  */
-function normalizeThrown(def: OperationDefinition, err: unknown): StructuredOperationError {
+function normalizeThrown(def: ToolDefinition, err: unknown): StructuredOperationError {
   if (isOperationError(err)) {
     const declared = def.errors.find((e) => e.code === err.code);
     if (!declared) {
@@ -178,7 +178,7 @@ function normalizeThrown(def: OperationDefinition, err: unknown): StructuredOper
   };
 }
 
-function toSummary(def: OperationDefinition): OperationSummary {
+function toSummary(def: ToolDefinition): ToolSummary {
   const { impl: _impl, ...summary } = def;
   return summary;
 }
@@ -228,29 +228,29 @@ function firstStrippedInputPath(
  * single validated call path: input schema -> impl -> result schema, with
  * every failure normalized into `StructuredOperationError`.
  */
-export class OperationRegistry {
-  private readonly definitions = new Map<string, OperationDefinition>();
+export class ToolRegistry {
+  private readonly definitions = new Map<string, ToolDefinition>();
 
   /** Register a definition. Throws synchronously on a duplicate name — names are unique and stable by construction, not by convention. */
   register<TInput extends z.ZodType, TResult extends z.ZodType, TErrorCode extends string>(
-    def: OperationDefinition<TInput, TResult, TErrorCode>,
+    def: ToolDefinition<TInput, TResult, TErrorCode>,
   ): void {
     if (this.definitions.has(def.name)) {
       throw new Error(
-        `OperationRegistry.register: "${def.name}" is already registered — operation names ` +
+        `ToolRegistry.register: "${def.name}" is already registered — operation names ` +
           'must be unique and stable.',
       );
     }
-    this.definitions.set(def.name, def as unknown as OperationDefinition);
+    this.definitions.set(def.name, def as unknown as ToolDefinition);
   }
 
   /** Enumerate every registered operation's metadata. Never invokes `impl`. */
-  listOperations(): OperationSummary[] {
+  listOperations(): ToolSummary[] {
     return [...this.definitions.values()].map(toSummary);
   }
 
   /** Look up one operation's full definition (including `impl`) by name, or `undefined`. */
-  getOperation(name: string): OperationDefinition | undefined {
+  getOperation(name: string): ToolDefinition | undefined {
     return this.definitions.get(name);
   }
 
@@ -261,7 +261,7 @@ export class OperationRegistry {
   /**
    * Validate `input` against the named operation's input schema, run its
    * `impl`, validate the return value against its result schema, and return
-   * a uniform `OperationOutcome` — success or a `StructuredOperationError`.
+   * a uniform `ToolOutcome` — success or a `StructuredOperationError`.
    * Never throws for an expected failure (unknown name, bad input, impl
    * throw, bad output); those are exactly what this method exists to turn
    * into a machine-readable result instead of an exception a caller has to
@@ -270,8 +270,8 @@ export class OperationRegistry {
   async dispatch<TResult = unknown>(
     name: string,
     input: unknown,
-    ctx: OperationContext = {},
-  ): Promise<OperationOutcome<TResult>> {
+    ctx: ToolContext = {},
+  ): Promise<ToolOutcome<TResult>> {
     const def = this.definitions.get(name);
     if (!def) {
       return {
@@ -336,4 +336,4 @@ export class OperationRegistry {
   }
 }
 
-export type { ExecutionHost, ExecutionRequirements, OperationContext, OperationNamespace };
+export type { ExecutionHost, ExecutionRequirements, ToolContext, ToolNamespace };

package/src/render/render-cinematic.ts

@@ -642,6 +642,21 @@ export async function launchEntryServer(
   engineRoot: string,
   onProgress: ((e: RenderCinematicProgress) => void) | undefined,
   signal?: AbortSignal,
+  options?: {
+    /**
+     * Extra args appended to the `npx vite` 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
+     * `localhost` default — which on an IPv6-first box binds only `::1`,
+     * so this function's own `127.0.0.1` readiness probe (and baseUrl)
+     * never connects. A caller rendering such a project passes
+     * `['--host', '127.0.0.1']` here (see
+     * `scripts/generate-learn-thumbnails.ts`). Optional and defaulted:
+     * every existing caller is byte-identical in behavior.
+     */
+    readonly extraViteArgs?: readonly string[];
+  },
 ): Promise<LaunchedServer> {
   if (/^https?:\/\//.test(entry)) {
     return { baseUrl: entry.replace(/\/$/, ''), stop: async () => {} };
@@ -667,7 +682,15 @@ export async function launchEntryServer(
   // reading those pipes) never exits even after the render is fully done.
   const child: ChildProcess = spawn(
     'npx',
-    ['vite', '--config', configPath, '--port', String(port), '--strictPort'],
+    [
+      'vite',
+      '--config',
+      configPath,
+      '--port',
+      String(port),
+      '--strictPort',
+      ...(options?.extraViteArgs ?? []),
+    ],
     { cwd: engineRoot, stdio: ['ignore', 'pipe', 'pipe'], detached: true },
   );
   let serverOutput = '';

package/src/tools.ts

@@ -1,24 +1,31 @@
 /**
  * Public project-tool contract.
  *
- * A tool is an ordinary registered JavaScript/TypeScript function. The SDK's
- * operation registry remains the internal validated dispatcher used by every
- * projection, but projects should not need a second public ontology merely
- * because the host calls their function through a transport.
+ * A tool is an ordinary registered function with a WIRE CONTRACT: declared
+ * input/result schemas, structured error codes, and the metadata a caller reads
+ * before invoking (`permission`, `host`, `mutates`, `supportsDryRun`). The
+ * contract exists because a tool is called across a process boundary — CLI to
+ * editor to node host, and `vgai mcp` to an external agent over stdio — where
+ * you cannot throw. `ToolRegistry.dispatch` turns every expected failure
+ * (unknown name, bad input, an `impl` throw, a bad return) into a typed outcome
+ * instead.
+ *
+ * This module is the surface every consumer imports. It re-exports rather than
+ * renames: there is ONE vocabulary, and it is this one.
  */
-export { OperationError as ToolError } from './errors.js';
+export { ToolError } from './errors.js';
 export {
-  defineOperation as defineTool,
-  type ErrorDefinition as ToolErrorDefinition,
-  type OperationDefinition as ToolDefinition,
-  type OperationOutcome as ToolOutcome,
-  OperationRegistry as ToolRegistry,
-  type OperationSummary as ToolSummary,
+  defineTool,
+  type ToolDefinition,
+  type ToolErrorDefinition,
+  type ToolOutcome,
+  ToolRegistry,
+  type ToolSummary,
 } from './registry.js';
 export type {
   ExecutionHost as ToolHost,
   ExecutionRequirements as ToolRequirements,
-  OperationContext as ToolContext,
   PermissionMetadata as ToolPermission,
   PermissionRisk as ToolPermissionRisk,
+  ToolContext,
 } from './types.js';

package/src/types.ts

@@ -4,8 +4,8 @@
  */
 
 /** The four namespaces every operation name must live under (§5.7). */
-export const OPERATION_NAMESPACES = ['project', 'editor', 'play', 'cinematic'] as const;
-export type OperationNamespace = (typeof OPERATION_NAMESPACES)[number];
+export const TOOL_NAMESPACES = ['project', 'editor', 'play', 'cinematic'] as const;
+export type ToolNamespace = (typeof TOOL_NAMESPACES)[number];
 
 /**
  * Which of the three hosts an operation executes on (§8 B1, the
@@ -22,7 +22,7 @@ export type OperationNamespace = (typeof OPERATION_NAMESPACES)[number];
  *
  * `cinematic.render` is pinned `node` and MUST NOT ride the editor relay's
  * short timeout — it is a long-running job (see `longRunning` on
- * `OperationDefinition`).
+ * `ToolDefinition`).
  */
 export type ExecutionHost = 'node' | 'editor-browser' | 'runtime-page';
 
@@ -114,7 +114,7 @@ export interface ProjectOutputWriter {
  * concrete fields (editor session ids, play session handles, render job
  * state); B1 only needs the two seams its sample operations touch.
  */
-export interface OperationContext {
+export interface ToolContext {
   /** Absolute path to the target project's root, for `project`-context ops. */
   projectRoot?: string;
   /** Base URL of a connected editor session, for `editor`-context ops. */