@volter/editor-sdk 0.5.57

package/src/http-transport.browser.ts

@@ -0,0 +1,14 @@
+/** Browser fetch owns connections and has no Node header timeout. */
+import type { Dispatcher } from 'undici';
+
+export function createDispatcher(_timeoutMs: number): undefined {
+  return undefined;
+}
+
+export function dispatchFetch(
+  url: string,
+  init?: RequestInit,
+  _dispatcher?: Dispatcher,
+): Promise<Response> {
+  return fetch(url, init);
+}

package/src/http-transport.node.ts

@@ -0,0 +1,19 @@
+/** Node session clients need explicit header deadlines for long modeling calls.
+ * Some runtimes supply an undici-compatible Agent without destroy(); callers
+ * close explicitly when that lifecycle method exists. */
+import { Agent, fetch as nodeFetch, type Dispatcher } from 'undici';
+
+export function createDispatcher(timeoutMs: number): Dispatcher {
+  return new Agent({ headersTimeout: timeoutMs, bodyTimeout: timeoutMs });
+}
+
+export async function dispatchFetch(
+  url: string,
+  init?: RequestInit,
+  dispatcher?: Dispatcher,
+): Promise<Response> {
+  if (!dispatcher) return fetch(url, init);
+  return await nodeFetch(url, {
+    ...(init as object), dispatcher,
+  }) as unknown as Response;
+}

package/src/index.ts

@@ -0,0 +1,128 @@
+export type {
+  GenerationBilling,
+  GenerationJob,
+  GenerationJobStatus,
+  GenerationJobsDocument,
+} from '@volter/editor-sdk/generations';
+export type {
+  EditorEnvelopeObservation,
+  GameDebugDoor,
+  HistoryStep,
+  OpenedDocument,
+} from './client.js';
+export { EditorClient, EditorCommandError } from './client.js';
+export type {
+  ToolAssetInspectorContributionMatch,
+  ToolAssetInspectorContributionProps,
+  ToolContributionAsset,
+  ToolContributionNode,
+  ToolContributionProps,
+  ToolGenerationResultContributionProps,
+  ToolInspectorContributionMatch,
+  ToolInspectorContributionProps,
+} from './contributions.js';
+export type {
+  DocumentClickStep,
+  DocumentKeyStep,
+  DocumentPasteStep,
+  DocumentProbeResult,
+  DocumentProbeScope,
+  DocumentProbeStep,
+  DocumentQueryStep,
+  DocumentSelectStep,
+  DocumentTypeStep,
+  ProbedElement,
+} from './document-probe.js';
+export { editorViewFromUrl, editorViewUrl } from './editor-view.js';
+export type { ExtensionContributionState } from './extension.js';
+export type {
+  ActiveDocumentCapture,
+  AssetCompareCapture,
+  AssetCompareOptions,
+  AssetCompareView,
+  AssetKind,
+  AssetPreviewBackground,
+  AssetPreviewCameraChoice,
+  AssetPreviewCapture,
+  AssetPreviewOptions,
+  AssetPreviewOrientation,
+  AssetPreviewPose,
+  AssetPreviewShotSetDefinition,
+  AssetPreviewShotWarning,
+  AssetPreviewSource,
+  AssetPreviewStage,
+  AssetPreviewView,
+  CaptureDimensions,
+  DocumentCameraPose,
+  DocumentLookOutcome,
+  DocumentTableEntryProjection,
+  DocumentTableProjection,
+  EditorCameraState,
+  EditorChromeCapture,
+  EditorChromeCaptureOptions,
+  EditorEntitySummary,
+  EditorState,
+  EditorView,
+  EditorViewBuiltInUtilityId,
+  EditorViewDocument,
+  EditorViewUtility,
+  EditorWorkspaceName,
+  GameCapture,
+  GameplayRecordingCapture,
+  GameplayRecordingOptions,
+  GameplayRecordingStarted,
+  GameplayRecordingTimeline,
+  GameplayReplayCapture,
+  HelperVisibility,
+  InspectedAction,
+  InspectedField,
+  InspectedFieldWrite,
+  InspectedHierarchy,
+  InspectedHierarchyRow,
+  InspectedInspection,
+  InspectedNothing,
+  InspectedSection,
+  InspectedSectionBody,
+  InspectedSubject,
+  InspectedWriteDestination,
+  InspectionPresentationKind,
+  InspectionSurface,
+  LabeledShotSetCapture,
+  PlayRecordingStatus,
+  PlayStarted,
+  PresentedEditorView,
+  ProjectInfo,
+  ProjectTemplate,
+  ProjectToolCatalog,
+  ProjectToolCatalogEntry,
+  ProjectToolContribution,
+  ProjectToolOutcome,
+  RecentProject,
+  ShadingMode,
+  ShotSetPoseMorph,
+  ShotSetPoseRotation,
+  ShotSetPoseStep,
+  ShotSetPoseTranslation,
+  ShotSetShot,
+  StoryCaptureOptions,
+  StoryVariantCapture,
+  StoryVariantImage,
+  StructureOp,
+  StructureOpOptions,
+  StructureOpResult,
+  TransformMode,
+  TransformSpace,
+  Vec3Value,
+  ViewPreset,
+  ViewportCapture,
+  ViewportTab,
+} from './types.js';
+export {
+  EDITOR_VIEW_BUILT_IN_UTILITY_IDS,
+  EDITOR_VIEW_DOCUMENT_KINDS,
+  EDITOR_VIEW_KEYS,
+  EDITOR_VIEW_TOOL_UTILITY_PREFIX,
+  EDITOR_VIEW_WORKSPACE_DOCUMENT_IDS,
+  isEditorViewDocumentKind,
+  isEditorViewUtility,
+} from './types.js';

