@vgai/engine 0.4.0 → 0.4.1

package/src/tools/define-tool.ts

@@ -1,191 +0,0 @@
-/**
- * Project tools — W4/W3 of `docs/DATA-TOOLS-DESIGN.md` (§3 contract).
- *
- * A project tool is ONE file, `src/tools/<name>.tool.tsx`, discovered by
- * folder scan (same physics as data assets, §3.1: zero registration, delete
- * the file → gone). The file exports exactly two things:
- *
- * ```tsx
- * export const tool = defineTool({
- *   id: 'tuning',          // stable slug — becomes the tab's test id
- *   title: 'Tuning',       // the tab label (rendered after a ⚙ marker)
- *   placement: 'document', // project-global dashboard (§3.2; 'dock' = deprecated alias)
- * });
- * export default function Tuning() { … }   // plain React
- * ```
- *
- * or, selection-scoped (W3 — §3.2's second placement):
- *
- * ```tsx
- * export const tool = defineTool({
- *   id: 'spin',
- *   title: 'Spin',
- *   placement: 'inspector',                  // selection-scoped section
- *   match: (node) => node?.kind === 'mesh',  // same contract as the
- * });                                        // inspector-section registry
- * export default function Spin({ node }: InspectorToolProps) { … }
- * ```
- *
- * The editor renders dock tools as visually distinct tabs after a separator
- * at the end of the bottom dock's tab row (§3.5); inspector tools render as
- * a ⚙-marked section in the Inspector rail whenever `match` accepts the
- * current selection. Both render inside an error boundary — a crashing tool
- * never takes the editor down. Tools are EDITOR-ONLY: no game build bundles
- * `src/tools/` (§4 — nothing in game code imports it), so dev/cheat surfaces
- * can never leak into a tester serve.
- *
- * This module is deliberately react-free metadata (the engine core outside
- * `src/react/` must not import react — `test/react-core-import-ban.test.ts`);
- * the react-facing tool hooks live in `@engine/react/use-data`, and the
- * editor-styled widget kit tools build panels from is `@editor/widgets`.
- */
-
-import type { AuthoringAdapter, EditorNode } from '../adapter';
-
-/**
- * Tool placements. Since W0 of the editor workspace-shell program
- * (docs/EDITOR-WORKSPACE-SHELL-TODO.md §7.2), placement describes MEANING,
- * not a physical container:
- *
- * - `'document'` — a substantial project-global surface (tuning dashboard,
- *   table, graph) that belongs in the center workspace;
- * - `'inspector'` — a selection-scoped section in the right Inspector rail;
- * - `'utility'` — a transient output/debug surface for the bottom drawer;
- * - `'dock'` — DEPRECATED physical compatibility alias. Existing dock tools
- *   remain in the bottom panel so projects do not lose the ability to tune
- *   them while watching the Game/Scene.
- *
- * Only an explicit `document` declaration replaces the center subject.
- * `utility` and legacy `dock` remain in the bottom drawer. Deliberately
- * still nothing else — no floating windows, no in-game overlay
- * host (docs/DATA-TOOLS-DESIGN.md §3.2 "deliberately NOT built").
- */
-export type ToolPlacement = 'document' | 'inspector' | 'utility' | 'dock';
-
-/** The project-global (non-selection-scoped) placements. */
-export type GlobalToolPlacement = 'document' | 'utility' | 'dock';
-
-/**
- * Compatibility means preserving behavior: legacy `'dock'` tools remain in
- * the bottom panel. New tools choose `'document'`, `'utility'`, or
- * `'inspector'` deliberately.
- */
-export function normalizeToolPlacement(
-  placement: ToolPlacement,
-): 'document' | 'inspector' | 'utility' {
-  return placement === 'dock' ? 'utility' : placement;
-}
-
-/** Fields every tool declares — see {@link defineTool} for the contract. */
-interface ToolConfigBase {
-  /**
-   * Stable slug for this tool: letters/digits/`-`/`_` only. It becomes the
-   * mount's `data-testid` (`bottom-tab-tool-<id>` for dock tools,
-   * `inspector-tool-<id>` for inspector tools), so keep it short and never
-   * rename it casually — automation and saved layouts key off it.
-   */
-  id: string;
-  /** Human label: the dock tab text, or the inspector section's header,
-   *  rendered after the ⚙ project-tool marker (§3.5). */
-  title: string;
-}
-
-/** A project-global tool (§3.2 W4; `'dock'` preserves its historical bottom
- *  placement through the `'utility'` compatibility normalization). */
-export interface GlobalToolConfig extends ToolConfigBase {
-  placement: GlobalToolPlacement;
-}
-
-/** A selection-scoped Inspector section (§3.2, W3). */
-export interface InspectorToolConfig extends ToolConfigBase {
-  placement: 'inspector';
-  /**
-   * When this section appears — the SAME contract as the editor's
-   * `inspector-section-registry`: called with the currently selected node
-   * (`null` in the no-selection/environment state) and the active authoring
-   * adapter; return `true` to render. Keep it cheap and pure — it runs on
-   * every inspector render. A `match` that throws is treated as `false`
-   * (with one console teaching error), never crashing the inspector.
-   */
-  match: (node: EditorNode | null, adapter: AuthoringAdapter) => boolean;
-}
-
-/** Metadata for a project tool — a discriminated union on `placement`. */
-export type ToolConfig = GlobalToolConfig | InspectorToolConfig;
-
-/**
- * Props the editor passes to an INSPECTOR tool's default-exported component
- * (dock tools receive no props). Everything richer (live game store, field
- * addresses) arrives through the §3.3 hooks, not through more props.
- */
-export interface InspectorToolProps {
-  /** The selected node your `match` accepted (`null` in the no-selection
-   *  state, if your `match` chose to accept it). */
-  node: EditorNode | null;
-  /** The selected node's stable id (`null` in the no-selection state). */
-  nodeId: string | null;
-}
-
-const TEMPLATE_EXAMPLE = 'the template worked example: src/tools/example.tool.tsx';
-
-/** Teaching-error helper (§6.5): every rejection names the fix and cites the
- *  template example by path. */
-function toolError(problem: string, fix: string): Error {
-  return new Error(`defineTool: ${problem} — ${fix} (see ${TEMPLATE_EXAMPLE}).`);
-}
-
-/**
- * Validate and freeze a project tool's metadata (docs/DATA-TOOLS-DESIGN.md
- * §3.1). Call it once at module scope of a `src/tools/<name>.tool.tsx` file
- * and export the result as `tool`, next to a default-exported React
- * component — the editor's folder scan picks the file up automatically.
- *
- * Fails loud (§6.5 "errors teach") on anything malformed rather than letting
- * a half-shaped tool render confusingly: bad `id`/`title`, an unknown
- * placement, an inspector tool without a callable `match`.
- *
- * The returned config is frozen: tool metadata is a definition, not state
- * (the same immutability rule data assets follow, §2.1).
- */
-export function defineTool(config: ToolConfig): Readonly<ToolConfig> {
-  if (config === null || typeof config !== 'object') {
-    throw toolError(
-      'expected a config object',
-      "call it as defineTool({ id, title, placement: 'document' })",
-    );
-  }
-  const { id, title, placement } = config;
-  if (
-    placement !== 'document' &&
-    placement !== 'utility' &&
-    placement !== 'dock' &&
-    placement !== 'inspector'
-  ) {
-    throw toolError(
-      `unknown placement ${JSON.stringify(placement)}`,
-      "the placements are 'document' (project-global center document), 'inspector' " +
-        "(selection-scoped section) and 'utility' (transient bottom-drawer output); " +
-        "'dock' remains accepted as a deprecated bottom-panel alias " +
-        '(docs/EDITOR-WORKSPACE-SHELL-TODO.md §7.2)',
-    );
-  }
-  if (typeof id !== 'string' || !/^[a-zA-Z0-9_-]+$/.test(id)) {
-    throw toolError(
-      `invalid id ${JSON.stringify(id)}`,
-      'pass a non-empty slug of letters, digits, "-" or "_" — it becomes the tool\'s data-testid (bottom-tab-tool-<id> / inspector-tool-<id>)',
-    );
-  }
-  if (typeof title !== 'string' || title.trim() === '') {
-    throw toolError(`invalid title ${JSON.stringify(title)}`, 'pass a short human-readable label');
-  }
-  if (placement === 'inspector') {
-    if (typeof config.match !== 'function') {
-      throw toolError(
-        `placement 'inspector' requires a match function (got ${JSON.stringify(config.match)})`,
-        "pass match: (node) => boolean — e.g. match: (node) => node?.kind === 'mesh' — deciding which selections show this section",
-      );
-    }
-    return Object.freeze({ id, title, placement, match: config.match });
-  }
-  return Object.freeze({ id, title, placement });
-}