@vgai/editor 0.2.0

package/server/packaged.ts

@@ -0,0 +1,571 @@
+/**
+ * Packaged editor server — the entry a `@vgai/editor` npm package resolves
+ * from a PROJECT's own `node_modules`, with NO monorepo checkout on disk
+ * (Phase B, docs/FRONTEND-FIRST-ROADMAP.md; see the phase plan's D-FORK
+ * decision + §0/§3 "the real work" for `@vgai/editor`).
+ *
+ * Run with:
+ *   VGAI_PROJECT=<projectDir> node dist-server/packaged.mjs
+ *
+ * ## Why this file exists (and isn't just `prod.ts`)
+ *
+ * `dev.ts` boots ONE Vite instance rooted at the monorepo checkout, which
+ * does double duty: it builds the editor's OWN React app AND resolves the
+ * OPENED PROJECT's module graph (bare imports like `three`/`zod`/`react`
+ * resolve only because that Vite's `root` is the repo root, whose hoisted
+ * `node_modules` has everything). `prod.ts` (the Electron packaging path)
+ * has no Vite at all — its `serveScripts` fallback in `editor-server.ts` is
+ * a hand-rolled `/@fs` route that only rewrites `@engine/` imports; it has
+ * NO handler for bare npm specifiers or `/node_modules/*` at all, so it
+ * cannot serve a real project's own module graph (see the phase plan's §0).
+ *
+ * This file is the missing second code path: it serves the editor's OWN
+ * app as a PREBUILT static SPA (`../dist/`, produced by the workspace-local
+ * `npm run build -w @vgai/editor`) — no dev-mode transform of the editor's
+ * own source is needed, since a project author isn't hot-reloading the
+ * editor's own UI — and boots a SEPARATE, PROJECT-ROOTED Vite instance
+ * (`root: <project>`, `configFile: false`, middleware mode, HMR + watch
+ * ENABLED) whose job is ONLY to resolve/transform the opened PROJECT's own
+ * source. Because that Vite instance's `root` is the project directory,
+ * Vite's own resolver naturally walks the PROJECT's OWN `node_modules` for
+ * every bare specifier (`three`, `zod`, `react`, `@vgai/scene-ui`, ...) —
+ * for free, with zero hand-written import rewriting. This is the same
+ * pattern `packages/editor/scripts/run-conformance.ts` uses to run the
+ * adapter conformance kit against an arbitrary external folder, adapted for
+ * live editing (HMR/watch on) instead of a one-shot SSR run.
+ *
+ * The `@engine/` alias project source still uses (pending the `@engine/*` →
+ * `@vgai/engine/*` migration the phase plan defers to a follow-up cleanup
+ * slice) is reconstructed here too — pointed at the PROJECT's own installed
+ * `@vgai/engine`, not a copy baked into this package's own tarball. A
+ * project pinning `@vgai/engine@0.3.0` must be served ITS 0.3.0 source, so
+ * `@vgai/engine`/`@vgai/scene-ui` are resolved via `createRequire`, rooted
+ * at the project directory — Node's own resolution algorithm, not a
+ * hardcoded path (see `resolveInstalledPackageSrcDir` in `server-utils.ts`,
+ * shared with `editor-server.ts`'s equivalent fix for `prod.ts`'s route).
+ *
+ * ## React-world OID authoring parity (DEBT-4 follow-on)
+ *
+ * `dev.ts` reaches TWO extra plugins via its `configFile:` (repo-root
+ * `vite.config.ts`): `uiOidPlugin()` (stamps `data-oid` on every JSX element
+ * in project-scoped `.tsx` files + serves the `/__ui-source/*` read/write
+ * endpoints the hierarchy/inspector's source-write path needs) and
+ * `reactWorldProviderPlugin()` (resolves the synthetic
+ * `/__vgai-game-provider` module `adapter-resolver.ts`'s
+ * `loadProjectGameProvider` imports — WITHOUT it, every `kind: 'react'`
+ * world 404s on mount, not just "authors without OID"). Both are carried
+ * over here, imported straight from this package's own `vite-plugin-ui-oid`
+ * / `vite-plugin-react-world-provider` (same files, no copy) and registered
+ * with NO extra scoping beyond their own built-in `defaultProjectScopeInclude`
+ * (already project-scoped — see that file's doc comment: excludes
+ * `node_modules`, vendored trees, and the vgai tooling/engine source, which
+ * this Vite instance never serves anyway since its `root` IS the project).
+ *
+ * `@vitejs/plugin-react` (`react()`) is DELIBERATELY NOT added here — this
+ * is the one piece of `dev.ts` parity that is a genuine, structural
+ * incompatibility, not a missing plugin call:
+ *
+ * 1. **Fast Refresh's preamble has nowhere to run.** `@vitejs/plugin-react`
+ *    only skips its fast-refresh code-injection when `config.isProduction ||
+ *    config.command === 'build' || config.server.hmr === false` — none of
+ *    which hold here (this instance is `middlewareMode` `serve` with `hmr`
+ *    ON, by design, for live editing). With fast-refresh injection ON, every
+ *    transformed `.tsx` module gets a trailer that THROWS
+ *    (`"@vitejs/plugin-react can't detect preamble. Something is wrong."`)
+ *    unless `window.$RefreshReg$`/`$RefreshSig$` were set by the preamble
+ *    script `transformIndexHtml` injects into an HTML page THAT INSTANCE
+ *    SERVES. This instance is `appType: 'custom'` (no HTML serving at all —
+ *    the editor's own shell is a PREBUILT static `dist/`, sent by `express.
+ *    static` below with zero Vite involvement, so no `transformIndexHtml`
+ *    hook ever runs for it either). Registering `react()` as-is would not
+ *    degrade gracefully to "no Fast Refresh" — it would make every react-
+ *    world/component module throw on first load, a regression versus
+ *    today's baseline (plain esbuild JSX, which works fine for basic JSX —
+ *    proven by the default template). The only way to silence just the
+ *    fast-refresh half (short of a bespoke preamble-bootstrap module the
+ *    browser would need to import before any project entry, itself a new
+ *    client-side subsystem) is `server.hmr: false` on the WHOLE instance,
+ *    which would also kill the `vgai-script-hmr` plugin below's WebSocket
+ *    delivery — not an acceptable trade for this slice.
+ * 2. **JSX compilation itself doesn't need it.** Vite's default esbuild JSX
+ *    transform (`automatic` runtime, no config here) already compiles
+ *    `.tsx`/`.jsx` correctly without `@vitejs/plugin-react` — proven by the
+ *    default (threejs-only) template authoring fine today, and unaffected
+ *    by this file's plugin list either way.
+ *
+ * So: OID stamping (source-write authoring) and the `GameProvider` identity
+ * fix are real, working parity gained by this change. React Fast Refresh
+ * for a project's own components remains NOT at `dev.ts` parity under the
+ * packaged runtime — a documented, structural gap, not a hidden one.
+ *
+ * **A second, deeper gap this change surfaced — FIXED by the C1 follow-on**
+ * (`phase-b/c1-react-mount`): `adapter-resolver.ts` used to mount every react
+ * world with THIS PACKAGE'S OWN bundled `react`/`react-dom` (`import {
+ * createRoot } from 'react-dom/client'` / `createElement`, statically baked
+ * into the prebuilt `dist/` at `npm run build -w @vgai/editor` time), while
+ * the entry component's own hooks ran against WHATEVER `react` the
+ * PROJECT'S OWN `node_modules` resolves (this Vite instance's `root` is the
+ * project, so bare `react` imports resolve there, by design — a project pins
+ * its own react version, independent of the editor). `dev.ts` avoids this
+ * exact failure mode via repo-root `vite.config.ts`'s `resolve.dedupe:
+ * ['react', 'react-dom', ...]`, which works ONLY because dev.ts's single
+ * Vite instance resolves BOTH the editor's own source and the opened
+ * project's source through the SAME `node_modules` — there is no equivalent
+ * collapsing point here: the editor's own react is baked into a separate,
+ * already-built production bundle, physically disconnected from this
+ * instance's live resolution of the project's react. Two separate `react`
+ * module instances meant the mounting `react-dom`'s hook dispatcher and the
+ * entry component's own `useState`/`useContext` calls read DIFFERENT
+ * internal singleton objects — the classic "duplicate React copies" failure.
+ * **Confirmed live, not theoretical, at the time this was still open**: a
+ * real-browser Playwright run against a tarball-installed, checkout-absent
+ * packaged editor (`vgai.game.json`'s `kind: 'react'` "hud" world,
+ * `useGameState`) threw exactly this at mount: `TypeError: Cannot read
+ * properties of null (reading 'useContext')` inside `useGame()`
+ * (`src/ui/game-state.tsx`), called from the project's `Hud` component,
+ * rendered by the editor's OWN bundled `react_stack_bottom_frame`
+ * (`assets/index-*.js`).
+ *
+ * The fix (C1): a react world's mount does NOT need to share react with the
+ * editor's own UI at all — it is an isolated `createRoot` subtree that only
+ * needs to be internally consistent with itself. So
+ * `adapter-resolver.ts`'s `resolveReactWorldMountRuntime()` now resolves
+ * `createElement`/`createRoot`/the engine-`GameProvider` fallback from the
+ * PROJECT's own graph under the packaged runtime, via this file's newly
+ * registered `reactWorldRuntimePlugin()` (a synthetic virtual module,
+ * `/__vgai-react-world-runtime`, the same "literal static re-export" trick
+ * `reactWorldProviderPlugin()` already uses for `GameProvider` — see
+ * `vite-plugin-react-world-runtime.ts`'s doc comment) — converging the mount
+ * call and the entry component's hooks on ONE react instance, the project's
+ * own. Gated on `isPackagedRuntime()` (`src/packaged-runtime.ts`, itself
+ * reading a `packaged` flag `/__editor/project` now reports) so `dev.ts`/
+ * Electron's existing static-import path — already correct via
+ * `resolve.dedupe` — stays byte-unchanged. See `adapter-resolver.ts`'s
+ * `resolveReactWorldMountRuntime` doc comment for the full mechanism, and
+ * the C1 build report for the real-browser proof (checkout absent, tarball-
+ * installed, no console error, DOM rendered).
+ *
+ * ## Scoped dependency discovery, not disabled discovery (C3 follow-on)
+ *
+ * `optimizeDeps` below used to carry `noDiscovery: true` (see git history for
+ * the exact prior comment): with the boot-time crawl DEFAULT-targeting the
+ * project's own `index.html`, and a scaffolded project's `src/main.ts`
+ * bootstrap containing a `?net=p2p-host`-gated `await import('../server/
+ * rooms')` that esbuild's scanner statically follows regardless of the
+ * runtime guard around it, that crawl reached real Colyseus SERVER code
+ * (`colyseus` -> `@colyseus/core` -> `@pm2/io`, a package with no browser-
+ * resolvable entry) and crashed the esbuild prebundle step outright. Turning
+ * discovery off entirely sidestepped that crash — at the cost of any CJS-
+ * only dependency NOT in the hardcoded `include` list below being served raw
+ * to the browser and failing (this is exactly what broke `examples/
+ * r3f-probe`: `@react-three/fiber`'s CJS transitive deps, e.g.
+ * `use-sync-external-store/shim/with-selector.js`, have no place to be
+ * hardcoded — this server serves ARBITRARY projects, most without R3F
+ * installed at all, and Vite errors on `include`-ing a not-installed dep).
+ *
+ * The fix (C3, `phase-b/c3-r3f-packaged`) is not "add R3F to the allowlist"
+ * — that just moves the whack-a-mole to the next ecosystem a project
+ * happens to pull in. It SCOPES the crawl instead of disabling it:
+ * `optimizeDeps.entries` is set (see `projectOptimizeDepsEntries` /
+ * `computeProjectOptimizeDepsEntries` in `project-optimize-deps-entries.ts`)
+ * to the OPENED PROJECT's own `vgai.game.json`-declared world `entry` files
+ * — the exact per-world mount code the editor's adapter-resolver dynamically
+ * imports for Play mode, never the project's `src/main.ts` bootstrap (a
+ * standalone-build concern this Vite instance never serves — the editor's
+ * own prebuilt SPA answers `/`). A world entry's own import graph reaches
+ * real client packages (react, R3F, a legitimate client `@colyseus/sdk`
+ * import for real multiplayer — `examples/third-person-arena/src/
+ * network.ts`) but never `server/`, so the `@pm2/io` crash class cannot
+ * occur no matter what a project's room code imports, while ANY CJS-needing-
+ * prebundle client dependency a world reaches gets auto-discovered and
+ * prebundled — no per-package allowlist, adapts to whatever the opened
+ * project actually has installed. `project-optimize-deps-entries.ts`'s doc
+ * comment has the empirical proof (direct `vite.optimizeDeps` runs, not just
+ * theory): scoped to the template's world entry, prebundling succeeds
+ * clean; scoped to `index.html` (the old default), it reproduces the exact
+ * `@pm2/io` crash; scoped to `examples/r3f-probe`'s world entries, `@react-
+ * three/fiber`/`@react-three/drei` are discovered and prebundled with no
+ * hardcoding; scoped to `examples/third-person-arena`'s world entry (a real
+ * colyseus multiplayer project), `@colyseus/sdk` prebundles clean too — the
+ * client SDK's own published build is self-contained and never reaches
+ * `@colyseus/core`'s server-only `Stats.mjs`. See the C3 build report for
+ * the real-browser proof (checkout absent, tarball-installed): R3F's
+ * `examples/r3f-probe` "net" world mounts with no console error, AND the
+ * pre-existing react-world (C1) / colyseus-bearing-project (this section)
+ * cases still work — no regression.
+ *
+ * ## Known scope trims (v1 — flagged, not silently dropped)
+ *
+ * - "New Project" scaffolding from WITHIN a packaged (no-checkout) editor
+ *   fails loudly instead of scaffolding — see `editor-server.ts`'s
+ *   `/__editor/create-project` handler (`packagedNoMonorepoTemplateError`).
+ *   `scaffoldProject`'s `monoRoot` assumes a monorepo checkout layout
+ *   (`<monoRoot>/packages/editor/template`), which a `node_modules`-
+ *   installed `@vgai/editor` does not have (only a bare `template/` at its
+ *   own package root). The phase plan (§6 landmine 5) already recommends
+ *   relocating `template/` into `create-vgai-project` as the real fix —
+ *   deferred there, not attempted here; `vgai create <name>` from a terminal
+ *   is the supported path today.
+ */
+
+import { realpathSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import express from 'express';
+import { createServer as createViteServer } from 'vite';
+import { projectGameStaticPlugin } from '../vite-plugin-project-game-static';
+import { reactWorldProviderPlugin } from '../vite-plugin-react-world-provider';
+import { reactWorldRuntimePlugin } from '../vite-plugin-react-world-runtime';
+import { uiOidPlugin } from '../vite-plugin-ui-oid';
+import { canonicalProjectRoot } from './canonical-path';
+import { createEditorServer } from './editor-server';
+import { shouldShadowGameGlobals } from './game-globals-shadow';
+import {
+  SERVER_ONLY_PREBUNDLE_EXCLUDE,
+  computeProjectOptimizeDepsEntries,
+} from './project-optimize-deps-entries';
+import {
+  friendlyListenError,
+  resolveBindHost,
+  resolveInstalledPackageSrcDir,
+} from './server-utils';
+import { registerSession, unregisterSession } from './session-registry';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+// This file lives directly under the `@vgai/editor` package root either as
+// `packages/editor/server/packaged.ts` (source, run via tsx) or as the
+// esbuild-bundled `packages/editor/dist-server/packaged.mjs` (`server/` and
+// `dist-server/` are BOTH direct children of the package root) — so
+// `resolve(__dirname, '..')` lands on the package root in either shape.
+const editorPackageRoot = path.resolve(__dirname, '..');
+// The workspace-local `npm run build -w @vgai/editor` (root `vite.config.ts`,
+// `--outDir packages/editor/dist`) output — the editor's own prebuilt SPA.
+const distPath = path.resolve(editorPackageRoot, 'dist');
+
+const PORT = Number(process.env['PORT']) || Number(process.env['VGAI_EDITOR_PORT']) || 5173;
+const HMR_PORT = Number(process.env['VGAI_HMR_PORT']) || (PORT === 5173 ? 24678 : PORT + 100);
+// S3: bind to loopback by default; opt-in to a wider interface via env.
+const HOST = resolveBindHost();
+
+if (!process.env['VGAI_PROJECT']) {
+  console.error(
+    '\n  \x1b[31mVGAI_PROJECT is required — the packaged editor has no monorepo checkout to fall ' +
+      'back to. Set VGAI_PROJECT=<absolute path to your vgai project>.\x1b[0m\n',
+  );
+  process.exit(1);
+}
+// Canonicalized (symlink-resolved) — see canonical-path.ts's doc comment
+// (dev.ts's identical fix: a react world's `GameProvider` colocation breaks
+// if this path and Vite's own resolver disagree on a symlinked segment).
+const projectPath = canonicalProjectRoot(process.env['VGAI_PROJECT']);
+
+// Worktree / hoisted-`node_modules` support — same rationale as dev.ts:
+// `node_modules` is very often a symlink, and Vite's `server.fs.allow`
+// matches on the symlink-RESOLVED path.
+const projectNodeModulesRealPath = (() => {
+  try {
+    const real = realpathSync(path.join(projectPath, 'node_modules'));
+    return real.startsWith(projectPath) ? null : real;
+  } catch {
+    return null;
+  }
+})();
+
+// D-X2: the project-static route must follow the CURRENTLY open project, not
+// a boot-time snapshot — mirrors dev.ts's `currentProjectRoot` box, updated
+// in the SAME `onProjectOpened` callback that extends Vite's fs.allow/
+// watcher/game-globals shadow for a newly opened project.
+let currentProjectRoot: string = projectPath;
+const projectRoots = new Set<string>([projectPath]);
+
+// C3: the OPENED project's own manifest-declared world entry files — scopes
+// `optimizeDeps.entries` below to exactly the client code a world can mount,
+// never `index.html`/the project's own bootstrap `main.ts` (which is how the
+// crawl used to reach `server/` room code and crash on `@pm2/io`). Boot-time
+// snapshot only, same trim as `engineSrc`/`resolve.alias` below — see
+// `project-optimize-deps-entries.ts`'s doc comment for the full rationale
+// and the empirical proof this avoids the colyseus-scanner crash.
+const projectOptimizeDepsEntries = computeProjectOptimizeDepsEntries(projectPath);
+
+// Kept byte-identical to dev.ts's copy (see its own doc comment) — the
+// lexical shadow prepended to every project module so `window`/`document`
+// resolve to the editor's gated proxies instead of the real, shared globals.
+const GAME_GLOBALS_PRELUDE =
+  'const window=(globalThis.__vgaiGameWindow||globalThis.window),' +
+  'document=(globalThis.__vgaiGameDocument||globalThis.document);\n';
+
+async function main(): Promise<void> {
+  const app = express();
+
+  // The project's own installed `@vgai/engine` — resolved from the PROJECT's
+  // node_modules (Node's own resolution algorithm), never a copy baked into
+  // this package's own tarball (see this file's header doc comment). Falls
+  // back to nothing (alias omitted) when unresolvable — e.g. a project that
+  // hasn't `npm install`ed yet, or predates Phase B — so a bad/missing
+  // install degrades to "no @engine alias" rather than blocking boot.
+  const engineSrc = resolveInstalledPackageSrcDir(projectPath, '@vgai/engine');
+  if (!engineSrc) {
+    console.warn(
+      '\n  \x1b[33mWarning:\x1b[0m no @vgai/engine resolvable from ' +
+        `${projectPath} — run npm install in the project first. ` +
+        '`@engine/*` imports will fail to resolve until then.\n',
+    );
+  }
+
+  // 1. Boot a Vite instance rooted at the PROJECT, not this editor package
+  //    or a monorepo checkout — its own node_modules resolves every bare
+  //    specifier for free (the run-conformance.ts pattern, live-editing not
+  //    one-shot: HMR + watch stay ON, unlike that script's headless SSR run).
+  const vite = await createViteServer({
+    configFile: false,
+    root: projectPath,
+    appType: 'custom', // no HTML serving/SPA-fallback — this instance only serves project modules
+    plugins: [
+      // React-world OID authoring parity (see this file's header doc comment,
+      // "React-world OID authoring parity"): live `data-oid` instrumentation +
+      // the `/__ui-source/*` read/write endpoints the hierarchy/inspector's
+      // source-write path needs. Uses its own built-in `defaultProjectScopeInclude`
+      // (already project-scoped) unmodified — no extra scoping needed since this
+      // instance's `root` IS the project already.
+      uiOidPlugin(),
+      // Resolves the synthetic `/__vgai-game-provider` module
+      // `adapter-resolver.ts`'s `loadProjectGameProvider` imports for every
+      // `kind: 'react'` world's mount — WITHOUT this, a react world 404s at
+      // mount time in packaged mode (this is a correctness fix, not just an
+      // authoring nicety). See vite-plugin-react-world-provider.ts's doc comment.
+      reactWorldProviderPlugin(),
+      // Resolves the synthetic `/__vgai-react-world-runtime` module
+      // `adapter-resolver.ts`'s `resolveReactWorldMountRuntime` imports —
+      // the dual-React-instance fix (this file's header doc comment,
+      // "React-world OID authoring parity" section, final paragraph): a
+      // react world's `createElement`/`createRoot`/engine-`GameProvider`
+      // fallback must come from THIS project-rooted Vite instance's own
+      // react, not the editor's separately-bundled static SPA copy. See
+      // vite-plugin-react-world-runtime.ts's doc comment.
+      reactWorldRuntimePlugin(),
+      // vgai-game-globals — byte-identical rationale to dev.ts's copy.
+      {
+        name: 'vgai-game-globals',
+        transform(code: string, id: string) {
+          const file = id.split('?')[0]!;
+          if (!shouldShadowGameGlobals(file, projectRoots)) return null;
+          return { code: GAME_GLOBALS_PRELUDE + code, map: null };
+        },
+      },
+      // Project-rooted verbatim static serving (D-X2) — same plugin dev.ts uses.
+      projectGameStaticPlugin(() => currentProjectRoot),
+      // Intercept project script changes and send a custom HMR event instead
+      // of triggering a full page reload — byte-identical to dev.ts's copy
+      // (always registered here since a project is ALWAYS open in packaged
+      // mode, unlike dev.ts's conditional-on-boot-time-projectPath gate).
+      {
+        name: 'vgai-script-hmr',
+        handleHotUpdate({
+          file,
+          server,
+        }: {
+          file: string;
+          server: { ws: { send: (msg: unknown) => void } };
+        }) {
+          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 (mirrors dev.ts's `return []`).
+          return [];
+        },
+      },
+    ],
+    optimizeDeps: {
+      // C3 (phase-b/c3-r3f-packaged) — SCOPED auto-discovery, not disabled
+      // discovery. This used to be `noDiscovery: true` (see git history for
+      // the pre-C3 version of this comment): that flag disabled Vite's
+      // AUTO-prebundling entirely — both the boot-time crawl AND the lazy,
+      // on-request discovery of new bare specifiers — because the DEFAULT
+      // crawl target (the project's own `index.html`) follows everything
+      // dynamically reachable from it, including the project's `server/`
+      // room code (a scaffolded project's `src/main.ts` dynamically imports
+      // `../server/rooms` behind a `?net=p2p-host` URL-param branch — a
+      // branch esbuild's scanner still statically follows), whose colyseus
+      // server transitive deps (`@colyseus/core` -> `@pm2/io`) have no
+      // browser-resolvable entry and crash the esbuild prebundle step
+      // (`Failed to resolve entry for package "@pm2/io"`).
+      //
+      // That worked for the react-only CJS fix (C1) because the fix could be
+      // fully hardcoded: react/react-dom are ALWAYS present (the editor
+      // itself depends on them). It does NOT work for R3F (or any other
+      // ecosystem a project's own `package.json` happens to pull in): this
+      // server can't hardcode `@react-three/fiber` into `include` for every
+      // possible project — most projects don't have it installed, and Vite
+      // errors on `include`-ing a dep that isn't there.
+      //
+      // The actual fix: scope the CRAWL, don't disable it. `entries` below
+      // points the crawl at the OPENED PROJECT's own manifest-declared world
+      // entry files (`computeProjectOptimizeDepsEntries` /
+      // `project-optimize-deps-entries.ts`) instead of `index.html` — the
+      // exact per-world mount code the editor's adapter-resolver dynamically
+      // imports for Play mode (NEVER the project's own `src/main.ts`
+      // bootstrap, which is a standalone-build concern this Vite instance
+      // never serves anyway — the editor's own prebuilt SPA answers `/`).
+      // A world entry's import graph can reach real client packages
+      // (`react`, `@react-three/fiber`, `@react-three/drei`, a legitimate
+      // client `@colyseus/sdk` import for real multiplayer) but never
+      // `server/` — see `project-optimize-deps-entries.ts`'s doc comment for
+      // the empirical proof (a direct `vite.optimizeDeps` run) that this
+      // scoping avoids the `@pm2/io` crash for a colyseus-bearing project
+      // while a `@react-three/fiber`-bearing world's CJS transitive deps
+      // (`use-sync-external-store` and friends) get discovered and
+      // prebundled automatically — no allowlist, adapts to whatever the
+      // opened project actually has installed.
+      //
+      // `include` below is now a MINIMUM baseline, not the only mechanism:
+      // React's JSX-runtime specifiers are INJECTED by the JSX transform
+      // (not written as literal source imports), so even an entries-scoped
+      // crawl does not reliably discover them on its own — the repo-root
+      // `vite.config.ts` / template `vite.config.ts` `optimizeDeps.include`
+      // carry the identical comment/list for the same reason. Kept
+      // unconditional (not project-conditional) since react/react-dom are
+      // always present (the editor's own react-world mount runtime depends
+      // on them regardless of what a given project uses).
+      //
+      // `react-dom` (bare, NOT just `/client`) was added for C1
+      // (`phase-b/c1-react-mount`): `vite-plugin-react-world-runtime.ts`'s
+      // synthetic `/__vgai-react-world-runtime` module re-exports `flushSync`
+      // from bare `react-dom` (the same peer `react-dom/client`'s `createRoot`
+      // comes from — `design-time-layers.ts`'s react-world layer mount needs
+      // it from that SAME installed package). Confirmed live at the time:
+      // a real-browser Playwright run against a tarball-installed,
+      // checkout-absent packaged editor threw exactly `SyntaxError: The
+      // requested module '/node_modules/react-dom/index.js' does not
+      // provide an export named 'flushSync'` at Play-mode mount before this
+      // entry was added.
+      include: [
+        'react',
+        'react-dom',
+        'react-dom/client',
+        'react/jsx-runtime',
+        'react/jsx-dev-runtime',
+      ],
+      entries: projectOptimizeDepsEntries,
+      // C3 hardening: belt to the entries-scoping suspenders. Entries-scoping
+      // ALREADY keeps the crawl out of `server/` for a well-formed project
+      // (so the colyseus server stack is never reached), but a project that
+      // VIOLATES D2 by value-importing `server/` room code FROM a world entry
+      // would drag `@colyseus/core` -> `@pm2/io` into the crawl and crash the
+      // esbuild prebundle step — which, unhandled in the async optimizer,
+      // hard-kills the whole packaged process (the only authoring surface).
+      // Excluding these SERVER-ONLY names stops esbuild crawling into them, so
+      // that pathological world degrades to a benign in-browser import failure
+      // instead of process death. Does NOT include `@colyseus/sdk` — the
+      // legitimate CLIENT SDK a real multiplayer project imports (D2, dynamic-
+      // imported) must still prebundle; it is a separate package and its path
+      // is untouched. See `project-optimize-deps-entries.ts`'s
+      // `SERVER_ONLY_PREBUNDLE_EXCLUDE` doc comment for the live proof.
+      exclude: [...SERVER_ONLY_PREBUNDLE_EXCLUDE],
+    },
+    resolve: {
+      alias: [
+        // The `@engine/*` alias project source still uses (pending the
+        // `@engine/*` → `@vgai/engine/*` migration deferred to a follow-up
+        // slice) — pointed at THIS project's own installed engine version,
+        // never a checkout or this editor package's own copy. Omitted
+        // entirely when unresolvable (see the warning above) rather than
+        // pointing at a wrong/nonexistent directory.
+        ...(engineSrc ? [{ find: /^@engine\//, replacement: `${engineSrc}/` }] : []),
+      ],
+    },
+    server: {
+      middlewareMode: true,
+      hmr: { port: HMR_PORT },
+      watch: {},
+      fs: {
+        allow: [projectPath, ...(projectNodeModulesRealPath ? [projectNodeModulesRealPath] : [])],
+      },
+    },
+  });
+
+  // 2. Mount editor API routes (/__editor/*). `engineRoot` has no monorepo
+  //    meaning in packaged mode (no checkout exists) — it's used by
+  //    `createEditorServer` only as (a) the "no project open" sentinel
+  //    default for `projectRoot`, which is never hit here since
+  //    `projectPath` is always set, and (b) `create-project`'s `monoRoot`
+  //    (New Project scaffolding from the in-editor UI — a pre-existing gap
+  //    in packaged mode, see this file's header doc comment). Pointing it at
+  //    this editor package's own root is the closest available analog and
+  //    keeps both uses well-defined rather than pointing at nothing.
+  const editorRouter = createEditorServer({
+    engineRoot: editorPackageRoot,
+    projectPath,
+    onProjectOpened(newProjectPath: string) {
+      const allowed = vite.config.server.fs.allow;
+      if (!allowed.includes(newProjectPath)) {
+        allowed.push(newProjectPath);
+      }
+      vite.watcher.add(newProjectPath);
+      projectRoots.add(newProjectPath);
+      currentProjectRoot = newProjectPath;
+      // Session parity with dev.ts (D12/Phase B): keep the registry pointing
+      // at the CURRENT project so `vgai edit`/`sessions`/cwd-resolution see
+      // switches, not boot state — same call, same shape.
+      registerSession({
+        project: newProjectPath,
+        port: PORT,
+        pid: process.pid,
+        startedAt: sessionStartedAt,
+      });
+    },
+  });
+  app.use(editorRouter);
+
+  // 3. The project-rooted Vite instance — handles `/@fs/`, `/@id/`, and any
+  //    request matching a real file under the project root (module
+  //    transform + bare-specifier resolution through the PROJECT's own
+  //    node_modules). `appType: 'custom'` means it calls `next()` instead of
+  //    synthesizing an HTML/404 response for anything else, so requests for
+  //    the editor's OWN app (`/`, `/assets/*`) fall through to step 4.
+  app.use(vite.middlewares);
+
+  // 4. Serve the editor's own PREBUILT SPA (static — no dev-mode transform
+  //    of the editor's own source; see this file's header doc comment).
+  app.use(express.static(distPath));
+  app.use((_req, res) => {
+    res.sendFile(path.join(distPath, 'index.html'));
+  });
+
+  // 5. Start Express
+  const sessionStartedAt = new Date().toISOString();
+  const server = app.listen(PORT, HOST, () => {
+    console.log(
+      `\n  \x1b[32mEditor server\x1b[0m (packaged) running at \x1b[36mhttp://${HOST}:${PORT}\x1b[0m`,
+    );
+    console.log(`  \x1b[33mProject\x1b[0m: ${projectPath}`);
+    console.log(`  \x1b[33mEditor\x1b[0m: \x1b[36mhttp://${HOST}:${PORT}/\x1b[0m\n`);
+    // D12/Phase B: announce this session so `vgai edit`/`sessions`/`play`
+    // (cwd-resolution) see the packaged runtime exactly like dev.ts's.
+    registerSession({
+      project: projectPath,
+      port: PORT,
+      pid: process.pid,
+      startedAt: sessionStartedAt,
+    });
+  });
+
+  server.on('error', (err: NodeJS.ErrnoException) => {
+    console.error(`\n  \x1b[31m${friendlyListenError(err, PORT, HOST)}\x1b[0m\n`);
+    process.exit(1);
+  });
+
+  const shutdown = () => {
+    unregisterSession(process.pid);
+    vite.close();
+    server.close();
+  };
+  process.once('SIGINT', shutdown);
+  process.once('SIGTERM', shutdown);
+  process.once('exit', () => unregisterSession(process.pid));
+}
+
+main().catch((err) => {
+  console.error('Failed to start packaged editor server:', err);
+  process.exit(1);
+});

package/server/prod.ts

@@ -0,0 +1,75 @@
+/**
+ * Editor production server — Express serves built frontend + API.
+ *
+ * Used by Electron or standalone production deployment.
+ * Run with:
+ *   npx tsx packages/editor/server/prod.ts
+ *
+ * Supports VGAI_PROJECT env var for initial project path.
+ */
+
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import express from 'express';
+import { canonicalProjectRoot } from './canonical-path';
+import { createEditorServer } from './editor-server';
+import { friendlyListenError, resolveBindHost } from './server-utils';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PORT = Number(process.env['PORT']) || 5173;
+// S3: bind to loopback by default; opt-in to a wider interface via env.
+const HOST = resolveBindHost();
+const engineRoot = process.env['VGAI_ENGINE_ROOT']
+  ? path.resolve(process.env['VGAI_ENGINE_ROOT'])
+  : path.resolve(__dirname, '../../..');
+// Canonicalized — see canonical-path.ts's doc comment (dev.ts's sibling fix).
+const projectPath = process.env['VGAI_PROJECT']
+  ? canonicalProjectRoot(process.env['VGAI_PROJECT'])
+  : undefined;
+
+async function main(): Promise<void> {
+  const app = express();
+
+  // 1. Mount editor API routes
+  const editorRouter = createEditorServer({ engineRoot, projectPath, serveScripts: true });
+  app.use(editorRouter);
+
+  // 2. Serve built frontend from dist/
+  const distPath = path.resolve(engineRoot, 'dist');
+  app.use(express.static(distPath));
+
+  // Fallback: serve index.html for unmatched routes (SPA behavior)
+  app.use((_req, res) => {
+    res.sendFile(path.join(distPath, 'index.html'));
+  });
+
+  // 3. Start Express
+  const server = app.listen(PORT, HOST, () => {
+    const addr = server.address();
+    const actualPort = typeof addr === 'object' && addr ? addr.port : PORT;
+    console.log(`\n  \x1b[32mProduction server\x1b[0m running at \x1b[36mhttp://${HOST}:${actualPort}\x1b[0m`);
+    if (projectPath) {
+      console.log(`  \x1b[33mProject\x1b[0m: ${projectPath}`);
+    }
+    console.log();
+    // Machine-readable signal for Electron to detect server readiness
+    console.log(`EDITOR_SERVER_READY:${actualPort}`);
+  });
+
+  // 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);
+  });
+
+  const shutdown = () => {
+    server.close();
+  };
+  process.once('SIGINT', shutdown);
+  process.once('SIGTERM', shutdown);
+}
+
+main().catch((err) => {
+  console.error('Failed to start production server:', err);
+  process.exit(1);
+});