@volter/game-editor 0.5.65

package/template/tsconfig.tools.json

@@ -0,0 +1,22 @@
+{
+  // The editor's lane (src/contributions/**, src/tools/**) — their own program, WITHOUT
+  // src/world.tsx: see the base tsconfig's "exclude" note (fiber's JSX
+  // augmentation must not mix with the editor design-system's polymorphic
+  // primitives these tools import via @editor/*).
+  //
+  // `exclude` MUST be reset here. `extends` inherits the base config's
+  // `exclude: ["src/tools", "src/contributions"]`, and exclude beats include — inheriting it makes
+  // this program compile ZERO files while still exiting 0, so every tool file
+  // is silently untypechecked. `npm run typecheck` cannot tell you: a program
+  // with no files is a PASSING program.
+  //
+  // Tools are NODE code (see src/contributions/module-source.ts's header) — the base
+  // config's browser-only `types: ["vite/client"]` is why they had to be
+  // excluded from it in the first place, so add node here.
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "types": ["vite/client", "node"]
+  },
+  "include": ["src/tools", "src/contributions"],
+  "exclude": []
+}

package/template/validate-asset-content.ts

@@ -0,0 +1,27 @@
+import { readFileSync } from 'node:fs';
+import { InputMapFileSchema } from '@volter/game-runtime/input/schema';
+
+/**
+ * Content validation for the project's structured input-map asset. Models,
+ * materials, animation, images, and audio use their ecosystem-native formats
+ * and are validated by their own loaders/tooling rather than vgai JSON schemas.
+ */
+export const ASSET_CONTENT_EXTENSIONS = ['.inputmap.json'] as const;
+
+export function validateAssetContentFile(path: string): string[] {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(readFileSync(path, 'utf-8'));
+  } catch (reason) {
+    return [`${path}: invalid JSON — ${reason instanceof Error ? reason.message : String(reason)}`];
+  }
+
+  if (!path.endsWith('.inputmap.json')) {
+    throw new Error(
+      `validateAssetContentFile: "${path}" is not a supported structured asset (${ASSET_CONTENT_EXTENSIONS.join(', ')})`,
+    );
+  }
+  const result = InputMapFileSchema.safeParse(raw);
+  if (result.success) return [];
+  return result.error.issues.map((issue) => `${path}: ${issue.path.join('.')}: ${issue.message}`);
+}

package/template/validate-assets.ts

@@ -0,0 +1,60 @@
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { ASSET_CONTENT_EXTENSIONS, validateAssetContentFile } from './validate-asset-content';
+
+// ---------------------------------------------------------------------------
+// Usage: npx tsx validate-assets.ts [folder]
+//
+// Content-parses every fetched-asset file under <folder>/public/ through the
+// engine's own Zod schema — the same one the runtime rejects a malformed
+// input map with, so a present-but-invalid `.inputmap.json` fails here instead
+// of at load. Defaults to the current
+// working directory.
+//
+// Shipped IN the project template so every scaffolded game gets a working
+// `npm run validate-assets`; the engine is imported via the published
+// the runtime packages' subpath exports, which resolve in both this monorepo and a
+// generated project.
+// ---------------------------------------------------------------------------
+
+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);
+}
+
+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;
+}
+
+const errors: string[] = [];
+const assetContentFiles = ASSET_CONTENT_EXTENSIONS.flatMap((ext) => collectFiles(publicDir, ext));
+for (const path of assetContentFiles) {
+  errors.push(...validateAssetContentFile(path));
+}
+
+if (errors.length > 0) {
+  console.error(`Asset validation failed with ${errors.length} error(s):\n`);
+  for (const err of errors) {
+    console.error(`  ${err}`);
+  }
+  process.exit(1);
+} else {
+  console.log(
+    `Validated ${assetContentFiles.length} asset file(s) ` +
+      `(.inputmap.json) in ${rootDir} — all OK`,
+  );
+}

package/template/validate-manifest.ts

