@vgai/editor 0.2.0

package/server/editor-server.ts

@@ -0,0 +1,1537 @@
+/**
+ * Express app factory for the editor backend.
+ *
+ * All /__editor/* API routes extracted from vite-plugin-asset-browser.ts.
+ * Works in both dev (alongside Vite middleware) and production (standalone).
+ */
+
+import { type ChildProcess, execFile, spawn } from 'node:child_process';
+import { createHash, randomUUID } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { appendFile, mkdir, readdir, readFile, stat, unlink, writeFile } from 'node:fs/promises';
+import { homedir, platform } from 'node:os';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+import chokidar, { type FSWatcher } from 'chokidar';
+import { type ScaffoldTemplate, scaffoldProject } from 'create-vgai-project';
+import type { Request, Response, Router } from 'express';
+import express from 'express';
+import { applyAssetRename } from '../../engine/src/scene/asset-paths';
+import type { SceneFile } from '../../engine/src/scene/scene-types';
+import { createAssetLibraryRouter } from './asset-library-routes';
+import { canonicalProjectRoot } from './canonical-path';
+import { addClient, broadcast, clientCount, removeClient } from './editor-sse';
+import { readProjectView } from './project-view';
+import type { CommandResult } from './server-utils';
+import {
+  classifyProjectSrcPath,
+  commandResponseFor,
+  escapeAppleScriptString,
+  findUniqueMoveMatch,
+  isAllowedEditorOrigin,
+  isMonorepoScaffoldRoot,
+  isPathInside,
+  isServableFsExtension,
+  PACKAGED_NO_MONOREPO_TEMPLATE_ERROR,
+  resolveInstalledPackageSrcDir,
+  sanitizeContentDispositionFilename,
+  validateManifestWrite,
+} from './server-utils';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface AssetEntry {
+  name: string;
+  type: 'file' | 'directory';
+  size: number;
+}
+
+interface RecentProject {
+  name: string;
+  path: string;
+  lastOpened: string;
+  thumbnail?: string;
+}
+
+const RECENT_PROJECTS_PATH = join(homedir(), '.vgai', 'recent-projects.json');
+const MAX_RECENT_PROJECTS = 20;
+
+async function loadRecentProjects(): Promise<RecentProject[]> {
+  try {
+    const raw = await readFile(RECENT_PROJECTS_PATH, 'utf-8');
+    const projects = JSON.parse(raw) as RecentProject[];
+    // Filter out projects whose paths no longer exist, populate thumbnails
+    const valid: RecentProject[] = [];
+    for (const p of projects) {
+      // §1C: a manifest-only folder (no project.json) is still a valid
+      // recent project — readProjectView is the one place this rule lives.
+      const view = await readProjectView(p.path);
+      if (!view) continue; // Path no longer exists / neither file describes it — skip
+      // Check for thumbnail
+      try {
+        await stat(join(p.path, '.vgai', 'thumbnail.png'));
+        p.thumbnail = `/__editor/project-thumbnail?path=${encodeURIComponent(p.path)}`;
+      } catch {
+        delete p.thumbnail;
+      }
+      valid.push(p);
+    }
+    return valid;
+  } catch {
+    return [];
+  }
+}
+
+async function saveRecentProjects(projects: RecentProject[]): Promise<void> {
+  await mkdir(dirname(RECENT_PROJECTS_PATH), { recursive: true });
+  await writeFile(RECENT_PROJECTS_PATH, JSON.stringify(projects, null, 2), 'utf-8');
+}
+
+async function addToRecentProjects(name: string, projectPath: string): Promise<void> {
+  const projects = await loadRecentProjects();
+  // Remove existing entry for this path
+  const filtered = projects.filter((p) => p.path !== projectPath);
+  // Add at the front
+  filtered.unshift({ name, path: projectPath, lastOpened: new Date().toISOString() });
+  // Trim to max
+  await saveRecentProjects(filtered.slice(0, MAX_RECENT_PROJECTS));
+}
+
+function slugify(name: string): string {
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '');
+}
+
+export interface EditorServerOptions {
+  /** Absolute path to the editor/engine repo root (for build scripts + artifacts). */
+  engineRoot: string;
+  /** Initial project path (optional — can be set later via open-project endpoint). */
+  projectPath?: string | undefined;
+  /** Serve project scripts via /@fs/ with esbuild transform (production only — Vite handles this in dev). */
+  serveScripts?: boolean;
+  /** Called when a project is opened at runtime — allows the dev server to update Vite's fs.allow. */
+  onProjectOpened?: ((projectPath: string) => void) | undefined;
+}
+
+// ---------------------------------------------------------------------------
+// File hashing — partial hash for large files (first 64KB + size)
+// ---------------------------------------------------------------------------
+
+const PARTIAL_HASH_THRESHOLD = 10 * 1024 * 1024; // 10MB
+
+async function hashAndSize(absPath: string): Promise<{ hash: string; size: number }> {
+  const data = await readFile(absPath);
+  const hash = createHash('sha256');
+  if (data.length > PARTIAL_HASH_THRESHOLD) {
+    hash.update(data.subarray(0, 65536));
+    hash.update(`\0size:${data.length}`);
+  } else {
+    hash.update(data);
+  }
+  return { hash: hash.digest('hex').slice(0, 16), size: data.length };
+}
+
+// ---------------------------------------------------------------------------
+// Recursive file scanning
+// ---------------------------------------------------------------------------
+
+async function findFiles(dir: string, ext: string): Promise<string[]> {
+  const results: string[] = [];
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return results;
+  }
+  for (const entry of entries) {
+    if (entry.name.startsWith('.')) continue;
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...(await findFiles(full, ext)));
+    } else if (entry.isFile() && entry.name.endsWith(ext)) {
+      results.push(full);
+    }
+  }
+  return results;
+}
+
+async function scanDirForHashes(
+  dir: string,
+  hashCache: Map<string, string>,
+  sizeCache: Map<string, number>,
+): Promise<void> {
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (entry.name.startsWith('.')) continue;
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      await scanDirForHashes(full, hashCache, sizeCache);
+    } else if (entry.isFile()) {
+      try {
+        const { hash, size } = await hashAndSize(full);
+        hashCache.set(full, hash);
+        sizeCache.set(full, size);
+      } catch {
+        /* skip unreadable files */
+      }
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// MIME type detection
+// ---------------------------------------------------------------------------
+
+const mimeTypes: Record<string, string> = {
+  json: 'application/json',
+  glb: 'model/gltf-binary',
+  gltf: 'model/gltf+json',
+  png: 'image/png',
+  jpg: 'image/jpeg',
+  jpeg: 'image/jpeg',
+  webp: 'image/webp',
+  svg: 'image/svg+xml',
+  wav: 'audio/wav',
+  mp3: 'audio/mpeg',
+  ogg: 'audio/ogg',
+  gif: 'image/gif',
+};
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+export function createEditorServer(options: EditorServerOptions): Router {
+  const { engineRoot } = options;
+
+  // Mutable project state — updated by open-project endpoint
+  let projectRoot = options.projectPath ?? engineRoot;
+  let publicRoot = resolve(projectRoot, 'public');
+
+  // ---- File hash cache + move detection ----
+  const fileHashCache = new Map<string, string>();
+  const fileSizeCache = new Map<string, number>();
+
+  interface PendingUnlink {
+    absPath: string;
+    relativePath: string;
+    hash: string;
+    size: number;
+    timestamp: number;
+  }
+
+  const MOVE_WINDOW_MS = 3000;
+  const pendingUnlinks: PendingUnlink[] = [];
+
+  // ---- Scene auto-rewrite on move ----
+  async function handleAssetMove(oldPath: string, newPath: string): Promise<void> {
+    const updatedFiles: string[] = [];
+
+    // Find and rewrite .vscn.json files
+    const sceneFiles = await findFiles(publicRoot, '.vscn.json');
+    for (const absFile of sceneFiles) {
+      try {
+        const raw = await readFile(absFile, 'utf-8');
+        if (!raw.includes(oldPath)) continue;
+        const doc = JSON.parse(raw) as SceneFile;
+        const renamed = applyAssetRename(doc, oldPath, newPath);
+        await writeFile(absFile, JSON.stringify(renamed, null, 2), 'utf-8');
+        updatedFiles.push('/' + relative(publicRoot, absFile));
+      } catch {
+        /* skip files that fail to parse/write */
+      }
+    }
+
+    // Find and rewrite .prefab.json files
+    const prefabFiles = await findFiles(publicRoot, '.prefab.json');
+    for (const absFile of prefabFiles) {
+      try {
+        const raw = await readFile(absFile, 'utf-8');
+        if (!raw.includes(oldPath)) continue;
+        const prefab = JSON.parse(raw) as { version: number; name: string; root: unknown };
+        const asSceneFile: SceneFile = {
+          version: prefab.version,
+          name: prefab.name,
+          entities: [prefab.root as SceneFile['entities'][number]],
+        };
+        const renamed = applyAssetRename(asSceneFile, oldPath, newPath);
+        prefab.root = renamed.entities[0];
+        await writeFile(absFile, JSON.stringify(prefab, null, 2), 'utf-8');
+        updatedFiles.push('/' + relative(publicRoot, absFile));
+      } catch {
+        /* skip */
+      }
+    }
+
+    broadcast('asset-moved', { oldPath, newPath, updatedFiles });
+  }
+
+  // ---- Chokidar watcher ----
+  let watcher: FSWatcher | null = null;
+  let srcWatcher: FSWatcher | null = null;
+
+  // Coalesce event bursts (e.g. a git checkout adding several files at once)
+  // into one broadcast per event name, trailing ~250ms after the last event.
+  const pendingBroadcasts = new Map<string, ReturnType<typeof setTimeout>>();
+  function broadcastDebounced(event: string, data: unknown, ms = 250): void {
+    const existing = pendingBroadcasts.get(event);
+    if (existing) clearTimeout(existing);
+    pendingBroadcasts.set(
+      event,
+      setTimeout(() => {
+        pendingBroadcasts.delete(event);
+        broadcast(event, data);
+      }, ms),
+    );
+  }
+
+  function startWatcher(): void {
+    watcher?.close();
+    srcWatcher?.close();
+    srcWatcher = null;
+    fileHashCache.clear();
+    fileSizeCache.clear();
+    pendingUnlinks.length = 0;
+
+    // Seed hash cache in background
+    scanDirForHashes(publicRoot, fileHashCache, fileSizeCache);
+
+    watcher = chokidar.watch(publicRoot, {
+      ignoreInitial: true,
+      ignored: /(^|[/\\])\../, // ignore dotfiles
+    });
+
+    watcher.on('change', async (filePath: string) => {
+      const abs = resolve(filePath);
+      if (!isPathInside(publicRoot, abs)) return;
+      try {
+        const { hash, size } = await hashAndSize(abs);
+        fileHashCache.set(abs, hash);
+        fileSizeCache.set(abs, size);
+      } catch {
+        /* ignore */
+      }
+
+      // Broadcast scene file changes so the editor can live-reload
+      if (abs.endsWith('.vscn.json')) {
+        try {
+          const content = await readFile(abs, 'utf-8');
+          const rel = '/' + relative(publicRoot, abs);
+          broadcast('scene-changed', { path: rel, content });
+        } catch {
+          /* file may have been deleted between events */
+        }
+      }
+    });
+
+    watcher.on('unlink', (filePath: string) => {
+      const abs = resolve(filePath);
+      if (!isPathInside(publicRoot, abs)) return;
+      const hash = fileHashCache.get(abs);
+      const size = fileSizeCache.get(abs);
+      if (hash !== undefined && size !== undefined) {
+        const rel = '/' + relative(publicRoot, abs);
+        pendingUnlinks.push({ absPath: abs, relativePath: rel, hash, size, timestamp: Date.now() });
+        fileHashCache.delete(abs);
+        fileSizeCache.delete(abs);
+      }
+    });
+
+    watcher.on('add', async (filePath: string) => {
+      const abs = resolve(filePath);
+      if (!isPathInside(publicRoot, abs)) return;
+
+      try {
+        const { hash, size } = await hashAndSize(abs);
+        fileHashCache.set(abs, hash);
+        fileSizeCache.set(abs, size);
+
+        // SC2: only treat a delete+create as a move when it is unambiguous —
+        // matching hash AND size, and a single such pending unlink. Otherwise
+        // an unrelated delete+create could silently rewrite scene refs.
+        const match = findUniqueMoveMatch(pendingUnlinks, hash, size, Date.now(), MOVE_WINDOW_MS);
+        if (match) {
+          const idx = pendingUnlinks.indexOf(match);
+          if (idx >= 0) pendingUnlinks.splice(idx, 1);
+          const newRelPath = '/' + relative(publicRoot, abs);
+          await handleAssetMove(match.relativePath, newRelPath);
+        }
+      } catch {
+        /* ignore read errors */
+      }
+    });
+
+    // ---- Second watcher: <project>/src (W6a, docs/DATA-TOOLS-DESIGN.md §7) ----
+    //
+    // The watcher above is scoped to `publicRoot` (`<project>/public`) only —
+    // it never sees `src/tools/*.tool.tsx` or `src/data/*.data.json`, so a
+    // NEW file there never showed up without a full editor reload (spec §7
+    // W4 field note c). Vite's own HMR (`vgai-script-hmr` in dev.ts, and
+    // `tool-loader.ts`'s listener on it) only fires on `change`, and the
+    // `VGAI_WATCH_POLL` poll-watcher (dev.ts) forwards its synthetic events
+    // into VITE's chokidar watcher only — never into this one. So this
+    // second watcher is self-contained here: it works in dev AND
+    // packaged/prod (this module is shared by both), and on drvfs
+    // (`/mnt/c`, no inotify) via the same `VGAI_WATCH_POLL` env var.
+    //
+    // add/unlink ONLY, never `change`: tool-content edits already ride the
+    // existing `vgai:script-update` HMR path, and a data-file `change` event
+    // would echo the DataPanel's own `/__editor/data-file` POST writes back
+    // into a refetch, clobbering in-flight drafts.
+    const srcDir = join(projectRoot, 'src');
+    if (projectRoot !== engineRoot && existsSync(srcDir)) {
+      // Same parse as dev.ts's `startProjectPollWatcher` (VGAI_WATCH_POLL=1,
+      // or =<ms> for the interval).
+      const pollRaw = Number(process.env['VGAI_WATCH_POLL']);
+      srcWatcher = chokidar.watch(srcDir, {
+        ignoreInitial: true,
+        ignored: /(^|[/\\])\../, // ignore dotfiles
+        ...(process.env['VGAI_WATCH_POLL']
+          ? { usePolling: true, interval: pollRaw > 1 ? pollRaw : 1000 }
+          : {}),
+      });
+      const onListChange = (filePath: string) => {
+        const rel = relative(projectRoot, resolve(filePath)).split(sep).join('/');
+        const kind = classifyProjectSrcPath(rel);
+        if (kind === 'tools') broadcastDebounced('tool-files-changed', { path: rel });
+        else if (kind === 'data') broadcastDebounced('data-files-changed', { path: rel });
+      };
+      srcWatcher.on('add', onListChange);
+      srcWatcher.on('unlink', onListChange);
+    }
+  }
+
+  // Start initial watcher
+  startWatcher();
+
+  // Periodic cleanup of stale pending unlinks
+  setInterval(() => {
+    const cutoff = Date.now() - MOVE_WINDOW_MS * 2;
+    while (pendingUnlinks.length > 0 && pendingUnlinks[0]!.timestamp < cutoff) {
+      pendingUnlinks.shift();
+    }
+  }, 5000);
+
+  // ---- Build state ----
+  const BUILD_SCRIPTS: Record<string, string> = {
+    web: 'build:web',
+  };
+  let activeBuild: ChildProcess | null = null;
+
+  // ---- Editor command relay + state ----
+  let editorState: Record<string, unknown> = {};
+
+  // Pending command results — keyed by requestId, resolved by browser POST
+  const pendingCommands = new Map<
+    string,
+    { resolve: (result: CommandResult) => void; timer: ReturnType<typeof setTimeout> }
+  >();
+  const COMMAND_TIMEOUT_MS = 5000;
+  // `play` is the one command whose ack is gated on the GAME, not the editor:
+  // the browser resolves it only after `enterPlayMode()` — which awaits the
+  // project's entire async `setup()` (asset loads, procedural worldgen). Under
+  // the generic 5s window any substantial game made `vgai play` report
+  // "editor connected but did not respond" while play in fact proceeded and
+  // succeeded (hit dogfooding a voxel game whose worldgen alone outlives 5s).
+  const PLAY_COMMAND_TIMEOUT_MS = 120_000;
+
+  // ---- Router ----
+  const router = express.Router();
+  router.use(express.json({ limit: '50mb' }));
+
+  // ---- CSRF / drive-by protection (S3) ----
+  // Mutating /__editor/* routes can write files, switch projects, and run npm
+  // builds (RCE). A malicious web page could POST to a locally-bound editor; an
+  // Origin allowlist (loopback only, by default) blocks that. Non-browser
+  // clients (CLI/SDK via Node fetch) send no Origin header and are allowed.
+  router.use((req: Request, res: Response, next) => {
+    const method = req.method.toUpperCase();
+    const isMutating =
+      method === 'POST' || method === 'PUT' || method === 'PATCH' || method === 'DELETE';
+    if (isMutating && req.path.startsWith('/__editor')) {
+      const host = process.env['VGAI_EDITOR_HOST'];
+      const extra = host ? [host] : [];
+      if (!isAllowedEditorOrigin(req.headers.origin, extra)) {
+        res.status(403).json({ error: 'Cross-origin request rejected.' });
+        return;
+      }
+    }
+    next();
+  });
+
+  // ---- Asset Library (online asset browsing + download) ----
+  router.use(
+    '/__editor/asset-library',
+    createAssetLibraryRouter(() => publicRoot),
+  );
+
+  // ---- Project file serving middleware ----
+  // Serves project.json from root and static files from project's public/
+  router.use((req: Request, res: Response, next) => {
+    // Only handle non-API requests when a project is open
+    if (projectRoot === engineRoot) return next();
+    const pathname = req.path;
+
+    // Skip editor API endpoints
+    if (pathname.startsWith('/__')) return next();
+    if (pathname.startsWith('/@')) return next();
+    if (pathname.startsWith('/node_modules')) return next();
+
+    // Serve project.json (or its manifest-synthesized compat view — §1C)
+    // from the project root, not public/.
+    if (pathname === '/project.json') {
+      readProjectView(projectRoot)
+        .then((view) => {
+          if (!view) return next();
+          res.json(view);
+        })
+        .catch(() => next());
+      return;
+    }
+
+    // Serve the RAW manifest (no view synthesis — the browser-side adapter
+    // resolver parses it itself via the pure `@engine/manifest/load` half;
+    // T3.3 slice 2 part C) from the project root, not public/. 404s (falls
+    // through to `next()`, same as any other missing project-root file) for
+    // legacy `project.json`-only projects — that is what makes the manifest
+    // branch a no-op for them.
+    if (pathname === '/vgai.game.json') {
+      readFile(join(projectRoot, 'vgai.game.json'), 'utf-8')
+        .then((raw) => {
+          res.setHeader('Content-Type', 'application/json');
+          res.send(raw);
+        })
+        .catch(() => next());
+      return;
+    }
+
+    const filePath = resolve(publicRoot, pathname.slice(1));
+    if (!filePath.startsWith(publicRoot)) return next();
+
+    stat(filePath)
+      .then(async (s) => {
+        if (!s.isFile()) return next();
+        const data = await readFile(filePath);
+        const ext = filePath.split('.').pop() ?? '';
+        res.writeHead(200, {
+          'Content-Type': mimeTypes[ext] ?? 'application/octet-stream',
+          'Content-Length': s.size,
+        });
+        res.end(data);
+      })
+      .catch(() => next());
+  });
+
+  // ---- Current project info ----
+  router.get('/__editor/project', async (_req: Request, res: Response) => {
+    if (projectRoot === engineRoot) {
+      // No project open
+      res.json({ project: null });
+      return;
+    }
+    const config = await readProjectView(projectRoot);
+    // hasUiRegistry: whether the project ships an OPTIONAL src/ui/registry.ts
+    // (scene-UI project mode, design/24-scene-ui.md D9). The client must not
+    // probe /@fs for it — a dev server answers 200 (SPA fallback) for missing
+    // files, and a dynamic import of a missing module logs an unsuppressible
+    // browser network error on every registry-less project.
+    const hasUiRegistry = await stat(join(projectRoot, 'src', 'ui', 'registry.ts')).then(
+      (s) => s.isFile(),
+      () => false,
+    );
+    // `packaged`: true iff this server is the no-monorepo-checkout runtime
+    // (`packages/editor/server/packaged.ts`) — same `isMonorepoScaffoldRoot`
+    // check the "New Project" packaged-mode guard already uses server-side
+    // (server-utils.ts). Client-side, `adapter-resolver.ts`'s react-world
+    // mount reads this to decide whether it must resolve its
+    // `react`/`react-dom/client`/`GameProvider` wrapper from the PROJECT's
+    // own module graph (packaged: the editor's prebuilt SPA bundles its OWN
+    // separate react copy, so a react world would dual-instance otherwise)
+    // or keep the existing static-import path (dev/electron: one shared Vite
+    // instance + root `vite.config.ts`'s `resolve.dedupe` already collapses
+    // them, so this flag is `false` there and that path stays unchanged).
+    const packaged = !isMonorepoScaffoldRoot(engineRoot);
+    res.json({ project: config ? { path: projectRoot, config, hasUiRegistry, packaged } : null });
+  });
+
+  // ---- SSE endpoint ----
+  router.get('/__editor/events', (req: Request, res: Response) => {
+    res.writeHead(200, {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache',
+      Connection: 'keep-alive',
+    });
+    res.write(':ok\n\n');
+    addClient(res);
+    req.on('close', () => removeClient(res));
+  });
+
+  // ---- Editor command relay ----
+  router.post('/__editor/command', (req: Request, res: Response) => {
+    const body = req.body as Record<string, unknown>;
+
+    // Fail fast when no editor browser tab holds a live SSE connection. Without
+    // this, the command silently waits the full COMMAND_TIMEOUT_MS before a
+    // generic timeout — and the caller can't tell "no editor open" from "editor
+    // open but the command hung". `clientCount()` is the live SSE-client count,
+    // so a 0 here is unambiguous: open the editor in a browser first.
+    if (clientCount() === 0) {
+      const { status, body: respBody } = commandResponseFor({
+        ok: false,
+        timedOut: true,
+        error: 'No editor connected — open the editor in a browser tab, then retry.',
+      });
+      res.status(status).json(respBody);
+      return;
+    }
+
+    // Assign a request ID so the browser can report the result back
+    const requestId = randomUUID();
+    const commandWithId = { ...body, _requestId: requestId };
+
+    // Create a promise that resolves when the browser reports the result.
+    // SC1: a timeout here means an editor IS connected but did not answer in
+    // time (the command hung or threw) — distinct from the no-editor case above.
+    const timeoutMs = body['type'] === 'play' ? PLAY_COMMAND_TIMEOUT_MS : COMMAND_TIMEOUT_MS;
+    const resultPromise = new Promise<CommandResult>((resolve) => {
+      const timer = setTimeout(() => {
+        pendingCommands.delete(requestId);
+        resolve({
+          ok: false,
+          timedOut: true,
+          error: 'Command timed out — editor connected but did not respond.',
+        });
+      }, timeoutMs);
+      pendingCommands.set(requestId, { resolve, timer });
+    });
+
+    broadcast('editor-command', commandWithId);
+
+    resultPromise.then((result) => {
+      const { status, body } = commandResponseFor(result);
+      res.status(status).json(body);
+    });
+  });
+
+  // ---- Editor command result (browser reports back) ----
+  router.post('/__editor/command-result', (req: Request, res: Response) => {
+    const body = req.body as {
+      _requestId: string;
+      ok: boolean;
+      error?: string;
+      data?: Record<string, unknown>;
+    };
+    const pending = pendingCommands.get(body._requestId);
+    if (pending) {
+      clearTimeout(pending.timer);
+      pendingCommands.delete(body._requestId);
+      pending.resolve(body);
+    }
+    res.json({ ok: true });
+  });
+
+  // ---- Editor state (browser reports / CLI reads) ----
+  router.get('/__editor/state', (_req: Request, res: Response) => {
+    // `editorState` is the last snapshot a browser POSTed; it persists even
+    // after every tab closes. Stamp the response with the LIVE SSE client count
+    // so callers can distinguish "an editor is attached now" from "this is stale
+    // cache from a tab that has since gone away".
+    const connected = clientCount();
+    res.json({ ...editorState, editorsConnected: connected, connected: connected > 0 });
+  });
+
+  router.post('/__editor/state', (req: Request, res: Response) => {
+    editorState = req.body as Record<string, unknown>;
+    res.json({ ok: true });
+  });
+
+  // ---- Asset listing ----
+  router.get('/__editor/assets', async (req: Request, res: Response) => {
+    const dir = (req.query['dir'] as string) ?? '';
+
+    if (dir.includes('..')) {
+      res.status(400).json({ error: 'Path traversal not allowed.' });
+      return;
+    }
+
+    const absRoot = resolve(projectRoot, 'public');
+    const absDir = join(absRoot, dir);
+
+    const rel = relative(absRoot, absDir);
+    if (rel.startsWith('..')) {
+      res.status(400).json({ error: 'Path outside root.' });
+      return;
+    }
+
+    try {
+      const dirents = await readdir(absDir, { withFileTypes: true });
+      const entries: AssetEntry[] = [];
+
+      for (const d of dirents) {
+        if (d.name.startsWith('.')) continue;
+        const entryPath = join(absDir, d.name);
+        if (d.isDirectory()) {
+          entries.push({ name: d.name, type: 'directory', size: 0 });
+        } else if (d.isFile()) {
+          const s = await stat(entryPath);
+          entries.push({ name: d.name, type: 'file', size: s.size });
+        }
+      }
+
+      entries.sort((a, b) => {
+        if (a.type !== b.type) return a.type === 'directory' ? -1 : 1;
+        return a.name.localeCompare(b.name);
+      });
+
+      res.json({ entries });
+    } catch (err: unknown) {
+      const code = (err as NodeJS.ErrnoException).code;
+      if (code === 'ENOENT' || code === 'ENOTDIR') {
+        res.status(404).json({ error: 'Directory not found.' });
+      } else {
+        res.status(500).json({ error: 'Internal server error.' });
+      }
+    }
+  });
+
+  // ---- Scene file listing (A4, D8) ----
+  // Recursive `*.vscn.json` listing under the project's `public/` — every
+  // scene file is a potential hierarchy root (D8 radio groups). NO user
+  // input is accepted (no query/body to derive a path from), so there is no
+  // traversal surface here at all — `findFiles` only ever walks DOWN from
+  // the fixed `publicRoot`.
+  router.get('/__editor/scenes', async (_req: Request, res: Response) => {
+    if (projectRoot === engineRoot) {
+      res.json({ scenes: [] });
+      return;
+    }
+    const files = await findFiles(publicRoot, '.vscn.json');
+    const scenes = files.map((f) => relative(publicRoot, f).split('\\').join('/')).sort();
+    res.json({ scenes });
+  });
+
+  // ---- Save file ----
+  router.post('/__editor/save-file', async (req: Request, res: Response) => {
+    const body = req.body as { path: string; content: string; encoding?: 'base64' };
+    const filePath = body.path ?? '';
+
+    if (!filePath || filePath.includes('..')) {
+      res.status(400).json({ error: 'Invalid path.' });
+      return;
+    }
+
+    const absPath = resolve(projectRoot, 'public', filePath);
+    if (!absPath.startsWith(publicRoot)) {
+      res.status(400).json({ error: 'Path outside public directory.' });
+      return;
+    }
+
+    try {
+      await mkdir(dirname(absPath), { recursive: true });
+      const data = body.encoding === 'base64' ? Buffer.from(body.content, 'base64') : body.content;
+      await writeFile(absPath, data, body.encoding === 'base64' ? undefined : 'utf-8');
+      res.json({ ok: true, path: filePath });
+    } catch {
+      res.status(500).json({ error: 'Failed to write file.' });
+    }
+  });
+
+  // ---- Download build artifact ----
+  router.get('/__editor/download', async (req: Request, res: Response) => {
+    const file = (req.query['file'] as string) ?? '';
+
+    if (!file || file.includes('..') || file.includes('/')) {
+      res.status(400).json({ error: 'Invalid file.' });
+      return;
+    }
+
+    // Build artifacts are produced in the engine repo, not the project dir
+    const absPath = resolve(engineRoot, file);
+    if (!absPath.startsWith(engineRoot)) {
+      res.status(400).json({ error: 'Path outside project.' });
+      return;
+    }
+
+    try {
+      const data = await readFile(absPath);
+      const s = await stat(absPath);
+      res.writeHead(200, {
+        'Content-Type': 'application/octet-stream',
+        // S7: strip control/quote chars from the user-supplied filename.
+        'Content-Disposition': `attachment; filename="${sanitizeContentDispositionFilename(file)}"`,
+        'Content-Length': s.size,
+      });
+      res.end(data);
+    } catch {
+      res.status(404).json({ error: 'File not found.' });
+    }
+  });
+
+  // ---- Export/build ----
+  router.post('/__editor/export', async (req: Request, res: Response) => {
+    if (activeBuild) {
+      res.status(409).json({ error: 'A build is already running.' });
+      return;
+    }
+
+    const body = req.body as { target: string };
+    const script = BUILD_SCRIPTS[body.target];
+    if (!script) {
+      res.status(400).json({ error: `Unknown target: ${body.target}` });
+      return;
+    }
+
+    res.writeHead(200, {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache',
+      Connection: 'keep-alive',
+    });
+    res.write(':ok\n\n');
+
+    // Build scripts live in the engine repo's package.json
+    const child = spawn('npm', ['run', script], {
+      cwd: engineRoot,
+      shell: true,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    activeBuild = child;
+
+    const sendLine = (line: string) => {
+      res.write(`event: log\ndata: ${JSON.stringify(line)}\n\n`);
+    };
+
+    let buffer = '';
+    const flushLines = (chunk: Buffer) => {
+      buffer += chunk.toString('utf-8');
+      const lines = buffer.split('\n');
+      buffer = lines.pop()!;
+      for (const line of lines) sendLine(line);
+    };
+
+    child.stdout!.on('data', flushLines);
+    child.stderr!.on('data', flushLines);
+
+    child.on('close', (code) => {
+      if (buffer) sendLine(buffer);
+      buffer = '';
+      activeBuild = null;
+      res.write(`event: done\ndata: ${JSON.stringify({ ok: code === 0, code })}\n\n`);
+      res.end();
+    });
+
+    req.on('close', () => {
+      if (activeBuild === child) {
+        child.kill();
+        activeBuild = null;
+      }
+    });
+  });
+
+  // ---- Recent projects ----
+  router.get('/__editor/recent-projects', async (_req: Request, res: Response) => {
+    const projects = await loadRecentProjects();
+    res.json({ projects });
+  });
+
+  // ---- Available `examples/<id>/` scaffold sources (Track E3, §1.F) ----
+  // Backs the "New Project" screen's optional "From example" picker — a
+  // best-effort convenience, not a critical path, so any failure (e.g. no
+  // examples/ dir at all in some deployment context) degrades to an empty
+  // list rather than a 500.
+  router.get('/__editor/examples', async (_req: Request, res: Response) => {
+    try {
+      const examplesDir = join(engineRoot, 'examples');
+      const dirents = await readdir(examplesDir, { withFileTypes: true });
+      const examples: Array<{ id: string; name: string }> = [];
+      for (const d of dirents) {
+        if (!d.isDirectory()) continue;
+        try {
+          const raw = await readFile(join(examplesDir, d.name, 'vgai.game.json'), 'utf-8');
+          const manifest = JSON.parse(raw) as { name?: string };
+          examples.push({ id: d.name, name: manifest.name ?? d.name });
+        } catch {}
+      }
+      res.json({ examples });
+    } catch {
+      res.json({ examples: [] });
+    }
+  });
+
+  // ---- Create project from template ----
+  router.post('/__editor/create-project', async (req: Request, res: Response) => {
+    // Phase B cleanup ITEM 2: packaged (no-monorepo) mode has no
+    // `<engineRoot>/packages/editor/template` to scaffold from — degrade
+    // loudly here, up front, instead of letting `scaffoldProject` crash
+    // confusingly partway through. See `isMonorepoScaffoldRoot`'s doc
+    // comment (server-utils.ts) for exactly what's missing and why.
+    if (!isMonorepoScaffoldRoot(engineRoot)) {
+      res.status(501).json({ error: PACKAGED_NO_MONOREPO_TEMPLATE_ERROR });
+      return;
+    }
+
+    const body = req.body as {
+      name: string;
+      location: string;
+      template: ScaffoldTemplate;
+      exampleId?: string;
+    };
+    const { name, location, template, exampleId } = body;
+
+    if (!name || !location) {
+      res.status(400).json({ error: 'Missing name or location.' });
+      return;
+    }
+
+    const slug = slugify(name);
+    if (!slug) {
+      res.status(400).json({ error: 'Invalid project name.' });
+      return;
+    }
+
+    // Expand ~ to home directory
+    const expandedLocation = location.startsWith('~/')
+      ? join(homedir(), location.slice(2))
+      : location;
+    const projectDir = resolve(expandedLocation, slug);
+
+    // Check if directory already exists
+    try {
+      await stat(projectDir);
+      res.status(409).json({ error: `Directory already exists: ${projectDir}` });
+      return;
+    } catch {
+      // Expected — directory doesn't exist yet
+    }
+
+    try {
+      // T3.6: shared scaffolder — packages/create-vgai-project/src/scaffold.ts.
+      // Same implementation `npx create-vgai-project` and `vgai create` use
+      // (copy template, rewrite @vgai/engine file: dep + tsconfig @engine/*
+      // paths/files array + vite alias + index.html title + project.json).
+      const result = scaffoldProject({
+        name,
+        targetDir: projectDir,
+        template,
+        monoRoot: engineRoot,
+        ...(exampleId !== undefined ? { exampleId } : {}),
+      });
+
+      // Ensure .vgai/ directory exists
+      await mkdir(join(projectDir, '.vgai'), { recursive: true });
+
+      // Add to recent projects
+      await addToRecentProjects(name, projectDir);
+
+      res.json({ ok: true, path: result.targetDir, config: result.projectConfig });
+    } catch (err) {
+      res.status(500).json({ error: `Failed to create project: ${err}` });
+    }
+  });
+
+  // ---- Native folder dialog ----
+  router.post('/__editor/browse-folder', async (req: Request, res: Response) => {
+    const body = req.body as { title?: string };
+    const title = body.title ?? 'Select Folder';
+    const os = platform();
+
+    try {
+      let selectedPath: string | null = null;
+
+      if (os === 'darwin') {
+        // macOS: use osascript to open a native folder dialog
+        const result = await new Promise<string>((ok, fail) => {
+          execFile(
+            'osascript',
+            [
+              '-e',
+              // S4: escape backslashes BEFORE quotes (and strip control chars)
+              // so the title can't break out of the AppleScript string literal.
+              `set theFolder to choose folder with prompt "${escapeAppleScriptString(title)}"`,
+              '-e',
+              'return POSIX path of theFolder',
+            ],
+            (err, stdout) => {
+              if (err) fail(err);
+              else ok(stdout.trim());
+            },
+          );
+        });
+        if (result) selectedPath = result.replace(/\/$/, ''); // strip trailing slash
+      } else if (os === 'linux') {
+        // Linux: try zenity, fall back to kdialog
+        const result = await new Promise<string>((ok, fail) => {
+          execFile(
+            'zenity',
+            ['--file-selection', '--directory', `--title=${title}`],
+            (err, stdout) => {
+              if (err) {
+                // Try kdialog as fallback
+                execFile(
+                  'kdialog',
+                  ['--getexistingdirectory', homedir(), '--title', title],
+                  (err2, stdout2) => {
+                    if (err2) fail(err2);
+                    else ok(stdout2.trim());
+                  },
+                );
+              } else {
+                ok(stdout.trim());
+              }
+            },
+          );
+        });
+        if (result) selectedPath = result;
+      }
+
+      res.json({ path: selectedPath });
+    } catch {
+      // User cancelled the dialog or no dialog tool available
+      res.json({ path: null });
+    }
+  });
+
+  // ---- Reveal in file manager ----
+  router.post('/__editor/reveal', (req: Request, res: Response) => {
+    const body = req.body as { path: string };
+    const targetPath = body.path;
+    if (!targetPath) {
+      res.status(400).json({ error: 'Missing path.' });
+      return;
+    }
+
+    const os = platform();
+    if (os === 'darwin') {
+      spawn('open', ['-R', targetPath], { stdio: 'ignore', detached: true }).unref();
+    } else if (os === 'linux') {
+      spawn('xdg-open', [dirname(targetPath)], { stdio: 'ignore', detached: true }).unref();
+    } else if (os === 'win32') {
+      spawn('explorer', ['/select,', targetPath], { stdio: 'ignore', detached: true }).unref();
+    }
+    res.json({ ok: true });
+  });
+
+  // ---- Save project thumbnail ----
+  router.post('/__editor/save-thumbnail', async (req: Request, res: Response) => {
+    const body = req.body as { dataUrl: string };
+    if (!body.dataUrl || projectRoot === engineRoot) {
+      res.status(400).json({ error: 'No project open or missing data.' });
+      return;
+    }
+
+    try {
+      // Save thumbnail as .vgai/thumbnail.png in project root
+      const base64Data = body.dataUrl.replace(/^data:image\/\w+;base64,/, '');
+      const vgaiDir = join(projectRoot, '.vgai');
+      await mkdir(vgaiDir, { recursive: true });
+      const thumbnailPath = join(vgaiDir, 'thumbnail.png');
+      await writeFile(thumbnailPath, Buffer.from(base64Data, 'base64'));
+
+      // Update recent projects entry with thumbnail path
+      const projects = await loadRecentProjects();
+      const entry = projects.find((p) => p.path === projectRoot);
+      if (entry) {
+        entry.thumbnail = `/__editor/project-thumbnail?path=${encodeURIComponent(projectRoot)}`;
+        await saveRecentProjects(projects);
+      }
+
+      res.json({ ok: true });
+    } catch {
+      res.status(500).json({ error: 'Failed to save thumbnail.' });
+    }
+  });
+
+  // ---- Serve project thumbnail ----
+  router.get('/__editor/project-thumbnail', async (req: Request, res: Response) => {
+    const targetPath = (req.query['path'] as string) ?? '';
+    if (!targetPath) {
+      res.status(400).json({ error: 'Missing path.' });
+      return;
+    }
+
+    const thumbnailPath = join(resolve(targetPath), '.vgai', 'thumbnail.png');
+    try {
+      const data = await readFile(thumbnailPath);
+      res.writeHead(200, { 'Content-Type': 'image/png', 'Cache-Control': 'max-age=60' });
+      res.end(data);
+    } catch {
+      res.status(404).end();
+    }
+  });
+
+  // ---- Open project (runtime switching) ----
+  router.post('/__editor/open-project', async (req: Request, res: Response) => {
+    const body = req.body as { path: string };
+    const newPath = body.path;
+
+    if (!newPath) {
+      res.status(400).json({ error: 'Missing path.' });
+      return;
+    }
+
+    // Canonicalized (symlink-resolved), not a plain `resolve` — see
+    // canonical-path.ts's doc comment (T6.2 slice 3 finding: a react world's
+    // `GameProvider` colocation breaks if this path and Vite's own resolver
+    // disagree on a symlinked segment).
+    const absPath = canonicalProjectRoot(newPath);
+
+    // Read project.json (or synthesize from vgai.game.json — §1C); accepts a
+    // manifest-only folder with no project.json.
+    const config = await readProjectView(absPath);
+    if (!config) {
+      res.status(400).json({ error: `No vgai.game.json or project.json at ${absPath}` });
+      return;
+    }
+
+    // Update mutable state
+    projectRoot = absPath;
+    publicRoot = resolve(absPath, 'public');
+
+    // Clear stale editor state from previous project
+    editorState = {};
+
+    // Ensure .vgai/ directory exists
+    await mkdir(join(absPath, '.vgai'), { recursive: true });
+
+    // Restart file watcher on new project
+    startWatcher();
+
+    // Allow Vite to serve /@fs/ paths from the project directory
+    options.onProjectOpened?.(absPath);
+
+    // Track in recent projects
+    await addToRecentProjects((config['name'] as string) ?? 'Untitled', absPath);
+
+    // Notify all connected editors
+    broadcast('project-changed', { path: absPath, config });
+
+    res.json({ ok: true, config });
+  });
+
+  // ---- /@fs/ script serving (production only) ----
+  // In dev mode, Vite's middleware handles /@fs/ paths with full HMR support.
+  // In production, this middleware provides the same capability: it reads files
+  // from disk, transpiles TypeScript via esbuild, and rewrites @engine/ imports
+  // so the browser's ES module loader can follow the dependency chain.
+  if (options.serveScripts) {
+    /** Resolve a module path, trying common extensions and index files. */
+    async function resolveFile(fsPath: string): Promise<string | null> {
+      const extensions = ['.ts', '.tsx', '.js', '.jsx'];
+      // Exact path
+      try {
+        const s = await stat(fsPath);
+        if (s.isFile()) return fsPath;
+        if (s.isDirectory()) {
+          for (const ext of extensions) {
+            try {
+              const idx = join(fsPath, `index${ext}`);
+              if ((await stat(idx)).isFile()) return idx;
+            } catch {
+              /* continue */
+            }
+          }
+        }
+      } catch {
+        /* continue */
+      }
+      // Try appending extensions
+      for (const ext of extensions) {
+        try {
+          const withExt = fsPath + ext;
+          if ((await stat(withExt)).isFile()) return withExt;
+        } catch {
+          /* continue */
+        }
+      }
+      return null;
+    }
+
+    router.use('/@fs', async (req: Request, res: Response, next) => {
+      // req.path is the portion after /@fs, e.g. /Users/foo/project/src/main.ts
+      const absPath = resolve(req.path);
+
+      // S5: containment with a trailing separator so a sibling directory whose
+      // name merely shares a prefix (e.g. `<root>-secrets`) cannot pass.
+      if (!isPathInside(projectRoot, absPath) && !isPathInside(engineRoot, absPath)) {
+        res.status(403).json({ error: 'Path not allowed.' });
+        return;
+      }
+
+      const filePath = await resolveFile(absPath);
+      if (!filePath) return next();
+
+      const ext = filePath.split('.').pop() ?? '';
+
+      // S5: only serve source/asset file types — never .env, keys, etc.
+      if (!isServableFsExtension(ext)) {
+        res.status(403).json({ error: 'File type not allowed.' });
+        return;
+      }
+
+      // B1b (packaging plan §3(b)1): rewrite `@engine/` to whatever the
+      // CURRENTLY OPEN project has actually installed as `@vgai/engine`
+      // (Node resolution rooted at `projectRoot`, re-read per request since
+      // `projectRoot` can change live via /__editor/open-project) — never a
+      // copy baked into wherever this server process's own code lives. Falls
+      // back to the checkout-relative `packages/engine/src` when no project
+      // is open or the project predates Phase B (no `@vgai/engine`
+      // dependency installed yet) — this is what keeps in-repo dev/Electron
+      // (prod.ts, no project-local install) working unchanged.
+      const engineSrc =
+        resolveInstalledPackageSrcDir(projectRoot, '@vgai/engine') ??
+        resolve(engineRoot, 'packages/engine/src');
+
+      if (['ts', 'tsx', 'jsx'].includes(ext)) {
+        try {
+          const { transform } = await import('esbuild');
+          const content = await readFile(filePath, 'utf-8');
+          const result = await transform(content, {
+            loader: ext as 'ts' | 'tsx' | 'jsx',
+            format: 'esm',
+            sourcemap: 'inline',
+            target: 'es2022',
+          });
+          // Rewrite @engine/ bare imports to /@fs/ absolute paths
+          const code = result.code.replace(
+            /(from\s+['"]|import\s*\(\s*['"])@engine\//g,
+            `$1/@fs/${engineSrc}/`,
+          );
+          res.setHeader('Content-Type', 'application/javascript');
+          res.send(code);
+        } catch (err) {
+          res.status(500).json({ error: `Transform failed: ${err}` });
+        }
+      } else if (ext === 'js' || ext === 'mjs') {
+        try {
+          const content = await readFile(filePath, 'utf-8');
+          // Rewrite @engine/ imports even in plain JS files
+          const code = content.replace(
+            /(from\s+['"]|import\s*\(\s*['"])@engine\//g,
+            `$1/@fs/${engineSrc}/`,
+          );
+          res.setHeader('Content-Type', 'application/javascript');
+          res.send(code);
+        } catch {
+          next();
+        }
+      } else {
+        // Other files (JSON, WASM, etc.) — serve as-is
+        try {
+          const data = await readFile(filePath);
+          res.setHeader('Content-Type', mimeTypes[ext] ?? 'application/octet-stream');
+          res.send(data);
+        } catch {
+          next();
+        }
+      }
+    });
+  }
+
+  // ---- Persistent editor state (.vgai/editor-state.json) ----
+  router.get('/__editor/editor-state', async (_req: Request, res: Response) => {
+    if (projectRoot === engineRoot) {
+      res.json({});
+      return;
+    }
+    try {
+      const raw = await readFile(join(projectRoot, '.vgai', 'editor-state.json'), 'utf-8');
+      res.json(JSON.parse(raw));
+    } catch {
+      res.json({});
+    }
+  });
+
+  router.post('/__editor/editor-state', async (req: Request, res: Response) => {
+    if (projectRoot === engineRoot) {
+      res.status(400).json({ error: 'No project open.' });
+      return;
+    }
+    try {
+      const vgaiDir = join(projectRoot, '.vgai');
+      await mkdir(vgaiDir, { recursive: true });
+      await writeFile(
+        join(vgaiDir, 'editor-state.json'),
+        JSON.stringify(req.body, null, 2),
+        'utf-8',
+      );
+      res.json({ ok: true });
+    } catch {
+      res.status(500).json({ error: 'Failed to save editor state.' });
+    }
+  });
+
+  // ---- Project-root `.vgai/` file access (T6.1 slice 3 overlay unification) ----
+  //
+  // The editor-state/thumbnail routes above already read/write
+  // `<projectRoot>/.vgai/...` directly via `node:fs` — but `StorageBackend`
+  // (`HttpStorage`/`/__editor/save-file` above) is hard-rooted at
+  // `<projectRoot>/public/`, so a `.vgai/overlays/<id>.json` written through
+  // that seam actually lands at `<projectRoot>/public/.vgai/overlays/<id>.json`
+  // (the two-`.vgai`-dirs finding recorded in BACKBONE-TASKS T3.3 close-out).
+  // This route pair is the fix: project-root-relative, scoped to `.vgai/` only
+  // (defense in depth — it is not a general project-file API), mirroring the
+  // editor-state route's mkdir-on-write / read-or-empty shape. Manifest-era
+  // world overlays (docs/MULTI-WORLD-DESIGN.md §1.G, `authoring/world-overlay.ts`)
+  // unified on this seam first; `authoring/ingest-overlay.ts`'s `loadOverlay`/
+  // `saveOverlay` (the T3.3 close-out remediation) now use it too, in server
+  // mode — every overlay, ingest-game or manifest-world, lands under this ONE
+  // project-root `.vgai/` namespace.
+  router.get('/__editor/vgai-file', async (req: Request, res: Response) => {
+    const relPath = (req.query['path'] as string) ?? '';
+    if (!relPath || relPath.includes('..') || !relPath.startsWith('.vgai/')) {
+      res.status(400).json({ error: 'Invalid path.' });
+      return;
+    }
+    if (projectRoot === engineRoot) {
+      res.status(404).json({ error: 'No project open.' });
+      return;
+    }
+    try {
+      const raw = await readFile(join(projectRoot, relPath), 'utf-8');
+      res.type('text/plain').send(raw);
+    } catch {
+      res.status(404).json({ error: 'Not found.' });
+    }
+  });
+
+  router.post('/__editor/vgai-file', async (req: Request, res: Response) => {
+    const body = req.body as { path?: string; content?: string };
+    const relPath = body.path ?? '';
+    if (!relPath || relPath.includes('..') || !relPath.startsWith('.vgai/')) {
+      res.status(400).json({ error: 'Invalid path.' });
+      return;
+    }
+    if (projectRoot === engineRoot) {
+      res.status(400).json({ error: 'No project open.' });
+      return;
+    }
+    try {
+      const absPath = join(projectRoot, relPath);
+      await mkdir(dirname(absPath), { recursive: true });
+      await writeFile(absPath, body.content ?? '', 'utf-8');
+      res.json({ ok: true });
+    } catch {
+      res.status(500).json({ error: 'Failed to write file.' });
+    }
+  });
+
+  // ---- Data assets (W2, docs/DATA-TOOLS-DESIGN.md §2.4/§2.5) ----
+  //
+  // The Data dock tab's server half. Discovery is the folder scan, per D3 (no
+  // asset database): every `src/data/*.data.json` of the open project, plus
+  // the sibling EMITTED `*.schema.json` when present — the editor consumes the
+  // JSON Schema interchange artifact and never executes the project's
+  // `.schema.ts` (§2.1). Raw file text is returned (not parsed JSON) so the
+  // client owns parse errors and can report a malformed file instead of this
+  // route 500ing on it.
+  //
+  // Why not `/__editor/save-file` + `/@fs/` reads: that seam is HARD-ROOTED at
+  // `<projectRoot>/public/` (see `HttpStorage`'s doc comment and the
+  // two-`.vgai`-dirs finding above) — data assets live under the project
+  // root's `src/data/`, outside its reach. Same fix as the `vgai-file` pair:
+  // a purpose-scoped route rooted at the project root, deliberately NOT a
+  // general project-file API (defense in depth — the write half accepts only
+  // `src/data/**/*.data.json`).
+  router.get('/__editor/data-files', async (_req: Request, res: Response) => {
+    if (projectRoot === engineRoot) {
+      res.json({ files: [] });
+      return;
+    }
+    const dataDir = join(projectRoot, 'src', 'data');
+    const found = await findFiles(dataDir, '.data.json');
+    const files: Array<{ path: string; content: string; schema: string | null }> = [];
+    for (const abs of found.sort()) {
+      let content: string;
+      try {
+        content = await readFile(abs, 'utf-8');
+      } catch {
+        continue; // deleted between scan and read — just omit it
+      }
+      // Sibling emitted schema (D4: generated + committed by default). Absent
+      // (project hasn't run `npm run emit-schemas`) → null; the client shows
+      // a teaching message rather than guessing widget types.
+      let schema: string | null = null;
+      try {
+        schema = await readFile(abs.replace(/\.data\.json$/, '.schema.json'), 'utf-8');
+      } catch {
+        /* no emitted schema */
+      }
+      files.push({ path: relative(projectRoot, abs).split('\\').join('/'), content, schema });
+    }
+    res.json({ files });
+  });
+
+  // D1 (spec §2.5): a Data-panel edit writes the `.data.json` IMMEDIATELY —
+  // game-is-the-document; undo is git. D5 RESOLVED here as the spec
+  // recommends: data writes are plain file writes and deliberately BYPASS the
+  // play-mode overlay regime entirely (the overlay is scene-entity-only —
+  // `.vgai/overlays/*` via `world-overlay.ts`/`ingest-overlay.ts`; nothing in
+  // that path ever touches `src/data/`). A running game picks the write up
+  // through the already-shipped HMR path (`dev.ts`'s `.data.json` exemption →
+  // the owning module's `import.meta.hot.accept` → `DataHandle.hotSwap`).
+  router.post('/__editor/data-file', async (req: Request, res: Response) => {
+    const body = req.body as { path?: string; content?: string };
+    const relPath = body.path ?? '';
+    if (
+      !relPath ||
+      relPath.includes('..') ||
+      !relPath.startsWith('src/data/') ||
+      !relPath.endsWith('.data.json')
+    ) {
+      res.status(400).json({ error: 'Invalid path — expected src/data/**/*.data.json.' });
+      return;
+    }
+    if (projectRoot === engineRoot) {
+      res.status(400).json({ error: 'No project open.' });
+      return;
+    }
+    if (typeof body.content !== 'string') {
+      res.status(400).json({ error: 'Missing content.' });
+      return;
+    }
+    // Fail loud on non-JSON before touching disk — a malformed write would
+    // wedge every consumer of the file (parse-on-load is the runtime contract,
+    // §2.3) and there is no buffering layer to catch it (D1).
+    try {
+      JSON.parse(body.content);
+    } catch {
+      res.status(400).json({ error: 'Content is not valid JSON.' });
+      return;
+    }
+    try {
+      const absPath = join(projectRoot, relPath);
+      await writeFile(absPath, body.content, 'utf-8');
+      res.json({ ok: true, path: relPath });
+    } catch {
+      res.status(500).json({ error: 'Failed to write file.' });
+    }
+  });
+
+  // ---- 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('/'),
+      })),
+    });
+  });
+
+  // ---- Manifest write (A4, D8 — the ONE manifest-write verb) ----
+  // Unlike every other write route above, this one HARD-CODES its
+  // destination: `join(projectRoot, 'vgai.game.json')`, NEVER derived from
+  // `req.body`. `validateManifestWrite` (server-utils.ts, unit-tested there)
+  // rejects anything else (a different filename, a traversal path, a
+  // non-string/non-JSON body) before this handler ever touches the
+  // filesystem — see `server-security.test.ts` for the rejection matrix.
+  router.post('/__editor/manifest', async (req: Request, res: Response) => {
+    const body = req.body as { path?: unknown; content?: unknown };
+    const result = validateManifestWrite(projectRoot, engineRoot, body);
+    if (!result.ok) {
+      res.status(result.status).json({ error: result.error });
+      return;
+    }
+    try {
+      const absPath = join(projectRoot, 'vgai.game.json');
+      await writeFile(absPath, result.content, 'utf-8');
+      res.json({ ok: true });
+    } catch {
+      res.status(500).json({ error: 'Failed to write manifest.' });
+    }
+  });
+
+  // ---- Play-mode console log persistence ----
+  const MAX_LOG_FILES = 20;
+  let activeLogFile: string | null = null;
+
+  router.post('/__editor/log-session', async (req: Request, res: Response) => {
+    const body = req.body as { action: 'start' | 'end' };
+
+    if (body.action === 'start') {
+      const logsDir = join(projectRoot, 'logs');
+      await mkdir(logsDir, { recursive: true });
+
+      // Prune old log files beyond MAX_LOG_FILES
+      try {
+        const files = (await readdir(logsDir))
+          .filter((f) => f.startsWith('play-') && f.endsWith('.jsonl'))
+          .sort();
+        const toRemove = files.slice(0, Math.max(0, files.length - MAX_LOG_FILES + 1));
+        for (const f of toRemove) {
+          await unlink(join(logsDir, f)).catch(() => {});
+        }
+      } catch {
+        /* logs dir may not exist yet */
+      }
+
+      const now = new Date();
+      const ts = now.toISOString().replace(/[:.]/g, '-').slice(0, 19);
+      const filename = `play-${ts}.jsonl`;
+      activeLogFile = join(logsDir, filename);
+      res.json({ ok: true, file: filename });
+    } else {
+      activeLogFile = null;
+      res.json({ ok: true });
+    }
+  });
+
+  router.get('/__editor/log-entries', async (_req: Request, res: Response) => {
+    if (!activeLogFile) {
+      res.json({ entries: [] });
+      return;
+    }
+    try {
+      const raw = await readFile(activeLogFile, 'utf-8');
+      const entries = raw
+        .trim()
+        .split('\n')
+        .filter(Boolean)
+        .map((line) => JSON.parse(line));
+      res.json({ entries });
+    } catch {
+      res.json({ entries: [] });
+    }
+  });
+
+  router.post('/__editor/log-entries', async (req: Request, res: Response) => {
+    if (!activeLogFile) {
+      res.status(409).json({ error: 'No active log session.' });
+      return;
+    }
+    const body = req.body as {
+      entries: Array<{
+        t: number;
+        level: string;
+        source?: string;
+        sub?: string;
+        msg: string;
+        meta?: Record<string, unknown>;
+      }>;
+    };
+    const lines = body.entries.map((e) => JSON.stringify(e)).join('\n') + '\n';
+    await appendFile(activeLogFile, lines, 'utf-8');
+    res.json({ ok: true });
+  });
+
+  return router;
+}