package/src/layout-arrangements.ts

@@ -0,0 +1,5 @@
+import type { WorkspaceArrangement } from '@volter/editor-project/adapter/workspace-arrangement';
+export type { WorkspaceArrangement, WorkspaceAreaContribution } from '@volter/editor-project/adapter/workspace-arrangement';
+
+export const GameArrangement: WorkspaceArrangement = { id: 'game', title: 'Game' };
+export const DesignArrangement: WorkspaceArrangement = { id: 'design', title: 'Design' };

package/src/layouts.tsx

@@ -0,0 +1,108 @@
+/** Programmable editor composition. Layouts are React components, not registry keys. */
+import { type ComponentType, type CSSProperties, createElement, type ReactNode } from 'react';
+import { DesignArrangement, type WorkspaceArrangement } from './layout-arrangements';
+import type { EditorView } from './types';
+
+export {
+  DesignArrangement,
+  GameArrangement,
+  type WorkspaceArrangement,
+} from './layout-arrangements';
+
+export interface EditorLayoutProps {
+  readonly playing: boolean;
+  readonly paused: boolean;
+}
+export type EditorLayout = ComponentType<EditorLayoutProps>;
+export interface LayoutFrameProps {
+  readonly children?: ReactNode;
+  readonly style?: CSSProperties;
+  /** Let the enclosing web page scroll when the pointer is over a viewport. */
+  readonly pageScroll?: boolean;
+}
+export interface WorkspaceProps {
+  readonly arrangement?: WorkspaceArrangement;
+  readonly immersivePlay?: boolean;
+  readonly playUtilities?: readonly string[];
+}
+export interface DocumentHandle {
+  /** Select exactly one named native object; ambiguous/missing names refuse. */
+  select(name: string): void;
+  transform(mode: 'combined' | 'translate' | 'rotate' | 'scale'): void;
+  frame(): void;
+}
+export interface DocumentViewProps {
+  readonly document:
+    | Extract<NonNullable<EditorView['document']>, { kind: 'story' | 'workspace' }>
+    | {
+        readonly kind: 'asset';
+        readonly path: string;
+        readonly assetKind?: 'source' | 'model' | 'image' | 'audio' | 'json';
+      };
+  readonly chrome?: boolean;
+  readonly active?: boolean;
+  readonly onReady?: (document: DocumentHandle) => void;
+}
+export interface LayoutHost {
+  readonly Frame: ComponentType<LayoutFrameProps>;
+  readonly Header: ComponentType;
+  readonly Footer: ComponentType;
+  readonly Workspace: ComponentType<WorkspaceProps>;
+  readonly Document: ComponentType<DocumentViewProps>;
+}
+const HOST_KEY = Symbol.for('vgai.editor.layout-host');
+const hosts = globalThis as typeof globalThis & { [HOST_KEY]?: LayoutHost };
+/** Installed once by the editor runtime; project modules share this SDK instance. */
+export function registerLayoutHost(value: LayoutHost): void {
+  hosts[HOST_KEY] = value;
+}
+function currentHost(): LayoutHost {
+  const host = hosts[HOST_KEY];
+  if (!host) throw new Error('Editor layouts require an editor host.');
+  return host;
+}
+export function EditorFrame(props: LayoutFrameProps) {
+  return createElement(currentHost().Frame, props);
+}
+export function EditorHeader() {
+  return createElement(currentHost().Header);
+}
+export function EditorFooter() {
+  return createElement(currentHost().Footer);
+}
+export function Workspace(props: WorkspaceProps) {
+  return createElement(currentHost().Workspace, props);
+}
+export function DocumentView(props: DocumentViewProps) {
+  return createElement(currentHost().Document, props);
+}
+
+/** Full game authoring, with the running game taking over the workspace during Play. */
+export function GameLayout() {
+  return (
+    <EditorFrame>
+      <EditorHeader />
+      <Workspace immersivePlay />
+      <EditorFooter />
+    </EditorFrame>
+  );
+}
+/** Studio keeps its authoring panels and opens analytics while the game runs. */
+export function StudioLayout() {
+  return (
+    <EditorFrame>
+      <EditorHeader />
+      <Workspace immersivePlay={false} playUtilities={['tool:analytics.analytics']} />
+      <EditorFooter />
+    </EditorFrame>
+  );
+}
+export function DesignLayout() {
+  return (
+    <EditorFrame>
+      <EditorHeader />
+      <Workspace arrangement={DesignArrangement} immersivePlay={false} />
+      <EditorFooter />
+    </EditorFrame>
+  );
+}