@@ -0,0 +1,55 @@
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { contributedKindModulePaths, registerKindModule } from '@volter/editor-project/manifest/kind-modules';
+import { loadGameManifestFile } from '@volter/editor-project/manifest/load-file';
+
+// ---------------------------------------------------------------------------
+// Usage: npx tsx validate-manifest.ts [manifestPath...]
+//
+// Single source of truth for game-manifest validation, shipped IN the
+// project template (mirrors validate-assets.ts) so every scaffolded game
+// gets a working `npm run validate-manifest`. Validates each given
+// `vgai.project.json` path via `loadGameManifestFile` (parse -> cross-field
+// checks -> resolution) and prints the
+// resolved adapter-root list (id, adapter identity) on success. Any failure
+// prints a descriptive error and
+// exits 1.
+//
+// Defaults to THIS template's own manifest (`vgai.project.json`, a sibling of
+// this script) when no path is given, so `npm run validate-manifest` works
+// out of the box both from the monorepo root and from a scaffolded project.
+// ---------------------------------------------------------------------------
+
+const defaultManifestPath = fileURLToPath(new URL('./vgai.project.json', import.meta.url));
+
+const args = process.argv.slice(2);
+const manifestPaths = args.length > 0 ? args.map((p) => resolve(p)) : [defaultManifestPath];
+
+let hadError = false;
+
+for (const manifestPath of manifestPaths) {
+  try {
+    // The project's own configuration kinds register first (ARCHITECTURE-CORE
+    // §The project model): this script runs under tsx, so it can evaluate them.
+    for (const modulePath of contributedKindModulePaths(dirname(manifestPath))) {
+      registerKindModule(await import(pathToFileURL(modulePath).href), modulePath);
+    }
+    const resolved = loadGameManifestFile(manifestPath);
+    console.log(
+      `${manifestPath}: OK — "${resolved.name}" v${resolved.version} (engine ${resolved.engine.version})`,
+    );
+    for (const root of resolved.roots) {
+      console.log(`  root "${root.id}" adapter=${root.adapter.identity}`);
+    }
+  } catch (e) {
+    hadError = true;
+    console.error(`${manifestPath}: FAILED`);
+    console.error(`  ${e instanceof Error ? e.message : String(e)}`);
+  }
+}
+
+if (hadError) {
+  process.exit(1);
+} else {
+  console.log(`Validated ${manifestPaths.length} manifest(s) — all OK`);
+}

package/template/vgai.adapter.ts

