@vgai/editor 0.4.0 → 0.4.1

package/server/catalog-import-recipe.ts

@@ -0,0 +1,97 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
+import {
+  type AssetImportPlan,
+  assetImportPlanSchema,
+  importRecipePath,
+} from '../src/asset-workflow/import-contract';
+
+export interface CatalogRecipeSource {
+  stagedPath: string;
+  path: string;
+  url: string;
+  role: 'primary' | 'dependency' | 'material' | 'texture';
+}
+
+export async function writeCatalogImportRecipe(input: {
+  stagingDirectory: string;
+  source: string;
+  familyId: string;
+  variantId: string;
+  deliveryId: string;
+  displayName: string;
+  destination: string;
+  recipeRelativePath?: string;
+  sources: readonly CatalogRecipeSource[];
+  generatedFiles?: readonly string[];
+  contentKind?: AssetImportPlan['contentKind'];
+  targetSkeleton?: string;
+  runtimeReady: boolean;
+  backend: AssetImportPlan['backend'];
+  attribution: AssetImportPlan['attribution'];
+  settings?: Partial<AssetImportPlan['settings']>;
+}): Promise<AssetImportPlan> {
+  const sourceFiles = await Promise.all(
+    input.sources.map(async (file) => {
+      const [bytes, info] = await Promise.all([readFile(file.stagedPath), stat(file.stagedPath)]);
+      return {
+        path: file.path,
+        url: file.url,
+        hash: createHash('sha256').update(bytes).digest('hex'),
+        size: info.size,
+        role: file.role,
+      };
+    }),
+  );
+  const sourceHash = createHash('sha256')
+    .update(
+      JSON.stringify(
+        sourceFiles
+          .map(({ path, hash, size }) => ({ path, hash, size }))
+          .sort((left, right) => left.path.localeCompare(right.path)),
+      ),
+    )
+    .digest('hex');
+  const plan = assetImportPlanSchema.parse({
+    version: 1,
+    id: randomUUID(),
+    identity: {
+      familyId: input.familyId,
+      variantId: input.variantId,
+      deliveryId: input.deliveryId,
+      source: input.source,
+      displayName: input.displayName,
+    },
+    sourceFiles,
+    generatedFiles: [...(input.generatedFiles ?? [])],
+    destination: input.destination,
+    contentKind: input.contentKind ?? 'model',
+    ...(input.targetSkeleton ? { targetSkeleton: input.targetSkeleton } : {}),
+    settings: {
+      scale: 1,
+      sourceUnits: 'auto',
+      upAxis: 'auto',
+      forwardAxis: 'auto',
+      normals: 'preserve',
+      tangents: 'preserve',
+      materials: 'import',
+      textures: 'copy',
+      animations: [],
+      meshOptimization: 'safe',
+      retainSource: true,
+      ...input.settings,
+    },
+    conflicts: [],
+    attribution: input.attribution,
+    sourceHash,
+    runtimeReady: input.runtimeReady,
+    backend: input.backend,
+    createdAt: new Date().toISOString(),
+  });
+  const recipeFile = input.recipeRelativePath ?? basename(importRecipePath(input.destination));
+  const recipePath = join(input.stagingDirectory, recipeFile);
+  await mkdir(dirname(recipePath), { recursive: true });
+  await writeFile(recipePath, `${JSON.stringify(plan, null, 2)}\n`);
+  return plan;
+}

package/server/catalog-reimport.ts

