@vgai/engine 0.5.2 → 0.5.3

package/src/manifest/schema.ts

@@ -1,12 +1,11 @@
-// T3.1 slice 1 — the game manifest schema (`vgai.game.json`).
+// T3.1 slice 1 — the game manifest schema (`vgai.project.json`).
 //
-// This is the serialized form of the Game's root list
-// (docs/GAME-ROOT-DESIGN.md §1, D6) — see docs/GAME-MANIFEST-DESIGN.md §3 for
-// the adjudicated field list this file implements exactly. `load.ts` is this
-// schema's runtime reader (T4.1 policy): it parses via this schema, then
-// layers the cross-field checks and default resolution §3/§5 describe. Every
-// field below has a `.describe()` (repo policy — powers
-// `scripts/generate-schema.ts` and the T4.1 schema-walk coverage test).
+// This is the serialized form of the Game's root list for the adjudicated
+// field list this file implements exactly. `load.ts` is this schema's runtime
+// reader (T4.1 policy): it parses via this schema, then layers the
+// cross-field checks and default resolution §3/§5 describe. Every field below
+// has a `.describe()` (repo policy — powers `scripts/generate-schema.ts` and
+// the T4.1 schema-walk coverage test).
 //
 // Naming: this file follows the repo's `XxxSchema` (Zod schema) / `Xxx`
 // (inferred type) convention used throughout `scene/schema/` — the design
@@ -18,19 +17,19 @@
 // inferred types, matching every other schema file in the repo.
 //
 // Adapter surface values mirror `AdapterSurface` in
-// `packages/engine/src/runtime/game.ts` (`'threejs' | 'pixijs' | 'react'`)
+// `packages/engine/src/runtime/game.ts` (`'three' | 'canvas' | 'dom'`)
 // by value, not by import. The adapter remains the sole root discriminator.
 
 import { z } from 'zod';
 
 /**
- * Current on-disk `vgai.game.json` format. Exported so editor/server
+ * Current on-disk `vgai.project.json` format. Exported so editor/server
  * compatibility checks do not duplicate the schema's literal value.
  */
 export const GAME_MANIFEST_VERSION = 2 as const;
 
 // ---------------------------------------------------------------------------