@@ -0,0 +1,76 @@
+/**
+ * This game's ADAPTER — the server side of the editor protocol.
+ *
+ * The editor is a universal CLIENT of a fixed protocol, and every game
+ * supplies its own adapter: a statically evaluable binding table mapping this
+ * project's regions to the libraries that serve them, its document table, and
+ * whatever it declares about itself. An adapter's SIZE measures this game's
+ * distance from native — which is why yours fits on a screen.
+ *
+ * Regions are derived mechanically from `vgai.project.json`'s `roots[]` — add
+ * a root to the manifest and its region appears here for free, with no edit to
+ * this file. `regionIncludes` states the PARAMETERS that derivation cannot
+ * produce: which source files each region owns beyond its entry's import reach.
+ * The rule stays selected; only the parameters are declared.
+ *
+ * WHY THAT TABLE IS NOT OPTIONAL. A file's region normally comes from which
+ * root's import closure reaches it — but reach is what the dev server's module
+ * graph holds AT THAT MOMENT, and a prefab opened through its own colocated
+ * story is reached from nothing. The editor stamps one source-id attribute per
+ * file (`userData-oid` for the R3F reconciler, `data-oid` for react-dom), and
+ * `data-oid` on a THREE object is not a degraded stamp: fiber pierces the dash,
+ * writes `object.data`, and THROWS the next time that object is applied to. So
+ * every directory of this game's R3F source says so here, once, and the answer
+ * stops depending on which module the browser asked for first. Add a component
+ * folder that renders R3F and add it to this list; the editor names the file
+ * and this fix (`OID001`/`OID003`) if you forget.
+ *
+ * What else IS stated below is this game's own document table — scenes and
+ * prefabs are its first two kinds; a page, a model, a bake are kinds the same
+ * way — because only
+ * this game knows where its scenes are declared:
+ *
+ *   - `scenesFromEntrypointSelection` reads `src/world.tsx`'s module-level
+ *     `const scenes = { … }` swap slot and answers one entry per key. That
+ *     reference is LOAD-BEARING — the world itself mounts through it — so it
+ *     cannot drift the way a `src/scenes/` folder convention can. Every entry
+ *     becomes a viewport document in the editor, and `default` is the one open
+ *     when the project opens.
+ *   - `prefabsFromStories` reads the colocated portable-CSF stories: a
+ *     component is a placeable prefab exactly when a story's `meta.component`
+ *     names it.
+ *
+ * Drop `selection` (and name no region) for a world that mounts ONE
+ * composition with no swap slot; the finder then answers with the single-scene
+ * degenerate table instead.
+ *
+ * Unknown keys are rejected by name — this file is validated the moment it is
+ * evaluated, so a typo fails here rather than becoming silence in the editor.
+ */
+
+import { defineAdapter } from '@volter/editor-project/adapter/adapter-module';
+
+export default defineAdapter({
+  regionIncludes: {
+    // Every `.tsx` under these folders renders on the `world` root's `three`
+    // surface. Scoped to `.tsx` on purpose: the declaration places JSX modules
+    // on a reconciler, and the plain `.ts` beside them (a capability's math, a
+    // shared state helper an overlay also imports) renders nothing at all.
+    world: {
+      include: [
+        'src/components/**/*.tsx',
+        'src/prefabs/**/*.tsx',
+        'src/scenes/**/*.tsx',
+        'src/lib/reflections/**/*.tsx',
+        'src/lib/static-batch/**/*.tsx',
+      ],
+    },
+  },
+  documents: {
+    find: [
+      { finder: 'scenesFromEntrypointSelection', regions: ['world'], selection: 'scenes' },
+      { finder: 'prefabsFromStories' },
+    ],
+    default: 'main',
+  },
+});

package/template/vgai.project.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "./node_modules/@volter/editor-project/schemas/vgai-project.schema.json",
+  "manifestVersion": 2,
+  "name": "My Game",
+  "appId": "com.example.mygame",
+  "version": "0.1.0",
+  "engine": {
+    "version": "0.5.57"
+  },
+  "resolution": {
+    "width": 1280,
+    "height": 720
+  },
+  "configurations": [
+    { "id": "web", "kind": "bundle", "script": "build", "args": ["--base", "./"] }
+  ],
+  "roots": [
+    {
+      "id": "world",
+      "adapter": "three",
+      "entry": "src/world.tsx"
+    }
+  ]
+}

package/template/vite.config.ts

