@vgai/editor 0.2.0

package/server/canonical-path.ts

@@ -0,0 +1,50 @@
+/**
+ * Canonicalize a project root path (T6.2 slice 3 finding — see
+ * docs/REACT-WORLD-DESIGN.md; reported in the slice-3 "Report back").
+ *
+ * Vite's own module resolver calls `fs.realpathSync` when resolving a
+ * STATIC relative import — e.g. a react world's entry module's own
+ * `import { useGameState } from './src/ui/game-state'` — which
+ * collapses a symlinked path segment (macOS's `/var` -> `/private/var`,
+ * hit by every project scaffolded under `os.tmpdir()`, as every e2e spec
+ * that calls `scaffoldProject()` does) to its real form.
+ * `adapter-resolver.ts`'s hand-built `/@fs/${projectRoot}/...` dynamic-import
+ * strings (which must bypass Vite's static analysis via `@vite-ignore` — the
+ * path is only known at runtime) do NOT go through that same resolution. So
+ * if `projectRoot` itself isn't already canonical, two DIFFERENT `/@fs/`
+ * URLs get produced for the exact same file: Vite's realpath'd rewrite of
+ * the entry module's own relative import vs. our raw, non-realpath'd string
+ * used to import `GameProvider` for the `<GameProvider>` wrap. Browser ES
+ * module identity is per-URL, so the SAME `game-state.tsx` loads as TWO
+ * separate module instances with TWO separate top-level `createContext()`
+ * calls — `useGameState`'s `useGame()` then throws "no Game in context"
+ * even though `<GameProvider>` genuinely wraps the entry (this is exactly
+ * what the T6.2 slice-3 AC e2e's first real-browser run of a react world
+ * caught).
+ *
+ * The fix is upstream of any one `/@fs/` string: canonicalize the project
+ * root ONCE, at the points a project path enters server state (dev/prod
+ * boot from `VGAI_PROJECT`, and the `/__editor/open-project` route) — every
+ * `/@fs/${projectRoot}` string built anywhere afterwards (browser-side,
+ * repo-wide, not just the react-world resolver) then already matches
+ * whatever Vite's own resolver would independently arrive at for that same
+ * project.
+ */
+import { realpathSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+/**
+ * Resolve `rawPath` to an absolute, symlink-canonicalized path. Falls back to
+ * a plain `path.resolve` if the path doesn't exist yet or `realpathSync`
+ * otherwise fails (e.g. a permissions error) — never throws, so a bad/odd
+ * path degrades to today's pre-canonicalization behavior rather than
+ * blocking project open.
+ */
+export function canonicalProjectRoot(rawPath: string): string {
+  const absolute = resolve(rawPath);
+  try {
+    return realpathSync(absolute);
+  } catch {
+    return absolute;
+  }
+}

package/server/cloud-asset-catalog.ts

@@ -0,0 +1,101 @@
+export const DEFAULT_CLOUD_ASSET_BASE_URL = 'https://vgai-asset-library.aaron-0ed.workers.dev';
+
+export interface CloudAssetObject {
+  key: string;
+  sha256: string;
+  sizeBytes: number;
+  contentType: string;
+  relativePath: string;
+}
+
+export interface CloudAssetFile {
+  label: string;
+  format: string;
+  main: CloudAssetObject;
+  dependencies: CloudAssetObject[];
+}
+
+export interface CloudAssetRecord {
+  id: string;
+  status: 'validated';
+  source: string;
+  name: string;
+  type: string;
+  license: string;
+  author: string;
+  sourceUrl: string;
+  attribution: string;
+  files: CloudAssetFile[];
+}
+
+interface CloudAssetManifest {
+  version: 1;
+  generatedAt: string;
+  assets: CloudAssetRecord[];
+}
+
+let cachedManifest: { value: CloudAssetManifest; url: string; loadedAt: number } | undefined;
+const CACHE_MS = 5 * 60 * 1000;
+
+export function getCloudAssetBaseUrl(): string {
+  return (process.env['VGAI_CLOUD_ASSET_URL'] ?? DEFAULT_CLOUD_ASSET_BASE_URL).replace(/\/+$/, '');
+}
+
+export async function loadCloudAssetManifest(): Promise<CloudAssetManifest | null> {
+  const baseUrl = getCloudAssetBaseUrl();
+  if (
+    cachedManifest &&
+    cachedManifest.url === baseUrl &&
+    Date.now() - cachedManifest.loadedAt < CACHE_MS
+  ) {
+    return cachedManifest.value;
+  }
+  try {
+    const response = await fetch(`${baseUrl}/v1/manifest`, { signal: AbortSignal.timeout(5_000) });
+    if (!response.ok) return null;
+    const value = (await response.json()) as CloudAssetManifest;
+    if (value.version !== 1 || !Array.isArray(value.assets)) return null;
+    cachedManifest = { value, url: baseUrl, loadedAt: Date.now() };
+    return value;
+  } catch {
+    return null;
+  }
+}
+
+export async function findCloudAsset(id: string): Promise<CloudAssetRecord | null> {
+  const manifest = await loadCloudAssetManifest();
+  return manifest?.assets.find((asset) => asset.id === id) ?? null;
+}
+
+export function cloudAssetObjectUrl(
+  assetId: string,
+  fileIndex: number,
+  dependencyIndex?: number,
+): string {
+  const base = `${getCloudAssetBaseUrl()}/v1/assets/${encodeURIComponent(assetId)}/files/${fileIndex}`;
+  return dependencyIndex === undefined ? base : `${base}/dependencies/${dependencyIndex}`;
+}
+
+export function parseCloudAssetObjectUrl(
+  value: string,
+  expectedAssetId: string,
+): { fileIndex: number; dependencyIndex?: number } | null {
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    return null;
+  }
+  const expectedBase = new URL(getCloudAssetBaseUrl());
+  if (url.protocol !== 'https:' || url.origin !== expectedBase.origin || url.search || url.hash)
+    return null;
+  const prefix = expectedBase.pathname.replace(/\/$/, '');
+  const relativePath = url.pathname.slice(prefix.length);
+  const match = /^\/v1\/assets\/([a-f0-9]{24})\/files\/(\d+)(?:\/dependencies\/(\d+))?$/.exec(
+    relativePath,
+  );
+  if (!match || match[1] !== expectedAssetId) return null;
+  const parsed: { fileIndex: number; dependencyIndex?: number } = { fileIndex: Number(match[2]) };
+  if (match[3] !== undefined) parsed.dependencyIndex = Number(match[3]);
+  return parsed;
+}