package/src/looks.ts

@@ -0,0 +1,14 @@
+/** Contribution data types are owned by the project adapter contract. */
+export type {
+  EditorKeyActionId,
+  KeyChord,
+  KeymapBindings,
+  KeymapContribution,
+  WorkspaceLayoutRegions,
+  WorkspaceLayoutContribution,
+  MaterialContribution,
+  DensityContribution,
+  IconCategoryTone,
+  IconSetContribution,
+  StyleContribution,
+} from '@volter/editor-project/adapter/editor-looks';

package/src/project/output-roots.ts

@@ -0,0 +1,73 @@
+/**
+ * The project directories a tool may commit generated bytes into, and the one
+ * normalizer every writer validates a path with.
+ *
+ * A project has two of them, and the difference is what SHIPS:
+ *
+ *   - `public/`     — game assets. Exported, served at a root-relative URL,
+ *                     loaded by the game's own source.
+ *   - `references/` — reference material: moodboards, style plates, generated
+ *                     stills and clips an author or an agent looks at while
+ *                     building. Ordinary files, indexed by the editor's Content
+ *                     panel like any other media, and NOT exported — the
+ *                     project's own build copies `publicDir` and nothing else.
+ *
+ * This lives in the SDK rather than beside one writer because the rule has more
+ * than one enforcer: the editor host's atomic project-output writer, and every
+ * registered provider boundary that takes an `outputDirectory` from a caller.
+ * Two copies of "must be under public/" is how a reference output becomes
+ * writable through one door and refused at the next.
+ */
+
+/** The writable output roots, in the order a chooser should offer them. */
+export const PROJECT_OUTPUT_ROOTS = ['public', 'references'] as const;
+
+export type ProjectOutputRoot = (typeof PROJECT_OUTPUT_ROOTS)[number];
+
+/** Human-readable list for an error message: `public/` or `references/`. */
+function rootList(): string {
+  return PROJECT_OUTPUT_ROOTS.map((root) => `${root}/`).join(' or ');
+}
+
+/** POSIX-normalized, `./`-stripped, trailing-slash-stripped. */
+function normalizeSlashes(path: string): string {
+  const slashed = path.replaceAll('\\', '/');
+  const segments: string[] = [];
+  for (const segment of slashed.split('/')) {
+    if (segment === '' || segment === '.') continue;
+    segments.push(segment);
+  }
+  return segments.join('/');
+}
+
+/** The root `path` sits under, or `undefined` when it sits under none. */
+export function projectOutputRootOf(path: string): ProjectOutputRoot | undefined {
+  const normalized = normalizeSlashes(path);
+  return PROJECT_OUTPUT_ROOTS.find(
+    (root) => normalized === root || normalized.startsWith(`${root}/`),
+  );
+}
+
+/**
+ * Validate and normalize a project-relative output path.
+ *
+ * Throws — with a message naming BOTH roots, because the common mistake is
+ * knowing about one of them — for an absolute path, an escape, a bare root
+ * with no file under it, or anything outside the roots above. `subject` names
+ * what is being validated in that message (`Generated output path`, `Fal
+ * outputDirectory`, …).
+ */
+export function normalizeProjectOutputPath(
+  path: string,
+  subject = 'Generated output path',
+): string {
+  const normalized = normalizeSlashes(path);
+  const escapes = normalized.split('/').includes('..');
+  const root = projectOutputRootOf(normalized);
+  if (path.startsWith('/') || escapes || root === undefined || normalized === root) {
+    throw new Error(
+      `${subject} ${JSON.stringify(path)} is invalid; it must be a project-relative path under ${rootList()}.`,
+    );
+  }
+  return normalized;
+}

