@vgai/editor 0.2.0

package/server/project-optimize-deps-entries.ts

@@ -0,0 +1,149 @@
+// C3 (phase-b/c3-r3f-packaged) — the adaptive `optimizeDeps.entries` source
+// for `packaged.ts`'s project-rooted Vite instance. See that file's header
+// doc comment, "optimizeDeps" section, for the full crawl-vs-crash story;
+// this module only computes WHICH files to scope the crawl to.
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { loadGameManifestFile } from '../../engine/src/manifest/load-file';
+
+/**
+ * SERVER-ONLY packages that must never be crawled INTO during the client
+ * dep-prebundle — passed to `optimizeDeps.exclude` in `packaged.ts` (C3
+ * hardening follow-on). Belt to the entries-scoping suspenders.
+ *
+ * ## The pathological case this closes
+ *
+ * The entries-scoping fix (`computeProjectOptimizeDepsEntries` below) makes
+ * the crawl start ONLY from a project's declared world entries — which
+ * NORMALLY never reach `server/` code, so the colyseus server stack
+ * (`colyseus` -> `@colyseus/core` -> `@pm2/io`) is never crawled and the
+ * esbuild-scanner crash that `noDiscovery: true` used to guard against never
+ * fires. But if a project VIOLATES the repo's D2 rule (CLAUDE.md
+ * "Networking": client code calls Colyseus via the CLIENT SDK
+ * `@colyseus/sdk`, dynamic-imported, and NEVER value-imports the `server/`
+ * room classes) by having a WORLD ENTRY statically `import` from `server/`,
+ * the crawl reaches `@colyseus/core`'s `Stats.mjs`, whose `import("@pm2/io")`
+ * has no resolvable browser entry, and esbuild's prebundle step THROWS from
+ * inside the async optimizer — which, unhandled, HARD-KILLS the whole
+ * packaged node process (the only authoring surface). That is a strictly
+ * harsher degrade than the old `noDiscovery: true`, which at least still
+ * booted an editor.
+ *
+ * `exclude`-ing these three names keeps esbuild from crawling into them
+ * during prebundle: even a world entry that (wrongly) reaches them no longer
+ * crashes the scanner — the offending world degrades to a benign browser-
+ * side runtime import failure for that ONE world, and the editor process
+ * survives and serves everything else. Verified live (a real, checkout-
+ * absent packaged boot against a project whose world entry value-imports
+ * `server/rooms`): without this list the server process dies at boot; with
+ * it, the server boots and serves.
+ *
+ * CRITICAL: this list must NOT contain `@colyseus/sdk` — that is the
+ * legitimate CLIENT SDK a real multiplayer project's own game code imports
+ * (dynamic-imported per D2; e.g. `examples/third-person-arena/src/
+ * network.ts`). It is a SEPARATE package from `@colyseus/core` — its own
+ * published `build/index.mjs` is a self-contained client bundle — and MUST
+ * still prebundle so those projects work. Excluding only the server-side
+ * names leaves the client SDK's prebundle path untouched (proven: a world
+ * entry importing `@colyseus/sdk` still prebundles it cleanly with this
+ * exclude list active).
+ */
+export const SERVER_ONLY_PREBUNDLE_EXCLUDE: readonly string[] = [
+  'colyseus',
+  '@colyseus/core',
+  '@pm2/io',
+];
+
+/**
+ * The project-relative CLIENT entry files `optimizeDeps.entries` should scope
+ * Vite's dependency-DISCOVERY crawl to, for the project rooted at
+ * `projectRoot` — every `worlds[].entry` its OWN `vgai.game.json` declares
+ * (default-adapter, code-authored worlds; scene-only worlds have no `entry`
+ * and contribute nothing here — their gameplay code is registered
+ * elsewhere, reached transitively from whichever world DOES declare an
+ * `entry`, e.g. the template's single world), deduped, and filtered to paths
+ * that exist on disk.
+ *
+ * ## Why THESE files, not `index.html` or the project's own bootstrap `main.ts`
+ *
+ * A project's `index.html` -> `src/main.ts` bootstrap ties every declared
+ * world together for the STANDALONE (`npm run game`) build, and — critically
+ * — the scaffolded template's own `main.ts` also carries the P2P-Colyseus
+ * URL-param branch that dynamically imports the project's OWN `server/rooms`
+ * (`await import('../server/rooms')`, gated behind `?net=p2p-host`, but
+ * esbuild's dependency scanner follows a string-literal dynamic `import()`
+ * as an unconditional graph edge regardless of the runtime guard around it).
+ * `server/rooms.ts` re-exports real Colyseus `Room` classes, whose `colyseus`
+ * (SERVER package) import chain reaches `@colyseus/core` -> `@pm2/io`, a
+ * package esbuild's prebundle step cannot resolve an entry for (confirmed
+ * empirically, not theoretically: a direct `vite.optimizeDeps` run scoped to
+ * `index.html`-style discovery against `packages/editor/template` throws
+ * `Failed to resolve entry for package "@pm2/io"` from inside
+ * `@colyseus/core/build/Stats.mjs`'s own `import("@pm2/io")` — this is
+ * `packaged.ts`'s ORIGINAL reason for `noDiscovery: true`, verified still
+ * true on this Vite version at the time of the C3 fix).
+ *
+ * A manifest's `worlds[].entry` files never reach that chain: they are the
+ * PER-WORLD mount code the editor's own adapter-resolver dynamically imports
+ * directly for Play mode / world mounting (never `src/main.ts` — that
+ * bootstrap is the STANDALONE build's concern, unrelated to how the editor
+ * itself mounts a world; see `packaged.ts`'s header doc comment). Scoping the
+ * crawl to exactly these files means: (a) it never touches `server/`, so the
+ * `@pm2/io` class of crash cannot occur no matter what a project's server
+ * room code imports, and (b) any CJS-needing-prebundle client dependency a
+ * world's own code reaches — `react`, `@react-three/fiber`, `@react-three/
+ * drei`, or some future ecosystem this repo has never heard of — gets
+ * auto-discovered and prebundled for free, with no per-package allowlist to
+ * maintain (this is what actually fixes the R3F class of bug this file's own
+ * feature exists for: `@react-three/fiber`'s CJS transitive deps like
+ * `use-sync-external-store` are reached from `examples/r3f-probe`'s
+ * `src/net-entry.tsx`, never from anything server-shaped).
+ *
+ * The client SDK case (`@colyseus/sdk`, the package a world's own game code
+ * legitimately imports for real multiplayer — e.g.
+ * `examples/third-person-arena/src/network.ts`) is DIFFERENT from the
+ * server-package case above and does NOT crash: `@colyseus/sdk`'s own
+ * published build (`build/index.mjs`) is a self-contained client bundle that
+ * does not pull in `@colyseus/core`'s server-only `Stats.mjs` (confirmed
+ * empirically the same way: a full prebundle scoped to
+ * `examples/third-person-arena`'s own `src/index.tsx` world entry succeeds
+ * and prebundles `@colyseus/sdk` cleanly).
+ *
+ * ## Known scope trim
+ *
+ * Computed ONCE, from the boot-time `VGAI_PROJECT`, exactly like this file's
+ * sibling `engineSrc`/`resolve.alias` resolution in `packaged.ts` — NOT
+ * re-computed when `onProjectOpened` switches to a different project mid-
+ * session (a pre-existing limitation of that callback: it only extends
+ * `fs.allow`/the watcher/the game-globals shadow, never anything that was
+ * baked into the Vite instance's `createServer` call, like `resolve.alias`
+ * already wasn't either). A switched-to project keeps whatever entries the
+ * ORIGINALLY opened project computed.
+ *
+ * Never throws: an absent/unparseable manifest (no project open yet, a
+ * pre-Phase-B project, a broken `vgai.game.json`) degrades to `[]` — the
+ * SAFEST fallback, not a guess. Per Vite's own `optimizeDeps.entries`
+ * resolution (`computeEntries` in vite's dep-scanner), a truthy-but-empty
+ * array short-circuits the `**\/*.html` crawl fallback WITHOUT crawling
+ * anything itself, so an unreadable manifest degrades to "no auto-discovery
+ * beyond the static `include` list" — the same conservative posture
+ * `noDiscovery: true` had, rather than falling back to a full crawl that
+ * could reach server code we know nothing about.
+ */
+export function computeProjectOptimizeDepsEntries(projectRoot: string): string[] {
+  let manifest: ReturnType<typeof loadGameManifestFile>;
+  try {
+    manifest = loadGameManifestFile(join(projectRoot, 'vgai.game.json'));
+  } catch {
+    return [];
+  }
+
+  const entries = new Set<string>();
+  for (const world of manifest.worlds) {
+    if (!world.entry) continue;
+    if (!existsSync(join(projectRoot, world.entry))) continue;
+    entries.add(world.entry);
+  }
+  return [...entries];
+}