package/server/dev.ts

@@ -0,0 +1,350 @@
+/**
+ * Editor dev server — Express + Vite middleware mode on a single port.
+ *
+ * Run with:
+ *   npx tsx packages/editor/server/dev.ts
+ *
+ * Supports VGAI_PROJECT env var for initial project path.
+ */
+
+import { type Dirent, readdirSync, realpathSync, statSync } 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 { canonicalProjectRoot } from './canonical-path';
+import { createEditorServer } from './editor-server';
+import { gameGlobalsShadowPlugin } from '../vite-plugin-game-globals';
+import { ingestGameShadowRoots } from './game-globals-shadow';
+import { friendlyListenError, resolveBindHost } from './server-utils';
+import { registerSession, unregisterSession } from './session-registry';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+// Port is env-overridable so multiple editor servers (e.g. parallel e2e/capture
+// runs across git worktrees) don't collide on 5173. Defaults preserve behavior.
+const PORT = Number(process.env['VGAI_EDITOR_PORT']) || 5173;
+const HMR_PORT = Number(process.env['VGAI_HMR_PORT']) || (PORT === 5173 ? 24678 : PORT + 100);
+// S3: bind to loopback by default; opt-in to a wider interface via env.
+const HOST = resolveBindHost();
+// Engine root is three levels up from packages/editor/server/
+const engineRoot = path.resolve(__dirname, '../../..');
+// Worktree / hoisted-monorepo support: `node_modules` is very often a SYMLINK
+// (git worktrees share ONE install; npm workspaces hoist to a parent), and its
+// realpath then lands OUTSIDE `engineRoot`. Vite's `server.fs.allow` matches on
+// the symlink-RESOLVED path, so without allowing the resolved node_modules a
+// game's own dependency — e.g. a vendored react game importing a font package —
+// 403s ("outside of Vite serving allow list") in a worktree checkout even
+// though it serves fine in a normal one. Allowing the project's own resolved
+// deps is safe, and this is a no-op when node_modules is a real directory
+// already under engineRoot.
+const nodeModulesRealPath = (() => {
+  try {
+    const real = realpathSync(path.join(engineRoot, 'node_modules'));
+    return real.startsWith(engineRoot) ? null : real;
+  } catch {
+    return null;
+  }
+})();
+// Canonicalized (symlink-resolved), not just `path.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, e.g. macOS's `/var` -> `/private/var`).
+const projectPath = process.env['VGAI_PROJECT']
+  ? canonicalProjectRoot(process.env['VGAI_PROJECT'])
+  : undefined;
+
+// D-X2 (docs/EXTERNAL-FOLDER-INGEST-DESIGN.md): the project-static route
+// (below) must follow the CURRENTLY open project, not a boot-time snapshot —
+// `open-project` can switch it live (`onProjectOpened` below). A mutable box
+// read by the plugin's thunk, updated in the SAME callback that already
+// extends Vite's fs.allow / watcher / game-globals shadow for a newly opened
+// project.
+let currentProjectRoot: string | undefined = projectPath;
+
+// Roots whose `/src/` modules are treated as game code and get the gated-globals
+// prelude (see below). Seeded from the env project (extended when the editor
+// opens/switches a project at runtime, onProjectOpened below) PLUS the fixed
+// in-tree ingest-fixture roots (R2c — see game-globals-shadow.ts's doc comment:
+// those same-realm `shared`/`deduped` fixtures are part of THIS package's own
+// `/src/` tree, not a project a user opens, so they need their own entry here).
+const projectRoots = new Set<string>(ingestGameShadowRoots(path.resolve(__dirname, '../src')));
+if (projectPath) projectRoots.add(projectPath);
+
+async function main(): Promise<void> {
+  const app = express();
+
+  // 1. Create Vite in middleware mode (before editor routes so we can pass the callback)
+  const vite = await createViteServer({
+    configFile: path.resolve(engineRoot, 'vite.config.ts'),
+    plugins: [
+      // Pipe gated `window`/`document` into game code: prepend a lexical shadow
+      // to every project `/src/` module so its globals resolve to the editor's
+      // gated proxies. Scoped to `projectRoots` — an opened project's root PLUS
+      // the fixed in-tree ingest-fixture roots (R2c) — so engine/editor code is
+      // untouched (it keeps the real window; its input is gated separately via
+      // InputManager.setEnabled). The repo-root config registers this same
+      // plugin over the ingest roots for the hosted build; the shared factory
+      // no-ops on already-shadowed code, so the overlap in dev is harmless.
+      gameGlobalsShadowPlugin(() => projectRoots),
+      // Project-rooted verbatim static serving (D-X2) — the external-folder
+      // sibling of `gameStaticPlugin`'s vendored-dist route (`vite.config.ts`,
+      // repo-root config). Always registered (not gated on `projectPath`
+      // being set at boot): a project can open LATER via `onProjectOpened`,
+      // and the route must still come alive then — the thunk reads
+      // `currentProjectRoot` live on every request.
+      projectGameStaticPlugin(() => currentProjectRoot),
+      // Intercept project script changes and send a custom HMR event
+      // instead of triggering a full page reload.
+      ...(projectPath
+        ? [
+            {
+              name: 'vgai-script-hmr',
+              configureServer(server: { watcher: { add: (p: string) => void } }) {
+                // Watch the project directory so changes outside the Vite root are detected
+                server.watcher.add(projectPath);
+              },
+              handleHotUpdate({
+                file,
+                server,
+              }: {
+                file: string;
+                server: { ws: { send: (msg: unknown) => void } };
+              }) {
+                // Vite's `file` hook argument is ALWAYS forward-slash normalized
+                // (its cross-platform module-id convention), but `projectPath`
+                // comes from `canonicalProjectRoot` -> `realpathSync`, which on
+                // Windows returns a native backslash path. A naive
+                // `file.startsWith(projectPath)` therefore NEVER matches on
+                // Windows ("C:/Users/...".startsWith("C:\\Users\\...") is
+                // false) — the custom `vgai:script-update` event silently never
+                // fires and every project edit falls through to Vite's default
+                // full-module-reload HMR instead. Compare forward-slash forms
+                // on both sides so this works identically on every OS.
+                const projectPathPosix = projectPath!.split(path.sep).join('/');
+                if (file.startsWith(projectPathPosix)) {
+                  // Data assets (docs/DATA-TOOLS-DESIGN.md §2.3) ride Vite's
+                  // STOCK HMR: fall through so the imported JSON module
+                  // updates and the owning handle module's
+                  // `import.meta.hot.accept('./x.data.json', …)` fires in the
+                  // running game (live tuning). Safe from the full-page-reload
+                  // hazard the swallow below exists for: the template's
+                  // handle module self-accepts the dep, and an unimported
+                  // .data.json maps to zero modules (no-op). Scene/asset
+                  // files stay swallowed — the editor owns those via SSE.
+                  if (/\.data\.json$/.test(file)) return;
+                  if (/\.(ts|tsx|js|jsx)$/.test(file)) {
+                    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.
+                  return [];
+                }
+              },
+            },
+          ]
+        : []),
+    ],
+    server: {
+      middlewareMode: true,
+      hmr: { port: HMR_PORT },
+      fs: {
+        allow: [
+          engineRoot,
+          ...(nodeModulesRealPath ? [nodeModulesRealPath] : []),
+          ...(projectPath ? [projectPath] : []),
+        ],
+      },
+    },
+    // Pass project path to editor client (server-first mode is implied by the
+    // dev server's Vite mode 'development' — see editor-mode.ts).
+    define: {
+      __VGAI_PROJECT_PATH__: JSON.stringify(projectPath ?? ''),
+      // Track N, N2 (docs/REACT-INGEST-LANDING-DESIGN.md D-N2): the absolute
+      // repo root, so `ingest/discovery-react.ts` can build the `projectRoot`
+      // an `ingest-react` fixture's `resolveWorldAdapter` call needs (its
+      // `entry`'s `/@fs/` dynamic import + `loadProjectGameProvider` lookup)
+      // WITHOUT a "current project" — these in-tree fixtures live in THIS
+      // package's own source tree, not a project a user opens (mirrors
+      // `ingestGameShadowRoots`'s identical reasoning for the game-globals
+      // shadow). Undefined in the `web` (browser-mode, no dev server) build —
+      // `ingestGameReactProjectRoot` degrades to `undefined` there, and every
+      // caller already gates on `getEditorMode() !== 'browser'` first.
+      __VGAI_ENGINE_ROOT__: JSON.stringify(engineRoot),
+    },
+  });
+
+  // 2. Mount editor API routes (/__editor/*) with Vite fs.allow update callback
+  const editorRouter = createEditorServer({
+    engineRoot,
+    projectPath,
+    onProjectOpened(newProjectPath: string) {
+      // Dynamically allow Vite to serve /@fs/ paths from the new project directory
+      const allowed = vite.config.server.fs.allow;
+      if (!allowed.includes(newProjectPath)) {
+        allowed.push(newProjectPath);
+      }
+      // Also start watching the project for HMR
+      vite.watcher.add(newProjectPath);
+      // And gate its modules with the game-globals prelude (see vgai-game-globals above).
+      projectRoots.add(newProjectPath);
+      // And point the project-static route (D-X2) at the newly opened project.
+      currentProjectRoot = newProjectPath;
+      // Keep the session registry (D12) pointing at the CURRENT project so
+      // `vgai edit` reuse/targeting decisions see switches, not boot state.
+      registerSession({
+        project: newProjectPath,
+        port: PORT,
+        pid: process.pid,
+        startedAt: sessionStartedAt,
+      });
+    },
+  });
+  app.use(editorRouter);
+  app.use(vite.middlewares);
+
+  // Opt-in PROJECT-SCOPED poll watching (VGAI_WATCH_POLL=1, or =<ms> for the
+  // interval). Load-bearing on WSL when the project lives on a Windows drive
+  // (/mnt/c, drvfs): inotify never fires there, so without polling the editor
+  // silently misses every external file edit — most visibly the data-asset
+  // live-tuning loop (docs/DATA-TOOLS-DESIGN.md §2.3: edit
+  // `src/data/*.data.json` in VS Code/agent while playing → HMR into the
+  // running game). The project's own vite.config.ts can NOT provide this —
+  // the editor boots Vite from the ENGINE's config and only `watcher.add()`s
+  // the project — so this env var is the single knob.
+  //
+  // Deliberately NOT Vite's `server.watch.usePolling`: that polls the whole
+  // watched set (the entire engine tree), and over drvfs the stat flood
+  // starves the event loop badly enough that play-mode's game mount never
+  // completes (field-tested 2026-07-10: editor shell loads, ▶ mounts nothing
+  // even after 45s; scoped polling mounts fine). Instead: a tiny mtime poller
+  // over the CURRENT project only, forwarding synthetic add/change/unlink
+  // events into Vite's watcher, which runs the normal invalidate+HMR pipeline.
+  if (process.env['VGAI_WATCH_POLL']) {
+    startProjectPollWatcher(vite.watcher, () => currentProjectRoot);
+  }
+
+  // 3. Start Express
+  const sessionStartedAt = new Date().toISOString();
+  const server = app.listen(PORT, HOST, () => {
+    console.log(
+      `\n  \x1b[32mEditor server\x1b[0m running at \x1b[36mhttp://${HOST}:${PORT}\x1b[0m`,
+    );
+    if (projectPath) {
+      console.log(`  \x1b[33mProject\x1b[0m: ${projectPath}`);
+    }
+    console.log(
+      `  \x1b[33mEditor\x1b[0m: \x1b[36mhttp://${HOST}:${PORT}/\x1b[0m\n`,
+    );
+    // D12: announce this session so `vgai edit` can reuse instead of hijack.
+    registerSession({
+      project: projectPath ?? null,
+      port: PORT,
+      pid: process.pid,
+      startedAt: sessionStartedAt,
+    });
+  });
+
+  // SC5: friendly message instead of an opaque crash on port conflict.
+  server.on('error', (err: NodeJS.ErrnoException) => {
+    console.error(`\n  \x1b[31m${friendlyListenError(err, PORT, HOST)}\x1b[0m\n`);
+    process.exit(1);
+  });
+
+  // Cleanup on shutdown
+  const shutdown = () => {
+    unregisterSession(process.pid);
+    vite.close();
+    server.close();
+  };
+  process.once('SIGINT', shutdown);
+  process.once('SIGTERM', shutdown);
+  process.once('exit', () => unregisterSession(process.pid));
+}
+
+/**
+ * VGAI_WATCH_POLL's engine: rescan the current project's tree every
+ * `interval` ms (default 1000; `VGAI_WATCH_POLL=<ms>` overrides), diff mtimes
+ * against the previous scan, and forward add/change/unlink as synthetic
+ * events on Vite's own chokidar watcher — from there the stock
+ * invalidate + handleHotUpdate pipeline (including the vgai-script-hmr
+ * plugin above) runs exactly as if inotify had fired. See the call site's
+ * comment for why this exists and why it is scoped to the project.
+ *
+ * Cost model: a project tree is small (tens to a few hundred files once
+ * node_modules/.git/dist are skipped), so even drvfs-priced stats are cheap.
+ * Switching projects re-baselines silently (no spurious event storm).
+ */
+function startProjectPollWatcher(
+  watcher: { emit: (event: string, file: string) => void },
+  getRoot: () => string | undefined,
+): void {
+  const raw = Number(process.env['VGAI_WATCH_POLL']);
+  const interval = raw > 1 ? raw : 1000;
+  const SKIP = new Set(['node_modules', '.git', 'dist', '.vgai', 'logs']);
+  let known: Map<string, number> | undefined;
+  let lastRoot: string | undefined;
+
+  const listDir = (dir: string): Dirent[] => {
+    try {
+      return readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return []; // directory vanished mid-scan
+    }
+  };
+
+  const statMtime = (file: string): number | undefined => {
+    try {
+      return statSync(file).mtimeMs;
+    } catch {
+      return undefined; // file vanished between readdir and stat
+    }
+  };
+
+  const scan = (dir: string, out: Map<string, number>): void => {
+    for (const entry of listDir(dir)) {
+      if (SKIP.has(entry.name)) continue;
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        scan(full, out);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      const mtime = statMtime(full);
+      if (mtime !== undefined) out.set(full, mtime);
+    }
+  };
+
+  const diffAndEmit = (prev: Map<string, number>, next: Map<string, number>): void => {
+    for (const [file, mtime] of next) {
+      const was = prev.get(file);
+      if (was === undefined) watcher.emit('add', file);
+      else if (was !== mtime) watcher.emit('change', file);
+    }
+    for (const file of prev.keys()) {
+      if (!next.has(file)) watcher.emit('unlink', file);
+    }
+  };
+
+  const tick = (): void => {
+    const root = getRoot();
+    if (root !== lastRoot) {
+      lastRoot = root;
+      known = undefined; // new/first project: baseline scan, emit nothing
+    }
+    if (root) {
+      const next = new Map<string, number>();
+      scan(root, next);
+      if (known) diffAndEmit(known, next);
+      known = next;
+    }
+    setTimeout(tick, interval);
+  };
+  setTimeout(tick, interval);
+  console.log(`  Project poll-watcher on (VGAI_WATCH_POLL, every ${interval}ms)`);
+}
+
+main().catch((err) => {
+  console.error('Failed to start dev server:', err);
+  process.exit(1);
+});