@vgai/editor 0.2.0 → 0.4.0-canary.20260715.0

package/template/tests/logic/room.test.ts

@@ -0,0 +1,100 @@
+/**
+ * L1-equivalent for multiplayer (`docs/ACCEPTANCE-DRIVER-SPEC.md` §2.3's
+ * "Multiplayer lane", Acceptance Driver build plan Task 4.4): boots the
+ * shipped `server/loopback.ts` harness in-process (the REAL `startColyseus`
+ * bootstrap + shipped `GameRoom`, on an ephemeral port — no mocks) and
+ * round-trips ONE message: the `__vgai:debugCommand` handler
+ * (`server/rooms/game-room.ts`), gated open via the `allowDebugCommands` room
+ * option, with a real `@colyseus/sdk` client.
+ */
+
+import { Client, type Room } from '@colyseus/sdk';
+import { afterEach, describe, expect, it } from 'vitest';
+import { type LoopbackColyseus, startLoopbackColyseus } from '../../server/loopback.js';
+
+function withTimeout<T>(promise: Promise<T>, ms: number, label: string): Promise<T> {
+  return Promise.race([
+    promise,
+    new Promise<T>((_, reject) => {
+      setTimeout(() => reject(new Error(`timed out after ${ms}ms waiting for: ${label}`)), ms);
+    }),
+  ]);
+}
+
+describe('game_room debugCommand round-trip over a loopback Colyseus server (no mocks)', () => {
+  let server: LoopbackColyseus | null = null;
+  let room: Room | null = null;
+
+  afterEach(async () => {
+    await room?.leave().catch(() => {});
+    room = null;
+    server?.stop();
+    server = null;
+  });
+
+  it('give-score mutates authoritative state and replies via __vgai:debugCommandResult', async () => {
+    server = await startLoopbackColyseus();
+    const client = new Client(server.url);
+
+    // The room option this room's onCreate reads (server/rooms/game-room.ts)
+    // — off by default, exactly what `vgai probe`/this harness opts into.
+    room = await client.joinOrCreate('game_room', { allowDebugCommands: true });
+
+    const resultPromise = new Promise<{ requestId: string; ok: boolean; result?: unknown }>(
+      (resolve) => {
+        room!.onMessage('__vgai:debugCommandResult', (payload: unknown) => {
+          resolve(payload as { requestId: string; ok: boolean; result?: unknown });
+        });
+      },
+    );
+
+    room.send('__vgai:debugCommand', { name: 'give-score', args: [5], requestId: 'req-1' });
+
+    const reply = await withTimeout(resultPromise, 5000, '__vgai:debugCommandResult');
+    expect(reply.requestId).toBe('req-1');
+    expect(reply.ok).toBe(true);
+    expect(reply.result).toEqual({ score: 5 });
+  }, 15000);
+
+  // AC-A3.2's refusal half (Acceptance Driver build plan Appendix B, D18's
+  // "off otherwise" server-side gate): a plain `npm run server` boot — no
+  // `allowDebugCommands` room option AND no `VGAI_ALLOW_DEBUG_COMMANDS` env
+  // var — must refuse `__vgai:debugCommand` rather than silently execute it.
+  it('refuses __vgai:debugCommand when booted without allowDebugCommands or the env var', async () => {
+    // Defensive: this room's `onCreate` also honors the env var (frozen
+    // decision: env-var OR room-option) — guard against it leaking in from
+    // whatever booted this test process, so the refusal path is actually
+    // exercised rather than accidentally skipped.
+    const previousEnv = process.env['VGAI_ALLOW_DEBUG_COMMANDS'];
+    delete process.env['VGAI_ALLOW_DEBUG_COMMANDS'];
+    try {
+      server = await startLoopbackColyseus();
+      const client = new Client(server.url);
+
+      // No `allowDebugCommands` option at all — the default a plain `npm run
+      // server` boot gets.
+      room = await client.joinOrCreate('game_room', {});
+
+      const resultPromise = new Promise<{ requestId: string; ok: boolean; error?: unknown }>(
+        (resolve) => {
+          room!.onMessage('__vgai:debugCommandResult', (payload: unknown) => {
+            resolve(payload as { requestId: string; ok: boolean; error?: unknown });
+          });
+        },
+      );
+
+      room.send('__vgai:debugCommand', { name: 'give-score', args: [5], requestId: 'req-2' });
+
+      const reply = await withTimeout(resultPromise, 5000, '__vgai:debugCommandResult');
+      expect(reply.requestId).toBe('req-2');
+      expect(reply.ok).toBe(false);
+      expect(reply.error).toBe('debug commands disabled');
+    } finally {
+      if (previousEnv === undefined) {
+        delete process.env['VGAI_ALLOW_DEBUG_COMMANDS'];
+      } else {
+        process.env['VGAI_ALLOW_DEBUG_COMMANDS'] = previousEnv;
+      }
+    }
+  }, 15000);
+});

package/template/tests/tsconfig.json