@@ -0,0 +1,247 @@
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { defineConfig } from 'vite';
+// 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 { manifestEntryModulesPlugin } from './manifest-entry-modules-plugin';
+import manifest from './vgai.project.json';
+
+/** A vgai runtime package served as SOURCE, the way the editor serves it. */
+const packageSource = (name: string) =>
+  path.join(path.dirname(createRequire(import.meta.url).resolve(`${name}/package.json`)), 'src');
+
+/**
+ * Run-4 dry-run friction #2 — auto-detect drvfs the SAME way the editor dev
+ * server does (`packages/editor/server/server-utils.ts`'s
+ * `resolveWatcherPollOptions`, and `dev.ts`'s own `projectOnDrvfs` check):
+ * on WSL, a project living on a Windows drive (`/mnt/<drive>/…`) never fires
+ * inotify, so without polling this standalone server (`npm run dev:standalone`)
+ * silently misses every external file edit — the same failure mode
+ * `dev.ts`'s comment documents for the editor. Before this fix, this file
+ * read ONLY `VGAI_WATCH_POLL`, so a project on drvfs polled in the editor
+ * but NOT in the standalone server — the two disagreed for no reason a
+ * developer could see.
+ *
+ * The editor's server utilities are not part of the project's package
+ * contract, so this
+ * duplicates the tiny drvfs check rather than reaching across a package
+ * boundary that doesn't exist here — same contract as the editor's own
+ * helper: `VGAI_WATCH_POLL=0` forces polling off anywhere, `=1`/`=<ms>`
+ * forces it on with that interval, unset auto-enables on a drvfs mount.
+ */
+function resolveWatchOption(): { usePolling: true; interval: number } | undefined {
+  const raw = process.env['VGAI_WATCH_POLL'];
+  if (raw !== undefined && raw !== '') {
+    if (raw === '0') return undefined;
+    const ms = Number(raw);
+    return { usePolling: true, interval: Number.isFinite(ms) && ms > 1 ? ms : 1000 };
+  }
+  const onDrvfs = process.platform === 'linux' && /^\/mnt\/[a-z]\//i.test(__dirname);
+  return onDrvfs ? { usePolling: true, interval: 1000 } : undefined;
+}
+
+/**
+ * `VITE_ALLOWED_HOSTS` — `all` allows any Host header, a comma list allows
+ * exactly those, unset leaves Vite's own default alone.
+ *
+ * Returned as a SPREADABLE fragment rather than a value, because the "unset"
+ * case must omit the key entirely: this project compiles under
+ * `exactOptionalPropertyTypes`, where `allowedHosts: undefined` is a type
+ * error against `ServerOptions`'s optional `allowedHosts?: true | string[]`.
+ * Vite reads an absent key and an explicitly-undefined one identically, so
+ * the spread is behavior-preserving and the types now agree.
+ */
+function resolveAllowedHosts(): { allowedHosts?: true | string[] } {
+  const raw = process.env['VITE_ALLOWED_HOSTS'];
+  if (raw === 'all') return { allowedHosts: true };
+  const hosts = raw?.split(',').filter(Boolean);
+  return hosts ? { allowedHosts: hosts } : {};
+}
+
+export default defineConfig({
+  // Build-path validation (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).
+  // The AUTOMATIC JSX runtime, set here rather than left to tsconfig.
+  //
+  // This project has no `@vitejs/plugin-react`; Vite's built-in esbuild does
+  // the JSX transform, and it picks the runtime from the tsconfig nearest the
+  // FILE. That covers `src/**`, but the vgai runtime packages are served as
+  // source out of their installed directories (see the aliases below), where
+  // the project's tsconfig does not reach — so their `.tsx` (e.g.
+  // `src/lib/react-root/react-root-adapter.tsx (formerly engine)`) compiled with the CLASSIC runtime, emitting
+  // bare `React.createElement` calls into a module that never imports React.
+  // The scaffold's game page died on `ReferenceError: React is not defined`.
+  esbuild: { jsx: 'automatic' },
+  plugins: [manifestEntryModulesPlugin(manifest)],
+  resolve: {
+    alias: {
+      '@volter/editor-project': packageSource('@volter/editor-project'),
+      '@volter/threejs-runtime': packageSource('@volter/threejs-runtime'),
+      '@volter/game-runtime': packageSource('@volter/game-runtime'),
+    },
+    // react/react-dom dedupe (GH #123): the aliases above resolve
+    // at the SOURCE-LINKED runtime checkout, so when Vite bundles the
+    // game runtime's react bridge module (`src/react/world-state.tsx` — the
+    // `<WorldProvider>` / `useWorldState` HUD bridge), module resolution walks
+    // up from THAT file and finds the CHECKOUT's `node_modules/react` — a
+    // different physical copy (often a different version) than this
+    // project's own. Two Reacts in one page means the Context object
+    // `WorldProvider` creates is not the one this project's tree looks up
+    // via `useContext`, so the documented HUD pattern crashes with "Invalid
+    // hook call" / "Cannot read properties of null (reading 'useContext')"
+    // on first render.
+    // `dedupe` forces Vite to collapse both import paths onto a single
+    // physical copy. Same fix, same reasoning, already applied for the
+    // identical dual-instance failure in this repo's own root
+    // `vite.config.ts` and in `examples/r3f-first-party/vite.config.ts`.
+    // '@react-three/fiber' joined the list with the D24 R3F default world:
+    // `src/world.tsx`'s drei imports and the source-served
+    // `@volter/game-runtime/world3d-react` adapter must agree on ONE fiber instance, or
+    // drei's hooks can't see the adapter's R3F root context and the fiber
+    // crashes pre-commit with "R3F: Hooks can only be used within the
+    // Canvas component!" (standalone-page-only — the editor's own server
+    // already optimizes fiber uniformly; browser-lane proof: 37-template-default-
+    // world's standalone test).
+    dedupe: ['react', 'react-dom', 'three', '@react-three/fiber', 'pixi.js', '@pixi/react'],
+  },
+  optimizeDeps: {
+    // Top-level `esbuild.jsx` does not govern dependency optimization. The
+    // installed `@volter/game-runtime/world3d-react` entry contains TSX, so its cold
+    // prebundle needs the automatic runtime too or it emits a bare `React`.
+    esbuildOptions: { jsx: 'automatic' },
+    // 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 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: [
+      // BARE `react`/`react-dom`, not just the jsx-runtime subpaths below.
+      // The engine is served as SOURCE to a scaffolded project, so Vite's
+      // startup dep scan does not walk far enough to discover engine modules
+      // that do `import { createElement } from 'react'`. Unoptimized, Vite
+      // serves React's raw CJS `index.js`, which has no named ESM exports, and
+      // the game page dies before boot with
+      //   The requested module '/node_modules/react/index.js' does not
+      //   provide an export named 'createElement'
+      // A fresh scaffold + a live bot run hit exactly this against
+      // the published 0.5.1 CLI: the shipped bot failed on its own
+      // scaffold. Listing them here forces the same pre-bundle pass as the
+      // subpaths, which also keeps them in ONE React instance (see `dedupe`
+      // above) rather than a second copy behind a different optimized chunk.
+      'react',
+      'react-dom',
+      'react/jsx-runtime',
+      'react/jsx-dev-runtime',
+      'react-dom/client',
+      // Reached through the generated manifest-entry module after startup;
+      // listing them prevents a first-boot optimizer reload.
+      'three',
+      'zod',
+      // The R3F default world: prebundle fiber and drei in the SAME
+      // optimizer pass so they share one fiber chunk — and so the
+      // source-served `@volter/game-runtime/world3d-react` adapter's bare fiber import
+      // rewrites to that same chunk. Split instances = drei hooks outside
+      // the adapter's root context (see the dedupe note above).
+      '@react-three/fiber',
+      '@react-three/drei',
+    ],
+    // `@volter/game-runtime/runtime/mount-game` must stay SOURCE, or the adapter registry
+    // splits into two instances and nothing mounts.
+    //
+    // The registry is module-level state shared by `mount-game` (which reads
+    // it) and whatever registers a factory into it — for `dom` roots that is
+    // now `src/lib/react-root` (the `react-root` capability), which used to be
+    // the engine package's own `react/root-adapter`.
+    //
+    // The original split: that engine file was a `.tsx` the optimizer REFUSES
+    // ("Cannot optimize dependency"), so it was always served as source, while
+    // `mount-game` is a `.ts` under `node_modules` the optimizer happily
+    // pre-bundled — giving the two halves separate copies of the registry.
+    // `main.ts` registered into one and `mountGameFromManifest` read the
+    // other, so a default scaffold died with `root "ui" has no registered
+    // adapter factory` and rendered an empty page.
+    //
+    // Now that the registering file is PROJECT source, both it and `main.ts`
+    // resolve `@volter/game-runtime/runtime/mount-game` the same way, so the specific split
+    // above can no longer form. The exclusion stays anyway: it is what pins
+    // this registry to ONE instance regardless of which capability registers
+    // into it, and a project that swaps React for Vue here must not have to
+    // rediscover this. Cheap insurance against a failure whose symptom is a
+    // blank page.
+    exclude: ['@volter/game-runtime/runtime/mount-game'],
+  },
+  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 run 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 browser-lane spec to hang waiting on the wrong server. See
+    // packages/editor/e2e/helpers/server.ts's `startStandaloneServer`.
+    strictPort: true,
+    // Poll for file changes instead of relying on inotify — AUTO-ENABLED on
+    // WSL when the project lives on a Windows drive (/mnt/c, drvfs: inotify
+    // never fires there), or edits to src/data/ or src/ generally silently never
+    // hot-reload into the running game.
+    // `VGAI_WATCH_POLL` is an explicit override (`=0` off anywhere, `=1`/
+    // `=<ms>` on anywhere) — see `resolveWatchOption` above, which the
+    // EDITOR dev server's own auto-detect mirrors, so one behavior covers
+    // both surfaces without the developer having to set anything. Safe to
+    // enable here: this standalone server only watches the project tree,
+    // which is small.
+    //
+    // VGAI_NO_WATCH=1 (set by a harness driving this page):
+    // disable watching entirely — a mid-run Vite reload resets
+    // `window.__vgai`/whatever is driving the standalone page out from under
+    // an in-flight run (the hollowstone reload-kills-the-run
+    // lesson). Mutually exclusive with the poll option (same `server.watch`
+    // key) — NO_WATCH wins when both would otherwise apply.
+    ...(process.env['VGAI_NO_WATCH']
+      ? { watch: null }
+      : // Watch source; never watch output: a build (`npm run build`,
+        // `vercel build`) rewriting dist/ or .vercel/output/ inside the
+        // project root would otherwise read as a source change and reload
+        // the page out from under an in-flight run.
+        { watch: { ...resolveWatchOption(), ignored: ['**/.vercel/**', '**/dist/**'] } }),
+    ...resolveAllowedHosts(),
+  },
+  build: {
+    target: 'es2022',
+    // The engine has several independently cacheable heavyweight domains. Keep
+    // them out of one 4+ MiB entry chunk so browsers can fetch/cache them in
+    // parallel and a change to game code does not invalidate every vendor byte.
+    // 2.25 MiB is the measured raw ceiling for the largest unavoidable vendor
+    // domain (Rapier); a game/engine chunk reaching it still warns.
+    chunkSizeWarningLimit: 2304,
+    rollupOptions: {
+      output: {
+        manualChunks(id) {
+          if (!id.includes('/node_modules/')) return undefined;
+          if (id.includes('/@dimforge/rapier3d')) return 'vendor-physics';
+          if (id.includes('/three/') || id.includes('/postprocessing/')) return 'vendor-three';
+          if (id.includes('/three.quarks/') || id.includes('/quarks.core/')) {
+            return 'vendor-particles';
+          }
+          if (id.includes('/recast-navigation')) return 'vendor-navigation';
+          if (id.includes('/react/') || id.includes('/react-dom/') || id.includes('/scheduler/')) {
+            return 'vendor-react';
+          }
+          if (id.includes('/tone/') || id.includes('/standardized-audio-context/')) {
+            return 'vendor-audio';
+          }
+          if (id.includes('/xstate/') || id.includes('/gsap/')) return 'vendor-animation';
+          if (id.includes('/colyseus') || id.includes('/@colyseus/')) return 'vendor-network';
+          return undefined;
+        },
+      },
+    },
+  },
+});