@@ -0,0 +1,141 @@
+import { copyFile, mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { basename, dirname, extname, join, relative, resolve } from 'node:path';
+import { type AssetImportPlan, assetImportPlanSchema } from '../src/asset-workflow/import-contract';
+import { type CatalogRecipeSource, writeCatalogImportRecipe } from './catalog-import-recipe';
+import {
+  findLocalAsset,
+  findLocalAssetFamily,
+  getLocalAssetLibraryRoot,
+  resolveCatalogFile,
+  resolveLocalAssetThumbnail,
+} from './local-asset-catalog';
+import {
+  convertStagedModelToGlb,
+  SERVER_CONVERTIBLE_MODEL_FORMATS,
+} from './model-import-conversion';
+import { replaceStagedProjectDirectory } from './project-output-writer';
+import { isPathInside } from './server-utils';
+
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: reacquisition, conversion, recipe regeneration, source-retention, and atomic replacement are one transaction boundary.
+export async function reimportLocalCatalogAsset(
+  publicRoot: string,
+  assetPath: string,
+  rawPlan: AssetImportPlan,
+): Promise<{ path: string; provenanceOperationId?: string }> {
+  const plan = assetImportPlanSchema.parse(rawPlan);
+  const normalizedAssetPath = assetPath.replace(/^\/+/, '');
+  if (normalizedAssetPath !== plan.destination || plan.identity.source !== 'local') {
+    throw new Error('Reimport identity does not match the selected local project asset.');
+  }
+  const family = await findLocalAssetFamily(plan.identity.familyId);
+  const variant = await findLocalAsset(plan.identity.variantId);
+  if (!family || !variant || variant.familyId !== family.id) {
+    throw new Error('The recorded catalog family/variant is no longer available.');
+  }
+  const sourceFile = variant.files[0];
+  if (!sourceFile) throw new Error('The recorded catalog variant has no source file.');
+  const destination = resolve(publicRoot, dirname(plan.destination));
+  if (!isPathInside(publicRoot, destination))
+    throw new Error('Reimport destination escapes public/.');
+  const staging = await mkdtemp(join(dirname(destination), `.${basename(destination)}.reimport-`));
+  try {
+    const libraryRoot = getLocalAssetLibraryRoot();
+    const primarySource = resolveCatalogFile(libraryRoot, sourceFile.path);
+    const primaryRelative = basename(primarySource);
+    const stagedPrimary = join(staging, primaryRelative);
+    await copyFile(primarySource, stagedPrimary);
+    const recipeSources: CatalogRecipeSource[] = [
+      {
+        stagedPath: stagedPrimary,
+        path: primaryRelative,
+        url: plan.sourceFiles[0]?.url ?? `vgai-local:${variant.id}:0`,
+        role: 'primary',
+      },
+    ];
+    for (const dependency of sourceFile.dependencies ?? []) {
+      const dependencySource = resolveCatalogFile(libraryRoot, dependency);
+      const sourceRelative = relative(dirname(primarySource), dependencySource);
+      const dependencyRelative = sourceRelative.startsWith('..')
+        ? basename(dependencySource)
+        : sourceRelative;
+      const destinationPath = join(staging, dependencyRelative);
+      await mkdir(dirname(destinationPath), { recursive: true });
+      await copyFile(dependencySource, destinationPath);
+      recipeSources.push({
+        stagedPath: destinationPath,
+        path: dependencyRelative.replaceAll('\\', '/'),
+        url: `catalog:${dependency}`,
+        role: dependencyRole(dependency),
+      });
+    }
+    const format = sourceFile.format.toLowerCase();
+    const resultFile = basename(plan.destination);
+    let backend: AssetImportPlan['backend'] = 'native';
+    if (SERVER_CONVERTIBLE_MODEL_FORMATS.has(format)) {
+      const output = await convertStagedModelToGlb(stagedPrimary, format, plan.settings);
+      await writeFile(join(staging, resultFile), output);
+      backend = 'threejs';
+    } else if (resultFile !== primaryRelative) {
+      await copyFile(stagedPrimary, join(staging, resultFile));
+    }
+    try {
+      const thumbnail = resolveLocalAssetThumbnail(libraryRoot, variant);
+      await copyFile(thumbnail, join(staging, '.vgai-thumbnail.webp'));
+    } catch {
+      // Thumbnails are a presentation cache and never invalidate a source reimport.
+    }
+    await writeCatalogImportRecipe({
+      stagingDirectory: staging,
+      source: 'local',
+      familyId: family.id,
+      variantId: variant.id,
+      deliveryId: plan.identity.deliveryId,
+      displayName: plan.identity.displayName ?? family.name,
+      destination: plan.destination,
+      sources: recipeSources,
+      contentKind: plan.contentKind,
+      ...(plan.targetSkeleton ? { targetSkeleton: plan.targetSkeleton } : {}),
+      generatedFiles: backend === 'threejs' ? [plan.destination] : [],
+      runtimeReady: ['glb', 'gltf'].includes(format) || backend === 'threejs',
+      backend,
+      attribution: plan.attribution,
+      settings: plan.settings,
+    });
+    if (backend === 'threejs' && !plan.settings.retainSource) {
+      await Promise.all(recipeSources.map((source) => rm(source.stagedPath, { force: true })));
+    }
+    const result = await replaceStagedProjectDirectory({
+      projectRoot: dirname(publicRoot),
+      stagedDirectory: staging,
+      destination,
+      provenance: {
+        operationName: 'catalog.asset.reimport',
+        operationSource: 'vgai-catalog',
+        input: {
+          familyId: family.id,
+          variantId: variant.id,
+          sourceHash: plan.sourceHash,
+          settings: plan.settings,
+        },
+      },
+    });
+    return {
+      path: plan.destination,
+      ...(result.provenanceOperationId
+        ? { provenanceOperationId: result.provenanceOperationId }
+        : {}),
+    };
+  } catch (error) {
+    await rm(staging, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+function dependencyRole(path: string): 'dependency' | 'material' | 'texture' {
+  const extension = extname(path).toLowerCase();
+  if (extension === '.mtl') return 'material';
+  if (['.png', '.jpg', '.jpeg', '.webp', '.ktx', '.ktx2', '.dds', '.tga'].includes(extension)) {
+    return 'texture';
+  }
+  return 'dependency';
+}

package/server/cloud-asset-catalog.ts

@@ -1,7 +1,7 @@
 export const DEFAULT_CLOUD_ASSET_BASE_URL = 'https://vgai-asset-library.aaron-0ed.workers.dev';
 
 export interface CloudAssetObject {
-  key: string;
+  key?: string;
   sha256: string;
   sizeBytes: number;
   contentType: string;
@@ -17,6 +17,8 @@ export interface CloudAssetFile {
 
 export interface CloudAssetRecord {
   id: string;
+  familyId?: string;
+  label?: string;
   status: 'validated';
   source: string;
   name: string;
@@ -25,17 +27,24 @@ export interface CloudAssetRecord {
   author: string;
   sourceUrl: string;
   attribution: string;
+  categories?: string[];
+  tags?: string[];
   files: CloudAssetFile[];
 }
 
 interface CloudAssetManifest {
-  version: 1;
+  version: 1 | 2;
   generatedAt: string;
   assets: CloudAssetRecord[];
 }
 
 let cachedManifest: { value: CloudAssetManifest; url: string; loadedAt: number } | undefined;
 const CACHE_MS = 5 * 60 * 1000;
+const GRAPHQL_ID_BATCH = 500;
+const graphqlAssetCache = new Map<
+  string,
+  { baseUrl: string; value: CloudAssetRecord | null; loadedAt: number }
+>();
 
 export function getCloudAssetBaseUrl(): string {
   return (process.env['VGAI_CLOUD_ASSET_URL'] ?? DEFAULT_CLOUD_ASSET_BASE_URL).replace(/\/+$/, '');
@@ -54,7 +63,7 @@ export async function loadCloudAssetManifest(): Promise<CloudAssetManifest | nul
     const response = await fetch(`${baseUrl}/v1/manifest`, { signal: AbortSignal.timeout(5_000) });
     if (!response.ok) return null;
     const value = (await response.json()) as CloudAssetManifest;
-    if (value.version !== 1 || !Array.isArray(value.assets)) return null;
+    if ((value.version !== 1 && value.version !== 2) || !Array.isArray(value.assets)) return null;
     cachedManifest = { value, url: baseUrl, loadedAt: Date.now() };
     return value;
   } catch {
@@ -63,8 +72,65 @@ export async function loadCloudAssetManifest(): Promise<CloudAssetManifest | nul
 }
 
 export async function findCloudAsset(id: string): Promise<CloudAssetRecord | null> {
-  const manifest = await loadCloudAssetManifest();
-  return manifest?.assets.find((asset) => asset.id === id) ?? null;
+  return (await findCloudAssets([id]))[0] ?? null;
+}
+
+async function queryCloudAssets(ids: readonly string[]): Promise<CloudAssetRecord[] | null> {
+  if (ids.length === 0) return [];
+  const response = await fetch(`${getCloudAssetBaseUrl()}/graphql`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      query: `query CloudAssets($ids: [ID!]!) {
+        assetsByIds(ids: $ids) {
+          id familyId label status source name type license author sourceUrl attribution categories tags
+          files: deliveries {
+            label format
+            main { sha256 sizeBytes contentType relativePath }
+            dependencies { sha256 sizeBytes contentType relativePath }
+          }
+        }
+      }`,
+      variables: { ids },
+    }),
+    signal: AbortSignal.timeout(5_000),
+  });
+  if (!response.ok) return null;
+  const body = (await response.json()) as {
+    data?: { assetsByIds?: CloudAssetRecord[] };
+    errors?: unknown[];
+  };
+  return body.errors || !Array.isArray(body.data?.assetsByIds) ? null : body.data.assetsByIds;
+}
+
+/** Resolve exact hosted variants through GraphQL; REST manifest is rollout fallback only. */
+export async function findCloudAssets(ids: readonly string[]): Promise<CloudAssetRecord[]> {
+  const uniqueIds = [...new Set(ids)];
+  const baseUrl = getCloudAssetBaseUrl();
+  const now = Date.now();
+  const unresolved = uniqueIds.filter((id) => {
+    const cached = graphqlAssetCache.get(id);
+    return !cached || cached.baseUrl !== baseUrl || now - cached.loadedAt >= CACHE_MS;
+  });
+  try {
+    for (let offset = 0; offset < unresolved.length; offset += GRAPHQL_ID_BATCH) {
+      const batch = unresolved.slice(offset, offset + GRAPHQL_ID_BATCH);
+      const found = await queryCloudAssets(batch);
+      if (!found) throw new Error('GraphQL catalog unavailable.');
+      const byId = new Map(found.map((asset) => [asset.id, asset]));
+      for (const id of batch) {
+        graphqlAssetCache.set(id, { baseUrl, value: byId.get(id) ?? null, loadedAt: now });
+      }
+    }
+    return uniqueIds.flatMap((id) => {
+      const asset = graphqlAssetCache.get(id)?.value;
+      return asset ? [asset] : [];
+    });
+  } catch {
+    const manifest = await loadCloudAssetManifest();
+    const requested = new Set(uniqueIds);
+    return manifest?.assets.filter((asset) => requested.has(asset.id)) ?? [];
+  }
 }
 
 export function cloudAssetObjectUrl(

package/server/dev.ts

@@ -209,7 +209,7 @@ async function main(): Promise<void> {
     engineRoot,
     projectPath,
     watchEngineSource: true,
-    loadProjectModule: (moduleId) => vite.ssrLoadModule(moduleId),
+    loadProjectModule: (moduleId: string) => vite.ssrLoadModule(moduleId),
     onProjectOpened(newProjectPath: string) {
       // Dynamically allow Vite to serve /@fs/ paths from the new project directory
       const allowed = vite.config.server.fs.allow;

package/server/editor-server.ts

@@ -19,6 +19,13 @@ import express from 'express';
 import { GAME_MANIFEST_VERSION } from '../../engine/src/manifest/schema';
 import { applyAssetRename } from '../../engine/src/scene/asset-paths';
 import type { SceneFile } from '../../engine/src/scene/scene-types';
+import {
+  deriveProjectAttributionReport,
+  emptyProjectProvenanceDocument,
+  formatProjectAttributionMarkdown,
+  PROJECT_PROVENANCE_PATH,
+  ProjectProvenanceDocumentSchema,
+} from '../../vgai-sdk/src/project/provenance';
 import {
   assertEditorCompatibility,
   assertProjectCompatibility,
@@ -39,10 +46,10 @@ import {
 } from './editor-sse';
 import { HarnessChatService } from './harness-chat-service';
 import {
-  discoverProjectOperations,
-  executeProjectOperation,
+  discoverProjectTools,
+  executeProjectTool,
   type ProjectModuleLoader,
-} from './project-operations';
+} from './project-tools';
 import { classifyValidatableFile, validateProjectFile } from './project-validation';
 import { readProjectView } from './project-view';
 import type { CommandResult } from './server-utils';
@@ -70,6 +77,7 @@ interface AssetEntry {
   name: string;
   type: 'file' | 'directory';
   size: number;
+  mtime: number;
 }
 
 interface RecentProject {
@@ -142,9 +150,26 @@ export interface EditorServerOptions {
   /** Dev checkout only: mark this long-running process stale when server-loaded source changes. */
   watchEngineSource?: boolean | undefined;
   /** Node-side project-module loader. Vite's ssrLoadModule supplies this in
-   * dev and packaged editors so discoverable project operations can remain
+   * dev and packaged editors so discoverable project tools can remain
    * ordinary TypeScript using the project's own dependency graph. */
   loadProjectModule?: ProjectModuleLoader | undefined;
+  /** Install a newly scaffolded project's dependencies before reporting it ready. */
+  installProjectDependencies?: ((projectPath: string) => Promise<void>) | undefined;
+}
+
+async function installProjectDependencies(projectPath: string): Promise<void> {
+  await new Promise<void>((resolveInstall, rejectInstall) => {
+    const child = spawn(
+      'npm',
+      ['install', '--no-audit', '--no-fund', '--loglevel=error'],
+      { cwd: projectPath, stdio: 'ignore', shell: true },
+    );
+    child.once('error', rejectInstall);
+    child.once('close', (code) => {
+      if (code === 0) resolveInstall();
+      else rejectInstall(new Error(`npm install exited with code ${code ?? 'unknown'}`));
+    });
+  });
 }
 
 function readRunningEngineVersion(engineRoot: string): string | null {
@@ -654,9 +679,8 @@ export function createEditorServer(options: EditorServerOptions): EditorServerRo
     // packaged/prod (this module is shared by both), and on drvfs
     // (`/mnt/c`, no inotify) via the same `VGAI_WATCH_POLL` env var.
     //
-    // Tool/data/story lists use add/unlink. Operation modules also use change:
-    // they are Node-loaded rather than browser-HMR-loaded, so metadata and
-    // implementation edits require a fresh catalog request.
+    // Tool/data/story lists use add/unlink. Registered tool modules also use
+    // change because their metadata and implementation are Node-loaded.
     const srcDir = join(projectRoot, 'src');
     if (projectRoot !== engineRoot && existsSync(srcDir)) {
       // #131: same polling decision as the publicRoot watcher above (env
@@ -674,20 +698,18 @@ export function createEditorServer(options: EditorServerOptions): EditorServerRo
               tools: 'tool-files-changed',
               data: 'data-files-changed',
               stories: 'story-files-changed',
-              operations: 'operation-files-changed',
             }[kind]
           : undefined;
         if (event) broadcastDebounced(event, { path: rel });
       };
       srcWatcher.on('add', onListChange);
       srcWatcher.on('unlink', onListChange);
-      // Tool edits ride Vite HMR and data edits have their own live-value
-      // path. Node-loaded project operations instead need a fresh catalog
-      // read when metadata or implementation changes in place.
+      // Registered callable tool edits need a fresh Node-side catalog read;
+      // contribution modules still ride ordinary Vite HMR in the browser.
       srcWatcher.on('change', (filePath) => {
         const rel = relative(projectRoot, resolve(filePath)).split(sep).join('/');
-        if (classifyProjectSrcPath(rel) === 'operations') {
-          broadcastDebounced('operation-files-changed', { path: rel });
+        if (classifyProjectSrcPath(rel) === 'tools') {
+          broadcastDebounced('tool-files-changed', { path: rel });
         }
       });
       srcWatcher.on('add', (filePath) => scheduleFileValidation(resolve(filePath)));
@@ -852,6 +874,55 @@ export function createEditorServer(options: EditorServerOptions): EditorServerRo
     createAssetLibraryRouter(() => publicRoot),
   );
 
+  // Derived credits view. The sole durable source is central project provenance.
+  router.get('/__editor/project-attribution', async (req: Request, res: Response) => {
+    if (projectRoot === engineRoot) {
+      res.status(400).json({ error: 'No project is open.' });
+      return;
+    }
+    try {
+      const raw = await readFile(join(projectRoot, PROJECT_PROVENANCE_PATH), 'utf8').catch(
+        (error: NodeJS.ErrnoException) => {
+          if (error.code === 'ENOENT') return null;
+          throw error;
+        },
+      );
+      const provenance = raw
+        ? ProjectProvenanceDocumentSchema.parse(JSON.parse(raw))
+        : emptyProjectProvenanceDocument();
+      const activeOperations = Object.fromEntries(
+        (
+          await Promise.all(
+            Object.entries(provenance.operations).map(async ([operationId, operation]) => {
+              const present = await Promise.all(
+                operation.outputs.map(async (output) => {
+                  const absolute = resolve(projectRoot, output.path);
+                  if (!isPathInside(projectRoot, absolute)) return false;
+                  return stat(absolute).then(
+                    (info) => info.isFile(),
+                    () => false,
+                  );
+                }),
+              );
+              return present.some(Boolean) ? ([operationId, operation] as const) : null;
+            }),
+          )
+        ).filter((entry): entry is readonly [string, (typeof provenance.operations)[string]] =>
+          Boolean(entry),
+        ),
+      );
+      const report = deriveProjectAttributionReport({ version: 1, operations: activeOperations });
+      const format = typeof req.query['format'] === 'string' ? req.query['format'] : 'json';
+      if (format === 'markdown' || req.accepts(['json', 'text/markdown']) === 'text/markdown') {
+        res.type('text/markdown').send(formatProjectAttributionMarkdown(report));
+        return;
+      }
+      res.json(report);
+    } catch (error) {
+      res.status(500).json({ error: `Project attribution failed: ${error}` });
+    }
+  });
+
   // ---- Project file serving middleware ----
   // Serves the v2 manifest from root and static files from project's public/
   router.use((req: Request, res: Response, next) => {
@@ -1253,11 +1324,11 @@ export function createEditorServer(options: EditorServerOptions): EditorServerRo
       for (const d of dirents) {
         if (d.name.startsWith('.')) continue;
         const entryPath = join(absDir, d.name);
+        const s = await stat(entryPath);
         if (d.isDirectory()) {
-          entries.push({ name: d.name, type: 'directory', size: 0 });
+          entries.push({ name: d.name, type: 'directory', size: 0, mtime: s.mtimeMs });
         } else if (d.isFile()) {
-          const s = await stat(entryPath);
-          entries.push({ name: d.name, type: 'file', size: s.size });
+          entries.push({ name: d.name, type: 'file', size: s.size, mtime: s.mtimeMs });
         }
       }
 
@@ -1513,6 +1584,8 @@ export function createEditorServer(options: EditorServerOptions): EditorServerRo
         ...(exampleId !== undefined ? { exampleId } : {}),
       });
 
+      await (options.installProjectDependencies ?? installProjectDependencies)(result.targetDir);
+
       // Ensure .vgai/ directory exists
       await mkdir(join(projectDir, '.vgai'), { recursive: true });
 
@@ -2075,50 +2148,27 @@ export function createEditorServer(options: EditorServerOptions): EditorServerRo
     }
   });
 
-  // ---- Project tools (W4, docs/DATA-TOOLS-DESIGN.md §3) ----
-  //
-  // Discovery for the dock's project-tool tabs: every
-  // `src/tools/**/*.tool.tsx` of the open project (folder scan, same D3
-  // physics as `/__editor/data-files` above — no registry, no cached
-  // manifest; §3.5 rule 2). Paths only: unlike data files, tool MODULES are
-  // loaded client-side through Vite's `/@fs/` dynamic-import path (the
-  // `script-loader.ts` pattern), so the code arrives transpiled with HMR —
-  // never as raw text through this route.
-  router.get('/__editor/tool-files', async (_req: Request, res: Response) => {
-    if (projectRoot === engineRoot) {
-      res.json({ files: [] });
-      return;
-    }
-    const toolsDir = join(projectRoot, 'src', 'tools');
-    const found = await findFiles(toolsDir, '.tool.tsx');
-    res.json({
-      files: found.sort().map((abs) => ({
-        path: relative(projectRoot, abs).split('\\').join('/'),
-      })),
-    });
-  });
-
-  // ---- Project operations (docs/PROJECT-OPERATIONS-DESIGN.md) ----
+  // ---- Registered project tools (docs/PROJECT-TOOLS-DESIGN.md) ----
   //
-  // Unlike project tools, operation modules are loaded on the NODE side.
-  // Merely listing a Node-native asset/map build script must never import it
+  // Callable modules are loaded on the NODE side. Merely listing a native
+  // asset/map build script must never import it
   // into the editor browser or make it reachable from a standalone game
   // bundle. Vite's ssrLoadModule is injected by the owning server and gives
   // us normal TS transform + project dependency resolution without a second
   // script runtime.
-  router.get('/__editor/project-operations', async (_req: Request, res: Response) => {
+  router.get('/__editor/project-tools', async (_req: Request, res: Response) => {
     if (projectRoot === engineRoot) {
-      res.json({ operations: [], loadErrors: [] });
+      res.json({ tools: [], loadErrors: [] });
       return;
     }
-    res.json(await discoverProjectOperations(projectRoot, options.loadProjectModule));
+    res.json(await discoverProjectTools(projectRoot, options.loadProjectModule));
   });
 
-  router.post('/__editor/project-operations/run', async (req: Request, res: Response) => {
+  router.post('/__editor/project-tools/run', async (req: Request, res: Response) => {
     if (projectRoot === engineRoot) {
       res.status(400).json({
         ok: false,
-        error: { code: 'NO_PROJECT_OPEN', message: 'Open a project before running an operation.' },
+        error: { code: 'NO_PROJECT_OPEN', message: 'Open a project before running a tool.' },
       });
       return;
     }
@@ -2126,13 +2176,13 @@ export function createEditorServer(options: EditorServerOptions): EditorServerRo
     if (typeof body.name !== 'string' || body.name.trim() === '') {
       res.status(400).json({
         ok: false,
-        error: { code: 'INVALID_OPERATION_NAME', message: 'Expected a non-empty operation name.' },
+        error: { code: 'INVALID_TOOL_NAME', message: 'Expected a non-empty tool name.' },
       });
       return;
     }
     const controller = new AbortController();
     req.once('aborted', () => controller.abort());
-    const result = await executeProjectOperation({
+    const result = await executeProjectTool({
       projectRoot,
       loadModule: options.loadProjectModule,
       name: body.name,
@@ -2251,6 +2301,7 @@ export function createEditorServer(options: EditorServerOptions): EditorServerRo
   // ---- Play-mode console log persistence ----
   const MAX_LOG_FILES = 20;
   let activeLogFile: string | null = null;
+  let logSessionSequence = 0;
 
   router.post('/__editor/log-session', async (req: Request, res: Response) => {
     const body = req.body as { action: 'start' | 'end' };
@@ -2273,8 +2324,12 @@ export function createEditorServer(options: EditorServerOptions): EditorServerRo
       }
 
       const now = new Date();
-      const ts = now.toISOString().replace(/[:.]/g, '-').slice(0, 19);
-      const filename = `play-${ts}.jsonl`;
+      // Milliseconds plus a process-local sequence make restart artifacts
+      // distinct even when two sessions begin inside the same millisecond.
+      // Lexicographic order remains chronological for pruning/tail tooling.
+      const ts = now.toISOString().replace(/[:.]/g, '-');
+      const sequence = String(++logSessionSequence).padStart(4, '0');
+      const filename = `play-${ts}-${sequence}.jsonl`;
       activeLogFile = join(logsDir, filename);
       res.json({ ok: true, file: filename });
     } else {

package/server/editor-sse.ts

@@ -119,6 +119,11 @@ export function updateClientControlHealth(clientId: string, health: ClientContro
   clientControlHealth.set(clientId, health);
 }
 
+/** Clear project-specific health snapshots while keeping live SSE sockets. */
+export function clearClientControlHealth(): void {
+  clientControlHealth.clear();
+}
+
 /** Number of currently-connected clients (exposed for tests). */
 export function clientCount(): number {
   return sseClients.size;