@@ -0,0 +1,30 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022", "DOM"],
+    // `tests/logic/room.test.ts` (Task 4.4) relatively imports `../../server/
+    // loopback.ts`, which transitively pulls in `server/rooms/*.ts` — those
+    // use `@colyseus/schema`'s `@type(...)` property decorators, which only
+    // type-check under the legacy decorators calling convention (matches
+    // `server/tsconfig.json`'s own flags).
+    "experimentalDecorators": true,
+    "useDefineForClassFields": false,
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noFallthroughCasesInSwitch": true,
+    "noPropertyAccessFromIndexSignature": true,
+    "exactOptionalPropertyTypes": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "verbatimModuleSyntax": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "skipLibCheck": true,
+    "noEmit": true
+  },
+  "include": ["./**/*.ts"]
+}

package/template/validate-manifest.ts

@@ -10,7 +10,7 @@ import { loadGameManifestFile } from '@vgai/engine/manifest/load-file';
 // gets a working `npm run validate-manifest`. Validates each given
 // `vgai.game.json` path via `loadGameManifestFile` (parse -> cross-field
 // checks -> resolution, see docs/GAME-MANIFEST-DESIGN.md §5) and prints the
-// resolved world list (id, kind, resolved adapter identity, per-context
+// resolved adapter-root list (id, adapter identity, per-context
 // capability tiers) on success. Any failure prints a descriptive error and
 // exits 1.
 //