package/server/project-view.ts

@@ -0,0 +1,65 @@
+// T3.3 slice 1 — server-side compat-view synthesis for `project.json` reads
+// (docs/CLI-ON-FOLDER-DESIGN.md §1C).
+//
+// A project folder's config view can come from two places: `project.json`
+// itself (legacy, still authoritative when present — including fields like
+// `appId` that have no manifest home) or, when that file is ABSENT, a
+// synthesized `{ name, defaultScene }` view derived from `vgai.game.json`
+// (`name` from the manifest; `defaultScene` from the first world's `scene`,
+// explicitly `null` if that world has none — e.g. an `entry`-based or ingest
+// world — NEVER omitted: a consumer that saw the key simply missing collapsed
+// "not declared" into "guess a path" via `?? 'scenes/default.vscn.json'`,
+// which is what caused `initial-scene.ts` to silently WRITE a placeholder
+// scene for a legal entry-only first world — §7.1-12 / R2b fix 1. `null` is
+// the explicit, typed "no scene declared" the consumer is forced to branch
+// on instead of defaulting through.
+//
+// This is the ONE place the project.json/manifest fallback rule lives —
+// every server route that reads project config goes through `readProjectView`
+// rather than re-implementing the fallback (editor-server.ts's static
+// `/project.json` serve, `GET /__editor/project`, `POST /__editor/open-project`'s
+// existence check, and the recent-projects existence check all call this).
+
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { loadGameManifestFile } from '../../engine/src/manifest/load-file';
+
+export type ProjectView = Record<string, unknown>;
+
+/**
+ * Read the compat project view for `root`.
+ *
+ * - `project.json` present -> its parsed contents verbatim (whatever fields
+ *   it has, including `appId`).
+ * - `project.json` absent, `vgai.game.json` present -> synthesized
+ *   `{ name, defaultScene }`, where `defaultScene` is the first world's
+ *   `scene` if declared, else explicit `null` (never omitted — appId is
+ *   omitted, though: it has no manifest home and nothing reads it per
+ *   docs/CLI-ON-FOLDER-DESIGN.md §1C).
+ * - Neither present, or the manifest exists but fails to parse -> `null`.
+ *   (The hard fail-loud-on-a-broken-manifest behavior lives at the CLI
+ *   discovery gate, `packages/vgai-cli/src/discovery.ts` — a server route
+ *   reading a broken manifest degrades to "no project" rather than crashing
+ *   the request.)
+ */
+export async function readProjectView(root: string): Promise<ProjectView | null> {
+  try {
+    const raw = await readFile(join(root, 'project.json'), 'utf-8');
+    return JSON.parse(raw) as ProjectView;
+  } catch {
+    // project.json absent/unreadable — fall through to the manifest.
+  }
+
+  try {
+    const manifest = loadGameManifestFile(join(root, 'vgai.game.json'));
+    const firstWorld = manifest.worlds[0];
+    // Always set the key — explicit `null`, not an omitted property, when the
+    // first world declares no scene (e.g. `entry`-only). See the module doc
+    // comment above: an omitted key is what let a naive `?? 'scenes/
+    // default.vscn.json'` consumer silently guess a path.
+    const view: ProjectView = { name: manifest.name, defaultScene: firstWorld?.scene ?? null };
+    return view;
+  } catch {
+    return null;
+  }
+}