package/src/project/tab-census.ts

@@ -0,0 +1,149 @@
+/**
+ * THE TAB RESOURCE CENSUS — one declaration of the profile a browser tab
+ * reports about itself, for every compilation unit that speaks it.
+ *
+ * WHAT IT IS. What a game tab is holding: JS heap, canvas backing stores,
+ * renderer resource counts, and how many project mount generations the
+ * document has accumulated. Sampled by the page every five seconds and carried
+ * on the heartbeat, so that a browser-level renderer death — which the presence
+ * system recovers from perfectly and would otherwise leave unexplained — has a
+ * number beside it. MEASUREMENT ONLY: nothing anywhere enforces a budget from
+ * these. The page-side sampler and its `why` are
+ * `packages/editor/src/tab-census.ts`.
+ *
+ * WHY IT LIVES HERE. This one shape crosses four compilation units — the page
+ * that samples it (`@vgai/editor`'s browser bundle), the editor server that
+ * files it (`@vgai/editor`'s node half), the editor-extension surface that
+ * describes the status response (`@volter/editor-sdk`), and the session journal
+ * plus the CLI row that print it (`@vgai/sdk`, `@vgai/cli`). Each of them used
+ * to spell the seven fields out again. `@vgai/sdk` is the only package all four
+ * already depend on: `@volter/editor-sdk` depends on `@vgai/sdk` and `@vgai/editor`
+ * depends on both, so this cannot live in `@volter/editor-sdk` without a cycle —
+ * and it does not belong in `@vgai/game-runtime`, whose subject is a running game,
+ * not an editor session's tabs.
+ *
+ * Deliberately import-free so a browser bundle can take it: the census's other
+ * `@vgai/sdk` home, `project/session-journal.ts`, reads `node:fs`.
+ *
+ * WHAT ELSE RIDES IT. The beat is the one channel that still moves when the
+ * page's main thread or the Blender worker is blocked, so `blender` — how long
+ * the worker's calls are taking and how long the main thread has been stalled —
+ * is carried here too (absent unless a Blender session exists in the tab). Same
+ * rule as the rest of this file: measurement only, no budget anywhere.
+ *
+ * ABSENT IS NOT ZERO. `heapUsedMB`/`heapLimitMB` are null off Chromium
+ * (`performance.memory` is non-standard). The renderer counts are ABSENT rather
+ * than zero when no game has registered a render-debug adapter, and `programs`
+ * is absent until a first render: a zero would read as "no textures", which is
+ * a different claim from "nobody measured".
+ */
+
+/**
+ * THE BLENDER WORKER'S STALLS, as numbers.
+ *
+ * WHY (measured 2026-09-16): one `blender-execute` held the Blender worker for
+ * over 1,800s and wedged the tab, and a 0.86s-per-call scene stretched into
+ * heartbeat timeouts that read as "tab present, did not respond". The product
+ * had no number for either. Owner ruling: a tab that stops answering is the
+ * product's defect regardless of what the machine is doing, and the product has
+ * to surface it — so these ride the census to `vgai status`.
+ *
+ * MEASURED BY THE PAGE, because neither blocked party can report on itself: the
+ * worker's own loop is what is stuck, and a stalled main thread cannot send.
+ * The call half comes from `BlenderRuntime.metrics()`
+ * (`packages/blender-engine/browser/runtime.ts`), the stall half from a `longtask`
+ * PerformanceObserver (`packages/editor/src/blender-tab-metrics.ts`).
+ *
+ * MEASUREMENT ONLY. No threshold here cancels, kills or budgets a call.
+ */
+export interface BlenderTabMetrics {
+  /** Age of the oldest OUTSTANDING worker call, or null when the worker is idle.
+   *  The only field with a number during a wedge. */
+  readonly inFlightMs: number | null;
+  /** Duration of the newest completed call; null before the first one. */
+  readonly lastCallMs: number | null;
+  /** The longest call this page has seen, counting an outstanding one. */
+  readonly maxCallMs: number | null;
+  /** Calls past 5s, and past 30s, since this page loaded. */
+  readonly callsOver5s: number;
+  readonly callsOver30s: number;
+  /** Longest `longtask` entry since page load, in ms; null off Chromium (the
+   *  Long Tasks API is not implemented everywhere) — never 0, which would read
+   *  as "the main thread never stalled". */
+  readonly longestTaskMs: number | null;
+  /** How many long tasks ran past 100ms since page load. */
+  readonly tasksOver100ms: number;
+  /** The longest long task that overlapped the newest call's window — what the
+   *  MAIN thread was doing while the worker was busy. Null when there has been
+   *  no call yet, or no long task during it. */
+  readonly lastCallLongestTaskMs: number | null;
+  /**
+   * THE ENGINE'S OWN MEMORY: the Blender module's linear memory in MB, read in
+   * the worker (`packages/blender-engine/browser/worker.ts`) and posted after every
+   * call. Null before the session's first call, and absent against a page that
+   * predates the field.
+   *
+   * It is here because no other number on this census answers the question.
+   * `heapUsedMB` is the PAGE's JS heap — a few tens of MB — while the engine's
+   * memory is the larger half of the tab by far, and a reader looking at the
+   * heap line alone concludes the tab is cheap. wasm32 memory never shrinks, so
+   * this is simultaneously the current size and the session's high-water mark.
+   *
+   * MEASURED 2026-09-18 on this bundle: 512 MB reserved at boot of which ~166
+   * MB is ever touched, reaching 1036 MB across `17-workshop-interior`. The
+   * reservation costs no resident pages; the growth does, permanently.
+   */
+  readonly wasmMemoryMB?: number | null;
+}
+
+/**
+ * A census as a CURRENT page produces it and the server files it.
+ *
+ * Every field here is guaranteed by a producer that always writes it, and
+ * `packages/editor/server/tab-heartbeat.ts`'s `parseCensus` is where that is
+ * checked: a beat frame missing `canvases`, `canvasMB` or `mountEpochs` is
+ * rejected outright rather than filed as a partial profile.
+ */
+export interface TabCensus {
+  /** `performance.memory.usedJSHeapSize` in MB; null off Chromium. */
+  readonly heapUsedMB: number | null;
+  /** `performance.memory.jsHeapSizeLimit` in MB; null off Chromium. */
+  readonly heapLimitMB: number | null;
+  /** Distinct project mount generations fetched by this document. */
+  readonly mountEpochs: number;
+  /** How many `<canvas>` elements the document holds. */
+  readonly canvases: number;
+  /** Their total pixel-buffer footprint: Σ width×height×4 bytes, in MB. */
+  readonly canvasMB: number;
+  /** `renderer.info.memory.textures` — absent with no mounted adapter. */
+  readonly textures?: number;
+  /** `renderer.info.memory.geometries` — absent with no mounted adapter. */
+  readonly geometries?: number;
+  /** Compiled programs — absent with no adapter, or before the first render. */
+  readonly programs?: number;
+  /** {@link BlenderTabMetrics} — absent unless this tab has a Blender session. */
+  readonly blender?: BlenderTabMetrics;
+}
+
+/**
+ * A census read back out of a RECORD, where the writer may predate a field.
+ *
+ * Exactly one field varies, and this is the only place that is said: a session
+ * journal line written before the mount census existed has no `mountEpochs`,
+ * and neither does a status response from an older editor server. The
+ * difference is a property of the READER's input, so it is named on the
+ * reader's type rather than by softening {@link TabCensus} — which is what the
+ * four hand-copied declarations did, and how the producers' own guarantee got
+ * lost on the way to the two SDKs.
+ *
+ * There is no runtime narrowing to point at because neither reader has a parse
+ * step to put one in: the journal is `JSON.parse` per line by recorded design
+ * (`session-journal.ts`: "nothing reads a journal back through a validator"),
+ * and the CLI reads the status body as JSON. So the absence is carried in the
+ * type and handled where it is printed — `formatTabCensus` omits the words
+ * rather than printing a fabricated count. Every {@link TabCensus} is a valid
+ * value of this type; the reverse is not.
+ */
+export type RecordedTabCensus = Omit<TabCensus, 'mountEpochs'> & {
+  readonly mountEpochs?: number;
+};

