@vgai/editor 0.2.0

package/template/validate-scenes.ts

@@ -0,0 +1,211 @@
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { collectAssetPaths } from '@vgai/engine/scene/asset-paths';
+import {
+  type ComponentRegistry,
+  isGameComponentClass,
+} from '@vgai/engine/scene/component-registry';
+import { parsePrefabFile, parseSceneFile, SceneParseError } from '@vgai/engine/scene/parse';
+import type { SceneEntity } from '@vgai/engine/scene/scene-types';
+import { ASSET_CONTENT_EXTENSIONS, validateAssetContentFile } from './validate-asset-content';
+
+// ---------------------------------------------------------------------------
+// Usage: npx tsx validate-scenes.ts [folder] [--components]
+//
+// Single source of truth for scene validation, shipped IN the project template so
+// every scaffolded game gets a working `npm run validate-scenes` (the engine is
+// imported via the published `@vgai/engine/*` subpath exports, which resolve in
+// both this monorepo and a generated project — unlike the old `../scripts/...`
+// path that only existed inside the monorepo).
+//
+// Validates all .vscn.json and .prefab.json files found recursively under
+// <folder>/public/ — plus all .mat.json/.inputmap.json/
+// .instances.json files, CONTENT-parsed through the engine's asset-content
+// Zod schemas the runtime rejects them with (previously these formats were
+// only existence-checked when a scene referenced them; a present-but-
+// malformed asset passed this command and failed at load).
+// Defaults to the current working directory.
+//
+// Checks:
+//   1. Structural validity (Zod schema parse) — scenes, prefabs, AND the
+//      fetched-asset formats (.mat.json/.inputmap.json/.instances.json)
+//   2. Asset references point to files that exist on disk
+//   3. Components exist in the registry (if --components flag provided)
+// ---------------------------------------------------------------------------
+
+const args = process.argv.slice(2);
+const rootDir = resolve(args[0] ?? '.');
+const publicDir = join(rootDir, 'public');
+
+if (!existsSync(publicDir)) {
+  console.error(`No public/ directory found in ${rootDir}`);
+  process.exit(1);
+}
+
+// Optionally load component registry for component-level validation.
+// Pass --components to enable (requires boilerplate examples to be available).
+const validateComponents = args.includes('--components');
+let componentRegistry: ComponentRegistry | null = null;
+
+if (validateComponents) {
+  // Import the project's component registry.
+  // The registry path is relative to the root folder being validated.
+  const registryPath = join(rootDir, 'src/scripts/registry');
+  try {
+    const mod = await import(registryPath);
+    componentRegistry = mod.componentRegistry;
+    if (!componentRegistry) {
+      console.error(`Registry at ${registryPath} does not export "componentRegistry"`);
+      process.exit(1);
+    }
+  } catch (e) {
+    console.error(
+      `--components requires a project with src/scripts/registry.ts exporting componentRegistry.\n` +
+        `  Looked in: ${registryPath}\n` +
+        `  Error: ${e}`,
+    );
+    process.exit(1);
+  }
+}
+
+// ---------------------------------------------------------------------------
+
+function collectFiles(dir: string, ext: string): string[] {
+  const result: string[] = [];
+  if (!existsSync(dir)) return result;
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    if (statSync(full).isDirectory()) {
+      result.push(...collectFiles(full, ext));
+    } else if (entry.endsWith(ext)) {
+      result.push(full);
+    }
+  }
+  return result;
+}
+
+function validateEntity(
+  entity: SceneEntity,
+  registry: ComponentRegistry,
+  file: string,
+  errors: string[],
+): void {
+  if (entity.components) {
+    for (const [name, data] of Object.entries(entity.components)) {
+      const Klass = registry[name];
+      if (!Klass) {
+        errors.push(`${file}: entity "${entity.name}" has unknown component "${name}"`);
+        continue;
+      }
+      // GameComponent v2: a registry entry is a GameComponentClass whose editable
+      // fields are declared on its `static schema` (a Zod object). Derive the valid
+      // field names from the schema's shape. Components with no schema (tag
+      // components like Player) accept no fields.
+      const validFields =
+        isGameComponentClass(Klass) && Klass.schema ? Object.keys(Klass.schema.shape) : [];
+      for (const field of Object.keys(data)) {
+        if (!validFields.includes(field)) {
+          errors.push(
+            `${file}: entity "${entity.name}" component "${name}" has unknown field "${field}" (valid: ${validFields.join(', ') || '(none)'})`,
+          );
+        }
+      }
+    }
+  }
+  if (entity.children) {
+    for (const child of entity.children) {
+      validateEntity(child, registry, file, errors);
+    }
+  }
+}
+
+function validateAssetPaths(assetPaths: Set<string>, file: string, errors: string[]): void {
+  for (const assetPath of assetPaths) {
+    const diskPath = join(publicDir, assetPath.replace(/^\//, ''));
+    if (!existsSync(diskPath)) {
+      errors.push(`${file}: broken asset reference "${assetPath}" — file not found`);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+
+const errors: string[] = [];
+
+const sceneFiles = collectFiles(publicDir, '.vscn.json');
+const prefabFiles = collectFiles(publicDir, '.prefab.json');
+const totalFiles = sceneFiles.length + prefabFiles.length;
+
+// Content-parse the three fetched-asset formats through their engine Zod
+// schemas (previously only existence-checked, and only when referenced by
+// a scene — a present-but-malformed .mat/.inputmap file passed
+// this command and failed at runtime fetch).
+const assetContentFiles = ASSET_CONTENT_EXTENSIONS.flatMap((ext) => collectFiles(publicDir, ext));
+for (const path of assetContentFiles) {
+  errors.push(...validateAssetContentFile(path));
+}
+
+// Validate scene files
+for (const path of sceneFiles) {
+  const raw = JSON.parse(readFileSync(path, 'utf-8'));
+
+  let data;
+  try {
+    data = parseSceneFile(raw);
+  } catch (e) {
+    if (e instanceof SceneParseError) {
+      for (const issue of e.issues) {
+        errors.push(`${path}: ${issue.path.join('.')}: ${issue.message}`);
+      }
+    } else {
+      errors.push(`${path}: ${e}`);
+    }
+    continue;
+  }
+
+  if (componentRegistry) {
+    for (const entity of data.entities) {
+      validateEntity(entity, componentRegistry, path, errors);
+    }
+  }
+
+  const assetPaths = collectAssetPaths(data.entities, data.environment);
+  validateAssetPaths(assetPaths, path, errors);
+}
+
+// Validate prefab files
+for (const path of prefabFiles) {
+  const raw = JSON.parse(readFileSync(path, 'utf-8'));
+
+  let data;
+  try {
+    data = parsePrefabFile(raw);
+  } catch (e) {
+    if (e instanceof SceneParseError) {
+      for (const issue of e.issues) {
+        errors.push(`${path}: ${issue.path.join('.')}: ${issue.message}`);
+      }
+    } else {
+      errors.push(`${path}: ${e}`);
+    }
+    continue;
+  }
+
+  const assetPaths = collectAssetPaths([data.root]);
+  validateAssetPaths(assetPaths, path, errors);
+}
+
+// ---------------------------------------------------------------------------
+
+if (errors.length > 0) {
+  console.error(`Scene validation failed with ${errors.length} error(s):\n`);
+  for (const err of errors) {
+    console.error(`  ${err}`);
+  }
+  process.exit(1);
+} else {
+  console.log(
+    `Validated ${totalFiles} scene/prefab file(s) and ${assetContentFiles.length} asset file(s) ` +
+      `(.mat/.inputmap/.instances) in ${rootDir} — all OK`,
+  );
+}

package/template/vgai.game.json

@@ -0,0 +1,21 @@
+{
+  "manifestVersion": 1,
+  "name": "my-game",
+  "version": "0.1.0",
+  "engine": {
+    "version": "0.2.0"
+  },
+  "worlds": [
+    {
+      "id": "main",
+      "kind": "threejs",
+      "adapter": "default",
+      "entry": "src/scripts/main.ts",
+      "scene": "scenes/default.vscn.json"
+    }
+  ],
+  "resolution": {
+    "width": 1280,
+    "height": 720
+  }
+}

package/template/vite.config.ts

@@ -0,0 +1,128 @@
+import path from 'path';
+import { defineConfig } from 'vite';
+// ENGINE-RELATIVE import, deliberately NOT '@vgai/engine/data/vite-plugin-data'
+// (the scaffolder rewrites this path to each project's engine location): Vite's
+// config loader (esbuild) only BUNDLES relative imports — a bare specifier is
+// externalized and loaded by plain node at config time, which cannot load the
+// engine's shipped TypeScript (ERR_UNKNOWN_FILE_EXTENSION: .ts).
+import { vgaiDataCheck } from '../../engine/src/data/vite-plugin-data';
+// Config-relative TS imports get bundled the same way — that is what lets the
+// project's executable Zod schemas reach the build-time check below.
+import { dataAssets } from './src/data/assets';
+
+// P2P builds (launched with `?net=p2p-host` / `?net=p2p-join`) route the Colyseus
+// packages onto @vgai/p2p-colyseus's browser-safe compat shims: `browser.ts` exposes
+// `configureP2PColyseusClient`, and `platform.ts` stands in for the node-only
+// `colyseus`/`@colyseus/core` server runtime so `../server/rooms` can be imported
+// into the browser for the in-page host.
+//
+// Default builds must NOT alias — they resolve the REAL Colyseus SDK from
+// node_modules so `net.connect('ws://…')` speaks the real Colyseus wire protocol
+// to a `npm run server` Colyseus server. The compat client's `ws://` branch speaks
+// its own JSON envelope protocol, so aliasing unconditionally silently breaks every
+// non-P2P multiplayer game. Gate per docs/P2P-COLYSEUS-MIGRATION.md Rule 5:
+// "Alias Colyseus packages to @vgai/p2p-colyseus only in P2P builds."
+const p2pBuild = process.env.VGAI_P2P === '1' || process.env.VGAI_P2P === 'true';
+
+const p2pAliases = p2pBuild
+  ? {
+      '@colyseus/sdk': path.resolve(__dirname, '../../p2p-colyseus/src/browser.ts'),
+      '@colyseus/schema': path.resolve(__dirname, '../../p2p-colyseus/src/schema.ts'),
+      '@colyseus/core': path.resolve(__dirname, '../../p2p-colyseus/src/platform.ts'),
+      colyseus: path.resolve(__dirname, '../../p2p-colyseus/src/platform.ts'),
+    }
+  : {};
+
+export default defineConfig({
+  // Build-path validation (docs/DATA-TOOLS-DESIGN.md §6.7, build-only): every
+  // registered data asset must still parse through its schema (the EXACT
+  // parse defineData runs at load), every `"file#key"` ref must resolve, and
+  // no `src/tools/` module may reach the shipped bundle (§4: tools are
+  // editor-only — never serve testers a build with dev/cheat surfaces).
+  plugins: [
+    vgaiDataCheck({
+      root: __dirname,
+      assets: dataAssets.map((a) => ({
+        schema: a.schema,
+        sourcePath: `src/data/${a.name}.data.json`,
+      })),
+    }),
+  ],
+  resolve: {
+    alias: {
+      '@engine': path.resolve(__dirname, '../../engine/src'),
+      ...p2pAliases,
+    },
+  },
+  optimizeDeps: {
+    // Pre-bundle deps that are only reached through the dynamically imported
+    // example modules (or injected by the JSX transform, like the React
+    // runtimes) so Vite does not discover them at runtime, re-optimize, and
+    // hard-reload the standalone runtime the first time a game selects them —
+    // that mid-session reload resets `window.__vgaiScene`/the menu out from
+    // under whatever is driving the page (the e2e dep-optimize-reload flake the
+    // 04 spec hit: the first cold select of `editor-tutorial` reloaded on
+    // `react/jsx-dev-runtime`). Verified against a cold scaffold: with these
+    // listed, a full sweep of the switcher games triggers zero page reloads.
+    include: [
+      'gsap',
+      'react/jsx-runtime',
+      'react/jsx-dev-runtime',
+      'react-dom/client',
+      'postprocessing',
+      'three.quarks',
+      'quarks.core',
+      '@dimforge/rapier3d-compat',
+    ],
+    // In a default (non-P2P) build, `main.ts`'s `?net=p2p-host` branch statically
+    // references `import('../server/rooms')` — server room classes that pull the
+    // node-only `colyseus`/`@colyseus/core` runtime (which imports `@pm2/io`). That
+    // branch never executes without `?net=p2p-host`, but vite's dep pre-bundler
+    // still follows the dynamic import while scanning and crashes trying to bundle
+    // the server runtime for the browser. Excluding the server-only packages makes
+    // scanning them a no-op; the branch stays inert at runtime. In P2P builds the
+    // alias above already routes these names to browser-safe shims, so no exclude.
+    ...(p2pBuild ? {} : { exclude: ['colyseus', '@colyseus/core'] }),
+  },
+  server: {
+    port: 5180,
+    // Fail loudly instead of silently rebinding to 5181+ if 5180 is still
+    // held by a lingering prior instance. Without this, a stale server left
+    // over from an earlier e2e spec file answers the NEW server's readiness
+    // probe (which targets the fixed 5180 URL) while the real new instance
+    // sits on a different port nobody is talking to -- a hazard previously
+    // observed causing a CI e2e spec to hang waiting on the wrong server. See
+    // packages/editor/e2e/helpers/server.ts's `startStandaloneServer`.
+    strictPort: true,
+    // VGAI_WATCH_POLL=1 (or =<ms>): poll for file changes instead of relying
+    // on inotify — REQUIRED on WSL when the project lives on a Windows drive
+    // (/mnt/c, drvfs: inotify never fires there), or edits to
+    // src/data/*.data.json silently never hot-reload into the running game
+    // (docs/DATA-TOOLS-DESIGN.md §2.3). Same env var the EDITOR dev server
+    // honors, so one knob covers both surfaces. Safe to enable here: this
+    // standalone server only watches the project tree, which is small.
+    ...(process.env.VGAI_WATCH_POLL
+      ? {
+          watch: {
+            usePolling: true,
+            interval:
+              Number(process.env.VGAI_WATCH_POLL) > 1 ? Number(process.env.VGAI_WATCH_POLL) : 1000,
+          },
+        }
+      : {}),
+    allowedHosts:
+      process.env.VITE_ALLOWED_HOSTS === 'all'
+        ? true
+        : process.env.VITE_ALLOWED_HOSTS?.split(',').filter(Boolean),
+  },
+  build: {
+    target: 'es2022',
+    // Same story as optimizeDeps.exclude above, but for the PRODUCTION build:
+    // rollup follows `main.ts`'s `import('../server/rooms')` and dies resolving
+    // the node-only colyseus runtime (`@pm2/io`) for the browser. Externalizing
+    // it leaves a bare dynamic `import('colyseus')` in the never-executed
+    // ?net=p2p-host branch (guarded by `configureP2PColyseusClient`, which only
+    // exists in aliased P2P builds). P2P builds resolve via the alias instead.
+    ...(p2pBuild ? {} : { rollupOptions: { external: ['colyseus', '@colyseus/core'] } }),
+  },
+});

package/vite-plugin-example-assets.ts

@@ -0,0 +1,60 @@
+/**
+ * vite-plugin-example-assets — copy every `examples/<id>/public/*` (repo root)
+ * into the `--mode web` build's output under `<outDir>/examples/<id>/...`, so
+ * a bundled example's relative asset fetches (e.g. `models/LittlestTokyo.glb`)
+ * resolve once namespaced by `setAssetPrefix('/examples/<id>/')` (see
+ * `packages/editor/src/browser-play-entry.ts`).
+ *
+ * Since each `examples/<id>/` (T3.5/D11 — docs/EXAMPLES-AS-PROJECTS-DESIGN.md
+ * §4) is now an independent sibling package, not a shared package tree, each example's
+ * OWN `public/` would otherwise collide at a flat deploy root (two examples
+ * both shipping a `models/` folder). Namespacing under `/examples/<id>/`
+ * mirrors `scripts/bundle-project-scripts.mjs`'s per-example dispatch id.
+ *
+ * Build-only, `--mode web` only (see `projectScriptsBundlePlugin` in
+ * vite.config.ts — same gating). Copies in `closeBundle` (not `buildStart` —
+ * the build's `outDir` doesn't exist yet at that point; not `writeBundle`
+ * either, to run strictly after Vite's own `publicDir` copy so our
+ * `examples/` subtree is never raced/clobbered) — verified empirically via
+ * `npm run build:web` producing `dist/examples/<id>/...`.
+ */
+import { cpSync, existsSync, mkdirSync, readdirSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+import type { Plugin, ResolvedConfig } from 'vite';
+
+export function exampleAssetsPlugin(repoRoot: string): Plugin {
+  let resolvedConfig: ResolvedConfig;
+  return {
+    name: 'vgai:example-assets',
+    apply: 'build',
+    configResolved(config) {
+      resolvedConfig = config;
+    },
+    closeBundle() {
+      const examplesDir = resolve(repoRoot, 'examples');
+      const outDir = isAbsolute(resolvedConfig.build.outDir)
+        ? resolvedConfig.build.outDir
+        : resolve(resolvedConfig.root, resolvedConfig.build.outDir);
+
+      if (!existsSync(examplesDir)) return;
+      const folderIds = readdirSync(examplesDir, { withFileTypes: true })
+        .filter((d) => d.isDirectory())
+        .map((d) => d.name)
+        .sort();
+
+      for (const id of folderIds) {
+        const publicDir = join(examplesDir, id, 'public');
+        const manifest = join(examplesDir, id, 'vgai.game.json');
+        const dest = join(outDir, 'examples', id);
+        // some examples ship no assets of their own
+        if (existsSync(publicDir)) cpSync(publicDir, dest, { recursive: true });
+        // The manifest is what `?project=<id>` routing resolves a deep link
+        // against (hosted-example.ts) — stage it beside the public/ contents.
+        if (existsSync(manifest)) {
+          mkdirSync(dest, { recursive: true });
+          cpSync(manifest, join(dest, 'vgai.game.json'));
+        }
+      }
+    },
+  };
+}

package/vite-plugin-game-globals.ts

@@ -0,0 +1,46 @@
+/**
+ * The `vgai-game-globals` transform — prepends `GAME_GLOBALS_PRELUDE` to game
+ * source so raw `window`/`document` input listeners resolve to the gated proxies
+ * (`gated-globals.ts`) instead of the real globals, making them focus-gated.
+ *
+ * Shared by BOTH Vite configs, which is the point:
+ *   - `server/dev.ts` registers it over an opened project's root PLUS the
+ *     same-realm ingest-fixture roots;
+ *   - the repo-root `vite.config.ts` registers it over the ingest-fixture roots
+ *     alone, which is what the hosted `--mode web` static build needs. Before
+ *     this existed the plugin lived only in `dev.ts`, so a same-realm ingested
+ *     game ran UNSHADOWED in the hosted editor — its input listeners fired
+ *     regardless of editor focus. The browser-side analogue of this seam is
+ *     `applyGameGlobalsShadow` (`browser-transpile.ts`, A3).
+ *
+ * `dev.ts` builds its Vite server with `configFile: <repo-root>/vite.config.ts`
+ * AND adds its own plugins, so in dev BOTH registrations are live and both
+ * `transform` hooks see the ingest-fixture modules. The prelude check below is
+ * what makes that safe: whichever runs first prepends, the other sees the
+ * prelude already there and no-ops. Prepending twice would shadow the shadow —
+ * the inner `const window` would resolve to the outer `const window` rather than
+ * to the gated proxy — and `const` redeclaration in one scope is a SyntaxError
+ * besides.
+ */
+import type { Plugin } from 'vite';
+import { shouldShadowGameGlobals } from './server/game-globals-shadow';
+// The DOM-free prelude module, NOT `src/gated-globals.ts`: this file is reachable
+// from `tsconfig.server.json` (via `server/dev.ts`), which compiles without the
+// DOM lib and so cannot see `window`/`document`/`EventListenerOrEventListenerObject`.
+import { GAME_GLOBALS_PRELUDE } from './src/game-globals-prelude';
+
+/**
+ * `getRoots` is a thunk, not a snapshot: `dev.ts` mutates its root set when a
+ * project opens after boot (`onProjectOpened`), and the transform must see that.
+ */
+export function gameGlobalsShadowPlugin(getRoots: () => Iterable<string>): Plugin {
+  return {
+    name: 'vgai-game-globals',
+    transform(code: string, id: string) {
+      const file = id.split('?')[0]!;
+      if (!shouldShadowGameGlobals(file, getRoots())) return null;
+      if (code.startsWith(GAME_GLOBALS_PRELUDE)) return null; // already shadowed
+      return { code: GAME_GLOBALS_PRELUDE + code, map: null };
+    },
+  };
+}

package/vite-plugin-game-static.ts

@@ -0,0 +1,71 @@
+/**
+ * vite-plugin-game-static — serve vendored real-game build output VERBATIM (no vite
+ * transform) so an externalized game bundle keeps its bare `import 'pixi.js'` specifiers
+ * (resolved by the iframe importmap, not rewritten to /node_modules/.vite/deps) and its
+ * AssetPack `.json` spritesheets stay raw JSON (not converted to ESM modules).
+ *
+ * Requests to `/pixi-game-static/<id>/<path>` are served from
+ * `vendor/pixi-games/_host/<id>-dist/<path>` with a correct content-type and zero
+ * transformation. This is pure HOST wiring — it never touches the vendored game source.
+ */
+import { readFile } from 'node:fs/promises';
+import { extname, join, normalize, resolve } from 'node:path';
+import type { Plugin } from 'vite';
+
+// Exported so `vite-plugin-project-game-static.ts` (D-X2, the external-folder
+// verbatim-serving sibling of this plugin) reuses the SAME MIME table rather
+// than drifting a second copy — both plugins serve the identical class of
+// content (a pixi bundle + AssetPack JSON + image/audio/font assets), just
+// rooted at a different directory.
+export const MIME: Record<string, string> = {
+  '.mjs': 'text/javascript',
+  '.js': 'text/javascript',
+  '.json': 'application/json',
+  '.png': 'image/png',
+  '.webp': 'image/webp',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.svg': 'image/svg+xml',
+  '.mp3': 'audio/mpeg',
+  '.ogg': 'audio/ogg',
+  '.wav': 'audio/wav',
+  '.woff2': 'font/woff2',
+  '.woff': 'font/woff',
+  '.ttf': 'font/ttf',
+};
+
+export function gameStaticPlugin(repoRoot: string): Plugin {
+  const distRoot = resolve(repoRoot, 'vendor/pixi-games/_host');
+  return {
+    name: 'vgai-game-static',
+    configureServer(server) {
+      server.middlewares.use('/pixi-game-static', async (req, res, next) => {
+        try {
+          const url = (req.url ?? '').split('?')[0] ?? '';
+          // url is like /<id>/<path...>
+          const m = /^\/([^/]+)\/(.+)$/.exec(url);
+          if (!m) return next();
+          // Both groups are guaranteed present by the regex match above
+          // (two required capture groups) — `noUncheckedIndexedAccess`
+          // types tuple-destructured array elements as possibly-undefined
+          // regardless, so assert what the match already proved.
+          const id = m[1]!;
+          const rel = m[2]!;
+          const filePath = normalize(join(distRoot, `${id}-dist`, rel));
+          // path-traversal guard: stay inside distRoot
+          if (!filePath.startsWith(distRoot)) {
+            res.statusCode = 403;
+            return res.end('forbidden');
+          }
+          const buf = await readFile(filePath);
+          res.setHeader('Content-Type', MIME[extname(filePath)] ?? 'application/octet-stream');
+          res.setHeader('Cache-Control', 'no-cache');
+          res.statusCode = 200;
+          res.end(buf);
+        } catch {
+          next();
+        }
+      });
+    },
+  };
+}

package/vite-plugin-project-game-static.ts

@@ -0,0 +1,84 @@
+/**
+ * vite-plugin-project-game-static — D-X2
+ * (docs/EXTERNAL-FOLDER-INGEST-DESIGN.md §2/§6 slice S1): the external-folder
+ * sibling of `vite-plugin-game-static.ts`. Serves the CURRENTLY OPEN
+ * project's own folder VERBATIM (no vite transform) at
+ * `/project-game-static/<path>` -> `<projectRoot>/<path>`, so an external
+ * pixi game's manifest can point `bundleUrl`/`assetBaseUrl`/`pixiModuleUrl`
+ * at a route that keeps its bare `import 'pixi.js'` un-rewritten (resolved by
+ * the iframe importmap instead) and its AssetPack `.json` spritesheets raw —
+ * the SAME R-X1 rationale `vite-plugin-game-static.ts`'s header records for
+ * the vendored-dist route, just rooted at an arbitrary user folder instead of
+ * `vendor/pixi-games/_host`.
+ *
+ * `getProjectRoot` is a THUNK, not a captured string: `open-project` can
+ * switch the current project live (`server/dev.ts`'s `onProjectOpened`
+ * callback), and this route must follow the CURRENT project root, not a
+ * boot-time snapshot — every request re-reads it. No project open (thunk
+ * returns `undefined`) -> `next()`, never a 5xx.
+ *
+ * `configureServer`-only (local dev server; hosted/browser mode is out of
+ * scope by construction — both manifest ingest routes already short-circuit
+ * on `getEditorMode() === 'browser'` before ever building a URL that would
+ * point here, `ingest-mode.ts:944,994`).
+ */
+import { readFile } from 'node:fs/promises';
+import { extname, join, normalize, resolve, sep } from 'node:path';
+import type { Plugin } from 'vite';
+import { MIME } from './vite-plugin-game-static';
+
+/**
+ * Resolve `rel` against `projectRoot`, refusing anything that escapes it.
+ * Plain `startsWith(root)` would wrongly admit a sibling folder that merely
+ * shares `root` as a string prefix (e.g. root `/a/b` and filePath `/a/bc/evil`)
+ * — the boundary must fall on a real path separator (or be an exact match).
+ * Returns `null` for an escape attempt.
+ */
+function resolveInsideProjectRoot(projectRoot: string, rel: string): string | null {
+  const root = resolve(projectRoot);
+  const filePath = normalize(join(root, rel));
+  if (filePath === root || filePath.startsWith(root + sep)) return filePath;
+  return null;
+}
+
+/** `req.url`'s path portion (query stripped), project-root-relative (leading
+ *  slash removed). Empty for the bare mount path (`/project-game-static`
+ *  itself, with nothing after it). */
+function requestRelPath(url: string | undefined): string {
+  // `.split('?')` always yields at least one element — `noUncheckedIndexedAccess`
+  // types index access as possibly-undefined regardless, so fall back to ''.
+  const path = (url ?? '').split('?')[0] ?? '';
+  return path.startsWith('/') ? path.slice(1) : path;
+}
+
+export function projectGameStaticPlugin(getProjectRoot: () => string | undefined): Plugin {
+  return {
+    name: 'vgai-project-game-static',
+    configureServer(server) {
+      server.middlewares.use('/project-game-static', async (req, res, next) => {
+        const projectRoot = getProjectRoot();
+        if (!projectRoot) return next(); // no project open — nothing to serve
+
+        const rel = requestRelPath(req.url);
+        if (!rel) return next();
+
+        const filePath = resolveInsideProjectRoot(projectRoot, rel);
+        if (!filePath) {
+          res.statusCode = 403;
+          res.end('forbidden');
+          return;
+        }
+
+        try {
+          const buf = await readFile(filePath);
+          res.setHeader('Content-Type', MIME[extname(filePath)] ?? 'application/octet-stream');
+          res.setHeader('Cache-Control', 'no-cache');
+          res.statusCode = 200;
+          res.end(buf);
+        } catch {
+          next();
+        }
+      });
+    },
+  };
+}