@vgai/editor 0.4.0 → 0.4.1

package/src/tool-loader.ts

@@ -1,218 +1,144 @@
 /**
- * Project-tool loader — W4/W3 of `docs/DATA-TOOLS-DESIGN.md` (§3.1 contract,
- * §3.5 discovery). The tool sibling of `script-loader.ts`: project
- * `src/tools/*.tool.tsx` modules are dynamically imported via Vite's `/@fs/`
- * path (the same loader pattern, cache-busted with `?t=` on every refresh so
- * a re-discover always gets fresh code).
- *
- * The registry here is LIVE project state derived from the folder scan
- * (`GET /__editor/tool-files`, editor-server.ts) — never a cached manifest
- * (§3.5 rule 2). Project-global tools (`placement: 'document' | 'utility'`,
- * plus the deprecated `'dock'` alias — widened in W0 of
- * docs/EDITOR-WORKSPACE-SHELL-TODO.md §7.2) go to their SEMANTIC homes since
- * W3 of that program (inventory rows T3/B12):
- *   - `document` tools open as CENTER workspace documents —
- *     `components/tool-documents.tsx` consumes the subscribe/get
- *     store below (`useSyncExternalStore`-shaped, mirroring `editorConsole`'s
- *     contract) and the palette lists one `Open Tool: <title>` action each;
- *   - `utility` tools and legacy `dock` tools are registered into the
- *     workspace-UTILITY registry by `publishGlobalTools` below.
- * Discovery LIFECYCLE (when the pass runs) lives in
- * `project-tool-discovery.ts`, started at editor init — not in any panel.
- * Inspector tools (`placement: 'inspector'`, W3) are threaded into the
- * PERMANENT section seam instead: each one becomes an
- * `inspector-section-registry` registration (the same contract the
- * first-party adapters use), wrapped in `InspectorToolSection`'s
- * editor-styled chrome + error boundary. The registry's own change
- * notification re-renders the inspector shell when tools (re)load.
- *
- * HMR: `dev.ts`'s `vgai-script-hmr` plugin already broadcasts
- * `vgai:script-update` for every project `.tsx` change (the same event
- * `play-mode.ts` reloads scripts from). The module-level listener at the
- * bottom re-runs the whole discover+import pass whenever the changed file
- * lives under `src/tools/` — Vite has already invalidated the changed
- * module(s) in its graph by then, so the cache-busted re-import picks up
- * edits to a tool AND to any helper module it imports, no editor reload.
- *
- * Failure physics (§6.5 "errors teach", §3's "never crashes the editor"):
- * a tool file that fails to import, or that lacks the `tool`/default-component
- * export pair, gets ONE console teaching error naming the file and citing the
- * template example, and is skipped — every other tool still loads. A throwing
- * inspector `match` is caught per call (logged once per load) and treated as
- * "no match". Render-time crashes are the error boundary's job
- * (`ToolHost.tsx` / `InspectorToolSection.tsx`), not ours.
+ * Browser loader for explicitly registered editor contributions attached to
+ * project tools. Callable discovery/execution stays Node-side; this module
+ * imports only contribution modules named by package.json metadata.
  */
 
 import type { AuthoringAdapter, EditorNode } from '@engine/adapter';
-import {
-  type GlobalToolPlacement,
-  type InspectorToolProps,
-  normalizeToolPlacement,
-  type ToolConfig,
-} from '@engine/tools/define-tool';
+import { EditorClient } from '@vgai/editor-sdk';
+import type {
+  ToolContributionProps,
+  ToolInspectorContributionMatch,
+  ToolInspectorContributionProps,
+} from '@vgai/editor-sdk/contributions';
 import { type ComponentType, createElement } from 'react';
 import { InspectorToolSection } from './components/InspectorToolSection';
 import { ToolHost } from './components/ToolHost';
 import { registerInspectorSections } from './inspector-section-registry';
 import { getCurrentProject } from './project-manager';
+import type {
+  ProjectToolCatalog,
+  ProjectToolCatalogEntry,
+  ProjectToolContribution,
+} from './project-tools';
 import { registerWorkspaceUtility } from './workspace-utility-registry';
 