package/src/project-tool-catalog.ts

@@ -0,0 +1,96 @@
+export type ToolContributionPoint =
+  | 'workspace.document'
+  | 'selection.inspector'
+  | 'asset.inspector'
+  | 'generation.result'
+  | 'workspace.utility'
+  | 'workspace.analytics'
+  | 'workspace.status';
+
+/**
+ * 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`, `*.analytics.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 {
+  /** Project-relative or package-absolute browser module path. */
+  entryPath: string;
+  /** The dependency that declared it (`package.json#vgai.contributions`),
+   *  absent for the project's own `src/contributions/` modules. */
+  package?: string;
+}
+
+export interface ProjectToolErrorSummary {
+  code: string;
+  summary: string;
+  dataSchema?: unknown;
+}
+
+export interface ProjectToolCatalogEntry {
+  name: string;
+  summary: string;
+  description: string;
+  sourcePath: string;
+  inputSchema: unknown;
+  resultSchema: unknown;
+  errors: ProjectToolErrorSummary[];
+  requires: Record<string, boolean | undefined>;
+  host: 'node' | 'editor-browser' | 'runtime-page';
+  mutates: boolean;
+  supportsDryRun: boolean;
+  longRunning: boolean;
+  permission: { risk: 'read' | 'write' | 'destructive'; summary: string };
+  generation?: { provider: string; role: 'submit' | 'poll' | 'cancel' | 'accept' };
+}
+
+export interface ProjectToolLoadError {
+  sourcePath: string;
+  message: string;
+}
+
+/**
+ * What a host says when it cannot load the project's TypeScript at all.
+ *
+ * ONE owner for the sentence, because two realms reach this state through
+ * different doors and both must say the same true thing rather than fall back
+ * to a fabricated empty catalog:
+ *
+ *  - the NODE side (`packages/editor/server/project-tools.ts`) when a host
+ *    builds the catalog with no `loadModule`; and
+ *  - the PAGE side (`packages/editor/src/project-tools.ts`), whose fetch of
+ *    `/__editor/project-tools` can be answered by an SPA FALLBACK — `200` and
+ *    HTML — when no editor server is in front of the origin, so an unguarded
+ *    fetch that merely checks `response.ok` reads a successful page load as a
+ *    successful catalog, then dies in
+ *    `res.json()`. The panel's empty state ("No project tools registered")
+ *    is a FACT about the project; a host that cannot ask has not learned it.
+ */
+export const NO_PROJECT_MODULE_HOST_MESSAGE =
+  'This editor host cannot RUN registered project tools (package.json#vgai.tools): callables ' +
+  'execute on the Node side. Contribution panels still load from project source; to run the ' +
+  'tools themselves, open the project in the Vite-backed dev or packaged editor.';
+
+/** The catalog row that states {@link NO_PROJECT_MODULE_HOST_MESSAGE}. */
+export function noProjectModuleHostError(): ProjectToolLoadError {
+  return { sourcePath: 'package.json#vgai.tools', message: NO_PROJECT_MODULE_HOST_MESSAGE };
+}
+
+/**
+ * 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[];
+}