-// Ingest capture strategy (world2d today; the general vocabulary D6/§4 names)
+// Ingest capture strategy (the general vocabulary D6/§4 names)
 // ---------------------------------------------------------------------------
 
 export const IngestStrategySchema = z.enum([
@@ -60,191 +59,279 @@ export type Tier = z.infer<typeof TierSchema>;
 // repeats its rendering substrate in a sibling `kind` field. Module and ingest
 // adapters carry the surface their adapter contract exposes because the host
 // must allocate a layer before the module has mounted.
+//
+// The surface vocabulary is `three | canvas | dom` — what the HOST HANDS the
+// root, not which library it uses. `canvas` and `dom` are platform primitives:
+// a canvas root may be Pixi, Phaser, Babylon, raw WebGL/WebGPU or a 2D context,
+// and a dom root may be React, Vue, Svelte or plain HTML, all through the
+// identical host. The former `canvas`/`react` named two libraries in a seam
+// that has nothing to do with either, which foreclosed the rest by
+// construction.
+//
+// All three surfaces are legal as a BARE adapter string: each names a root the
+// engine itself mounts from an `entry` module — `three` through the R3F lane
+// (`@engine/world3d-react`), `canvas` through the Pixi lane
+// (`@engine/canvas-react`), `dom` through the React lane. In every case the
+// entry's document is its own TSX source. A root the engine does NOT mount
+// arrives as an `{ ingest }` root or a `{ module }` adapter the project
+// supplies, both of which name their `surface` explicitly.
+//
+// `three` earns a kind of its own because the host must provide something the
+// platform cannot: the ONE shared `three` instance (identity matters — ingest
+// games bring their own, and r3f depends on dedupe). React needs no equivalent,
+// which is exactly why react is a `dom` root rather than its own kind.
+//
+// The pre-rename spellings `threejs`/`pixijs`/`react` are REMOVED, not
+// normalized (WO-LR1 item 2, the legacy-removal doctrine at
+// ARCHITECTURE-CORE §Vocabulary). Normalization was a second way to say the
+// same thing: two spellings both parsed, so both kept being written, and
+// SECOND readers grew (the dev server's surface probe, the hosted-editor
+// bundler's alias sets) each re-implementing the same map. A manifest naming
+// an old spelling now fails to parse with an issue that names the canonical
+// value and the exact one-line edit.
 // ---------------------------------------------------------------------------
 
+/** Removed spellings → the canonical value each one must be rewritten to. */
+const REMOVED_SURFACE_SPELLING: Readonly<Record<string, 'three' | 'canvas' | 'dom'>> = {
+  threejs: 'three',
+  pixijs: 'canvas',
+  react: 'dom',
+};
+
+/** Removed spellings legal as a BARE adapter (a root the engine itself mounts). */
+const REMOVED_BARE_ADAPTER_SPELLING: Readonly<Record<string, 'three' | 'canvas' | 'dom'>> = {
+  threejs: 'three',
+  pixijs: 'canvas',
+  react: 'dom',
+};
+
+function removedSpellingMessage(bad: string, where: 'adapter' | 'adapter.surface'): string {
+  const canonical =
+    where === 'adapter' ? REMOVED_BARE_ADAPTER_SPELLING[bad] : REMOVED_SURFACE_SPELLING[bad];
+  return (
+    `Game manifest: \`${where}\`: "${bad}" — that spelling was REMOVED (WO-LR1; ` +
+    'ARCHITECTURE-CORE §Vocabulary). The surface vocabulary is ' +
+    "'three' | 'canvas' | 'dom' — what the HOST HANDS the root, never which " +
+    `library it uses.\nFix: change \`${where}\` to "${canonical}".`
+  );
+}
+
+/** Reject a removed surface spelling wherever one may appear — the bare
+ *  shorthand, or the `surface` field of a module/ingest adapter — with an issue
+ *  naming the canonical value. Runs as a Zod preprocess so the message wins
+ *  over the union's generic discriminant error. */
+function rejectRemovedRootAdapterSpelling(value: unknown, ctx: z.core.$RefinementCtx): unknown {
+  if (typeof value === 'string' && REMOVED_BARE_ADAPTER_SPELLING[value]) {
+    ctx.addIssue({ code: 'custom', message: removedSpellingMessage(value, 'adapter') });
+    return z.NEVER;
+  }
+  if (value && typeof value === 'object' && 'surface' in value) {
+    const surface = (value as { surface?: unknown }).surface;
+    if (typeof surface === 'string' && REMOVED_SURFACE_SPELLING[surface]) {
+      ctx.addIssue({
+        code: 'custom',
+        message: removedSpellingMessage(surface, 'adapter.surface'),
+      });
+      return z.NEVER;
+    }
+  }
+  return value;
+}
+
 export const RootAdapterSchema = z
-  .union([
-    z.enum(['threejs', 'pixijs', 'react']),
-    z
-      .object({
-        module: z
-          .string()
-          .describe('Game-folder-relative path to a custom adapter module (trust boundary)'),
-        surface: z
-          .enum(['threejs', 'pixijs', 'react'])
-          .describe('Native surface exposed by this custom adapter contract'),
-      })
-      .strict(),
-    z
-      .object({
-        surface: z
-          .enum(['threejs', 'pixijs', 'react'])
-          .describe('Native surface captured from the unmodified game'),
-        ingest: z
-          .object({
-            strategy: IngestStrategySchema.describe(
-              'Capture mechanics rung this ingested root uses (§4) — also the root`s natural local capability tier',
-            ),
-            entryHtml: z
-              .string()
-              .optional()
-              .describe(
-                'Entry HTML path, project-relative. WIRED for opaque-embed (D-W2, ' +
-                  'docs/WAVE4-FTUE-HARDENING-DESIGN.md): the file`s bytes are read verbatim through ' +
-                  'the project-static route and hosted in a sandboxed iframe (embed-only, no scene ' +
-                  'introspection), for both pixijs and threejs roots. Legal but NOT wired to a ' +
-                  'mount for iframe-reachable (a named error at resolve names this — use `bundleUrl` ' +
-                  'instead, the wired reachable route).',
+  .preprocess(
+    rejectRemovedRootAdapterSpelling,
+    z.union([
+      z.enum(['three', 'canvas', 'dom']),
+      z
+        .object({
+          module: z
+            .string()
+            .describe('Game-folder-relative path to a custom adapter module (trust boundary)'),
+          surface: z
+            .enum(['three', 'canvas', 'dom'])
+            .describe('Native surface exposed by this custom adapter contract'),
+        })
+        .strict(),
+      z
+        .object({
+          surface: z
+            .enum(['three', 'canvas', 'dom'])
+            .describe('Native surface captured from the unmodified game'),
+          ingest: z
+            .object({
+              strategy: IngestStrategySchema.describe(
+                'Capture mechanics rung this ingested root uses (§4) — also the root`s natural local capability tier',
               ),
-            assets: z
-              .record(z.string(), z.string())
-              .optional()
-              .describe(
-                'Path-substring -> served-URL rewrites for this ingested game (IngestGame.assets today)',
-              ),
-            domStubs: z
-              .array(z.string())
-              .optional()
-              .describe('DOM API stub ids this ingested game requires to run headlessly/in-realm'),
-            captureTimeoutMs: z
-              .number()
-              .optional()
-              .describe('Max time to wait for in-realm/cross-realm capture before failing loudly'),
-            // Track P (docs/PIXI-INGEST-LANDING-DESIGN.md §2) — the six
-            // iframe-reachable-multi mount fields (`ingest-iframe-2d.ts`'s
-            // `IframeReachableMultiOpts`), legal ONLY when `strategy` is
-            // 'iframe-reachable' (enforced by the `.superRefine` below).
-            bundleUrl: z
-              .string()
-              .optional()
-              .describe(
-                'Absolute URL of the externalized built game bundle — the WIRED iframe-reachable ' +
-                  'mount route (iframe-reachable only), for BOTH pixijs (Track P, ' +
-                  "ingest-iframe-2d.ts's mountIngestGame2DIframeReachableMulti) and threejs (D-W1, " +
-                  'docs/WAVE4-FTUE-HARDENING-DESIGN.md, ' +
-                  "ingest-iframe-reachable-adapter.ts's mountIngestGameIframeReachableBundle). " +
-                  'PRECONDITION: the bundle must externalize its root`s own runtime as a bare, ' +
-                  'un-rewritten import (`pixi.js` for pixijs, `three` for threejs — `vgai bundle` ' +
-                  'does this for you) so it resolves through the iframe importmap to the HOST ' +
-                  'instance the capture trap is installed on; a bundle with an inlined runtime is ' +
-                  'unreachable and degrades to the embed-only floor. Exactly one of bundleUrl/' +
-                  'entryHtml is required when strategy is iframe-reachable.',
-              ),
-            baseHref: z
-              .string()
-              .optional()
-              .describe(
-                "Iframe <base href> so the game's relative asset URLs resolve (iframe-reachable only).",
-              ),
-            assetBaseUrl: z
-              .string()
-              .optional()
-              .describe(
-                "Host-side basePath forced onto the trapped runtime's own asset resolution — " +
-                  "pixi's `Assets.init` for a pixijs root, three's " +
-                  '`DefaultLoadingManager.setURLModifier` for a threejs root (D-W1) — absolute, or ' +
-                  "root-relative (resolved against the editor page's own origin at mount time, " +
-                  'ingest-mode.ts, so a static manifest never has to know the dev-server port) ' +
-                  '(iframe-reachable only — a document.write iframe keeps the parent window.location).',
-              ),
-            extraDeps: z
-              .array(z.string())
-              .optional()
-              .describe(
-                "Bare specifiers of this root's externalized deps beyond its own runtime " +
-                  "(pixi.js/three — e.g. '@pixi/sound', 'gsap'). Resolved by the editor's " +
-                  'host-namespace registry into module namespaces when known (D-P1 — the manifest ' +
-                  'carries data, not code); an unregistered specifier falls back to the open ' +
-                  "project's own node_modules (D-Z3, docs/WAVE3-ADAPTER-PLUMBING-DESIGN.md), served " +
-                  'as a verbatim iframe importmap URL. Throws a named error if neither resolves it ' +
-                  '(iframe-reachable only).',
-              ),
-            pixiModuleUrl: z
-              .string()
-              .optional()
-              .describe(
-                'PIXI-ONLY: standalone matching-major pixi ESM URL to trap instead of the host ' +
-                  "pixi, for version-skewed games (e.g. a v6 game on a v8 host); this field's " +
-                  'PRESENCE is how the skew is expressed (D-P2 — no separate strategy/tier for ' +
-                  'version skew) (iframe-reachable only). Declaring this on a `kind: "threejs"` ' +
-                  'root is schema-legal (this field is kind-agnostic here) but throws a NAMED ' +
-                  'not-supported error at resolve — three has no version-skew mount this wave (D-W7, ' +
-                  'docs/WAVE4-FTUE-HARDENING-DESIGN.md: a hypothetical `threeModuleUrl` is explicitly ' +
-                  'parked, no consumer exists).',
-              ),
-            bodyHtml: z
-              .string()
-              .optional()
-              .describe(
-                'HTML injected into the iframe body before the game script boots (e.g. a ' +
-                  '`<div id="game-root">` the game expects to find) (iframe-reachable only).',
-              ),
-          })
-          .describe(
-            'Ingest adapter configuration for an unmodified game (a repo-vendored game or your ' +
-              'own external folder)',
-          )
-          .superRefine((ingest, ctx) => {
-            // Track P (docs/PIXI-INGEST-LANDING-DESIGN.md §2/D-P4): the six
-            // iframe-reachable-multi fields only make sense for the
-            // iframe-reachable-multi mount — reject them under any other
-            // strategy (mirrors ui.ts's dead-field-under-wrong-variant pattern).
-            const iframeOnlyFields: ReadonlyArray<
-              readonly [
-                key:
-                  | 'bundleUrl'
-                  | 'baseHref'
-                  | 'assetBaseUrl'
-                  | 'extraDeps'
-                  | 'pixiModuleUrl'
-                  | 'bodyHtml',
-                present: boolean,
-              ]
-            > = [
-              ['bundleUrl', ingest.bundleUrl !== undefined],
-              ['baseHref', ingest.baseHref !== undefined],
-              ['assetBaseUrl', ingest.assetBaseUrl !== undefined],
-              ['extraDeps', ingest.extraDeps !== undefined],
-              ['pixiModuleUrl', ingest.pixiModuleUrl !== undefined],
-              ['bodyHtml', ingest.bodyHtml !== undefined],
-            ];
-            if (ingest.strategy !== 'iframe-reachable') {
-              for (const [key, present] of iframeOnlyFields) {
-                if (present) {
-                  ctx.addIssue({
-                    code: z.ZodIssueCode.custom,
-                    message:
-                      `\`${key}\` is only legal when strategy is 'iframe-reachable' (got ` +
-                      `"${ingest.strategy}") — bundleUrl/baseHref/assetBaseUrl/extraDeps/` +
-                      "pixiModuleUrl/bodyHtml are the iframe-reachable-multi mount's options " +
-                      '(pixijs: ingest-iframe-2d.ts IframeReachableMultiOpts; threejs, D-W1: ' +
-                      'ingest-iframe-reachable-adapter.ts IframeReachableBundleOpts) and have no ' +
-                      'meaning under any other strategy.',
-                    path: [key],
-                  });
+              entryHtml: z
+                .string()
+                .optional()
+                .describe(
+                  'Entry HTML path, project-relative. WIRED for opaque-embed (D-W2): ' +
+                    'the file`s bytes are read verbatim through ' +
+                    'the project-static route and hosted in a sandboxed iframe (embed-only, no scene ' +
+                    'introspection), for both canvas and three roots. Legal but NOT wired to a ' +
+                    'mount for iframe-reachable (a named error at resolve names this — use `bundleUrl` ' +
+                    'instead, the wired reachable route).',
+                ),
+              assets: z
+                .record(z.string(), z.string())
+                .optional()
+                .describe(
+                  'Path-substring -> served-URL rewrites for this ingested game (IngestGame.assets today)',
+                ),
+              domStubs: z
+                .array(z.string())
+                .optional()
+                .describe(
+                  'DOM API stub ids this ingested game requires to run headlessly/in-realm',
+                ),
+              captureTimeoutMs: z
+                .number()
+                .optional()
+                .describe(
+                  'How long to wait for capture before REPORTING the degrade loudly — not how ' +
+                    'long to keep listening. On the self-hosted-three route the devtools ' +
+                    'subscription is permanent, so a renderer appearing later still upgrades a ' +
+                    'reported-embed-only mount in place; the host clamps this value so a long ' +
+                    'one cannot block the editor on a question the upgrade path answers anyway.',
+                ),
+              // The six iframe-reachable-multi mount fields
+              // (`ingest-iframe-2d.ts`'s `IframeReachableMultiOpts`), legal
+              // ONLY when `strategy` is 'iframe-reachable' (enforced by the
+              // `.superRefine` below).
+              bundleUrl: z
+                .string()
+                .optional()
+                .describe(
+                  'Absolute URL of the externalized built game bundle — the WIRED iframe-reachable ' +
+                    'mount route (iframe-reachable only), for BOTH canvas (Track P, ' +
+                    "ingest-iframe-2d.ts's mountIngestGame2DIframeReachableMulti) and three (D-W1, " +
+                    "ingest-iframe-reachable-adapter.ts's mountIngestGameIframeReachableBundle). " +
+                    'PRECONDITION: the bundle must externalize its root`s own runtime as a bare, ' +
+                    'un-rewritten import (`pixi.js` for canvas, `three` for three — `vgai bundle` ' +
+                    'does this for you) so it resolves through the iframe importmap to the HOST ' +
+                    'instance the capture trap is installed on; a bundle with an inlined runtime is ' +
+                    'unreachable and degrades to the embed-only floor. Exactly one of bundleUrl/' +
+                    'entryHtml is required when strategy is iframe-reachable.',
+                ),
+              baseHref: z
+                .string()
+                .optional()
+                .describe(
+                  "Iframe <base href> so the game's relative asset URLs resolve (iframe-reachable only).",
+                ),
+              assetBaseUrl: z
+                .string()
+                .optional()
+                .describe(
+                  "Host-side basePath forced onto the trapped runtime's own asset resolution — " +
+                    "pixi's `Assets.init` for a canvas root, three's " +
+                    '`DefaultLoadingManager.setURLModifier` for a three root (D-W1) — absolute, or ' +
+                    "root-relative (resolved against the editor page's own origin at mount time, " +
+                    'ingest-mode.ts, so a static manifest never has to know the dev-server port) ' +
+                    '(iframe-reachable only — a document.write iframe keeps the parent window.location).',
+                ),
+              extraDeps: z
+                .array(z.string())
+                .optional()
+                .describe(
+                  "Bare specifiers of this root's externalized deps beyond its own runtime " +
+                    "(pixi.js/three — e.g. '@pixi/sound', 'gsap'). Resolved by the editor's " +
+                    'host-namespace registry into module namespaces when known (D-P1 — the manifest ' +
+                    'carries data, not code); an unregistered specifier falls back to the open ' +
+                    "project's own node_modules (D-Z3), served " +
+                    'as a verbatim iframe importmap URL. Throws a named error if neither resolves it ' +
+                    '(iframe-reachable only).',
+                ),
+              pixiModuleUrl: z
+                .string()
+                .optional()
+                .describe(
+                  'PIXI-ONLY: standalone matching-major pixi ESM URL to trap instead of the host ' +
+                    "pixi, for version-skewed games (e.g. a v6 game on a v8 host); this field's " +
+                    'PRESENCE is how the skew is expressed (D-P2 — no separate strategy/tier for ' +
+                    'version skew) (iframe-reachable only). Declaring this on a `kind: "three"` ' +
+                    'root is schema-legal (this field is kind-agnostic here) but throws a NAMED ' +
+                    'not-supported error at resolve — three has no version-skew mount this wave ' +
+                    '(D-W7: a hypothetical `threeModuleUrl` is explicitly parked, no consumer ' +
+                    'exists).',
+                ),
+              bodyHtml: z
+                .string()
+                .optional()
+                .describe(
+                  'HTML injected into the iframe body before the game script boots (e.g. a ' +
+                    '`<div id="game-root">` the game expects to find) (iframe-reachable only).',
+                ),
+            })
+            .describe(
+              'Ingest adapter configuration for an unmodified game (a repo-vendored game or your ' +
+                'own external folder)',
+            )
+            .superRefine((ingest, ctx) => {
+              // The six iframe-reachable-multi fields only make sense for the
+              // iframe-reachable-multi mount — reject them under any other
+              // strategy (mirrors ui.ts's dead-field-under-wrong-variant pattern).
+              const iframeOnlyFields: ReadonlyArray<
+                readonly [
+                  key:
+                    | 'bundleUrl'
+                    | 'baseHref'
+                    | 'assetBaseUrl'
+                    | 'extraDeps'
+                    | 'pixiModuleUrl'
+                    | 'bodyHtml',
+                  present: boolean,
+                ]
+              > = [
+                ['bundleUrl', ingest.bundleUrl !== undefined],
+                ['baseHref', ingest.baseHref !== undefined],
+                ['assetBaseUrl', ingest.assetBaseUrl !== undefined],
+                ['extraDeps', ingest.extraDeps !== undefined],
+                ['pixiModuleUrl', ingest.pixiModuleUrl !== undefined],
+                ['bodyHtml', ingest.bodyHtml !== undefined],
+              ];
+              if (ingest.strategy !== 'iframe-reachable') {
+                for (const [key, present] of iframeOnlyFields) {
+                  if (present) {
+                    ctx.addIssue({
+                      code: z.ZodIssueCode.custom,
+                      message:
+                        `\`${key}\` is only legal when strategy is 'iframe-reachable' (got ` +
+                        `"${ingest.strategy}") — bundleUrl/baseHref/assetBaseUrl/extraDeps/` +
+                        "pixiModuleUrl/bodyHtml are the iframe-reachable-multi mount's options " +
+                        '(canvas: ingest-iframe-2d.ts IframeReachableMultiOpts; three, D-W1: ' +
+                        'ingest-iframe-reachable-adapter.ts IframeReachableBundleOpts) and have no ' +
+                        'meaning under any other strategy.',
+                      path: [key],
+                    });
+                  }
                 }
+                return;
               }
-              return;
-            }
-            const hasBundleUrl = ingest.bundleUrl !== undefined;
-            const hasEntryHtml = ingest.entryHtml !== undefined;
-            if (hasBundleUrl === hasEntryHtml) {
-              ctx.addIssue({
-                code: z.ZodIssueCode.custom,
-                message:
-                  "strategy 'iframe-reachable' requires EXACTLY ONE of `bundleUrl` (externalized " +
-                  'multi-file bundle, the iframe-reachable-multi mount) or `entryHtml` (single-' +
-                  `file/legacy iframe entry) — ${hasBundleUrl ? 'both are present' : 'neither is present'}.`,
-                path: hasBundleUrl ? ['bundleUrl'] : ['entryHtml'],
-              });
-            }
-          }),
-      })
-      .strict(),
-  ])
+              const hasBundleUrl = ingest.bundleUrl !== undefined;
+              const hasEntryHtml = ingest.entryHtml !== undefined;
+              if (hasBundleUrl === hasEntryHtml) {
+                ctx.addIssue({
+                  code: z.ZodIssueCode.custom,
+                  message:
+                    "strategy 'iframe-reachable' requires EXACTLY ONE of `bundleUrl` (externalized " +
+                    'multi-file bundle, the iframe-reachable-multi mount) or `entryHtml` (single-' +
+                    `file/legacy iframe entry) — ${hasBundleUrl ? 'both are present' : 'neither is present'}.`,
+                  path: hasBundleUrl ? ['bundleUrl'] : ['entryHtml'],
+                });
+              }
+            }),
+        })
+        .strict(),
+    ]),
+  )
   .describe(
-    "Root adapter identity: built-in 'threejs'/'pixijs'/'react', a custom " +
-      '{ module, surface } adapter, or an { ingest, surface } adapter for an unmodified game',
+    "Root adapter identity: built-in 'three'/'canvas'/'dom' (what the host hands " +
+      "the root — 'canvas' covers Pixi/Phaser/Babylon/raw WebGL, 'dom' covers " +
+      'React/Vue/plain HTML), a custom { module, surface } adapter, or an ' +
+      '{ ingest, surface } adapter for an unmodified game.',
   );
 export type RootAdapter = z.infer<typeof RootAdapterSchema>;
 
@@ -269,27 +356,35 @@ export const AdapterRootSchema = z
     adapter: RootAdapterSchema.describe(
       "This root's adapter and sole rendering/lifecycle discriminator",
     ),
-    scene: z
-      .string()
-      .optional()
-      .describe(
-        '.vscn.json / .scn2d.json scene path (default adapters only — ingest adapters keep their own formats)',
-      ),
     entry: z
       .string()
       .optional()
       .describe(
-        "Module exporting setup()/adapter (default adapters' code-authored alternative to `scene`)",
+        'Module exporting a world root — a TSX/R3F component or a setup()/adapter (three), or a ' +
+          'React component (dom). Required for every built-in adapter root.',
       ),
     zOrder: z
       .number()
       .int()
       .default(0)
-      .describe('Canvas stacking order (COMPOSITION-DESIGN); ties broken by array order'),
+      .describe('Canvas stacking order; ties broken by array order'),
     pausable: z
       .boolean()
       .default(true)
       .describe('Whether play-mode pause/step applies to this root'),
+    dev: z
+      .boolean()
+      .default(false)
+      .describe(
+        "Marks this root as a DEV LAYER: the game's own dev GUI, not shipped game content. " +
+          'Four readers act on it. `mountManifestRoots` mounts it only when dev layers are ' +
+          'enabled (`devLayersEnabled`, runtime/dev-layers.ts), so a production build carries ' +
+          'no dev GUI; the host stacks every dev root ABOVE every non-dev root (a dev layer ' +
+          'sits topmost, and as a DOM layer it steals no input from the game while closed); ' +
+          'the play compositor EXCLUDES dev layers from a capture unless the capture asks for ' +
+          'them; and the editor mounts a dev root as edit-time CHROME rather than authorable ' +
+          'content (no hierarchy entry, no OID stamping, no JSX write-back, not selectable).',
+      ),
     loop: z
       .enum(['gated', 'self-driven'])
       .default('gated')
@@ -315,8 +410,20 @@ export const AdapterRootSchema = z
   .strict();
 export type AdapterRoot = z.infer<typeof AdapterRootSchema>;
 
+/**
+ * The MEDIUM a root occupies — its surface, i.e. what the host hands it. A
+ * bare adapter string names its own surface; `{ module, surface }` and
+ * `{ ingest, surface }` name it explicitly. Bucketing by surface is what makes
+ * a first-party `@pixi/react` world, an ingested canvas game and a custom
+ * canvas module ONE medium: they all compete for the same canvas surface, and
+ * which library draws on it is not what the rule below is about.
+ */
+function rootMedium(root: AdapterRoot): 'three' | 'canvas' | 'dom' {
+  return typeof root.adapter === 'string' ? root.adapter : root.adapter.surface;
+}
+
 // ---------------------------------------------------------------------------
-// Learn metadata (FT-5, docs/FTUE-LEARN-SYSTEM-DESIGN.md §3)
+// Learn metadata (FT-5)
 // ---------------------------------------------------------------------------
 
 export const LearnKindSchema = z
@@ -367,14 +474,14 @@ export const LearnMetadataSchema = z
   })
   .strict()
   .describe(
-    'Learner-facing metadata (FT-5, docs/FTUE-LEARN-SYSTEM-DESIGN.md §3) — powers the example ' +
+    'Learner-facing metadata (FT-5) — powers the example ' +
       'gallery, New Project wizard, and Learn-site catalog. Registries are generated from this ' +
       'block; there is no parallel hand-edited catalog.',
   );
 export type LearnMetadata = z.infer<typeof LearnMetadataSchema>;
 
 // ---------------------------------------------------------------------------
-// Game manifest (vgai.game.json)
+// Game manifest (vgai.project.json)
 // ---------------------------------------------------------------------------
 
 export const GameManifestSchema = z
@@ -391,13 +498,6 @@ export const GameManifestSchema = z
       .string()
       .optional()
       .describe('Stable reverse-domain application id used by packaged targets'),
-    editorPort: z
-      .number()
-      .int()
-      .min(1024)
-      .max(65535)
-      .optional()
-      .describe('Stable preferred local editor port; launchers may fall forward when occupied'),
     version: z.string().describe("The game's own version (used for orphan detection)"),
     engine: z
       .object({
@@ -413,31 +513,74 @@ export const GameManifestSchema = z
       .array(AdapterRootSchema)
       .min(1)
       .superRefine((roots, ctx) => {
-        // D-V6 (docs/WAVE5-MULTIWORLD-INGEST-DESIGN.md §1G debt,
-        // docs/MULTI-WORLD-DESIGN.md §1G): root ids are described as unique
-        // above but that was describe-only at the SCHEMA level — only
-        // load.ts's loader-level cross-field check caught a collision, so
-        // any OTHER consumer of this schema (the generated JSON Schema,
-        // editor tooling) saw duplicate ids as legal. Enforced HERE instead,
-        // naming every colliding id (not just the first found) — overlay
-        // files are keyed by root id (`.vgai/overlays/<id>.json`), so a
-        // silently-permitted duplicate would have two roots silently share
-        // one overlay.
+        // D-V6 (debt): root ids are described as unique above but that was
+        // describe-only at the SCHEMA level — only load.ts's loader-level
+        // cross-field check caught a collision, so any OTHER consumer of this
+        // schema (the generated JSON Schema, editor tooling) saw duplicate
+        // ids as legal. Enforced HERE instead, naming every colliding id (not
+        // just the first found) — a root id is the key every per-world editor
+        // surface is addressed by, so a silently-permitted duplicate would
+        // have two roots silently collide.
         const counts = new Map<string, number>();
         for (const root of roots) counts.set(root.id, (counts.get(root.id) ?? 0) + 1);
         const duplicates = [...counts.entries()].filter(([, n]) => n > 1).map(([id]) => id);
-        if (duplicates.length === 0) return;
-        const idsText = duplicates.map((id) => `"${id}"`).join(', ');
-        ctx.addIssue({
-          code: z.ZodIssueCode.custom,
-          message:
-            duplicates.length === 1
-              ? `Game manifest: duplicate root id ${idsText} — root ids must be unique across the manifest (enforced-unique).`
-              : `Game manifest: duplicate root ids: ${idsText} — root ids must be unique across the manifest (enforced-unique).`,
-        });
+        if (duplicates.length > 0) {
+          const idsText = duplicates.map((id) => `"${id}"`).join(', ');
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message:
+              duplicates.length === 1
+                ? `Game manifest: duplicate root id ${idsText} — root ids must be unique across the manifest (enforced-unique).`
+                : `Game manifest: duplicate root ids: ${idsText} — root ids must be unique across the manifest (enforced-unique).`,
+          });
+        }
+
+        // A project has at most ONE world root per MEDIUM (owner-ratified).
+        // The medium is the surface (see `rootMedium`), so `three`, `dom` and
+        // the canvas surface are the three buckets — a first-party canvas
+        // world, a canvas ingest and a canvas module are the SAME medium.
+        //
+        // Enforced here rather than left to the reader because the editor
+        // mounts exactly one root per medium (`resolveFocusedThreejsRootId`
+        // is a `find`, and the design-time layer stack hosts the one dom
+        // root): a second root of the same medium parsed cleanly and was then
+        // silently never mounted, which is the failure mode this rejects.
+        //
+        // DEV LAYERS ARE COUNTED SEPARATELY. A `dev: true` root is not content
+        // competing for the medium — it is the game's dev GUI stacked above
+        // everything (`create-runtime.ts`'s stacking pass), and the editor
+        // mounts it as chrome, not as the one dom document. Counting it with
+        // the content roots would make the ratified shape — a game with a HUD
+        // and a dev panel, both `dom` — unrepresentable. The one-per-medium
+        // rule still applies WITHIN the dev band, for the same
+        // silently-never-mounted reason.
+        const idsByMedium = new Map<string, string[]>();
+        for (const root of roots) {
+          const medium = `${root.dev ? 'dev ' : ''}${rootMedium(root)}`;
+          const ids = idsByMedium.get(medium);
+          if (ids) ids.push(root.id);
+          else idsByMedium.set(medium, [root.id]);
+        }
+        for (const [medium, ids] of idsByMedium) {
+          if (ids.length < 2) continue;
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message:
+              `Game manifest: a project has at most one ${medium} world root — ` +
+              `${ids.map((id) => `"${id}"`).join(', ')} all occupy the ${medium} surface. ` +
+              'Keep one and remove the rest, or move a root to a different medium ' +
+              "(three / canvas / dom); only one root per medium is ever mounted, so a second one's " +
+              'content would never appear.',
+          });
+        }
       })
       .describe(
-        "The Game's explicit, non-empty adapter-root composition. There is no implicit root.",
+        "The Game's explicit, non-empty adapter-root composition. There is no implicit root. " +
+          'Root ids are unique, and a project declares at most ONE world root per medium — ' +
+          'one `three`, one `dom`, one canvas-surface root (first-party canvas, canvas ingest ' +
+          'and canvas module are the same medium). A `dev: true` root is counted in its own ' +
+          'band: a dev layer is chrome stacked above the game, not content competing for the ' +
+          'medium, so a game may declare a `dom` HUD and a `dom` dev layer — but not two of either.',
       ),
     authoring: z
       .object({
@@ -475,6 +618,30 @@ export const GameManifestSchema = z
           .describe(
             'Module path for the Colyseus room bootstrap; defaults to the scaffolded server bootstrap',
           ),
+        relay: z
+          .object({
+            signalingUrl: z
+              .string()
+              .optional()
+              .describe(
+                'Managed relay signaling URL to prefer over the client default; omitted when the deploy did not pin one',
+              ),
+            accessToken: z
+              .string()
+              .describe(
+                'Room-scoped managed-relay access token minted at `vgai deploy` and read by the standalone client (main.ts)',
+              ),
+            expiresAt: z
+              .number()
+              .describe(
+                'Token expiry as epoch milliseconds; the client falls back to a tokenless join once elapsed',
+              ),
+          })
+          .strict()
+          .optional()
+          .describe(
+            'Deploy-baked managed-relay credentials. NEVER hand-authored in source — written only into the staged manifest by `vgai deploy` and fetched at runtime by the standalone client',
+          ),
       })
       .optional()
       .describe('Multiplayer server config (Colyseus), if this game registers a room'),
@@ -506,7 +673,7 @@ export const GameManifestSchema = z
           .boolean()
           .describe(
             'Declares that ALL gameplay RNG in this project flows through ctx.random (the ' +
-              'named-stream seeded PRNG, docs/D15-DETERMINISM-DESIGN.md) rather than raw ' +
+              'named-stream seeded PRNG) rather than raw ' +
               'Math.random/Date.now/performance.now. Three runtime enforcers key off this flag: ' +
               'the boot-time seeding reader (mount-manifest.ts seeds ctx.random from ' +
               'defaultSeed/?vgai-seed=/explicit config, in that precedence, only when true), the ' +
@@ -514,7 +681,7 @@ export const GameManifestSchema = z
               "project's src/ for raw RNG/wall-clock calls), and the dev-mode Math.random phase " +
               'trap (runtime/gameplay-rng-trap.ts — warns once per call site during a gameplay ' +
               'frame, never throws). Default false: an undeclared project gets no determinism ' +
-              'contract at all (that IS the opt-out — no dead field, per the T4.1 policy).',
+              'contract at all (that IS the opt-out — no dead field).',
           ),
         defaultSeed: z
           .number()
@@ -529,7 +696,7 @@ export const GameManifestSchema = z
       })
       .optional()
       .describe(
-        'Seeded-RNG determinism contract (D15, docs/D15-DETERMINISM-DESIGN.md) — governs ' +
+        'Seeded-RNG determinism contract (D15) — governs ' +
           'whether ctx.random is boot-seeded from a reproducible seed and whether the ' +
           'gameplay-rng-ban scan / dev-mode Math.random phase trap are active for this project.',
       ),
@@ -561,7 +728,7 @@ export const GameManifestSchema = z
           .optional()
           .describe(
             'Maximum allowed entity-tagged scene-graph nodes (nodes carrying ' +
-              "userData.entityId) summed across the game's threejs/pixijs worlds at the end " +
+              "userData.entityId) summed across the game's three/canvas worlds at the end " +
               'of a `vgai perf` run. Exact and deterministic under a seed — no tolerance band.',
           ),
         maxDrawCalls: z
@@ -589,7 +756,7 @@ export const GameManifestSchema = z
         message:
           'Game manifest: `budget` must set at least one metric (frameCpuMsP95, physicsMsP95, ' +
           'maxEntities, maxDrawCalls, maxTriangles) — an empty budget block gates nothing ' +
-          '(T4.1 no-dead-fields policy).',
+          '(the no-dead-fields policy).',
       })
       .optional()
       .describe(
@@ -604,6 +771,6 @@ export const GameManifestSchema = z
     ),
   })
   .strict()
-  .describe('Game manifest (vgai.game.json) — the complete v2 project configuration');
+  .describe('Game manifest (vgai.project.json) — the complete v2 project configuration');
 
 export type GameManifest = z.infer<typeof GameManifestSchema>;