package/template-dotfiles/gitignore

@@ -0,0 +1,63 @@
+# Dependencies
+node_modules
+
+# Build output
+dist/
+dist-server/
+*.local
+
+# Vite cache
+.vite/
+
+# The editor's machine-local state. The rest of .vgai/ (overlays, thumbnail,
+# provenance, generations, assets) is project data and is committed.
+.vgai/editor-state.json
+.vgai/session.json
+.vgai/collaboration.json
+.vgai/workbench.json
+.vgai/captures/
+.vgai/tmp/
+.vgai/last-run/
+.vgai/prev-run/
+.vgai/screenshots/
+.vgai/recordings/
+.vgai/check-idioms.json
+.vgai/tripwire-gate.json
+
+# Session and Play logs
+logs/
+*.jsonl
+
+# Playwright / test output
+test-results/
+playwright-report/
+.playwright-mcp/
+
+# OS junk
+.DS_Store
+Thumbs.db
+
+# Local env files
+.env
+.env.local
+.env.*.local
+
+# ztrack (added by ztrack init)
+.volter/tracker/tracker.sqlite
+.volter/tracker/tracker.sqlite-*
+.volter/tracker/tracker.sqlite.lock
+.volter/tracker/local-store.json
+.volter/agent-dispatch/
+.volter/github/
+.volter/sync/
+.volter/.ztrack-loop.json
+.volter/.ztrack-loop-iter-*
+.volter/.ztrack-loop-exempt-*
+.volter/.ztrack-loop-capped.json
+# ztrack also writes .volter/tracker/.gitignore covering the audit files below.
+# Restated here because npm strips every nested .gitignore from a package
+# tarball (the same fact `restorePackagedTemplateDotfiles` exists for), so a
+# project scaffolded from the PACKAGED editor never receives that file.
+.volter/tracker/.audit.jsonl
+.volter/tracker/.audit-state.json
+.volter/tracker/.audit.lock

