@vgai/editor 0.4.0 → 0.4.1

package/server/project-tools.ts

@@ -0,0 +1,529 @@
+/**
+ * Registered project-tool discovery and execution.
+ *
+ * Project modules stay ordinary TS/JS. This server-side boundary is the only
+ * loader: it reads explicit `package.json#vgai.tools` registrations, asks the
+ * owning Vite server to load each callable module in Node, validates the
+ * exported ToolDefinition, and dispatches through the existing internal SDK
+ * registry. Optional React contributions are separate browser modules and are
+ * never imported merely because a callable tool was listed or executed.
+ */
+
+import { readFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { dirname, resolve, sep } from 'node:path';
+import { z } from 'zod';
+import type { OperationDefinition, OperationOutcome } from '../../vgai-sdk/src/registry';
+import { OperationRegistry } from '../../vgai-sdk/src/registry';
+import { runWithGenerativeExecutionCapture } from './generative-execution-context';
+import { createProjectOutputWriter } from './project-output-writer';
+
+export type ProjectModuleLoader = (absoluteModuleId: string) => Promise<unknown>;
+
+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 };
+  contributions: ProjectToolContribution[];
+}
+
+export type ToolContributionPoint =
+  | 'workspace.document'
+  | 'selection.inspector'
+  | 'workspace.utility';
+
+export interface ProjectToolContribution {
+  id: string;
+  point: ToolContributionPoint;
+  title: string;
+  entryPath: string;
+}
+
+export interface ProjectToolLoadError {
+  sourcePath: string;
+  message: string;
+}
+
+export interface ProjectToolCatalog {
+  tools: ProjectToolCatalogEntry[];
+  loadErrors: ProjectToolLoadError[];
+}
+
+interface LoadedCatalog extends ProjectToolCatalog {
+  definitions: Map<string, OperationDefinition>;
+}
+
+interface ToolModule {
+  absolutePath: string;
+  sourcePath: string;
+  contributions: ProjectToolContribution[];
+  registrationError?: string;
+}
+
+interface ToolContributionRegistration {
+  id: string;
+  point: ToolContributionPoint;
+  title: string;
+  entry: string;
+}
+
+type ToolRegistration =
+  | string
+  | {
+      entry: string;
+      contributions?: ToolContributionRegistration[];
+    };
+
+interface PackageJsonShape {
+  name?: string;
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+  vgai?: { tools?: ToolRegistration[] };
+}
+
+async function readPackageJson(path: string): Promise<PackageJsonShape | null> {
+  try {
+    return JSON.parse(await readFile(path, 'utf8')) as PackageJsonShape;
+  } catch {
+    return null;
+  }
+}
+
+function resolveDependencyPackageJson(
+  requireFromProject: ReturnType<typeof createRequire>,
+  dependencyName: string,
+): string | null {
+  try {
+    return requireFromProject.resolve(`${dependencyName}/package.json`);
+  } catch {
+    return null;
+  }
+}
+
+function registrationEntry(registration: ToolRegistration): string | null {
+  return typeof registration === 'string' ? registration : registration?.entry;
+}
+
+function registrationContributions(
+  registration: ToolRegistration,
+): ToolContributionRegistration[] | undefined {
+  return typeof registration === 'object' && registration !== null
+    ? registration.contributions
+    : undefined;
+}
+
+function validRelativeModule(spec: unknown): spec is string {
+  return typeof spec === 'string' && spec.startsWith('./') && !spec.includes('..');
+}
+
+function validContributionPoint(value: unknown): value is ToolContributionPoint {
+  return (
+    value === 'workspace.document' ||
+    value === 'selection.inspector' ||
+    value === 'workspace.utility'
+  );
+}
+
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: one explicit manifest validator keeps every contribution field and teaching error at the package boundary.
+function resolveContributions(
+  registrations: unknown,
+  root: string,
+  dependency: boolean,
+): { contributions: ProjectToolContribution[]; error?: string } {
+  if (registrations === undefined) return { contributions: [] };
+  if (!Array.isArray(registrations)) {
+    return { contributions: [], error: '`contributions` must be an array' };
+  }
+  const contributions: ProjectToolContribution[] = [];
+  const ids = new Set<string>();
+  for (const [index, value] of registrations.entries()) {
+    if (!value || typeof value !== 'object') {
+      return { contributions: [], error: `contributions[${index}] must be an object` };
+    }
+    const candidate = value as Partial<ToolContributionRegistration>;
+    if (typeof candidate.id !== 'string' || !/^[a-z][a-z0-9-]*$/.test(candidate.id)) {
+      return {
+        contributions: [],
+        error: `contributions[${index}].id must be a lowercase kebab-case id`,
+      };
+    }
+    if (ids.has(candidate.id)) {
+      return {
+        contributions: [],
+        error: `duplicate contribution id ${JSON.stringify(candidate.id)}`,
+      };
+    }
+    if (!validContributionPoint(candidate.point)) {
+      return {
+        contributions: [],
+        error:
+          `contributions[${index}].point must be ` +
+          `'workspace.document', 'selection.inspector', or 'workspace.utility'`,
+      };
+    }
+    if (typeof candidate.title !== 'string' || candidate.title.trim() === '') {
+      return { contributions: [], error: `contributions[${index}].title must be non-empty` };
+    }
+    if (!validRelativeModule(candidate.entry)) {
+      return {
+        contributions: [],
+        error: `contributions[${index}].entry must be a ./-relative module without parent traversal`,
+      };
+    }
+    const absoluteEntry = resolve(root, candidate.entry);
+    if (!absoluteEntry.startsWith(`${root}${sep}`)) {
+      return {
+        contributions: [],
+        error: `contributions[${index}].entry resolves outside its package`,
+      };
+    }
+    ids.add(candidate.id);
+    contributions.push({
+      id: candidate.id,
+      point: candidate.point,
+      title: candidate.title.trim(),
+      entryPath: dependency ? absoluteEntry : candidate.entry.slice(2),
+    });
+  }
+  return { contributions };
+}
+
+async function advertisedDependencyTools(
+  requireFromProject: ReturnType<typeof createRequire>,
+  dependencyName: string,
+): Promise<ToolModule[]> {
+  const packageJsonPath = resolveDependencyPackageJson(requireFromProject, dependencyName);
+  if (!packageJsonPath) return [];
+  const dependencyPackage = await readPackageJson(packageJsonPath);
+  const registrations = dependencyPackage?.vgai?.tools;
+  if (!Array.isArray(registrations)) return [];
+  const packageRoot = dirname(packageJsonPath);
+  return registrations.map((registration, index): ToolModule => {
+    const entry = registrationEntry(registration);
+    const registrationPath = `${dependencyName}:package.json#vgai.tools[${index}]`;
+    if (!validRelativeModule(entry)) {
+      return {
+        absolutePath: packageJsonPath,
+        sourcePath: registrationPath,
+        contributions: [],
+        registrationError: 'must be a ./-relative tool module without parent traversal',
+      };
+    }
+    const absolutePath = resolve(packageRoot, entry);
+    if (!absolutePath.startsWith(`${packageRoot}${sep}`)) {
+      return {
+        absolutePath,
+        sourcePath: registrationPath,
+        contributions: [],
+        registrationError: 'resolves outside the dependency package',
+      };
+    }
+    const resolved = resolveContributions(
+      registrationContributions(registration),
+      packageRoot,
+      true,
+    );
+    if (resolved.error) {
+      return {
+        absolutePath,
+        sourcePath: registrationPath,
+        contributions: [],
+        registrationError: resolved.error,
+      };
+    }
+    return {
+      absolutePath,
+      sourcePath: `${dependencyName}:${entry.slice(2)}`,
+      contributions: resolved.contributions,
+    };
+  });
+}
+
+async function dependencyToolModules(projectRoot: string): Promise<ToolModule[]> {
+  const projectPackage = await readPackageJson(resolve(projectRoot, 'package.json'));
+  if (!projectPackage) return [];
+  const dependencyNames = [
+    ...Object.keys(projectPackage.dependencies ?? {}),
+    ...Object.keys(projectPackage.devDependencies ?? {}),
+  ].sort();
+  const requireFromProject = createRequire(resolve(projectRoot, 'package.json'));
+  return (
+    await Promise.all(
+      dependencyNames.map((name) => advertisedDependencyTools(requireFromProject, name)),
+    )
+  ).flat();
+}
+
+async function projectToolModules(projectRoot: string): Promise<ToolModule[]> {
+  const projectPackage = await readPackageJson(resolve(projectRoot, 'package.json'));
+  const registrations = projectPackage?.vgai?.tools;
+  if (!Array.isArray(registrations)) return [];
+  return registrations.map((registration, index): ToolModule => {
+    const entry = registrationEntry(registration);
+    const registrationPath = `package.json#vgai.tools[${index}]`;
+    if (!validRelativeModule(entry)) {
+      return {
+        absolutePath: resolve(projectRoot, 'package.json'),
+        sourcePath: registrationPath,
+        contributions: [],
+        registrationError: 'must be a ./-relative tool module without parent traversal',
+      };
+    }
+    const absolutePath = resolve(projectRoot, entry);
+    if (!absolutePath.startsWith(`${projectRoot}${sep}`)) {
+      return {
+        absolutePath,
+        sourcePath: registrationPath,
+        contributions: [],
+        registrationError: 'resolves outside the project',
+      };
+    }
+    const resolved = resolveContributions(
+      registrationContributions(registration),
+      projectRoot,
+      false,
+    );
+    if (resolved.error) {
+      return {
+        absolutePath,
+        sourcePath: registrationPath,
+        contributions: [],
+        registrationError: resolved.error,
+      };
+    }
+    return {
+      absolutePath,
+      sourcePath: entry.slice(2),
+      contributions: resolved.contributions,
+    };
+  });
+}
+
+function operationShape(value: unknown): value is OperationDefinition {
+  if (value === null || typeof value !== 'object') return false;
+  const candidate = value as Partial<OperationDefinition>;
+  return (
+    typeof candidate.name === 'string' &&
+    typeof candidate.summary === 'string' &&
+    typeof candidate.description === 'string' &&
+    candidate.input !== null &&
+    typeof candidate.input === 'object' &&
+    typeof candidate.input.safeParse === 'function' &&
+    candidate.result !== null &&
+    typeof candidate.result === 'object' &&
+    typeof candidate.result.safeParse === 'function' &&
+    Array.isArray(candidate.errors) &&
+    candidate.requires !== null &&
+    typeof candidate.requires === 'object' &&
+    (candidate.host === 'node' ||
+      candidate.host === 'editor-browser' ||
+      candidate.host === 'runtime-page') &&
+    typeof candidate.mutates === 'boolean' &&
+    typeof candidate.supportsDryRun === 'boolean' &&
+    candidate.permission !== null &&
+    typeof candidate.permission === 'object' &&
+    typeof candidate.impl === 'function'
+  );
+}
+
+function jsonSchema(schema: z.ZodType): unknown {
+  return z.toJSONSchema(schema);
+}
+
+function toCatalogEntry(
+  definition: OperationDefinition,
+  sourcePath: string,
+  contributions: ProjectToolContribution[],
+): ProjectToolCatalogEntry {
+  return {
+    name: definition.name,
+    summary: definition.summary,
+    description: definition.description,
+    sourcePath,
+    inputSchema: jsonSchema(definition.input),
+    resultSchema: jsonSchema(definition.result),
+    errors: definition.errors.map((error) => ({
+      code: error.code,
+      summary: error.summary,
+      ...(error.data ? { dataSchema: jsonSchema(error.data) } : {}),
+    })),
+    requires: { ...definition.requires },
+    host: definition.host,
+    mutates: definition.mutates,
+    supportsDryRun: definition.supportsDryRun,
+    longRunning: definition.longRunning === true,
+    permission: { ...definition.permission },
+    contributions,
+  };
+}
+
+async function loadCatalog(
+  projectRoot: string,
+  loadModule: ProjectModuleLoader | undefined,
+): Promise<LoadedCatalog> {
+  const definitions = new Map<string, OperationDefinition>();
+  const tools: ProjectToolCatalogEntry[] = [];
+  const loadErrors: ProjectToolLoadError[] = [];
+  const files = [
+    ...(await projectToolModules(projectRoot)),
+    ...(await dependencyToolModules(projectRoot)),
+  ].sort((a, b) => a.sourcePath.localeCompare(b.sourcePath));
+
+  const loadableFiles = files.filter((file) => {
+    if (!file.registrationError) return true;
+    loadErrors.push({ sourcePath: file.sourcePath, message: file.registrationError });
+    return false;
+  });
+
+  if (loadableFiles.length > 0 && !loadModule) {
+    loadErrors.push({
+      sourcePath: 'package.json#vgai.tools',
+      message:
+        'This editor host cannot load project TypeScript modules. Use the Vite-backed dev or packaged editor.',
+    });
+    return { tools, loadErrors, definitions };
+  }
+
+  const registry = new OperationRegistry();
+  for (const { absolutePath, sourcePath, contributions } of loadableFiles) {
+    try {
+      const imported = (await loadModule?.(absolutePath)) as Record<string, unknown> | undefined;
+      const definition = imported?.['tool'];
+      if (!operationShape(definition)) {
+        throw new Error(
+          'does not export a complete `tool` definition; export `tool = defineTool({...})` from @vgai/sdk/tools',
+        );
+      }
+      if (!definition.name.startsWith('project.')) {
+        throw new Error(
+          `declares ${JSON.stringify(definition.name)}; project-local tool names must start with "project."`,
+        );
+      }
+      if (definition.mutates && definition.permission.risk === 'read') {
+        throw new Error(
+          `declares mutates:true with read risk; mutating operations must declare write or destructive risk`,
+        );
+      }
+      registry.register(definition);
+      const entry = toCatalogEntry(definition, sourcePath, contributions);
+      definitions.set(definition.name, definition);
+      tools.push(entry);
+    } catch (error) {
+      loadErrors.push({
+        sourcePath,
+        message: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  tools.sort((a, b) => a.name.localeCompare(b.name));
+  return { tools, loadErrors, definitions };
+}
+
+export async function discoverProjectTools(
+  projectRoot: string,
+  loadModule: ProjectModuleLoader | undefined,
+): Promise<ProjectToolCatalog> {
+  const { definitions: _definitions, ...catalog } = await loadCatalog(projectRoot, loadModule);
+  return catalog;
+}
+
+export type ProjectToolExecution =
+  | { status: 200; body: OperationOutcome; changedProject: boolean }
+  | {
+      status: 404 | 409;
+      body: { ok: false; error: { code: string; message: string } };
+      changedProject: false;
+    };
+
+export async function executeProjectTool(options: {
+  projectRoot: string;
+  loadModule: ProjectModuleLoader | undefined;
+  name: string;
+  input: unknown;
+  confirmed: boolean;
+  signal?: AbortSignal;
+}): Promise<ProjectToolExecution> {
+  const loaded = await loadCatalog(options.projectRoot, options.loadModule);
+  const definition = loaded.definitions.get(options.name);
+  if (!definition) {
+    return {
+      status: 404,
+      changedProject: false,
+      body: {
+        ok: false,
+        error: {
+          code: 'PROJECT_TOOL_NOT_FOUND',
+          message: `No registered project tool is named ${JSON.stringify(options.name)}.`,
+        },
+      },
+    };
+  }
+  if (definition.host !== 'node') {
+    return {
+      status: 409,
+      changedProject: false,
+      body: {
+        ok: false,
+        error: {
+          code: 'PROJECT_TOOL_HOST_UNAVAILABLE',
+          message:
+            `Project tool ${JSON.stringify(options.name)} declares host ${JSON.stringify(definition.host)}. ` +
+            'This host currently executes Node-hosted project tools; call reusable browser/runtime functions directly.',
+        },
+      },
+    };
+  }
+  if ((definition.mutates || definition.permission.risk !== 'read') && !options.confirmed) {
+    return {
+      status: 409,
+      changedProject: false,
+      body: {
+        ok: false,
+        error: {
+          code: 'PROJECT_TOOL_CONFIRMATION_REQUIRED',
+          message:
+            `${definition.permission.risk} tool ${JSON.stringify(options.name)} requires explicit confirmation: ` +
+            definition.permission.summary,
+        },
+      },
+    };
+  }
+
+  const registry = new OperationRegistry();
+  registry.register(definition);
+  const provenanceInput = definition.input.safeParse(options.input);
+  const operationSource = loaded.tools.find((entry) => entry.name === options.name)?.sourcePath;
+  const outcome = await runWithGenerativeExecutionCapture(() =>
+    registry.dispatch(options.name, options.input, {
+      projectRoot: options.projectRoot,
+      projectOutputs: createProjectOutputWriter(options.projectRoot, {
+        operationName: definition.name,
+        ...(operationSource ? { operationSource } : {}),
+        ...(provenanceInput.success ? { input: provenanceInput.data } : {}),
+      }),
+      ...(options.signal ? { signal: options.signal } : {}),
+    }),
+  );
+  return {
+    status: 200,
+    body: outcome,
+    changedProject: definition.mutates && outcome.ok,
+  };
+}

package/server/server-utils.ts

@@ -336,7 +336,7 @@ export function validateManifestWrite(
  * Which editor list a `src/**` add/unlink invalidates, or `null` if it's
  * irrelevant. Feeds the editor-server's second `src/`-scoped chokidar
  * watcher (`startWatcher()` in editor-server.ts) so a NEW
- * `src/tools/*.tool.tsx`, project operations, or data/schema files show up
+ * registered tool modules or data/schema files show up
  * in the dock/DATA tab without a full editor reload (spec §7 W4 field note
  * c). `.schema.json` is included on the `data` side: its add/unlink flips the
  * DATA tab between the no-emitted-schema teaching message and real widgets.
@@ -344,18 +344,21 @@ export function validateManifestWrite(
  * `*.stories.tsx`/`*.stories.ts` anywhere under `src/` — the Stories tab.
  *
  * `relPath` is project-root-relative with forward slashes (same convention
- * `/__editor/data-files` and `/__editor/tool-files` already use).
+ * `/__editor/data-files` already uses).
  */
-export function classifyProjectSrcPath(
-  relPath: string,
-): 'tools' | 'data' | 'stories' | 'operations' | null {
-  if (relPath.startsWith('src/tools/') && relPath.endsWith('.tool.tsx')) return 'tools';
+export function classifyProjectSrcPath(relPath: string): 'tools' | 'data' | 'stories' | null {
   if (
-    relPath.startsWith('src/operations/') &&
-    (relPath.endsWith('.operation.ts') || relPath.endsWith('.operation.js'))
-  ) {
-    return 'operations';
-  }
+    relPath.startsWith('src/tools/') &&
+    (relPath.endsWith('.tool.ts') ||
+      relPath.endsWith('.tool.js') ||
+      relPath.endsWith('.document.tsx') ||
+      relPath.endsWith('.document.jsx') ||
+      relPath.endsWith('.inspector.tsx') ||
+      relPath.endsWith('.inspector.jsx') ||
+      relPath.endsWith('.utility.tsx') ||
+      relPath.endsWith('.utility.jsx'))
+  )
+    return 'tools';
   if (
     relPath.startsWith('src/data/') &&
     (relPath.endsWith('.data.json') || relPath.endsWith('.schema.json'))

package/src/EditorContext.tsx

@@ -18,9 +18,9 @@ import { createHmrStableReactContext } from './hmr-stable-react-context';
 import { initProject } from './initial-scene';
 import { type InteractiveEditScope, InteractiveEditScopeContext } from './interactive-edit-scope';
 import { getCurrentProject } from './project-manager';
-import { startProjectOperationDiscovery } from './project-operations';
 import { startProjectStoryDiscovery } from './project-story-discovery';
-import { startProjectToolDiscovery } from './project-tool-discovery';
+import { startProjectToolContributionDiscovery } from './project-tool-discovery';
+import { startProjectToolCatalog } from './project-tools';
 
 export interface EditorStats {
   fps: number;
@@ -92,9 +92,9 @@ export function EditorProvider({ children }: { children: ReactNode }) {
   // keeps re-running on project change / tool-file add/unlink) whether or
   // not the Dockview workspace is mounted. WorkspaceDock only consumes the
   // discovered registrations.
-  useEffect(() => startProjectToolDiscovery(), []);
+  useEffect(() => startProjectToolContributionDiscovery(), []);
 
-  useEffect(() => startProjectOperationDiscovery(), []);
+  useEffect(() => startProjectToolCatalog(), []);
 
   // CSF stories may exist without a currently mounted React root. Discover
   // them at editor init so hierarchy/Inspector story affordances and restored

package/src/action-registry.ts

@@ -203,6 +203,18 @@ export function buildStaticActions(
       category: 'action',
       execute: () => store.setShadingMode('unlit'),
     },
+    {
+      id: 'shading.normals',
+      label: 'Normal Shading',
+      category: 'action',
+      execute: () => store.setShadingMode('normals'),
+    },
+    {
+      id: 'shading.overdraw',
+      label: 'Overdraw Shading',
+      category: 'action',
+      execute: () => store.setShadingMode('overdraw'),
+    },
     {
       id: 'view.top',
       label: 'Top View',

package/src/asset-editor-context.tsx

@@ -10,6 +10,7 @@ import type { ReactNode } from 'react';
 import { useSyncExternalStore } from 'react';
 import { themeVars } from './design-system';
 import { createHmrRegistrationGroup } from './hmr-registration-group';
+import { closeWorkspaceUtility } from './workspace-dock-controller';
 import { registerWorkspaceStatus } from './workspace-status-registry';
 import { registerWorkspaceUtility } from './workspace-utility-registry';
 
@@ -62,6 +63,14 @@ export function activateAssetEditorContext(value: AssetEditorContextValue): () =
     if (active?.token !== token) return;
     active = null;
     notifyChanged();
+    // React cleans the outgoing document effect before activating the next
+    // document's effect. Defer one microtask so model → model keeps the same
+    // Controls tab, while model → scene/image closes the now-ownerless tab.
+    queueMicrotask(() => {
+      if (getActiveAssetEditorContext()?.controls == null) {
+        closeWorkspaceUtility(ASSET_EDITOR_CONTROLS_UTILITY_ID);
+      }
+    });
   };
 }
 

package/src/asset-events.ts

@@ -110,11 +110,9 @@ export function connectSceneEvents(onSceneChanged: (event: SceneChangedEvent) =>
  * Connect to the editor server's SSE endpoint for project TOOL file
  * add/unlink events (W6a, docs/DATA-TOOLS-DESIGN.md §7 W4 field note c). The
  * server's `src/`-scoped watcher (`editor-server.ts`'s `startWatcher()`)
- * broadcasts `tool-files-changed` whenever a `src/tools/*.tool.tsx` is added
- * or removed; the event carries no payload of substance beyond the touched
- * path — callers just re-run their own full rescan (`refreshProjectTools` is
- * cheap by design, same physics as the D3 "discovery IS the folder scan"
- * rule the DATA tab already follows).
+ * broadcasts `tool-files-changed` whenever a registered tool or contribution
+ * source is added, changed, or removed. The event carries no payload of
+ * substance beyond the touched path; callers refresh package registrations.
  */
 export function connectToolFileEvents(onChanged: () => void): () => void {
   // Browser mode: no Node dev server / SSE — a project-src file add/remove
@@ -125,16 +123,6 @@ export function connectToolFileEvents(onChanged: () => void): () => void {
   return () => source.close();
 }
 
-/** Project-operation add/change/unlink events. Operation definitions are
- * Node-loaded, so all three changes trigger a fresh catalog read rather than
- * relying on the browser-only project-tool HMR path. */
-export function connectOperationFileEvents(onChanged: () => void): () => void {
-  if (getEditorMode() === 'browser') return () => {};
-  const source = connectEvents();
-  source.addEventListener('operation-files-changed', () => onChanged());
-  return () => source.close();
-}
-
 /**
  * Connect to the editor server's SSE endpoint for project DATA file
  * add/unlink events (W6a). Mirrors `connectToolFileEvents` for

package/src/asset-selection.ts

@@ -36,6 +36,9 @@ export interface SelectedAsset {
   readonly health?: 'healthy' | 'source-only' | 'unsupported' | 'stale-import';
   readonly sourcePath?: string;
   readonly selectionCount?: number;
+  readonly selectionTotalBytes?: number;
+  readonly selectionFormats?: readonly string[];
+  readonly selectionReimportableCount?: number;
   readonly dependencies?: readonly string[];
   readonly references?: readonly { ownerPath: string; jsonPath: string }[];
   readonly healthCodes?: readonly string[];