@vgai/engine 0.5.2 → 0.5.3

package/src/manifest/load.ts

@@ -1,4 +1,4 @@
-// T3.1 slice 1 — the game manifest loader/validator (docs/GAME-MANIFEST-DESIGN.md §5).
+// The game manifest loader/validator.
 //
 // Pure data-in/data-out: `loadGameManifest(raw)` parses `raw` against
 // `GameManifestSchema`, runs the cross-field checks §3 promises beyond what
@@ -31,23 +31,22 @@ import {
 export type ResolvedAdapter =
   | {
       readonly type: 'builtin';
-      readonly identity: 'threejs' | 'pixijs' | 'react';
-      readonly surface: 'threejs' | 'pixijs' | 'react';
+      readonly identity: 'three' | 'canvas' | 'dom';
+      readonly surface: 'three' | 'canvas' | 'dom';
     }
   | {
       readonly type: 'module';
       readonly identity: 'module';
       readonly module: string;
-      readonly surface: 'threejs' | 'pixijs' | 'react';
+      readonly surface: 'three' | 'canvas' | 'dom';
     }
   | {
       readonly type: 'ingest';
-      // 'ingest-react' (Track N, N1 — docs/REACT-INGEST-LANDING-DESIGN.md
-      // D-N2) is assigned here purely structurally (kind === 'react'), same
-      // as 'ingest-three'/'ingest-pixi': this loader stays strategy-agnostic
-      // at resolve time, exactly like the other two ingest identities
-      // (`ceilingFor`/`resolveCapabilities` below already derive tiers per
-      // `strategy` regardless of `kind`). The v1 "deduped rung only" rule
+      // 'ingest-react' (Track N, N1) is assigned here purely structurally (kind
+      // === 'dom'), same as 'ingest-three'/'ingest-pixi': this loader stays
+      // strategy-agnostic at resolve time, exactly like the other two ingest
+      // identities (`ceilingFor`/`resolveCapabilities` below already derive tiers
+      // per `strategy` regardless of `kind`). The v1 "deduped rung only" rule
       // (D-N3) is enforced editor-side, at the resolver
       // (`packages/editor/src/adapter-resolver.ts`'s `resolveIngestReactAdapter`)
       // — not here — mirroring how THIS file never rejects
@@ -55,13 +54,13 @@ 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 surface: 'three' | 'canvas' | 'dom';
       readonly strategy: IngestStrategy;
       readonly entryHtml: string | undefined;
       readonly assets: Record<string, string> | undefined;
       readonly domStubs: string[] | undefined;
       readonly captureTimeoutMs: number | undefined;
-      /** Track P (docs/PIXI-INGEST-LANDING-DESIGN.md §2) — iframe-reachable-multi mount fields. */
+      /** Iframe-reachable-multi mount fields. */
       readonly bundleUrl: string | undefined;
       readonly baseHref: string | undefined;
       readonly assetBaseUrl: string | undefined;
@@ -75,10 +74,12 @@ export interface ResolvedAdapterRoot {
   readonly surface: ResolvedAdapter['surface'];
   readonly description: string | undefined;
   readonly adapter: ResolvedAdapter;
-  readonly scene: string | undefined;
   readonly entry: string | undefined;
   readonly zOrder: number;
   readonly pausable: boolean;
+  /** `dev: true` — this root is a DEV LAYER, not shipped game content. See
+   *  `manifest/schema.ts`'s `dev` field for the four readers. */
+  readonly dev: boolean;
   readonly loop: 'gated' | 'self-driven';
   /** Every optional resolved: both contexts always present (§4/§5). */
   readonly capabilities: { readonly local: Tier; readonly hosted: Tier };
@@ -88,7 +89,6 @@ export interface ResolvedGameManifest {
   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). */
@@ -116,7 +116,7 @@ export interface ResolvedGameManifest {
   /** 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`. */
+   *  trap.. */
   readonly determinism:
     | { readonly seededRandom: boolean; readonly defaultSeed?: number | undefined }
     | undefined;
@@ -133,16 +133,16 @@ export interface ResolvedGameManifest {
         readonly maxTriangles?: number | undefined;
       }
     | undefined;
-  /** FT-5 (docs/FTUE-LEARN-SYSTEM-DESIGN.md §3) — learner-facing metadata on
-   *  shipped example projects; read by the editor server's registry surface
-   *  (`GET /__editor/examples`, packages/editor/server/editor-server.ts) to
-   *  generate the gallery/wizard/Learn-catalog registries. */
+  /** Learner-facing metadata on shipped example projects; read by the editor
+   *  server's registry surface (`GET /__editor/examples`,
+   *  packages/editor/server/editor-server.ts) to generate the
+   *  gallery/wizard/Learn-catalog registries. */
   readonly learn: LearnMetadata | undefined;
 }
 
 // ---------------------------------------------------------------------------
-// §4 — the per-context ceiling table (named + exported: the tier-table doc
-// test in slice 2 pins docs/CAPABILITY-TIERS.md's rows against this).
+// §4 — the per-context ceiling table (named + exported so the tier-table test
+// can pin its rows against this).
 // ---------------------------------------------------------------------------
 
 /**
@@ -204,45 +204,26 @@ function isModuleAdapter(
   return typeof adapter === 'object' && 'module' in adapter;
 }
 
-function isIngestAdapter(
-  adapter: RootAdapter,
-): adapter is Extract<RootAdapter, { ingest: { strategy: IngestStrategy } }> {
-  return typeof adapter === 'object' && 'ingest' in adapter;
-}
-
 // ---------------------------------------------------------------------------
 // Cross-field checks (§3 — beyond what Zod alone enforces)
 // ---------------------------------------------------------------------------
 //
-// 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 `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
-// `Error` — the exact message shape `checkUniqueWorldIds` used to throw
-// directly — rather than a raw multi-issue `ZodError` dump, so existing
-// callers/tests that pattern-match the message text are unaffected by the
-// enforcement moving one layer down.
-
-function checkAdapterSceneEntryRules(root: AdapterRoot): void {
+// Root-id uniqueness used to be a cross-field check HERE
+// (`checkUniqueRootIds`, removed) — it moved 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 `Error` — the exact message shape
+// `checkUniqueRootIds` used to throw directly — rather than a raw multi-issue
+// `ZodError` dump, so existing callers/tests that pattern-match the message
+// text are unaffected by the enforcement moving one layer down.
+
+function checkAdapterEntryRules(root: AdapterRoot): void {
   const { adapter } = root;
-  if (typeof adapter === 'string' && !root.scene && !root.entry) {
-    throw new Error(
-      `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 (adapter === 'react' && root.scene !== undefined) {
-    throw new Error(
-      `Game manifest: React root "${root.id}" declares \`scene\` — React roots use JSX entry modules.`,
-    );
-  }
-  if (isIngestAdapter(adapter) && root.scene !== undefined) {
+  if (typeof adapter === 'string' && !root.entry) {
     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).",
+      `Game manifest: root "${root.id}" uses the '${adapter}' adapter but declares no ` +
+        '`entry` — a built-in adapter root is authored as an entry module.',
     );
   }
 }
@@ -250,14 +231,12 @@ function checkAdapterSceneEntryRules(root: AdapterRoot): void {
 // Historical note (Track N, N1): this file used to reject EVERY `kind:
 // '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 root. There is nothing
-// left to reject at THIS layer: `checkAdapterSceneEntryRules` above already
-// 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.
+// that program — react+ingest is now a structurally legal combination,
+// resolved to the `'ingest-react'` identity by `resolveAdapter` below like
+// any other ingest root. There is nothing left to reject at THIS layer: 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.
 
 // ---------------------------------------------------------------------------
 // Resolution (§5)
@@ -283,9 +262,9 @@ function resolveAdapter(root: AdapterRoot): ResolvedAdapter {
   // 'ingest-pixi' — see the `ResolvedAdapter` type's comment above for why
   // this stays strategy-agnostic here).
   const identity =
-    adapter.surface === 'threejs'
+    adapter.surface === 'three'
       ? 'ingest-three'
-      : adapter.surface === 'pixijs'
+      : adapter.surface === 'canvas'
         ? 'ingest-pixi'
         : 'ingest-react';
   const ingest = adapter.ingest;
@@ -363,16 +342,19 @@ function checkEngineVersionPin(version: string): void {
  * 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
+ * resolution; `entry` drives the entry cross-field rule and is
  * carried through; `zOrder` drives the final sort; `pausable`/`loop` are
  * carried through as-is (their consumers are the runtime/CLI, T3.2/T3.3);
+ * `dev` is carried through for the four dev-layer readers (`mountManifestRoots`'s
+ * ship gate, the host's topmost stacking pass, the play compositor's capture
+ * exclusion, and the editor's chrome-not-content seam);
  * `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 root's description into `IngestGame.description`.
  */
 function resolveRoot(root: AdapterRoot): ResolvedAdapterRoot {
-  checkAdapterSceneEntryRules(root);
+  checkAdapterEntryRules(root);
   const adapter = resolveAdapter(root);
 
   return {
@@ -380,10 +362,10 @@ function resolveRoot(root: AdapterRoot): ResolvedAdapterRoot {
     surface: adapter.surface,
     description: root.description,
     adapter,
-    scene: root.scene,
     entry: root.entry,
     zOrder: root.zOrder,
     pausable: root.pausable,
+    dev: root.dev,
     loop: root.loop,
     capabilities: resolveCapabilities(root),
   };
@@ -400,18 +382,25 @@ function resolveRoot(root: AdapterRoot): ResolvedAdapterRoot {
  * any Zod validation failure or cross-field rule violation.
  */
 export function loadGameManifest(raw: unknown): ResolvedGameManifest {
+  // Removed-format guard FIRST, on the raw value: a legacy `.vscn.json` root
+  // would otherwise fail Zod's `roots` discriminated union with a confusing
+  // shape error instead of a migration message (WO-8).
   const parsed = GameManifestSchema.safeParse(raw);
   if (!parsed.success) {
-    // 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 root id'),
+    // D-V6: the `roots` `superRefine`'s composition issues — a duplicate root
+    // id, or more than one world root of the same medium — are the
+    // schema-level violations this loader surfaces as a clean, single `Error`
+    // (matching `checkUniqueRootIds`'s pre-D-V6 message shape) rather than a
+    // raw multi-issue dump, because each one already reads as a finished
+    // sentence naming the offending ids. 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 compositionIssue = parsed.error.issues.find(
+      (issue) =>
+        issue.message.startsWith('Game manifest: duplicate root id') ||
+        issue.message.startsWith('Game manifest: a project has at most one'),
     );
-    if (dupIssue) throw new Error(dupIssue.message);
+    if (compositionIssue) throw new Error(compositionIssue.message);
     throw parsed.error;
   }
   const manifest: GameManifest = parsed.data;
@@ -437,7 +426,6 @@ export function loadGameManifest(raw: unknown): ResolvedGameManifest {
     manifestVersion: manifest.manifestVersion,
     name: manifest.name,
     appId: manifest.appId,
-    editorPort: manifest.editorPort,
     version: manifest.version,
     engine: { version: manifest.engine.version },
     roots,

package/src/manifest/locate.ts

@@ -0,0 +1,55 @@
+// Finding the project manifest ON DISK. There is ONE filename — see
+// `./filename.ts` for why the old one was removed rather than kept readable.
+//
+// Deliberately dependency-light — `node:fs` + `node:path` + `./filename` and
+// NOTHING else (no Zod, no `./load`). Several callers are explicitly
+// schema-free by design (`packages/editor/server/project-root-surface.ts`,
+// `packages/editor/vite-plugin-ui-oid.ts`) and must be able to locate a
+// manifest without dragging the validator in.
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import {
+  MANIFEST_FILENAME,
+  REMOVED_MANIFEST_FILENAME,
+  removedManifestFilenameMessage,
+} from './filename';
+
+/**
+ * Throw the rename instruction if `dir` carries only the REMOVED manifest
+ * filename. The `assertNoRemoved*` shape: a removed thing must reject loudly
+ * naming the exact fix, never be silently ignored (which would present as
+ * "this folder is not a project" — a diagnosis pointing nowhere).
+ *
+ * Returns normally when `dir` holds the current manifest, or neither file.
+ */
+export function assertNoRemovedManifestFilename(dir: string): void {
+  if (existsSync(join(dir, MANIFEST_FILENAME))) return;
+  if (!existsSync(join(dir, REMOVED_MANIFEST_FILENAME))) return;
+  throw new Error(removedManifestFilenameMessage(join(dir, REMOVED_MANIFEST_FILENAME)));
+}
+
+/**
+ * The manifest path inside `dir`. Always `vgai.project.json` — so a "not
+ * found" message names the filename a project must be using — except that a
+ * directory carrying only the removed `vgai.game.json` THROWS the rename
+ * instruction instead of reporting a phantom path.
+ *
+ * This is the drop-in replacement for a hand-written `join(dir, …)` everywhere
+ * a manifest is READ. Writers want {@link manifestWritePath}.
+ */
+export function resolveManifestPath(dir: string): string {
+  assertNoRemovedManifestFilename(dir);
+  return join(dir, MANIFEST_FILENAME);
+}
+
+/** True when `dir` holds a manifest. A lone `vgai.game.json` throws. */
+export function hasManifest(dir: string): boolean {
+  assertNoRemovedManifestFilename(dir);
+  return existsSync(join(dir, MANIFEST_FILENAME));
+}
+
+/** Where a manifest gets WRITTEN in `dir`. There is one answer. */
+export function manifestWritePath(dir: string): string {
+  return join(dir, MANIFEST_FILENAME);
+}