@vgai/engine 0.2.0 → 0.4.0-canary.20260715.0

package/src/manifest/load.ts

@@ -14,12 +14,12 @@
 // only need `loadGameManifest` never pull in `node:fs`.
 
 import {
+  type AdapterRoot,
   type GameManifest,
   GameManifestSchema,
   type IngestStrategy,
+  type RootAdapter,
   type Tier,
-  type WorldAdapter,
-  type WorldEntry,
 } from './schema';
 
 // ---------------------------------------------------------------------------
@@ -29,10 +29,16 @@ import {
 /** D6's resolved adapter identities. */
 export type ResolvedAdapter =
   | {
-      readonly type: 'default';
-      readonly identity: 'default-three' | 'default-pixi' | 'default-react';
+      readonly type: 'builtin';
+      readonly identity: 'threejs' | 'pixijs' | 'react';
+      readonly surface: 'threejs' | 'pixijs' | 'react';
+    }
+  | {
+      readonly type: 'module';
+      readonly identity: 'module';
+      readonly module: string;
+      readonly surface: 'threejs' | 'pixijs' | 'react';
     }
-  | { readonly type: 'module'; readonly identity: 'module'; readonly module: string }
   | {
       readonly type: 'ingest';
       // 'ingest-react' (Track N, N1 — docs/REACT-INGEST-LANDING-DESIGN.md
@@ -48,6 +54,7 @@ export type ResolvedAdapter =
       // strategies either; `resolveIngestDescriptor`/`resolveIngest2DDescriptor`
       // are where "not yet buildable" strategies throw.
       readonly identity: 'ingest-three' | 'ingest-pixi' | 'ingest-react';
+      readonly surface: 'threejs' | 'pixijs' | 'react';
       readonly strategy: IngestStrategy;
       readonly entryHtml: string | undefined;
       readonly assets: Record<string, string> | undefined;
@@ -62,9 +69,9 @@ export type ResolvedAdapter =
       readonly bodyHtml: string | undefined;
     };
 
-export interface ResolvedWorldEntry {
+export interface ResolvedAdapterRoot {
   readonly id: string;
-  readonly kind: WorldEntry['kind'];
+  readonly surface: ResolvedAdapter['surface'];
   readonly description: string | undefined;
   readonly adapter: ResolvedAdapter;
   readonly scene: string | undefined;
@@ -77,14 +84,41 @@ export interface ResolvedWorldEntry {
 }
 
 export interface ResolvedGameManifest {
-  readonly manifestVersion: 1;
+  readonly manifestVersion: 2;
   readonly name: string;
+  readonly appId: string | undefined;
+  readonly editorPort: number | undefined;
   readonly version: string;
   readonly engine: { readonly version: string };
   /** Sorted by zOrder; ties broken by original array order (§3). */
-  readonly worlds: readonly ResolvedWorldEntry[];
+  readonly roots: readonly ResolvedAdapterRoot[];
   readonly server: { readonly room: string; readonly module: string } | undefined;
   readonly resolution: { readonly width: number; readonly height: number } | undefined;
+  readonly authoring:
+    | {
+        readonly hierarchy?:
+          | {
+              readonly rootLabels?: Readonly<Record<string, string>> | undefined;
+              readonly groups?:
+                | readonly {
+                    readonly id: string;
+                    readonly label: string;
+                    readonly roots: readonly string[];
+                  }[]
+                | undefined;
+            }
+          | undefined;
+      }
+    | undefined;
+  /** D18 — read by the debug-bridge installer to gate `?vgai-debug=1` in production builds. */
+  readonly debug: { readonly allowInProduction: boolean } | undefined;
+  /** D15 — read by `mount-manifest.ts`'s boot-time seeding reader (gates
+   *  whether `ctx.random` is seeded from `defaultSeed`/`?vgai-seed=`), the
+   *  gameplay-rng-ban burn-down scan, and the dev-mode Math.random phase
+   *  trap. See `docs/D15-DETERMINISM-DESIGN.md`. */
+  readonly determinism:
+    | { readonly seededRandom: boolean; readonly defaultSeed?: number | undefined }
+    | undefined;
 }
 
 // ---------------------------------------------------------------------------
@@ -94,12 +128,12 @@ export interface ResolvedGameManifest {
 
 /**
  * Ceiling (maximum legal declared `Tier`) per adapter type and delivery
- * context. `default` worlds are always first-party in both contexts (D6/§2 —
- * a first-party world is fully vgai-native everywhere). `ingest` worlds are
+ * context. `default` roots are always first-party in both contexts (D6/§2 —
+ * a first-party root is fully vgai-native everywhere). `ingest` roots are
  * ceilinged by their own capture `strategy`: locally the local CLI's Vite
  * pipeline gives bundler dedupe, so every strategy reaches its own natural
  * rung; hosted has no bundler (esbuild-wasm + externals only), and a
- * `deduped` world is DEFINED by being source built through our pipeline — no
+ * `deduped` root is DEFINED by being source built through our pipeline — no
  * prebuilt bundle exists to fall back to an iframe rung, and nothing
  * implements a hosted build for it, so hosted is `unsupported` (honesty over
  * optimism; if the hosted esbuild-wasm path ever proves capable, raising
@@ -109,11 +143,11 @@ export interface ResolvedGameManifest {
  * adapter's reach is not derivable", §4) — modeled here as `first-party`
  * (the top rank), i.e. no ceiling actually constrains a module adapter's
  * declared tier; the loader instead requires the tier to be declared
- * explicitly for module worlds (see `resolveCapabilities`), since there is no
+ * explicitly for module roots (see `resolveCapabilities`), since there is no
  * default to derive.
  */
 export const CAPABILITY_CEILINGS = {
-  default: { local: 'first-party', hosted: 'first-party' },
+  builtin: { local: 'first-party', hosted: 'first-party' },
   ingest: {
     shared: { local: 'shared', hosted: 'shared' },
     deduped: { local: 'deduped', hosted: 'unsupported' },
@@ -146,14 +180,14 @@ const SEMVER_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z-.]+)?(?:\+[0-9A-Za-z-.]+)?$/;
 // ---------------------------------------------------------------------------
 
 function isModuleAdapter(
-  adapter: WorldAdapter,
-): adapter is Extract<WorldAdapter, { module: string }> {
+  adapter: RootAdapter,
+): adapter is Extract<RootAdapter, { module: string }> {
   return typeof adapter === 'object' && 'module' in adapter;
 }
 
 function isIngestAdapter(
-  adapter: WorldAdapter,
-): adapter is Extract<WorldAdapter, { ingest: { strategy: IngestStrategy } }> {
+  adapter: RootAdapter,
+): adapter is Extract<RootAdapter, { ingest: { strategy: IngestStrategy } }> {
   return typeof adapter === 'object' && 'ingest' in adapter;
 }
 
@@ -161,9 +195,9 @@ function isIngestAdapter(
 // Cross-field checks (§3 — beyond what Zod alone enforces)
 // ---------------------------------------------------------------------------
 //
-// D-V6 (docs/WAVE5-MULTIWORLD-INGEST-DESIGN.md): world-id uniqueness used to
+// D-V6 (docs/WAVE5-MULTIWORLD-INGEST-DESIGN.md): root-id uniqueness used to
 // be a cross-field check HERE (`checkUniqueWorldIds`, removed) — it moved
-// INTO `GameManifestSchema`'s `worlds` `superRefine` (schema.ts) instead, so
+// INTO `GameManifestSchema`'s `roots` `superRefine` (schema.ts) instead, so
 // the generated JSON Schema and any other schema consumer see the same
 // constraint the loader always enforced. `parseManifest` below catches that
 // one recognizable schema-level issue and rethrows it as a clean, single
@@ -172,17 +206,22 @@ function isIngestAdapter(
 // callers/tests that pattern-match the message text are unaffected by the
 // enforcement moving one layer down.
 
-function checkAdapterSceneEntryRules(world: WorldEntry): void {
-  const { adapter } = world;
-  if (adapter === 'default' && !world.scene && !world.entry) {
+function checkAdapterSceneEntryRules(root: AdapterRoot): void {
+  const { adapter } = root;
+  if (typeof adapter === 'string' && !root.scene && !root.entry) {
     throw new Error(
-      `Game manifest: world "${world.id}" uses the 'default' adapter but declares neither ` +
-        '`scene` nor `entry` — a default-adapter world requires one of the two (§3).',
+      `Game manifest: root "${root.id}" uses the '${adapter}' adapter but declares neither ` +
+        '`scene` nor `entry` — a built-in adapter root requires an authored document or entry.',
     );
   }
-  if (isIngestAdapter(adapter) && world.scene !== undefined) {
+  if (adapter === 'react' && root.scene !== undefined) {
     throw new Error(
-      `Game manifest: world "${world.id}" uses an { ingest } adapter but declares \`scene\` — ` +
+      `Game manifest: React root "${root.id}" declares \`scene\` — React roots use JSX entry modules.`,
+    );
+  }
+  if (isIngestAdapter(adapter) && root.scene !== undefined) {
+    throw new Error(
+      `Game manifest: root "${root.id}" uses an { ingest } adapter but declares \`scene\` — ` +
         'ingest adapters forbid `scene` (adapt-never-migrate: ingested games keep their own ' +
         "formats; overlay persistence is T3.2's) (§3).",
     );
@@ -190,13 +229,13 @@ function checkAdapterSceneEntryRules(world: WorldEntry): void {
 }
 
 // Historical note (Track N, N1): this file used to reject EVERY `kind:
-// 'react'` + `{ ingest }` world outright here (`checkReactAdapterRestriction`,
+// 'react'` + `{ ingest }` root outright here (`checkReactAdapterRestriction`,
 // citing "no react ingest program is un-parked"). Track N un-parks exactly
 // that program (docs/REACT-INGEST-LANDING-DESIGN.md) — react+ingest is now a
 // structurally legal combination, resolved to the `'ingest-react'` identity
-// by `resolveAdapter` below like any other ingest world. There is nothing
+// by `resolveAdapter` below like any other ingest root. There is nothing
 // left to reject at THIS layer: `checkAdapterSceneEntryRules` above already
-// forbids `scene` on any `{ ingest }`-adapter world (kind-agnostic), and the
+// forbids `scene` on any `{ ingest }`-adapter root (kind-agnostic), and the
 // v1 "deduped strategy only" restriction is an editor-resolver concern
 // (D-N3), not a manifest-shape concern — see the `ResolvedAdapter` type's
 // comment above.
@@ -205,28 +244,36 @@ function checkAdapterSceneEntryRules(world: WorldEntry): void {
 // Resolution (§5)
 // ---------------------------------------------------------------------------
 
-function resolveAdapter(world: WorldEntry): ResolvedAdapter {
-  const { adapter, kind } = world;
+function resolveAdapter(root: AdapterRoot): ResolvedAdapter {
+  const { adapter } = root;
 
-  if (adapter === 'default') {
-    const identity =
-      kind === 'threejs' ? 'default-three' : kind === 'pixijs' ? 'default-pixi' : 'default-react';
-    return { type: 'default', identity };
+  if (typeof adapter === 'string') {
+    return { type: 'builtin', identity: adapter, surface: adapter };
   }
 
   if (isModuleAdapter(adapter)) {
-    return { type: 'module', identity: 'module', module: adapter.module };
+    return {
+      type: 'module',
+      identity: 'module',
+      module: adapter.module,
+      surface: adapter.surface,
+    };
   }
 
   // isIngestAdapter (Track N, N1: 'ingest-react' joins 'ingest-three'/
   // 'ingest-pixi' — see the `ResolvedAdapter` type's comment above for why
   // this stays strategy-agnostic here).
   const identity =
-    kind === 'threejs' ? 'ingest-three' : kind === 'pixijs' ? 'ingest-pixi' : 'ingest-react';
+    adapter.surface === 'threejs'
+      ? 'ingest-three'
+      : adapter.surface === 'pixijs'
+        ? 'ingest-pixi'
+        : 'ingest-react';
   const ingest = adapter.ingest;
   return {
     type: 'ingest',
     identity,
+    surface: adapter.surface,
     strategy: ingest.strategy,
     entryHtml: ingest.entryHtml,
     assets: ingest.assets,
@@ -241,23 +288,23 @@ function resolveAdapter(world: WorldEntry): ResolvedAdapter {
   };
 }
 
-function ceilingFor(adapter: WorldAdapter, context: 'local' | 'hosted'): Tier {
-  if (adapter === 'default') return CAPABILITY_CEILINGS.default[context];
+function ceilingFor(adapter: RootAdapter, context: 'local' | 'hosted'): Tier {
+  if (typeof adapter === 'string') return CAPABILITY_CEILINGS.builtin[context];
   if (isModuleAdapter(adapter)) return CAPABILITY_CEILINGS.module[context];
   return CAPABILITY_CEILINGS.ingest[adapter.ingest.strategy][context];
 }
 
-function resolveCapabilities(world: WorldEntry): { local: Tier; hosted: Tier } {
+function resolveCapabilities(root: AdapterRoot): { local: Tier; hosted: Tier } {
   const contexts = ['local', 'hosted'] as const;
   const result = {} as { local: Tier; hosted: Tier };
 
   for (const context of contexts) {
-    const declared = world.capabilities?.[context];
+    const declared = root.capabilities?.[context];
     if (declared !== undefined) {
-      const ceiling = ceilingFor(world.adapter, context);
+      const ceiling = ceilingFor(root.adapter, context);
       if (TIER_RANK[declared] > TIER_RANK[ceiling]) {
         throw new Error(
-          `Game manifest: world "${world.id}": declared capabilities.${context} tier "${declared}" ` +
+          `Game manifest: root "${root.id}": declared capabilities.${context} tier "${declared}" ` +
             `exceeds the "${ceiling}" ceiling for this adapter in the ${context} context (§4). ` +
             'Under-claiming (including `unsupported`) is legal; over-claiming is not.',
         );
@@ -267,15 +314,15 @@ function resolveCapabilities(world: WorldEntry): { local: Tier; hosted: Tier } {
     }
 
     // Omitted -> derive.
-    if (world.adapter === 'default') {
+    if (typeof root.adapter === 'string') {
       result[context] = 'first-party';
-    } else if (isModuleAdapter(world.adapter)) {
+    } else if (isModuleAdapter(root.adapter)) {
       throw new Error(
-        `Game manifest: world "${world.id}": { module } adapter requires an explicit ` +
+        `Game manifest: root "${root.id}": { module } adapter requires an explicit ` +
           `capabilities.${context} declaration — a custom adapter's reach is not derivable (§4).`,
       );
     } else {
-      result[context] = CAPABILITY_CEILINGS.ingest[world.adapter.ingest.strategy][context];
+      result[context] = CAPABILITY_CEILINGS.ingest[root.adapter.ingest.strategy][context];
     }
   }
 
@@ -292,10 +339,10 @@ function checkEngineVersionPin(version: string): void {
 }
 
 /**
- * Resolve one already-Zod-validated world entry into its `ResolvedWorldEntry`
+ * Resolve one already-Zod-validated root entry into its `ResolvedAdapterRoot`
  * (adapter identity, capabilities, and a pass-through of every other field).
- * Every `WorldEntry` field participates here or in a check above:
- * `id`/`kind` drive adapter resolution + uniqueness; `adapter` (incl. its
+ * Every `AdapterRoot` field participates here or in a check above:
+ * `id` drives uniqueness; `adapter` (incl. its surface and
  * `module`/`ingest.*` sub-fields) drives identity + capability-ceiling
  * resolution; `scene`/`entry` drive the scene/entry cross-field rule and are
  * carried through; `zOrder` drives the final sort; `pausable`/`loop` are
@@ -303,22 +350,23 @@ function checkEngineVersionPin(version: string): void {
  * `capabilities.{local,hosted}` drive tier resolution; `description` (T3.3
  * slice 3) is carried through as-is — its consumer today is
  * `resolveIngestDescriptor` (packages/editor/src/adapter-resolver.ts), which
- * threads an ingest-three world's description into `IngestGame.description`.
+ * threads an ingest-three root's description into `IngestGame.description`.
  */
-function resolveWorld(world: WorldEntry): ResolvedWorldEntry {
-  checkAdapterSceneEntryRules(world);
+function resolveRoot(root: AdapterRoot): ResolvedAdapterRoot {
+  checkAdapterSceneEntryRules(root);
+  const adapter = resolveAdapter(root);
 
   return {
-    id: world.id,
-    kind: world.kind,
-    description: world.description,
-    adapter: resolveAdapter(world),
-    scene: world.scene,
-    entry: world.entry,
-    zOrder: world.zOrder,
-    pausable: world.pausable,
-    loop: world.loop,
-    capabilities: resolveCapabilities(world),
+    id: root.id,
+    surface: adapter.surface,
+    description: root.description,
+    adapter,
+    scene: root.scene,
+    entry: root.entry,
+    zOrder: root.zOrder,
+    pausable: root.pausable,
+    loop: root.loop,
+    capabilities: resolveCapabilities(root),
   };
 }
 
@@ -329,20 +377,20 @@ function resolveWorld(world: WorldEntry): ResolvedWorldEntry {
 /**
  * Parse + validate + resolve a raw manifest value into a `ResolvedGameManifest`.
  * Pure data-in/data-out (no `fs`) — see `load-file.ts` for the Node path-based
- * wrapper. Throws a descriptive `Error` (naming the offending world/field) on
+ * wrapper. Throws a descriptive `Error` (naming the offending root/field) on
  * any Zod validation failure or cross-field rule violation.
  */
 export function loadGameManifest(raw: unknown): ResolvedGameManifest {
   const parsed = GameManifestSchema.safeParse(raw);
   if (!parsed.success) {
-    // D-V6: the `worlds` `superRefine`'s duplicate-id issue is the one
+    // D-V6: the `roots` `superRefine`'s duplicate-id issue is the one
     // schema-level violation this loader still surfaces as a clean, single
     // `Error` (matching `checkUniqueWorldIds`'s pre-D-V6 message shape) —
     // every other schema violation keeps propagating as the raw `ZodError`
     // it always has (unchanged behavior, e.g. the iframe-reachable
     // field-exclusivity / manifestVersion checks).
     const dupIssue = parsed.error.issues.find((issue) =>
-      issue.message.startsWith('Game manifest: duplicate world id'),
+      issue.message.startsWith('Game manifest: duplicate root id'),
     );
     if (dupIssue) throw new Error(dupIssue.message);
     throw parsed.error;
@@ -351,16 +399,16 @@ export function loadGameManifest(raw: unknown): ResolvedGameManifest {
 
   checkEngineVersionPin(manifest.engine.version);
 
-  const resolvedWithIndex = manifest.worlds.map((world, index) => ({
-    world: resolveWorld(world),
+  const resolvedWithIndex = manifest.roots.map((root, index) => ({
+    root: resolveRoot(root),
     index,
   }));
 
   resolvedWithIndex.sort(
-    (a, b) => a.world.zOrder - b.world.zOrder || a.index - b.index, // ties -> array order (§3)
+    (a, b) => a.root.zOrder - b.root.zOrder || a.index - b.index, // ties -> array order (§3)
   );
 
-  const worlds = resolvedWithIndex.map(({ world }) => world);
+  const roots = resolvedWithIndex.map(({ root }) => root);
 
   const server = manifest.server
     ? { room: manifest.server.room, module: manifest.server.module ?? DEFAULT_SERVER_MODULE }
@@ -369,10 +417,15 @@ export function loadGameManifest(raw: unknown): ResolvedGameManifest {
   return {
     manifestVersion: manifest.manifestVersion,
     name: manifest.name,
+    appId: manifest.appId,
+    editorPort: manifest.editorPort,
     version: manifest.version,
     engine: { version: manifest.engine.version },
-    worlds,
+    roots,
     server,
     resolution: manifest.resolution,
+    authoring: manifest.authoring,
+    debug: manifest.debug,
+    determinism: manifest.determinism,
   };
 }