@@ -32,13 +32,13 @@ for (const manifestPath of manifestPaths) {
     console.log(
       `${manifestPath}: OK — "${resolved.name}" v${resolved.version} (engine ${resolved.engine.version})`,
     );
-    for (const world of resolved.worlds) {
-      const { adapter } = world;
+    for (const root of resolved.roots) {
+      const { adapter } = root;
       const adapterLabel =
         adapter.type === 'ingest' ? `${adapter.identity} (${adapter.strategy})` : adapter.identity;
       console.log(
-        `  world "${world.id}" kind=${world.kind} adapter=${adapterLabel} ` +
-          `tiers={local: ${world.capabilities.local}, hosted: ${world.capabilities.hosted}}`,
+        `  root "${root.id}" adapter=${adapterLabel} ` +
+          `tiers={local: ${root.capabilities.local}, hosted: ${root.capabilities.hosted}}`,
       );
     }
   } catch (e) {

package/template/validate-scenes.ts

@@ -6,7 +6,7 @@ import {
   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 type { PrefabFile, SceneEntity, SceneFile } from '@vgai/engine/scene/scene-types';
 import { ASSET_CONTENT_EXTENSIONS, validateAssetContentFile } from './validate-asset-content';
 
 // ---------------------------------------------------------------------------
@@ -30,7 +30,21 @@ import { ASSET_CONTENT_EXTENSIONS, validateAssetContentFile } from './validate-a
 //   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)
+//   3. Components exist in the registry, AND every authored field is one the
+//      component's schema actually declares — run BY DEFAULT (no flag
+//      needed): a leftover scene referencing a component that was renamed or
+//      deleted used to pass "all OK" as long as it was --components-checked
+//      by hand. `src/scripts/registry(.ts)` is imported opportunistically —
+//      if it imports cleanly, component checks run; if it can't be imported
+//      (missing, or a real syntax/type error), ONE line explains that
+//      component-level validation was SKIPPED and why, and the command still
+//      exits 0 on structural success (a broken registry blocks its own
+//      typecheck already; this command must not become a second, confusing
+//      way to learn that).
+//      `--components` upgrades this to STRICT mode: a registry that can't be
+//      imported is then a hard failure (exit 1) instead of a soft skip — for
+//      callers (CI, a pre-release check) that need to assert component
+//      validation definitely ran, not merely attempted.
 // ---------------------------------------------------------------------------
 
 const args = process.argv.slice(2);
@@ -42,29 +56,47 @@ if (!existsSync(publicDir)) {
   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');
+// Component-level validation is opt-OUT (default ON), not opt-in.
+// `--components` only changes what happens when the registry can't be
+// imported: soft-skip (default) vs. hard-fail (strict).
+const strictComponents = 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');
+// The registry path is relative to the root folder being validated.
+const registryPath = join(rootDir, 'src/scripts/registry');
+const hasComponentDocuments =
+  collectFiles(publicDir, '.vscn.json').length > 0 ||
+  collectFiles(publicDir, '.prefab.json').length > 0;
+// React-only projects deliberately have no scene documents or component
+// registry. Silence is the honest result there: there is nothing whose
+// component names could be checked, even in --components mode.
+if (hasComponentDocuments) {
   try {
     const mod = await import(registryPath);
-    componentRegistry = mod.componentRegistry;
-    if (!componentRegistry) {
+    if (mod.componentRegistry) {
+      componentRegistry = mod.componentRegistry;
+    } else if (strictComponents) {
       console.error(`Registry at ${registryPath} does not export "componentRegistry"`);
       process.exit(1);
+    } else {
+      console.warn(
+        `Component-level validation skipped — ${registryPath} does not export "componentRegistry" ` +
+          '(pass --components to make this a hard failure). Continuing with structural checks only.',
+      );
     }
   } catch (e) {
-    console.error(
-      `--components requires a project with src/scripts/registry.ts exporting componentRegistry.\n` +
-        `  Looked in: ${registryPath}\n` +
-        `  Error: ${e}`,
+    if (strictComponents) {
+      console.error(
+        `--components requires a project with src/scripts/registry.ts exporting componentRegistry.\n` +
+          `  Looked in: ${registryPath}\n` +
+          `  Error: ${e}`,
+      );
+      process.exit(1);
+    }
+    console.warn(
+      `Component-level validation skipped — could not import registry at ${registryPath}: ${e} ` +
+        '(pass --components to make this a hard failure). Continuing with structural checks only.',
     );
-    process.exit(1);
   }
 }
 
@@ -149,7 +181,7 @@ for (const path of assetContentFiles) {
 for (const path of sceneFiles) {
   const raw = JSON.parse(readFileSync(path, 'utf-8'));
 
-  let data;
+  let data: SceneFile;
   try {
     data = parseSceneFile(raw);
   } catch (e) {
@@ -177,7 +209,7 @@ for (const path of sceneFiles) {
 for (const path of prefabFiles) {
   const raw = JSON.parse(readFileSync(path, 'utf-8'));
 
-  let data;
+  let data: PrefabFile;
   try {
     data = parsePrefabFile(raw);
   } catch (e) {

package/template/vgai.game.json

@@ -1,21 +1,28 @@
 {
-  "manifestVersion": 1,
-  "name": "my-game",
+  "$schema": "./packages/engine/schemas/vgai-game.schema.json",
+  "manifestVersion": 2,
+  "name": "My Game",
+  "appId": "com.example.mygame",
+  "editorPort": 5173,
   "version": "0.1.0",
   "engine": {
-    "version": "0.2.0"
+    "version": "0.4.0-canary.20260715.0"
   },
-  "worlds": [
-    {
-      "id": "main",
-      "kind": "threejs",
-      "adapter": "default",
-      "entry": "src/scripts/main.ts",
-      "scene": "scenes/default.vscn.json"
-    }
-  ],
   "resolution": {
     "width": 1280,
     "height": 720
-  }
+  },
+  "roots": [
+    {
+      "id": "world",
+      "adapter": "threejs",
+      "scene": "scenes/default.vscn.json"
+    },
+    {
+      "id": "ui",
+      "adapter": "react",
+      "entry": "src/ui/game.tsx",
+      "zOrder": 100
+    }
+  ]
 }

package/template/vite.config.ts

@@ -8,7 +8,9 @@ import { defineConfig } from 'vite';
 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 { manifestEntryModulesPlugin } from './manifest-entry-modules-plugin';
 import { dataAssets } from './src/data/assets';
+import manifest from './vgai.game.json';
 
 // 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
@@ -33,6 +35,41 @@ const p2pAliases = p2pBuild
     }
   : {};
 
+/**
+ * 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 game`)
+ * 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.
+ *
+ * Not a shared import: this file cannot reach
+ * `packages/editor/server/server-utils.ts` the way it reaches the engine
+ * (`../../engine/src/...` above) — a scaffolded project depends on
+ * `@vgai/engine` and gets the CLI scaffolder's engine-relative path rewrite
+ * (`rewriteEngineRelativeFilePath`, `create-vgai-project/src/scaffold.ts`);
+ * there is no equivalent rewrite (or dependency) for the editor's `server/`
+ * code, which is never vendored into a scaffolded project at all. 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;
+}
+
 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
@@ -40,6 +77,7 @@ export default defineConfig({
   // no `src/tools/` module may reach the shipped bundle (§4: tools are
   // editor-only — never serve testers a build with dev/cheat surfaces).
   plugins: [
+    manifestEntryModulesPlugin(manifest),
     vgaiDataCheck({
       root: __dirname,
       assets: dataAssets.map((a) => ({
@@ -53,6 +91,22 @@ export default defineConfig({
       '@engine': path.resolve(__dirname, '../../engine/src'),
       ...p2pAliases,
     },
+    // react/react-dom dedupe (GH #123): the '@engine' alias above resolves
+    // at the SOURCE-LINKED engine checkout, so when Vite bundles the
+    // engine's react bridge module (`src/react/game-state.tsx` — the
+    // `<GameProvider>` / `useGameState` 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
+    // `GameProvider` 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-probe/vite.config.ts`.
+    dedupe: ['react', 'react-dom'],
   },
   optimizeDeps: {
     // Pre-bundle deps that are only reached through the dynamically imported
@@ -94,22 +148,29 @@ export default defineConfig({
     // 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,
-          },
-        }
-      : {}),
+    // 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/*.data.json silently never
+    // hot-reload into the running game (docs/DATA-TOOLS-DESIGN.md §2.3).
+    // `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 (`vgai probe`, Acceptance Driver build plan Task 4.1):
+    // disable watching entirely — a mid-run Vite reload resets
+    // `window.__vgai`/whatever is driving the standalone page out from under
+    // an in-flight acceptance 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 }
+      : (() => {
+          const watch = resolveWatchOption();
+          return watch ? { watch } : {};
+        })()),
     allowedHosts:
       process.env.VITE_ALLOWED_HOSTS === 'all'
         ? true