package/workbench/src/media/game-cover.css

@@ -0,0 +1,83 @@
+/* THE GAME EDITOR'S OWN SPLASH — what this product draws into the kit's opening cover
+   (`VgaiProduct.cover`, `packages/editor/workbench/src/vgaiCover.ts`).
+
+   IT SPELLS CLASSIC'S PALETTE, for the same reason the model editor's spells Blender's: the
+   cover paints BEFORE any theme extension is registered — the web workbench's first frame is
+   the page config's `initialColorTheme` — so a splash written against `--vscode-*` would wear
+   the workbench's default dark for exactly the seconds it exists instead of this product's
+   look. Classic is the editor's own Graphite and it ships no theme extension at all, so these
+   values come from `@vgai/editor-sdk`'s `widgets/theme.ts`, named beside them:
+
+     #1a1a1a  GRAPHITE_BG[0]        surface.shell — the window's outermost band
+     #242424  GRAPHITE_BG[1]        surface.panel
+     #c5c8ce  GRAPHITE_TEXT[1]      content.primary
+     #9aa0a6  GRAPHITE_TEXT[2]      content.muted
+     #333333  GRAPHITE_BORDER[1]    boundary.default
+     #579eff  GRAPHITE_ACCENT       accent.default
+
+   Nothing here names a font: Classic is the workbench's own UI font, which is what this
+   product wearing no look extension means. */
+
+.vgai-game-cover {
+	position: absolute;
+	inset: 0;
+	display: flex;
+	flex-direction: column;
+	align-items: center;
+	justify-content: center;
+	gap: 10px;
+	background: #1a1a1a;
+	color: #c5c8ce;
+}
+
+/* THE MARK: a play triangle inside the panel surface — the one glyph this product's whole
+   transport is built around. Inline SVG in the product's own markup, so there is no image to
+   fetch and the first frame is the first frame. */
+.vgai-game-cover-mark {
+	width: 56px;
+	height: 56px;
+	opacity: 0.92;
+}
+
+.vgai-game-cover-title {
+	font-size: 26px;
+	font-weight: 600;
+	letter-spacing: 0.02em;
+}
+
+.vgai-game-cover-folder {
+	font-size: 12px;
+	color: #9aa0a6;
+}
+
+/* Indeterminate ON PURPOSE: this product knows WHAT it is waiting for and not how far along it
+   is, and a bar that invented a percentage would be a lie a person can see. */
+.vgai-game-cover-rail {
+	position: relative;
+	width: 220px;
+	height: 2px;
+	margin-top: 6px;
+	overflow: hidden;
+	background: #333333;
+}
+
+.vgai-game-cover-rail::after {
+	content: "";
+	position: absolute;
+	top: 0;
+	bottom: 0;
+	width: 40%;
+	background: #579eff;
+	animation: vgai-game-cover-travel 1.25s ease-in-out infinite;
+}
+
+@keyframes vgai-game-cover-travel {
+	0% { left: -40%; }
+	100% { left: 100%; }
+}
+
+.vgai-game-cover-state {
+	font-size: 11px;
+	min-height: 14px;
+	color: #9aa0a6;
+}