package/server/server-utils.ts

@@ -0,0 +1,430 @@
+/**
+ * Pure, dependency-light helpers for the editor server.
+ *
+ * Everything here is side-effect free and unit-testable (see
+ * packages/editor/test/server-security.test.ts). The route handlers in
+ * editor-server.ts / asset-library-routes.ts delegate their security and
+ * correctness checks to these functions so the logic can be verified in
+ * isolation.
+ */
+
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join, resolve, sep } from 'node:path';
+
+// ---------------------------------------------------------------------------
+// Path containment (S1 / S5 / S6)
+// ---------------------------------------------------------------------------
+
+/**
+ * True if `child` resolves to the same path as `parent`, or to a path strictly
+ * inside it. Defends against `..` traversal and sibling-prefix attacks where a
+ * naive `startsWith` would accept `/a/public-secrets` as inside `/a/public`.
+ */
+export function isPathInside(parent: string, child: string): boolean {
+  const resolvedParent = resolve(parent);
+  const resolvedChild = resolve(child);
+  if (resolvedChild === resolvedParent) return true;
+  const parentWithSep = resolvedParent.endsWith(sep) ? resolvedParent : resolvedParent + sep;
+  return resolvedChild.startsWith(parentWithSep);
+}
+
+// ---------------------------------------------------------------------------
+// Asset source + host allowlists (S1 / S2)
+// ---------------------------------------------------------------------------
+
+export const ALLOWED_ASSET_SOURCES = ['polyhaven', 'ambientcg', 'local'] as const;
+export type AllowedAssetSource = (typeof ALLOWED_ASSET_SOURCES)[number];
+
+/** Allowlist the `source` segment so it can never escape the library directory. */
+export function isAllowedAssetSource(source: unknown): source is AllowedAssetSource {
+  return (
+    typeof source === 'string' && (ALLOWED_ASSET_SOURCES as readonly string[]).includes(source)
+  );
+}
+
+/** Known CDN / API domains the server is permitted to fetch from. */
+export const ASSET_HOST_ALLOWLIST = [
+  'polyhaven.com',
+  'polyhaven.org',
+  'ambientcg.com',
+  'struffelproduction.com', // ambientCG's download CDN
+];
+
+/**
+ * True if `host` is an IPv4/IPv6 literal inside a private, loopback,
+ * link-local, or otherwise non-routable range. Used to block SSRF to metadata
+ * endpoints (e.g. 169.254.169.254) and internal services.
+ */
+export function isPrivateOrLinkLocalHost(host: string): boolean {
+  const h = host.replace(/^\[|\]$/g, '').toLowerCase();
+
+  if (h === 'localhost' || h.endsWith('.localhost')) return true;
+
+  // IPv6 loopback / link-local / unique-local.
+  if (h === '::1' || h === '::') return true;
+  if (h.startsWith('fe80:') || h.startsWith('fc') || h.startsWith('fd')) return true;
+  // IPv4-mapped IPv6, e.g. ::ffff:169.254.169.254
+  const mapped = h.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/);
+  if (mapped) return isPrivateOrLinkLocalHost(mapped[1]!);
+
+  const m = h.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+  if (!m) return false;
+  const a = Number(m[1]);
+  const b = Number(m[2]);
+  if (a === 0 || a === 10 || a === 127) return true; // 0.x, private, loopback
+  if (a === 169 && b === 254) return true; // link-local (cloud metadata)
+  if (a === 172 && b >= 16 && b <= 31) return true; // private
+  if (a === 192 && b === 168) return true; // private
+  if (a === 100 && b >= 64 && b <= 127) return true; // CGNAT
+  if (a >= 224) return true; // multicast / reserved
+  return false;
+}
+
+/**
+ * Validate a body-supplied download URL: must be HTTPS, point at an allowlisted
+ * CDN host, and not resolve to a private / link-local literal IP. (S2)
+ */
+export function isAllowedAssetHost(urlString: string): boolean {
+  let u: URL;
+  try {
+    u = new URL(urlString);
+  } catch {
+    return false;
+  }
+  if (u.protocol !== 'https:') return false;
+  const host = u.hostname.toLowerCase();
+  if (isPrivateOrLinkLocalHost(host)) return false;
+  return ASSET_HOST_ALLOWLIST.some((d) => host === d || host.endsWith('.' + d));
+}
+
+// ---------------------------------------------------------------------------
+// AppleScript escaping (S4)
+// ---------------------------------------------------------------------------
+
+// Matches ASCII control characters (U+0000–U+001F).
+const CONTROL_CHARS = /[\u0000-\u001f]/g;
+
+/**
+ * Escape a string for safe inclusion inside a double-quoted AppleScript literal.
+ * Backslashes must be doubled BEFORE quotes are escaped, otherwise an injected
+ * trailing backslash neutralises the closing quote. Control characters are
+ * stripped so they can't break out of the `-e` argument.
+ */
+export function escapeAppleScriptString(s: string): string {
+  return s.replace(CONTROL_CHARS, ' ').replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+
+// ---------------------------------------------------------------------------
+// Content-Disposition filename sanitization (S7)
+// ---------------------------------------------------------------------------
+
+// Control chars, double-quote, and backslash are unsafe in a quoted filename.
+const UNSAFE_FILENAME_CHARS = /[\u0000-\u001f"\\]/g;
+
+/**
+ * Reduce an arbitrary name to a safe `filename="..."` value: basename only, no
+ * path separators, quotes, backslashes, or control characters.
+ */
+export function sanitizeContentDispositionFilename(name: string): string {
+  const base = name.split(/[\\/]/).pop() ?? '';
+  const cleaned = base.replace(UNSAFE_FILENAME_CHARS, '').trim();
+  return cleaned || 'download';
+}
+
+// ---------------------------------------------------------------------------
+// /@fs served-extension allowlist (S5)
+// ---------------------------------------------------------------------------
+
+const SERVABLE_FS_EXTENSIONS = new Set([
+  'ts',
+  'tsx',
+  'js',
+  'jsx',
+  'mjs',
+  'cjs',
+  'json',
+  'wasm',
+  'css',
+  'glsl',
+  'vert',
+  'frag',
+]);
+
+/** Restrict /@fs serving to source/asset file types (never .env, keys, etc.). */
+export function isServableFsExtension(ext: string): boolean {
+  return SERVABLE_FS_EXTENSIONS.has(ext.toLowerCase());
+}
+
+// ---------------------------------------------------------------------------
+// Origin allowlist for mutating editor routes (S3)
+// ---------------------------------------------------------------------------
+
+/** True for loopback hostnames (localhost / 127.0.0.0/8 / ::1). */
+export function isLoopbackHostname(host: string): boolean {
+  const h = host.replace(/^\[|\]$/g, '').toLowerCase();
+  if (h === 'localhost' || h === '::1') return true;
+  return /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(h);
+}
+
+/**
+ * CSRF / drive-by defense for mutating `/__editor/*` routes. A browser always
+ * sends an `Origin` on cross-site POSTs; if present it must be a loopback origin
+ * (or an explicitly-allowed host). Non-browser clients (the CLI/SDK using Node
+ * `fetch`) send no `Origin` and are allowed.
+ */
+export function isAllowedEditorOrigin(
+  origin: string | undefined,
+  extraAllowedHosts: string[] = [],
+): boolean {
+  if (!origin) return true;
+  let u: URL;
+  try {
+    u = new URL(origin);
+  } catch {
+    return false;
+  }
+  const host = u.hostname.toLowerCase();
+  if (isLoopbackHostname(host)) return true;
+  return extraAllowedHosts.some((h) => h.toLowerCase() === host);
+}
+
+// ---------------------------------------------------------------------------
+// Installed-package source resolution (B1b, packaging plan §3(b)1)
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve `packageName`'s own `src/` directory as INSTALLED in `fromDir`'s
+ * `node_modules` — Node's own resolution algorithm, rooted at `fromDir` (a
+ * project directory), not at wherever this server process's own code lives.
+ *
+ * Why: a project that pins `@vgai/engine@0.3.0` must be served ITS 0.3.0
+ * source, never a copy baked into whatever package happens to be running the
+ * editor server — otherwise the exact version-skew class Phase B exists to
+ * kill (an editor silently serving a different engine version than the one
+ * the project declares) reappears one layer down, inside script-serving.
+ * `packageName`'s `exports` map must publish a `./package.json` entry (both
+ * `@vgai/engine` and `@vgai/scene-ui` do, as of B1a) for `require.resolve` to
+ * find it.
+ *
+ * Returns `null` (never throws) when `packageName` isn't resolvable from
+ * `fromDir` — no project open, a pre-Phase-B project with no such
+ * dependency, or a project that hasn't `npm install`ed yet. Callers fall back
+ * to a checkout-relative default in that case.
+ */
+export function resolveInstalledPackageSrcDir(fromDir: string, packageName: string): string | null {
+  try {
+    const req = createRequire(join(fromDir, 'package.json'));
+    const pkgJsonPath = req.resolve(`${packageName}/package.json`);
+    return join(dirname(pkgJsonPath), 'src');
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Bind host + listen-error helpers (S3 / SC5)
+// ---------------------------------------------------------------------------
+
+/** Resolve the interface to bind to. Defaults to loopback; opt-in via env. */
+export function resolveBindHost(env: NodeJS.ProcessEnv = process.env): string {
+  return env['VGAI_EDITOR_HOST'] || env['EDITOR_HOST'] || '127.0.0.1';
+}
+
+/** Format a friendly message for a server `listen` error (notably EADDRINUSE). */
+export function friendlyListenError(
+  err: NodeJS.ErrnoException,
+  port: number,
+  host: string,
+): string {
+  if (err.code === 'EADDRINUSE') {
+    return (
+      `Port ${port} is already in use on ${host}. ` +
+      `Another editor instance may already be running — stop it, or set PORT / VGAI_EDITOR_HOST ` +
+      `to a free address and try again.`
+    );
+  }
+  if (err.code === 'EACCES') {
+    return `Permission denied binding to ${host}:${port}. Try a port above 1024.`;
+  }
+  return `Failed to start server on ${host}:${port}: ${err.message}`;
+}
+
+// ---------------------------------------------------------------------------
+// File-move disambiguation (SC2)
+// ---------------------------------------------------------------------------
+
+export interface MoveCandidate {
+  hash: string;
+  size: number;
+  timestamp: number;
+}
+
+/**
+ * A delete+create pair is treated as a move (and triggers scene-ref rewriting)
+ * only when it is unambiguous: the added file must match a pending unlink by
+ * BOTH content hash AND byte size, that match must be unique, and it must fall
+ * within the move window. Hash-only matching risks rewriting scene files on an
+ * unrelated delete+create that happens to collide. (SC2)
+ */
+export function findUniqueMoveMatch<T extends MoveCandidate>(
+  candidates: readonly T[],
+  addedHash: string,
+  addedSize: number,
+  now: number,
+  windowMs: number,
+): T | null {
+  const matches = candidates.filter(
+    (c) => c.hash === addedHash && c.size === addedSize && now - c.timestamp < windowMs,
+  );
+  return matches.length === 1 ? matches[0]! : null;
+}
+
+// ---------------------------------------------------------------------------
+// Manifest write validation (A4, D8) — POST /__editor/manifest
+// ---------------------------------------------------------------------------
+
+export interface ManifestWriteBody {
+  path?: unknown;
+  content?: unknown;
+}
+
+export type ManifestWriteValidation =
+  | { ok: true; content: string }
+  | { ok: false; status: number; error: string };
+
+/**
+ * Validate a `POST /__editor/manifest` request body. The route HARD-CODES the
+ * write destination (`join(projectRoot, 'vgai.game.json')`) — this function
+ * never returns a path, only a green light + the (already-string, already-
+ * valid-JSON) content to write, so there is no way for a caller to derive the
+ * destination from user input even by accident. Rejects: no project open,
+ * any `path` other than the literal `'vgai.game.json'` (traversal, a
+ * different filename, an absolute path — all rejected identically), a
+ * non-string `content`, and content that fails to `JSON.parse`.
+ */
+export function validateManifestWrite(
+  projectRoot: string,
+  engineRoot: string,
+  body: ManifestWriteBody,
+): ManifestWriteValidation {
+  if (projectRoot === engineRoot) {
+    return { ok: false, status: 400, error: 'No project open.' };
+  }
+  if (body.path !== undefined && body.path !== 'vgai.game.json') {
+    return {
+      ok: false,
+      status: 400,
+      error: "Invalid path — only 'vgai.game.json' may be written.",
+    };
+  }
+  if (typeof body.content !== 'string') {
+    return { ok: false, status: 400, error: 'Invalid content — expected a JSON string.' };
+  }
+  try {
+    JSON.parse(body.content);
+  } catch {
+    return { ok: false, status: 400, error: 'Content is not valid JSON.' };
+  }
+  return { ok: true, content: body.content };
+}
+
+// ---------------------------------------------------------------------------
+// Project src/ watcher classification (W6a, docs/DATA-TOOLS-DESIGN.md §7)
+// ---------------------------------------------------------------------------
+
+/**
+ * Which editor list a `src/**` add/unlink invalidates, or `null` if it's
+ * irrelevant. Feeds the editor-server's second `src/`-scoped chokidar
+ * watcher (`startWatcher()` in editor-server.ts) so a NEW
+ * `src/tools/*.tool.tsx` or `src/data/*.data.json`/`*.schema.json` shows up
+ * in the dock/DATA tab without a full editor reload (spec §7 W4 field note
+ * c). `.schema.json` is included on the `data` side: its add/unlink flips the
+ * DATA tab between the no-emitted-schema teaching message and real widgets.
+ *
+ * `relPath` is project-root-relative with forward slashes (same convention
+ * `/__editor/data-files` and `/__editor/tool-files` already use).
+ */
+export function classifyProjectSrcPath(relPath: string): 'tools' | 'data' | null {
+  if (relPath.startsWith('src/tools/') && relPath.endsWith('.tool.tsx')) return 'tools';
+  if (
+    relPath.startsWith('src/data/') &&
+    (relPath.endsWith('.data.json') || relPath.endsWith('.schema.json'))
+  ) {
+    return 'data';
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Command-relay response shaping (SC1)
+// ---------------------------------------------------------------------------
+
+export interface CommandResult {
+  ok?: boolean;
+  timedOut?: boolean;
+  error?: string;
+  /** Optional payload for commands that answer with data (e.g. `capture-viewport`'s base64 PNG). */
+  data?: Record<string, unknown>;
+}
+
+/** Map a relayed-command result to an HTTP status + body. A timeout (no editor
+ *  connected) is a distinct 504 error rather than a fake success. (SC1)
+ *  `data`, when present on a success, is spread into the response body
+ *  alongside `ok: true` so callers (`HttpEditorTransport.sendCommand`) see it
+ *  at the top level rather than needing a second field of indirection. */
+export function commandResponseFor(result: CommandResult): {
+  status: number;
+  body: Record<string, unknown>;
+} {
+  if (result.ok) return { status: 200, body: { ok: true, ...(result.data ?? {}) } };
+  if (result.timedOut) {
+    return {
+      status: 504,
+      body: { ok: false, error: result.error ?? 'Command timed out — no editor connected.' },
+    };
+  }
+  return { status: 400, body: { ok: false, error: result.error } };
+}
+
+// ---------------------------------------------------------------------------
+// "New Project" packaged-mode guard (Phase B cleanup, ITEM 2)
+// ---------------------------------------------------------------------------
+
+/**
+ * True iff `engineRoot` looks like a real monorepo checkout `scaffoldProject`
+ * can read a starter/example template from — i.e.
+ * `<engineRoot>/packages/editor/template` exists, the EXACT path
+ * `create-vgai-project`'s `scaffoldProject` reads for the starter template
+ * (`packages/create-vgai-project/src/scaffold.ts`'s `templateDir`; the
+ * `--example <id>` path similarly reads `<engineRoot>/examples/<id>`, which
+ * only exists under the same monorepo layout).
+ *
+ * A packaged (`node_modules`-installed) `@vgai/editor`'s `engineRoot` is the
+ * EDITOR PACKAGE's own root instead of a monorepo checkout root (see
+ * `packaged.ts`'s header doc comment, "Known scope trims" — `createEditorServer`
+ * is constructed with `engineRoot: editorPackageRoot` there, since there is no
+ * real monorepo on disk to point at). That directory has no
+ * `packages/editor/template` subtree — only a bare `template/` at its own
+ * root — so this correctly reports `false` there, and `true` for both `dev.ts`
+ * (real `engineRoot`) and `prod.ts` (Electron packaging, also a real checkout
+ * at build time).
+ */
+export function isMonorepoScaffoldRoot(engineRoot: string): boolean {
+  return existsSync(join(engineRoot, 'packages', 'editor', 'template'));
+}
+
+/**
+ * The actionable error `POST /__editor/create-project` returns when
+ * `!isMonorepoScaffoldRoot(engineRoot)` (packaged mode). `scaffoldProject`'s
+ * `monoRoot` assumes a monorepo checkout layout the packaged runtime doesn't
+ * have (`isMonorepoScaffoldRoot`'s doc comment) — rather than let it crash
+ * partway through with a confusing `ENOENT` reading a nonexistent template
+ * dir, the route fails loudly, up front, with the supported alternative.
+ * Relocating `template/` into `create-vgai-project` (so a packaged editor's
+ * "New Project" could scaffold without a monorepo at all) is the real fix,
+ * tracked as a follow-up (phase plan §6 landmine 5) — not attempted here.
+ */
+export const PACKAGED_NO_MONOREPO_TEMPLATE_ERROR =
+  "Creating a new project from inside the packaged editor isn't supported yet. " +
+  'Run `vgai create <name>` in a terminal, then open the result with `vgai edit <name>`.';