@vgai/editor-sdk 0.4.0 → 0.4.1

package/README.md

@@ -30,17 +30,52 @@ One export, `EditorClient`, plus its types (`EditorState`, `ProjectInfo`,
   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`,
-  `setHelperType`
+- Display: `setGrid`, `setHelpers`, `setStats`, `setShadingMode` (`solid`,
+  `unlit`, `wireframe`, `normals`, or `overdraw`), `setHelperType` (including
+  the independent `bounds` category). Shading targets the active Scene/Game
+  viewport and remains render-only, session-local state.
 - Transform tools: `setTransformMode`, `setTransformSpace`, `setSnap`
 - Scene/project: `openScene`, `createProject`, `openProject`, `getProject`,
   `listRecentProjects`
 - State/logs: `getState`, `waitForState(predicate, timeoutMs)`,
   `getLogEntries`
+- Project tools: `listProjectTools`, `runProjectTool`
 
 Commands throw on `{ ok: false }` responses, including the server's timeout
 when no browser editor is connected — failures are never silently swallowed.
 
+### Editor contributions for project tools
+
+An optional React contribution is a normal default-exported component. Import
+its props from `@vgai/editor-sdk/contributions`; the editor supplies the exact
+registered tool and an already-configured client:
+
+```tsx
+import { Button } from '@editor/widgets';
+import type { ToolContributionProps } from '@vgai/editor-sdk/contributions';
+
+export default function MapBuilder({ tool, client }: ToolContributionProps) {
+  return (
+    <Button
+      variant="solid"
+      onClick={() => void client.runProjectTool(tool.name, { seed: 42 }, { confirm: true })}
+    >
+      Build map
+    </Button>
+  );
+}
+```
+
+The package registration chooses `workspace.document`, `workspace.utility`, or
+`selection.inspector`. Inspector contributions additionally receive
+`node`/`nodeId` and export `match(node, adapter)`. There is no extension class,
+lifecycle, or proprietary UI description.
+
+Use ordinary React/CSS for composition and `@editor/widgets` for controls.
+Shape the UI for its contribution point: a bounded workspace for documents, a
+dense single column for inspector sections, and a compact row/status block for
+utilities. Badges are for short statuses and counts, not headings.
+
 ### Asset Lab capture
 
 `captureAssetPreview` accepts exactly one source: an authored entity hierarchy

package/package.json

@@ -2,7 +2,7 @@
   "name": "@vgai/editor-sdk",
   "author": "Volter AI, Inc.",
   "license": "Apache-2.0",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "type": "module",
   "repository": {
     "type": "git",
@@ -16,6 +16,7 @@
     "src"
   ],
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./contributions": "./src/contributions.ts"
   }
 }

package/src/client.ts

@@ -7,9 +7,9 @@ import type {
   GameCapture,
   HelperVisibility,
   ProjectInfo,
-  ProjectOperationCatalog,
-  ProjectOperationOutcome,
   ProjectTemplate,
+  ProjectToolCatalog,
+  ProjectToolOutcome,
   RecentProject,
   ShadingMode,
   TransformMode,
@@ -285,32 +285,32 @@ export class EditorClient {
     return data.projects;
   }
 
-  // --- Project operations ---
+  // --- Registered project tools ---
 
-  /** List live project-local operation definitions below `src/operations/`.
-   * The editor server loads metadata in Node; operation modules never enter the
+  /** List tools explicitly registered in `package.json#vgai.tools`.
+   * The editor server loads callable metadata in Node; 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;
+  async listProjectTools(): Promise<ProjectToolCatalog> {
+    const res = await fetch(`${this.baseUrl}/__editor/project-tools`);
+    if (!res.ok) throw new Error(`Failed to list project tools: ${res.status}`);
+    return (await res.json()) as ProjectToolCatalog;
   }
 
-  /** Execute one Node-hosted project operation through the existing validated
-   * operation registry. Write/destructive operations require `confirm:true`. */
-  async runProjectOperation(
+  /** Execute one Node-hosted project tool through the shared validated
+   * dispatcher. Write/destructive tools require `confirm:true`. */
+  async runProjectTool(
     name: string,
     input: unknown = {},
     options: { confirm?: boolean } = {},
-  ): Promise<ProjectOperationOutcome> {
-    const res = await fetch(`${this.baseUrl}/__editor/project-operations/run`, {
+  ): Promise<ProjectToolOutcome> {
+    const res = await fetch(`${this.baseUrl}/__editor/project-tools/run`, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify({ name, input, confirm: options.confirm === true }),
     });
-    const body = (await res.json()) as ProjectOperationOutcome;
+    const body = (await res.json()) as ProjectToolOutcome;
     if (!body || typeof body !== 'object' || typeof body.ok !== 'boolean') {
-      throw new Error(`Project operation returned an invalid response (${res.status}).`);
+      throw new Error(`Project tool returned an invalid response (${res.status}).`);
     }
     return body;
   }

package/src/contributions.ts

@@ -0,0 +1,39 @@
+/**
+ * Props for ordinary React components registered at editor contribution
+ * points. There is deliberately no extension class or lifecycle: package
+ * metadata names a module and the editor renders its default export.
+ */
+
+import type { EditorClient } from './client.js';
+import type { ProjectToolCatalogEntry } from './types.js';
+
+/** Stable, format-neutral selection data available to inspector contributions. */
+export interface ToolContributionNode {
+  readonly id: string;
+  readonly label: string;
+  readonly role?: string;
+  readonly secondaryLabel?: string;
+  readonly kind: string;
+  readonly parentId: string | null;
+  readonly childIds: string[];
+  readonly flags: object;
+}
+
+export interface ToolContributionProps {
+  /** The exact registered callable this contribution presents. */
+  readonly tool: ProjectToolCatalogEntry;
+  /** Direct editor SDK client; invoke with `client.runProjectTool(tool.name, ...)`. */
+  readonly client: EditorClient;
+}
+
+export interface ToolInspectorContributionProps extends ToolContributionProps {
+  readonly node: ToolContributionNode | null;
+  readonly nodeId: string | null;
+}
+
+/** Optional named export required by `selection.inspector` contributions. */
+export type ToolInspectorContributionMatch = (
+  node: ToolContributionNode | null,
+  /** Adapter-native API. Import its concrete type when a contribution needs it. */
+  adapter: unknown,
+) => boolean;

package/src/index.ts

@@ -1,4 +1,10 @@
 export { EditorClient } from './client.js';
+export type {
+  ToolContributionNode,
+  ToolContributionProps,
+  ToolInspectorContributionMatch,
+  ToolInspectorContributionProps,
+} from './contributions.js';
 export type {
   AssetKind,
   AssetPreviewBackground,
@@ -12,10 +18,11 @@ export type {
   GameCapture,
   HelperVisibility,
   ProjectInfo,
-  ProjectOperationCatalog,
-  ProjectOperationCatalogEntry,
-  ProjectOperationOutcome,
   ProjectTemplate,
+  ProjectToolCatalog,
+  ProjectToolCatalogEntry,
+  ProjectToolContribution,
+  ProjectToolOutcome,
   RecentProject,
   ShadingMode,
   TransformMode,

package/src/types.ts

@@ -9,6 +9,7 @@ export type AssetKind =
   | 'material';
 
 export interface HelperVisibility {
+  bounds: boolean;
   lights: boolean;
   cameras: boolean;
   colliders: boolean;
@@ -103,7 +104,7 @@ export interface EditorState {
   showGrid: boolean;
   showHelpers: boolean;
   showStats: boolean;
-  shadingMode: 'solid' | 'wireframe' | 'unlit';
+  shadingMode: ShadingMode;
   helperVisibility: HelperVisibility;
   transformMode: 'translate' | 'rotate' | 'scale';
   transformSpace: 'world' | 'local';
@@ -167,7 +168,7 @@ export interface EditorState {
 }
 
 export type ViewPreset = 'top' | 'front' | 'right' | 'perspective';
-export type ShadingMode = 'solid' | 'wireframe' | 'unlit';
+export type ShadingMode = 'solid' | 'unlit' | 'wireframe' | 'normals' | 'overdraw';
 export type TransformMode = 'translate' | 'rotate' | 'scale';
 export type TransformSpace = 'world' | 'local';
 
@@ -186,7 +187,7 @@ export interface RecentProject {
   thumbnail?: string;
 }
 
-export interface ProjectOperationCatalogEntry {
+export interface ProjectToolCatalogEntry {
   name: string;
   summary: string;
   description: string;
@@ -200,14 +201,28 @@ export interface ProjectOperationCatalogEntry {
   supportsDryRun: boolean;
   longRunning: boolean;
   permission: { risk: 'read' | 'write' | 'destructive'; summary: string };
+  contributions: ProjectToolContribution[];
 }
 
-export interface ProjectOperationCatalog {
-  operations: ProjectOperationCatalogEntry[];
+export type ToolContributionPoint =
+  | 'workspace.document'
+  | 'selection.inspector'
+  | 'workspace.utility';
+
+export interface ProjectToolContribution {
+  id: string;
+  point: ToolContributionPoint;
+  title: string;
+  /** Project-relative or package-absolute browser module path. */
+  entryPath: string;
+}
+
+export interface ProjectToolCatalog {
+  tools: ProjectToolCatalogEntry[];
   loadErrors: Array<{ sourcePath: string; message: string }>;
 }
 
-export type ProjectOperationOutcome =
+export type ProjectToolOutcome =
   | { ok: true; data: unknown }
   | {
       ok: false;