@vgai/editor 0.2.0 → 0.4.0-canary.20260715.0

package/server/local-asset-catalog.ts

@@ -2,6 +2,15 @@ import { createHash } from 'node:crypto';
 import { readFile, stat } from 'node:fs/promises';
 import { extname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { assetCapabilities } from '../src/asset-workflow/asset-capabilities';
+import {
+  type AssetCatalog,
+  type AssetFamily,
+  type AssetFile,
+  type AssetVariant,
+  parseAssetCatalog,
+} from '../src/asset-workflow/asset-types';
+import { migrateLegacyAssetCatalog } from './asset-catalog-v2';
 import { isPathInside } from './server-utils';
 
 export const DEFAULT_LOCAL_ASSET_LIBRARY_ROOT = '/Volumes/PeakSSD/vgai-asset-library';
@@ -10,17 +19,12 @@ export const REPOSITORY_ASSET_CATALOG_PATH = fileURLToPath(
 );
 
 export type LocalAssetType = 'model' | 'animation' | 'source';
-
-export interface LocalAssetFile {
-  label: string;
-  path: string;
-  format: string;
-  sizeBytes: number;
-  dependencies?: string[];
-}
+export type LocalAssetFile = AssetFile;
 
 export interface LocalCatalogAsset {
+  /** Variant identity. Family identity is explicit and separately exposed. */
   id: string;
+  familyId: string;
   source: string;
   name: string;
   type: LocalAssetType;
@@ -33,12 +37,12 @@ export interface LocalCatalogAsset {
   files: LocalAssetFile[];
   animationCount?: number;
   clipNames?: string[];
+  variants: readonly AssetVariant[];
 }
 
-export interface LocalAssetCatalog {
-  version: 1;
-  generatedAt: string;
-  assets: LocalCatalogAsset[];
+export interface LocalAssetCatalog extends AssetCatalog {
+  /** Valid variant projections, derived once at load for existing server consumers. */
+  readonly assets: readonly LocalCatalogAsset[];
 }
 
 export function getLocalAssetLibraryRoot(): string {
@@ -49,9 +53,7 @@ export function getLocalCatalogPath(root = getLocalAssetLibraryRoot()): string {
   return resolve(root, 'catalog', 'catalog.json');
 }
 
-export async function resolveLocalCatalogPath(
-  root = getLocalAssetLibraryRoot(),
-): Promise<string> {
+export async function resolveLocalCatalogPath(root = getLocalAssetLibraryRoot()): Promise<string> {
   const externalPath = getLocalCatalogPath(root);
   try {
     await stat(externalPath);
@@ -74,10 +76,17 @@ export async function loadLocalAssetCatalog(
     return cachedCatalog;
   }
 
-  const parsed = JSON.parse(await readFile(catalogPath, 'utf8')) as LocalAssetCatalog;
-  if (parsed.version !== 1 || !Array.isArray(parsed.assets)) {
-    throw new Error(`Unsupported local asset catalog at ${catalogPath}`);
-  }
+  const input: unknown = JSON.parse(await readFile(catalogPath, 'utf8'));
+  const normalized =
+    input && typeof input === 'object' && 'version' in input && input.version === 1
+      ? migrateLegacyAssetCatalog(input)
+      : parseAssetCatalog(input);
+  const parsed: LocalAssetCatalog = {
+    ...normalized,
+    assets: normalized.families.flatMap((family) =>
+      family.variants.map((variant) => projectCatalogVariant(family, variant)),
+    ),
+  };
   cachedCatalog = parsed;
   cachedPath = catalogPath;
   cachedMtimeMs = catalogStat.mtimeMs;
@@ -89,7 +98,49 @@ export async function findLocalAsset(
   root = getLocalAssetLibraryRoot(),
 ): Promise<LocalCatalogAsset | null> {
   const catalog = await loadLocalAssetCatalog(root);
-  return catalog.assets.find((asset) => asset.id === id) ?? null;
+  const exactVariant = catalog.assets.find((asset) => asset.id === id);
+  if (exactVariant) return exactVariant;
+  const family = catalog.families.find((candidate) => candidate.id === id);
+  return family ? preferredLocalAssetVariant(family) : null;
+}
+
+export async function findLocalAssetFamily(
+  id: string,
+  root = getLocalAssetLibraryRoot(),
+): Promise<AssetFamily | null> {
+  const catalog = await loadLocalAssetCatalog(root);
+  return (
+    catalog.families.find((family) => family.id === id) ??
+    catalog.families.find((family) => family.variants.some((variant) => variant.id === id)) ??
+    null
+  );
+}
+
+function projectCatalogVariant(family: AssetFamily, variant: AssetVariant): LocalCatalogAsset {
+  return {
+    id: variant.id,
+    familyId: family.id,
+    source: family.source,
+    name: family.name,
+    type: variant.type,
+    categories: family.categories,
+    tags: family.tags,
+    license: family.license,
+    author: family.author,
+    sourceUrl: family.sourceUrl,
+    thumbnail: variant.thumbnail.path,
+    files: variant.files,
+    ...(variant.animationCount !== undefined ? { animationCount: variant.animationCount } : {}),
+    ...(variant.clipNames !== undefined ? { clipNames: variant.clipNames } : {}),
+    variants: family.variants,
+  };
+}
+
+export function preferredLocalAssetVariant(family: AssetFamily): LocalCatalogAsset {
+  const ranked = rankLocalAssetPreviewVariants(
+    family.variants.map((variant) => projectCatalogVariant(family, variant)),
+  );
+  return ranked[0] ?? projectCatalogVariant(family, family.variants[0]!);
 }
 
 export function localAssetMatchesType(asset: LocalCatalogAsset, type?: string): boolean {
@@ -113,6 +164,76 @@ export function resolveCatalogFile(root: string, relativePath: string): string {
   return absolutePath;
 }
 
+/** Stable SSD cache location for a catalog card's generated preview. */
+export function localAssetThumbnailPath(asset: LocalCatalogAsset): string {
+  return asset.thumbnail ?? `thumbnails/${asset.id}.webp`;
+}
+
+/** Resolve a generated/upstream thumbnail without allowing catalog path escapes. */
+export function resolveLocalAssetThumbnail(root: string, asset: LocalCatalogAsset): string {
+  return resolveCatalogFile(root, localAssetThumbnailPath(asset));
+}
+
+const PREVIEW_FORMAT_PRIORITY: Record<string, number> = {
+  glb: 0,
+  gltf: 1,
+  obj: 2,
+  dae: 3,
+  fbx: 4,
+  stl: 5,
+  ply: 6,
+  '3ds': 7,
+  bvh: 8,
+};
+
+/**
+ * Identify format variants of the same catalog item without relying on category order.
+ * Catalog sources consistently use `sources/<source-root>/<collection>/...`; collection plus
+ * normalized display name distinguishes same-named assets from different packs and GSO objects.
+ */
+export function localAssetVariantKey(asset: LocalCatalogAsset): string {
+  return asset.familyId;
+}
+
+/** Best-first preview candidates for every source-format variant of an asset. */
+export function localAssetPreviewVariants(
+  asset: LocalCatalogAsset,
+  catalogAssets: readonly LocalCatalogAsset[],
+): LocalCatalogAsset[] {
+  const key = localAssetVariantKey(asset);
+  return rankLocalAssetPreviewVariants(
+    catalogAssets.filter((candidate) => localAssetVariantKey(candidate) === key),
+  );
+}
+
+/** Rank an already-associated set of semantic variants without regrouping it. */
+export function rankLocalAssetPreviewVariants(
+  variants: readonly LocalCatalogAsset[],
+): LocalCatalogAsset[] {
+  return [...variants].sort((left, right) => {
+    const leftFile = left.files[0];
+    const rightFile = right.files[0];
+    const formatDifference =
+      (PREVIEW_FORMAT_PRIORITY[leftFile?.format ?? ''] ?? 99) -
+      (PREVIEW_FORMAT_PRIORITY[rightFile?.format ?? ''] ?? 99);
+    if (formatDifference !== 0) return formatDifference;
+    const qualityDifference =
+      previewPathPenalty(leftFile?.path) - previewPathPenalty(rightFile?.path);
+    if (qualityDifference !== 0) return qualityDifference;
+    return (leftFile?.path ?? '').localeCompare(rightFile?.path ?? '');
+  });
+}
+
+function previewPathPenalty(path: string | undefined): number {
+  const normalized = path?.toLowerCase() ?? '';
+  let penalty = 0;
+  if (normalized.includes('unity')) penalty += 4;
+  if (normalized.includes('draco')) penalty += 3;
+  if (normalized.includes('quantized')) penalty += 2;
+  if (normalized.includes('embedded')) penalty += 1;
+  return penalty;
+}
+
 export function searchLocalCatalog(
   catalog: LocalAssetCatalog,
   options: { q?: string; type?: string; category?: string; offset?: number; limit?: number },
@@ -121,7 +242,7 @@ export function searchLocalCatalog(
   const category = options.category?.toLowerCase();
   const type = options.type === 'all' ? undefined : options.type;
 
-  const matches = catalog.assets.filter((asset) => {
+  const matches = catalog.families.map(preferredLocalAssetVariant).filter((asset) => {
     if (!localAssetMatchesType(asset, type)) return false;
     if (category && !asset.categories.some((value) => value.toLowerCase() === category)) {
       return false;
@@ -151,7 +272,21 @@ export function localAssetSlug(asset: LocalCatalogAsset): string {
     .toLowerCase()
     .replace(/[^a-z0-9]+/g, '-')
     .replace(/^-|-$/g, '');
-  return `${base || 'asset'}-${asset.id.slice(0, 8)}`;
+  return `${base || 'asset'}-${asset.familyId.slice(0, 8)}`;
+}
+
+export function localAssetCapabilities(asset: LocalCatalogAsset) {
+  const capabilities = assetCapabilities(asset.files[0]?.format ?? 'unknown');
+  return {
+    previewable: capabilities.previewable,
+    importable: capabilities.importable,
+    runtimeReady: capabilities.runtimeReady,
+    animated: capabilities.animated || (asset.animationCount ?? 0) > 0,
+    deliveryAvailable: asset.variants.some((variant) =>
+      variant.deliveries.some((delivery) => delivery.available),
+    ),
+    health: capabilities.runtimeReady ? 'healthy' : capabilities.importable ? 'source-only' : 'unsupported',
+  } as const;
 }
 
 export function makeLocalAssetId(source: string, key: string): string {

package/server/packaged.ts

@@ -28,7 +28,7 @@
  * ENABLED) whose job is ONLY to resolve/transform the opened PROJECT's own
  * source. Because that Vite instance's `root` is the project directory,
  * Vite's own resolver naturally walks the PROJECT's OWN `node_modules` for
- * every bare specifier (`three`, `zod`, `react`, `@vgai/scene-ui`, ...) —
+ * every bare specifier (`three`, `zod`, `react`, ...) —
  * for free, with zero hand-written import rewriting. This is the same
  * pattern `packages/editor/scripts/run-conformance.ts` uses to run the
  * adapter conformance kit against an arbitrary external folder, adapted for
@@ -39,7 +39,7 @@
  * slice) is reconstructed here too — pointed at the PROJECT's own installed
  * `@vgai/engine`, not a copy baked into this package's own tarball. A
  * project pinning `@vgai/engine@0.3.0` must be served ITS 0.3.0 source, so
- * `@vgai/engine`/`@vgai/scene-ui` are resolved via `createRequire`, rooted
+ * `@vgai/engine` is resolved via `createRequire`, rooted
  * at the project directory — Node's own resolution algorithm, not a
  * hardcoded path (see `resolveInstalledPackageSrcDir` in `server-utils.ts`,
  * shared with `editor-server.ts`'s equivalent fix for `prod.ts`'s route).
@@ -122,7 +122,7 @@
  * packaged editor (`vgai.game.json`'s `kind: 'react'` "hud" world,
  * `useGameState`) threw exactly this at mount: `TypeError: Cannot read
  * properties of null (reading 'useContext')` inside `useGame()`
- * (`src/ui/game-state.tsx`), called from the project's `Hud` component,
+ * (`@vgai/engine/react/game-state`), called from the project's `Hud` component,
  * rendered by the editor's OWN bundled `react_stack_bottom_frame`
  * (`assets/index-*.js`).
  *
@@ -208,21 +208,22 @@
  *   is the supported path today.
  */
 
-import { realpathSync } from 'node:fs';
+import { readFileSync, realpathSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import express from 'express';
 import { createServer as createViteServer } from 'vite';
 import { projectGameStaticPlugin } from '../vite-plugin-project-game-static';
-import { reactWorldProviderPlugin } from '../vite-plugin-react-world-provider';
 import { reactWorldRuntimePlugin } from '../vite-plugin-react-world-runtime';
 import { uiOidPlugin } from '../vite-plugin-ui-oid';
 import { canonicalProjectRoot } from './canonical-path';
 import { createEditorServer } from './editor-server';
 import { shouldShadowGameGlobals } from './game-globals-shadow';
+import { closeHttpServer, createProcessShutdown } from './process-shutdown';
+import { classifyProjectHotUpdate } from './project-hmr-files';
 import {
-  SERVER_ONLY_PREBUNDLE_EXCLUDE,
   computeProjectOptimizeDepsEntries,
+  SERVER_ONLY_PREBUNDLE_EXCLUDE,
 } from './project-optimize-deps-entries';
 import {
   friendlyListenError,
@@ -243,7 +244,11 @@ const editorPackageRoot = path.resolve(__dirname, '..');
 const distPath = path.resolve(editorPackageRoot, 'dist');
 
 const PORT = Number(process.env['PORT']) || Number(process.env['VGAI_EDITOR_PORT']) || 5173;
-const HMR_PORT = Number(process.env['VGAI_HMR_PORT']) || (PORT === 5173 ? 24678 : PORT + 100);
+// Keep generated projects' paired HMR sockets in a disjoint band from their
+// persisted 20000-29999 editor-port preferences (plus launcher fall-forward).
+const DEFAULT_HMR_PORT =
+  PORT >= 20_000 && PORT < 30_100 ? PORT + 10_000 : PORT === 5173 ? 24678 : PORT + 100;
+const HMR_PORT = Number(process.env['VGAI_HMR_PORT']) || DEFAULT_HMR_PORT;
 // S3: bind to loopback by default; opt-in to a wider interface via env.
 const HOST = resolveBindHost();
 
@@ -320,6 +325,14 @@ async function main(): Promise<void> {
     configFile: false,
     root: projectPath,
     appType: 'custom', // no HTML serving/SPA-fallback — this instance only serves project modules
+    // This Vite instance transforms not only project TSX (which uiOidPlugin
+    // already sends through automatic JSX) but also the installed engine's
+    // React bridge. Vite/esbuild otherwise compiles that dependency source to
+    // `React.createElement` even though the canonical bridge uses named React
+    // imports and intentionally has no global `React` binding. Keep Fast
+    // Refresh out (the custom app has no preamble host), but make the JSX
+    // runtime explicit for every TSX module served through this graph.
+    esbuild: { jsx: 'automatic' },
     plugins: [
       // React-world OID authoring parity (see this file's header doc comment,
       // "React-world OID authoring parity"): live `data-oid` instrumentation +
@@ -328,12 +341,6 @@ async function main(): Promise<void> {
       // (already project-scoped) unmodified — no extra scoping needed since this
       // instance's `root` IS the project already.
       uiOidPlugin(),
-      // Resolves the synthetic `/__vgai-game-provider` module
-      // `adapter-resolver.ts`'s `loadProjectGameProvider` imports for every
-      // `kind: 'react'` world's mount — WITHOUT this, a react world 404s at
-      // mount time in packaged mode (this is a correctness fix, not just an
-      // authoring nicety). See vite-plugin-react-world-provider.ts's doc comment.
-      reactWorldProviderPlugin(),
       // Resolves the synthetic `/__vgai-react-world-runtime` module
       // `adapter-resolver.ts`'s `resolveReactWorldMountRuntime` imports —
       // the dual-React-instance fix (this file's header doc comment,
@@ -367,11 +374,25 @@ async function main(): Promise<void> {
           file: string;
           server: { ws: { send: (msg: unknown) => void } };
         }) {
-          if (/\.(ts|tsx|js|jsx)$/.test(file)) {
+          const kind = classifyProjectHotUpdate(
+            file,
+            currentProjectRoot,
+            /\.[jt]sx?$/.test(file) ? readFileSync(file, 'utf-8') : '',
+          );
+          if (kind === 'outside' || kind === 'stock-data') return;
+          if (kind === 'react') return;
+          if (kind === 'component') {
             server.ws.send({ type: 'custom', event: 'vgai:script-update', data: { file } });
           }
-          // Swallow all project file changes — the editor handles scene/asset
-          // updates via its own SSE channel (mirrors dev.ts's `return []`).
+          if (kind === 'restart') {
+            server.ws.send({
+              type: 'custom',
+              event: 'vgai:restart-required',
+              data: { file },
+            });
+          }
+          // Swallow non-runtime project changes. In particular, building or
+          // running a tool under scripts/ must never import it into Play mode.
           return [];
         },
       },
@@ -465,6 +486,12 @@ async function main(): Promise<void> {
     },
     resolve: {
       alias: [
+        // Project-authored editor tools import the editor's public widget kit
+        // through `@editor/widgets` (the scaffolder writes the matching
+        // tsconfig path). In checkout mode the root Vite config supplies this
+        // alias; this project-rooted packaged Vite instance has no configFile,
+        // so it must reconstruct the runtime half from its own package root.
+        { find: /^@editor\//, replacement: `${path.join(editorPackageRoot, 'src')}/` },
         // The `@engine/*` alias project source still uses (pending the
         // `@engine/*` → `@vgai/engine/*` migration deferred to a follow-up
         // slice) — pointed at THIS project's own installed engine version,
@@ -496,6 +523,7 @@ async function main(): Promise<void> {
   const editorRouter = createEditorServer({
     engineRoot: editorPackageRoot,
     projectPath,
+    loadProjectModule: (moduleId) => vite.ssrLoadModule(moduleId),
     onProjectOpened(newProjectPath: string) {
       const allowed = vite.config.server.fs.allow;
       if (!allowed.includes(newProjectPath)) {
@@ -555,13 +583,15 @@ async function main(): Promise<void> {
     process.exit(1);
   });
 
-  const shutdown = () => {
+  const shutdown = createProcessShutdown({
+    tasks: [() => closeHttpServer(server), () => editorRouter.close(), () => vite.close()],
+  });
+  const unregisterAndShutdown = (signal: string) => {
     unregisterSession(process.pid);
-    vite.close();
-    server.close();
+    void shutdown(signal);
   };
-  process.once('SIGINT', shutdown);
-  process.once('SIGTERM', shutdown);
+  process.once('SIGINT', () => unregisterAndShutdown('SIGINT'));
+  process.once('SIGTERM', () => unregisterAndShutdown('SIGTERM'));
   process.once('exit', () => unregisterSession(process.pid));
 }
 

package/server/process-shutdown.ts

@@ -0,0 +1,136 @@
+import { type ChildProcess, execFileSync } from 'node:child_process';
+import type { Server } from 'node:http';
+
+/**
+ * Terminate a detached child and its whole process tree. Shared by the e2e
+ * server harness and the packaged probe runner: keeping this under `server/`
+ * makes the runtime utility part of the editor package instead of forcing a
+ * published command to import an unshipped e2e helper.
+ */
+export function stopProcess(proc: ChildProcess): Promise<void> {
+  const signalGroup = (signal: NodeJS.Signals) => {
+    if (proc.pid === undefined) return;
+    if (process.platform === 'win32') {
+      try {
+        execFileSync('taskkill', ['/PID', String(proc.pid), '/T', '/F'], { stdio: 'ignore' });
+      } catch {
+        /* already dead, or taskkill unavailable */
+      }
+      try {
+        proc.kill(signal);
+      } catch {
+        /* already dead */
+      }
+      return;
+    }
+    try {
+      process.kill(-proc.pid, signal);
+    } catch {
+      try {
+        proc.kill(signal);
+      } catch {
+        /* already dead */
+      }
+    }
+  };
+
+  return new Promise((resolve) => {
+    if (proc.exitCode !== null || proc.signalCode !== null) {
+      signalGroup('SIGKILL');
+      resolve();
+      return;
+    }
+    const timer = setTimeout(() => {
+      signalGroup('SIGKILL');
+      resolve();
+    }, 5000);
+    proc.on('exit', () => {
+      clearTimeout(timer);
+      signalGroup('SIGKILL');
+      resolve();
+    });
+    signalGroup('SIGTERM');
+  });
+}
+
+export interface ProcessShutdownOptions {
+  timeoutMs?: number;
+  tasks: ReadonlyArray<() => void | Promise<void>>;
+  exit?: (code: number) => void;
+  log?: (message: string) => void;
+}
+
+/** Stop accepting requests and forcibly release persistent HTTP/SSE sockets. */
+export function closeHttpServer(server: Server): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (!server.listening) {
+      server.closeAllConnections?.();
+      resolve();
+      return;
+    }
+    server.close((error) => (error ? reject(error) : resolve()));
+    // `server.close()` waits for persistent SSE/keep-alive connections. They
+    // have no useful work after process shutdown begins, so close them after
+    // removing the listener and eliminate the restart race on the HTTP port.
+    server.closeAllConnections?.();
+  });
+}
+
+/**
+ * Build an idempotent, bounded signal handler.
+ *
+ * Node's default signal exit is disabled as soon as an application installs
+ * a SIGTERM/SIGINT listener. Tooling loaders (notably tsx/esbuild) may retain
+ * internal handles even after every application server and watcher closes,
+ * so waiting for an empty event loop is not a shutdown contract. Resources
+ * get one bounded graceful window and then the process exits explicitly.
+ */
+export function createProcessShutdown(
+  options: ProcessShutdownOptions,
+): (why: string) => Promise<void> {
+  const timeoutMs = options.timeoutMs ?? 5_000;
+  const exit = options.exit ?? ((code: number) => process.exit(code));
+  const log = options.log ?? ((message: string) => process.stderr.write(`${message}\n`));
+  let pending: Promise<void> | null = null;
+
+  return (why: string) => {
+    if (pending) return pending;
+    pending = (async () => {
+      let timeout: ReturnType<typeof setTimeout> | undefined;
+      const cleanup = Promise.allSettled(
+        options.tasks.map(async (task) => {
+          await task();
+        }),
+      );
+      const result = await Promise.race([
+        cleanup.then((settled) => ({ type: 'settled' as const, settled })),
+        new Promise<{ type: 'timeout' }>((resolve) => {
+          timeout = setTimeout(() => resolve({ type: 'timeout' }), timeoutMs);
+        }),
+      ]);
+      if (timeout) clearTimeout(timeout);
+
+      if (result.type === 'timeout') {
+        log(`[vgai-editor] cleanup timed out after ${timeoutMs}ms (${why}); forcing exit`);
+        exit(1);
+        return;
+      }
+      const failures = result.settled.filter(
+        (item): item is PromiseRejectedResult => item.status === 'rejected',
+      );
+      if (failures.length > 0) {
+        log(
+          `[vgai-editor] cleanup failed (${why}): ${failures
+            .map((item) =>
+              item.reason instanceof Error ? item.reason.message : String(item.reason),
+            )
+            .join('; ')}`,
+        );
+        exit(1);
+        return;
+      }
+      exit(0);
+    })();
+    return pending;
+  };
+}

package/server/prod.ts

@@ -13,6 +13,7 @@ import { fileURLToPath } from 'node:url';
 import express from 'express';
 import { canonicalProjectRoot } from './canonical-path';
 import { createEditorServer } from './editor-server';
+import { closeHttpServer, createProcessShutdown } from './process-shutdown';
 import { friendlyListenError, resolveBindHost } from './server-utils';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -47,7 +48,9 @@ async function main(): Promise<void> {
   const server = app.listen(PORT, HOST, () => {
     const addr = server.address();
     const actualPort = typeof addr === 'object' && addr ? addr.port : PORT;
-    console.log(`\n  \x1b[32mProduction server\x1b[0m running at \x1b[36mhttp://${HOST}:${actualPort}\x1b[0m`);
+    console.log(
+      `\n  \x1b[32mProduction server\x1b[0m running at \x1b[36mhttp://${HOST}:${actualPort}\x1b[0m`,
+    );
     if (projectPath) {
       console.log(`  \x1b[33mProject\x1b[0m: ${projectPath}`);
     }
@@ -62,11 +65,11 @@ async function main(): Promise<void> {
     process.exit(1);
   });
 
-  const shutdown = () => {
-    server.close();
-  };
-  process.once('SIGINT', shutdown);
-  process.once('SIGTERM', shutdown);
+  const shutdown = createProcessShutdown({
+    tasks: [() => closeHttpServer(server), () => editorRouter.close()],
+  });
+  process.once('SIGINT', () => void shutdown('SIGINT'));
+  process.once('SIGTERM', () => void shutdown('SIGTERM'));
 }
 
 main().catch((err) => {

package/server/project-hmr-files.ts

@@ -0,0 +1,41 @@
+import path from 'node:path';
+
+export type ProjectHotUpdateKind =
+  | 'outside'
+  | 'stock-data'
+  | 'react'
+  | 'component'
+  | 'restart'
+  | 'ignore';
+
+/**
+ * Classify a Vite watcher update for the editor's project-script HMR seam.
+ *
+ * Only modules below the project's `src/` directory are game code. Build
+ * output, tests, one-off scripts, and dependency caches may also contain
+ * JavaScript, but importing them into the live game is both surprising and
+ * unsafe (a project build used to make the editor import `dist/assets/*`).
+ */
+export function classifyProjectHotUpdate(
+  file: string,
+  projectRoot: string,
+  source = '',
+): ProjectHotUpdateKind {
+  const normalizedFile = file.replaceAll('\\', '/');
+  const normalizedRoot = projectRoot.replaceAll('\\', '/').replace(/\/$/, '');
+  const relative = path.posix.relative(normalizedRoot, normalizedFile);
+
+  if (relative === '' || relative === '..' || relative.startsWith('../')) return 'outside';
+  if (relative === 'vgai.game.json') return 'restart';
+  if (!relative.startsWith('src/')) return 'ignore';
+  // Project-operation wrappers are editor/server tooling. A game that wants
+  // shared generation imports the underlying ordinary module, not this
+  // discoverability wrapper, so editing an operation must not request a full
+  // game restart.
+  if (/^src\/operations\/.*\.operation\.(ts|js)$/.test(relative)) return 'ignore';
+  if (/\.data\.json$/.test(relative)) return 'stock-data';
+  if (!/\.(ts|tsx|js|jsx)$/.test(relative)) return 'ignore';
+  if (/\bextends\s+(?:[A-Za-z_$][\w$]*\.)?GameComponent\b/.test(source)) return 'component';
+  if (/\.(tsx|jsx)$/.test(relative)) return 'react';
+  return 'restart';
+}