-/** Fields shared by every successfully loaded project tool. */
-interface LoadedToolBase {
-  /** `ToolConfig.id` — the mount's `data-testid` suffix. */
+interface LoadedToolContributionBase {
+  /** Tool-qualified contribution id; registration ids are local to one tool. */
   id: string;
-  /** `ToolConfig.title` — the tab label / section header (after ⚙, §3.5). */
+  registrationId: string;
   title: string;
-  /** Project-relative source file, e.g. `src/tools/example.tool.tsx`. */
   file: string;
-  /** Bumped on every (re)load — keys the host so an HMR reload remounts the
-   *  component fresh and clears any tripped error boundary. */
   version: number;
+  tool: ProjectToolCatalogEntry;
 }
 
-/**
- * One successfully loaded project-global tool. `placement` is kept AS
- * DECLARED (`'document'`, `'utility'`, or the deprecated `'dock'` alias —
- * workspace-shell TODO §7.2); `normalizeToolPlacement` decides the physical
- * home: `document` → center document, `utility`/`dock` → workspace utility.
- */
-export interface GlobalTool extends LoadedToolBase {
-  placement: GlobalToolPlacement;
-  /** The module's default export — plain React, rendered inside `ToolHost`. */
-  Component: ComponentType;
+export interface GlobalToolContribution extends LoadedToolContributionBase {
+  point: 'workspace.document' | 'workspace.utility';
+  Component: ComponentType<ToolContributionProps>;
 }
 
-/** One successfully loaded inspector tool (W3), ready to register. */
-export interface InspectorTool extends LoadedToolBase {
-  placement: 'inspector';
-  /** The module's default export, rendered inside `InspectorToolSection`. */
-  Component: ComponentType<InspectorToolProps>;
-  /** The tool's own selection predicate (§3.1 — registry contract). */
-  match: (node: EditorNode | null, adapter: AuthoringAdapter) => boolean;
+export interface InspectorToolContribution extends LoadedToolContributionBase {
+  point: 'selection.inspector';
+  Component: ComponentType<ToolInspectorContributionProps>;
+  match: ToolInspectorContributionMatch;
 }
 
-export type ProjectTool = GlobalTool | InspectorTool;
+export type LoadedToolContribution = GlobalToolContribution | InspectorToolContribution;
 
-const TEMPLATE_EXAMPLE = 'the template worked example: src/tools/example.tool.tsx';
+const TEMPLATE_EXAMPLE = 'src/tools/tuning.document.tsx';
 
-/**
- * Validate a dynamically imported tool module against the §3.1 contract:
- * `export const tool = defineTool(…)` plus a default-exported React
- * component (and, for `placement: 'inspector'`, a callable `match`). Pure
- * and export-tested; returns either the loaded tool or the teaching error to
- * print — the caller owns the console (`refreshProjectTools`) so tests don't
- * have to spy on it.
- */
-export function extractProjectTool(
+export function extractProjectToolContribution(
   mod: unknown,
   file: string,
   version: number,
-): { tool: ProjectTool } | { error: string } {
+  tool: ProjectToolCatalogEntry,
+  registration: ProjectToolContribution,
+): { contribution: LoadedToolContribution } | { error: string } {
   const record = (mod ?? {}) as Record<string, unknown>;
-  const config = record['tool'] as ToolConfig | undefined;
-  if (
-    config === null ||
-    typeof config !== 'object' ||
-    typeof config.id !== 'string' ||
-    typeof config.title !== 'string'
-  ) {
-    return {
-      error:
-        `[tools] ${file} does not export \`tool\` — every project tool exports ` +
-        `\`export const tool = defineTool({ id, title, placement: 'document' | 'inspector' | 'utility' })\` ` +
-        `(docs/DATA-TOOLS-DESIGN.md §3.1; see ${TEMPLATE_EXAMPLE}). Skipped.`,
-    };
-  }
-  if (
-    config.placement !== 'document' &&
-    config.placement !== 'utility' &&
-    config.placement !== 'dock' &&
-    config.placement !== 'inspector'
-  ) {
-    return {
-      error:
-        `[tools] ${file} has placement ${JSON.stringify((config as { placement?: unknown }).placement)} — ` +
-        `the placements are 'document', 'inspector' and 'utility' ('dock' is a deprecated ` +
-        `bottom-panel compatibility alias — docs/EDITOR-WORKSPACE-SHELL-TODO.md §7.2). Skipped.`,
-    };
-  }
   const Component = record['default'];
   if (typeof Component !== 'function') {
     return {
       error:
-        `[tools] ${file} has no default-exported React component — export default a plain ` +
-        `function component next to \`tool\` (docs/DATA-TOOLS-DESIGN.md §3.1; see ` +
-        `${TEMPLATE_EXAMPLE}). Skipped.`,
+        `[tool contributions] ${file} has no default-exported React component ` +
+        `(see ${TEMPLATE_EXAMPLE}). Skipped.`,
     };
   }
-  const base = { id: config.id, title: config.title, file, version };
-  if (config.placement === 'inspector') {
-    // Re-checked here (defineTool already validates) because a hand-rolled
-    // `tool` object can bypass defineTool entirely.
-    if (typeof config.match !== 'function') {
+  const base = {
+    id: `${tool.name}:${registration.id}`,
+    registrationId: registration.id,
+    title: registration.title,
+    file,
+    version,
+    tool,
+  };
+  if (registration.point === 'selection.inspector') {
+    const match = record['match'];
+    if (typeof match !== 'function') {
       return {
         error:
-          `[tools] ${file} has placement 'inspector' but no \`match\` function — pass ` +
-          `match: (node) => boolean in defineTool (docs/DATA-TOOLS-DESIGN.md §3.1; see ` +
-          `${TEMPLATE_EXAMPLE}). Skipped.`,
+          `[tool contributions] ${file} targets 'selection.inspector' but does not export ` +
+          '`match(node, adapter)`. Skipped.',
       };
     }
     return {
-      tool: {
+      contribution: {
         ...base,
-        placement: 'inspector',
-        Component: Component as ComponentType<InspectorToolProps>,
-        match: config.match,
+        point: registration.point,
+        Component: Component as ComponentType<ToolInspectorContributionProps>,
+        match: match as ToolInspectorContributionMatch,
       },
     };
   }
-  return { tool: { ...base, placement: config.placement, Component: Component as ComponentType } };
+  return {
+    contribution: {
+      ...base,
+      point: registration.point,
+      Component: Component as ComponentType<ToolContributionProps>,
+    },
+  };
 }
 
-// --- The live registry (subscribe/get store, `useSyncExternalStore`-shaped) ---
+let globalContributions: GlobalToolContribution[] = [];
+const listeners = new Set<() => void>();
 
-let _globalTools: GlobalTool[] = [];
-const _listeners = new Set<() => void>();
+export function getGlobalToolContributions(): GlobalToolContribution[] {
+  return globalContributions;
+}
 
-/** Every current project-global tool (stable reference between refreshes). */
-export function getGlobalTools(): GlobalTool[] {
-  return _globalTools;
+export function getDocumentToolContributions(): GlobalToolContribution[] {
+  return globalContributions.filter((item) => item.point === 'workspace.document');
 }
 
-/** Explicit document-placement tools: what opens as center documents.
- * Legacy `'dock'` preserves its original bottom-panel behavior. */
-export function getDocumentTools(): GlobalTool[] {
-  return _globalTools.filter((t) => normalizeToolPlacement(t.placement) === 'document');
+export function subscribeToolContributions(fn: () => void): () => void {
+  listeners.add(fn);
+  return () => listeners.delete(fn);
 }
 
-/** Subscribe to global-tool registry changes. Returns an unsubscribe function. */
-export function subscribeGlobalTools(fn: () => void): () => void {
-  _listeners.add(fn);
-  return () => _listeners.delete(fn);
+let editorClient: EditorClient | null = null;
+
+export function getToolContributionClient(): EditorClient {
+  if (!editorClient) {
+    const origin = globalThis.location?.origin;
+    editorClient = origin ? new EditorClient({ url: origin }) : new EditorClient();
+  }
+  return editorClient;
 }
 
-// Inspector tools live in the SECTION registry, not a parallel store: each
-// loaded tool holds one `registerInspectorSections` registration, replaced
-// wholesale on every refresh (fresh Section identity per load = remount =
-// tripped error boundaries clear on HMR, same physics as the dock's
-// version-keyed `ToolHost`).
-let _unregisterInspectorTools: Array<() => void> = [];
+let unregisterInspectorContributions: Array<() => void> = [];
 
-function registrationForInspectorTool(tool: InspectorTool): () => void {
-  // A project `match` that throws must not take the inspector shell down —
-  // it runs inside `Inspector.tsx`'s render. Teach once per load, then
-  // treat as "no match" (the §6.5 failure physics, at match granularity).
+function registrationForInspectorContribution(item: InspectorToolContribution): () => void {
   let warned = false;
   return registerInspectorSections({
-    match: (node, adapter) => {
+    match: (node: EditorNode | null, adapter: AuthoringAdapter) => {
       try {
-        return tool.match(node, adapter);
-      } catch (err) {
+        return item.match(node, adapter);
+      } catch (error) {
         if (!warned) {
           warned = true;
           teachingError(
-            `[tools] ${tool.file}'s match() threw — treating it as "no match" until the file ` +
-              `is fixed and saved (docs/DATA-TOOLS-DESIGN.md §3.1).\n${String(err)}`,
+            `[tool contributions] ${item.file}'s match() threw; treating it as no match until ` +
+              `the file is fixed and saved.\n${String(error)}`,
           );
         }
         return false;
@@ -220,128 +146,113 @@ function registrationForInspectorTool(tool: InspectorTool): () => void {
     },
     Section: ({ adapter, nodeId }) =>
       createElement(InspectorToolSection, {
-        id: tool.id,
-        title: tool.title,
-        file: tool.file,
-        Component: tool.Component,
+        id: item.id,
+        title: item.title,
+        file: item.file,
+        tool: item.tool,
+        Component: item.Component,
         adapter,
         nodeId,
       }),
   });
 }
 
-function publishInspectorTools(tools: InspectorTool[]): void {
-  for (const unregister of _unregisterInspectorTools) unregister();
-  _unregisterInspectorTools = tools.map(registrationForInspectorTool);
+function publishInspectorContributions(items: InspectorToolContribution[]): void {
+  for (const unregister of unregisterInspectorContributions) unregister();
+  unregisterInspectorContributions = items.map(registrationForInspectorContribution);
 }
 
-/**
- * Re-run the whole discovery pass: scan (`/__editor/tool-files`) → import
- * each module fresh (`/@fs/` + `?t=` cache-bust) → validate → publish (dock
- * store + inspector-section registrations). Cheap by design (a project has
- * a handful of tools), so it doubles as the v1 HMR path — see the module
- * doc comment. Never throws: per-file failures are console teaching errors
- * and the file is skipped.
- */
-export async function refreshProjectTools(): Promise<void> {
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: one bounded load pass preserves the catalog order while routing three explicit contribution points.
+export async function refreshProjectToolContributions(): Promise<void> {
   const project = getCurrentProject();
   if (!project) {
-    publishGlobalTools([]);
-    publishInspectorTools([]);
+    publishGlobalContributions([]);
+    publishInspectorContributions([]);
     return;
   }
 
-  let paths: string[];
+  let catalog: ProjectToolCatalog;
   try {
-    const res = await fetch('/__editor/tool-files');
-    if (!res.ok) return; // no dev server route (e.g. browser mode) — keep whatever we had
-    const { files } = (await res.json()) as { files: Array<{ path: string }> };
-    paths = files.map((f) => f.path);
+    const response = await fetch('/__editor/project-tools');
+    if (!response.ok) return;
+    catalog = (await response.json()) as ProjectToolCatalog;
   } catch {
-    return; // server unreachable — keep whatever we had
+    return;
   }
 
   const version = Date.now();
-  const nextGlobal: GlobalTool[] = [];
-  const nextInspector: InspectorTool[] = [];
-  const seen = new Set<string>();
-  for (const file of paths) {
-    let mod: unknown;
-    try {
-      // Same `/@fs/` dynamic-import path as script-loader.ts — the module
-      // arrives through Vite (transpiled, aliases resolved), and the `?t=`
-      // bust guarantees a fresh evaluation on every refresh.
-      mod = await import(/* @vite-ignore */ `/@fs/${project.rootPath}/${file}?t=${version}`);
-    } catch (err) {
-      // Import-time failure: a syntax error, or defineTool itself throwing
-      // its teaching error — surface it verbatim, name the file, keep the
-      // editor alive.
-      teachingError(
-        `[tools] failed to load ${file} — fix the error below or delete the file ` +
-          `(see ${TEMPLATE_EXAMPLE}). Skipped.\n${String(err)}`,
-      );
-      continue;
-    }
-    const result = extractProjectTool(mod, file, version);
-    if ('error' in result) {
-      teachingError(result.error);
-      continue;
-    }
-    if (seen.has(result.tool.id)) {
-      teachingError(
-        `[tools] ${file} reuses tool id "${result.tool.id}" — ids must be unique per project ` +
-          `(they key the dock tabs and inspector sections). Skipped.`,
+  const nextGlobal: GlobalToolContribution[] = [];
+  const nextInspector: InspectorToolContribution[] = [];
+  for (const tool of catalog.tools) {
+    for (const registration of tool.contributions) {
+      const modulePath = registration.entryPath.startsWith('/')
+        ? registration.entryPath
+        : `${project.rootPath}/${registration.entryPath}`;
+      let mod: unknown;
+      try {
+        mod = await import(/* @vite-ignore */ `/@fs/${modulePath}?t=${version}`);
+      } catch (error) {
+        teachingError(
+          `[tool contributions] failed to load ${registration.entryPath}; fix the module or ` +
+            `remove its contribution registration.\n${String(error)}`,
+        );
+        continue;
+      }
+      const result = extractProjectToolContribution(
+        mod,
+        registration.entryPath,
+        version,
+        tool,
+        registration,
       );
-      continue;
+      if ('error' in result) {
+        teachingError(result.error);
+        continue;
+      }
+      if (result.contribution.point === 'selection.inspector') {
+        nextInspector.push(result.contribution);
+      } else {
+        nextGlobal.push(result.contribution);
+      }
     }
-    seen.add(result.tool.id);
-    if (result.tool.placement === 'inspector') nextInspector.push(result.tool);
-    else nextGlobal.push(result.tool);
   }
-  publishGlobalTools(nextGlobal);
-  publishInspectorTools(nextInspector);
+  publishGlobalContributions(nextGlobal);
+  publishInspectorContributions(nextInspector);
 }
 
-// Utility-placement and legacy dock tools hold live workspace-utility
-// registrations, replaced wholesale on every refresh — unregister-first is
-// the registry's own duplicate-id discipline, and a fresh Content per load
-// re-keys ToolHost so HMR clears a tripped error boundary (same physics as
-// the inspector-tool registrations above).
-let _unregisterUtilityTools: Array<() => void> = [];
+let unregisterUtilityContributions: Array<() => void> = [];
 
-function publishGlobalTools(next: GlobalTool[]): void {
-  _globalTools = next;
-  for (const fn of _listeners) fn();
-  for (const unregister of _unregisterUtilityTools) unregister();
-  _unregisterUtilityTools = next
-    .filter((t) => normalizeToolPlacement(t.placement) === 'utility')
-    .map((t) =>
+function publishGlobalContributions(next: GlobalToolContribution[]): void {
+  globalContributions = next;
+  for (const fn of listeners) fn();
+  for (const unregister of unregisterUtilityContributions) unregister();
+  unregisterUtilityContributions = next
+    .filter((item) => item.point === 'workspace.utility')
+    .map((item) =>
       registerWorkspaceUtility({
-        id: `tool:${t.id}`,
-        title: t.title,
-        Content: () => createElement(ToolHost, { tool: t, key: `${t.id}:${t.version}` }),
+        id: `tool:${item.id}`,
+        title: item.title,
+        Content: () =>
+          createElement(ToolHost, {
+            contribution: item,
+            key: `${item.id}:${item.version}`,
+          }),
       }),
     );
 }
 
-/** Test-only publish seam — exercises the same store/utility sync the real
- *  discovery pass runs, without a dev server. */
-export function __publishGlobalToolsForTest(next: GlobalTool[]): void {
-  publishGlobalTools(next);
+export function __publishGlobalToolContributionsForTest(next: GlobalToolContribution[]): void {
+  publishGlobalContributions(next);
 }
 
 function teachingError(message: string): void {
-  // biome-ignore lint/suspicious/noConsole: deliberate, greppable — a broken project tool must be loud in the editor console without crashing the editor (§6.5 "errors teach"; mirrors data-asset.ts's hotSwap rejection)
+  // biome-ignore lint/suspicious/noConsole: broken project contributions must be loud without crashing the editor
   console.error(message);
 }
 
-// --- HMR: re-discover on any src/tools/ change (see module doc comment) ---
 if (import.meta.hot) {
   import.meta.hot.on('vgai:script-update', (data: { file: string }) => {
-    // `data.file` is absolute and forward-slash normalized (dev.ts). Any
-    // change under src/tools/ — the tool itself OR a helper it imports —
-    // triggers a full cheap refresh; Vite already invalidated the module.
     if (!data.file.includes('/src/tools/')) return;
-    void refreshProjectTools();
+    void refreshProjectToolContributions();
   });
 }

package/src/viewport-shading-boundary.ts

@@ -0,0 +1,15 @@
+import type { ViewportShadingRenderer } from '@engine/render/viewport-shading';
+import type * as THREE from 'three';
+import { EDITOR_LAYER } from './editor-layers';
+
+/**
+ * Scene diagnostic shading targets authored/runtime meshes only. Editor
+ * infrastructure shares the native scene for authoring, but its custom
+ * gizmo materials are part of the editor implementation and must stay native.
+ */
+export const isEditorViewportShadingTarget: Parameters<ViewportShadingRenderer['render']>[3] = (
+  mesh: THREE.Mesh,
+) =>
+  !mesh.layers.isEnabled(EDITOR_LAYER) &&
+  !mesh.userData['editorHelper'] &&
+  !mesh.userData['engineInternal'];

package/src/widgets/index.ts

@@ -6,7 +6,8 @@
  * the exact components its inspector renders — so a project tool built from
  * them looks native to the editor and re-skins with it.
  *
- * Import it from a `src/tools/*.tool.tsx` file:
+ * Import it from an editor contribution such as
+ * `src/tools/tuning.document.tsx`:
  *
  * ```tsx
  * import { Inline, NumberInput, SectionHeader, themeVars } from '@editor/widgets';

package/src/workspace-dock-controller.ts

@@ -11,6 +11,10 @@ export interface WorkspaceDockCommands {
   showNavigator(id: 'hierarchy' | 'assets' | 'asset-library'): void;
   showUtility(id: string): void;
   toggleUtility(id: string): void;
+  /** Remove a transient utility from its current Dockview location. Hosts
+   * restore the utility that was active before it was revealed, or collapse
+   * an edge drawer that was opened only for this utility. */
+  closeUtility?(id: string): void;
   showAuxiliary(id: 'undo-history'): void;
   toggleFocus(): void;
   resetLayout(): void;
@@ -46,6 +50,10 @@ export function toggleWorkspaceUtility(id: string): void {
   invoke((value) => value.toggleUtility(id));
 }
 
+export function closeWorkspaceUtility(id: string): void {
+  invoke((value) => value.closeUtility?.(id));
+}
+
 export function showWorkspaceAuxiliary(id: 'undo-history'): void {
   invoke((value) => value.showAuxiliary(id));
 }

package/src/workspace-document-registry.ts

@@ -32,8 +32,8 @@ import type { ComponentType } from 'react';
 /**
  * Semantic document kinds — §7.1 "title, semantic kind, and optional
  * source/provenance metadata". One entry per real first-party implementer
- * §7.1 enumerates, plus `'tool'` for project-authored document-placement
- * tools (§7.2). Extend the union when a new document kind genuinely ships;
+ * §7.1 enumerates, plus distinct generic project-tool runners and optional
+ * project-authored tool surfaces. Extend the union when a new document kind genuinely ships;
  * the registry itself never branches on it.
  */
 export type WorkspaceDocumentKind =
@@ -46,8 +46,8 @@ export type WorkspaceDocumentKind =
   | 'data' // data asset form/table document (§5)
   | 'content-browser' // optional thumbnail-heavy browser (§5)
   | 'build-profiles' // build configuration (§8: 'Build Profiles')
-  | 'operation' // project-local validated tooling operation
-  | 'tool'; // project-authored document-placement tool (§7.2)
+  | 'project-tool' // registered callable using the generic runner
+  | 'tool-contribution'; // optional React presentation for a registered project tool
 
 /** Where a document came from — §7.1 "optional source/provenance metadata".
  *  All fields optional: a Game preview has none; a scene has a `sourcePath`;