@vgai/editor 0.2.0 → 0.4.0-canary.20260715.0

package/src/ingest/games/pointerlock-maze/vgai.game.json

@@ -1,19 +1,22 @@
 {
-  "manifestVersion": 1,
+  "manifestVersion": 2,
   "name": "three.js — Pointer-Lock Maze",
   "version": "0.1.0",
   "engine": {
     "version": "0.1.0"
   },
-  "worlds": [
+  "roots": [
     {
       "id": "pointerlock-maze",
-      "kind": "threejs",
       "description": "Upstream misc_controls_pointerlock: WASD + pointer-lock first-person walk over a procedural box field. Own scene/camera/renderer/rAF/input. Needs #blocker/#instructions DOM.",
       "adapter": {
+        "surface": "threejs",
         "ingest": {
           "strategy": "shared",
-          "domStubs": ["blocker", "instructions"]
+          "domStubs": [
+            "blocker",
+            "instructions"
+          ]
         }
       },
       "entry": "game.js"

package/src/ingest/games-2d/bubbo-bubbo/vgai.game.json

@@ -1,16 +1,16 @@
 {
-  "manifestVersion": 1,
+  "manifestVersion": 2,
   "name": "Bubbo Bubbo (real OSS game)",
   "version": "0.1.0",
   "engine": {
     "version": "0.1.0"
   },
-  "worlds": [
+  "roots": [
     {
       "id": "bubbo-bubbo",
-      "kind": "pixijs",
       "description": "REAL unmodified OSS PixiJS game — pixijs/open-games Bubbo Bubbo, vendored byte-for-byte under vendor/pixi-games/bubbo-bubbo (MIT) and mounted via the iframe-reachable-multi route (Track P). Requires the gitignored externalized bundle: run vendor/pixi-games/_host/build-bubbo.sh first.",
       "adapter": {
+        "surface": "pixijs",
         "ingest": {
           "strategy": "iframe-reachable",
           "bundleUrl": "/pixi-game-static/bubbo-bubbo/bubbo-bubbo.mjs",

package/src/ingest/games-2d/bunnymark/vgai.game.json

@@ -1,16 +1,16 @@
 {
-  "manifestVersion": 1,
+  "manifestVersion": 2,
   "name": "Bunnymark",
   "version": "0.1.0",
   "engine": {
     "version": "0.1.0"
   },
-  "worlds": [
+  "roots": [
     {
       "id": "bunnymark",
-      "kind": "pixijs",
       "description": "Canonical PixiJS sprite-batching stress test — thousands of bouncing sprites.",
       "adapter": {
+        "surface": "pixijs",
         "ingest": {
           "strategy": "shared"
         }

package/src/ingest/games-2d/flappy/vgai.game.json

@@ -1,16 +1,16 @@
 {
-  "manifestVersion": 1,
+  "manifestVersion": 2,
   "name": "Flappy Bird",
   "version": "0.1.0",
   "engine": {
     "version": "0.1.0"
   },
-  "worlds": [
+  "roots": [
     {
       "id": "flappy",
-      "kind": "pixijs",
       "description": "Gravity/physics, keyboard + pointer input, AABB collision, scrolling, score HUD.",
       "adapter": {
+        "surface": "pixijs",
         "ingest": {
           "strategy": "shared"
         }

package/src/ingest/games-2d/flappy-pixi/vgai.game.json

@@ -1,16 +1,16 @@
 {
-  "manifestVersion": 1,
+  "manifestVersion": 2,
   "name": "Flappy Pixi (real OSS game, pixi v6)",
   "version": "0.1.0",
   "engine": {
     "version": "0.1.0"
   },
-  "worlds": [
+  "roots": [
     {
       "id": "flappy-pixi",
-      "kind": "pixijs",
       "description": "REAL unmodified OSS PixiJS game — aliexme's Flappy Pixi, vendored byte-for-byte under vendor/pixi-games/flappy-pixi (MIT). Pixi v6 on the v8 host via version-skew (D-P2): pixiModuleUrl's PRESENCE swaps the trapped instance to a served standalone pixi@6.5.10 build. Assets are inlined in the bundle. Requires the gitignored bundles: run vendor/pixi-games/_host/build-flappy-pixi.sh first.",
       "adapter": {
+        "surface": "pixijs",
         "ingest": {
           "strategy": "iframe-reachable",
           "bundleUrl": "/pixi-game-static/flappy-pixi/flappy-pixi.mjs",

package/src/ingest/games-2d/puzzling-potions/vgai.game.json

@@ -1,16 +1,16 @@
 {
-  "manifestVersion": 1,
+  "manifestVersion": 2,
   "name": "Puzzling Potions (real OSS game)",
   "version": "0.1.0",
   "engine": {
     "version": "0.1.0"
   },
-  "worlds": [
+  "roots": [
     {
       "id": "puzzling-potions",
-      "kind": "pixijs",
       "description": "REAL unmodified OSS PixiJS game — pixijs/open-games Puzzling Potions (match-3 with Spine animations; spine-pixi-v8 pinned exactly 4.2.95 — see host-namespace-registry.ts), vendored byte-for-byte under vendor/pixi-games/puzzling-potions (MIT), iframe-reachable-multi route (Track P). Requires the gitignored externalized bundle: run vendor/pixi-games/_host/build-puzzling-potions.sh first.",
       "adapter": {
+        "surface": "pixijs",
         "ingest": {
           "strategy": "iframe-reachable",
           "bundleUrl": "/pixi-game-static/puzzling-potions/puzzling-potions.mjs",

package/src/ingest/games-2d/tilemap-camera/vgai.game.json

@@ -1,16 +1,16 @@
 {
-  "manifestVersion": 1,
+  "manifestVersion": 2,
   "name": "Tilemap + Camera",
   "version": "0.1.0",
   "engine": {
     "version": "0.1.0"
   },
-  "worlds": [
+  "roots": [
     {
       "id": "tilemap-camera",
-      "kind": "pixijs",
       "description": "Real @pixi/tilemap CompositeTilemap (60x40 grid) + keyboard player + camera follow.",
       "adapter": {
+        "surface": "pixijs",
         "ingest": {
           "strategy": "shared"
         }

package/src/ingest/games-react/react-rpg/vgai.game.json

@@ -1,16 +1,16 @@
 {
-  "manifestVersion": 1,
+  "manifestVersion": 2,
   "name": "React RPG: 2e (real OSS game)",
   "version": "2.0.0",
   "engine": {
     "version": "0.1.0"
   },
-  "worlds": [
+  "roots": [
     {
       "id": "react-rpg",
-      "kind": "react",
       "description": "REAL unmodified native-React OSS game — ASteinheiser/react-rpg.com, vendored byte-for-byte under vendor/react-games/react-rpg (MIT) and mounted via the ingest-react identity (Track N, D-N1/D-N2/D-N3). No authoring in v1 (D-N8) — this world is ingested read-only, no scene/write-back surface.",
       "adapter": {
+        "surface": "react",
         "ingest": {
           "strategy": "deduped"
         }

package/src/ingest/types.ts

@@ -81,7 +81,7 @@ export interface IngestGame {
    * a manifest that has one. `ingest/discovery.ts`'s in-tree fixture route
    * sets this from the parsed manifest's `version`; `adapter-resolver.ts`'s
    * `resolveIngestDescriptor` (the CLI-on-folder / manifest-world route)
-   * cannot — it only has a `ResolvedWorldEntry`, not the manifest's top-level
+   * cannot — it only has a `ResolvedAdapterRoot`, not the manifest's top-level
    * `version` — so `ingest-mode.ts`'s `enterIngestModeFromManifestWorld`
    * threads the resolved manifest's `version` through as an explicit
    * parameter instead, taking precedence over this field where both exist.

package/src/ingest-mode.ts

@@ -32,7 +32,7 @@
 
 import { readGameContract } from '@engine/adapter/ingest/game-contract';
 import { extractUpstreamPin } from '@engine/adapter/ingest/upstream-pin';
-import type { ResolvedGameManifest, ResolvedWorldEntry } from '@engine/manifest/load';
+import type { ResolvedAdapterRoot, ResolvedGameManifest } from '@engine/manifest/load';
 import type { Tier } from '@engine/manifest/schema';
 import type { Overlay2D } from '@engine/world2d/authoring-2d';
 import {
@@ -90,7 +90,6 @@ import {
   ReactDomAuthoringAdapter,
   type ReactDomOverlay,
 } from './authoring/react-dom-authoring-adapter';
-import { unregisterUndoAdapter } from './authoring/undo-timeline';
 import { loadWorldOverlay, saveWorldOverlay, worldOverlayPath } from './authoring/world-overlay';
 import { World2DAuthoringAdapter } from './authoring/world2d-authoring-adapter';
 import { editorConsole } from './editor-console';
@@ -134,7 +133,7 @@ interface IngestSession {
  * own sections), referenced here by forward type reference.
  *
  * `siblings` (D-V2, docs/WAVE5-MULTIWORLD-INGEST-DESIGN.md, F24 composite):
- * a composite manifest's OTHER worlds, mounted beside this session's ingest
+ * a composite manifest's OTHER roots, mounted beside this session's ingest
  * world (`ingest-siblings.ts`'s `mountIngestSiblings`) — always `[]` for
  * every non-composite entry path (the in-tree fixture glob route, the
  * `?ingest=` URL route, a single-world manifest). `exitActiveIngest` below
@@ -490,7 +489,7 @@ async function mountThreeIframeReachableBundle(
  *
  * `declaredTier` (T3.4 slice 1, docs/ADAPTER-AUTHORING-DESIGN.md §1.C
  * retrofit) is the world's declared `capabilities.local` tier, when known —
- * only `enterIngestModeFromManifestWorld` has a `ResolvedWorldEntry` to read
+ * only `enterIngestModeFromManifestWorld` has a `ResolvedAdapterRoot` to read
  * it from; the in-tree fixture route (`enterIngestMode`) has no manifest at
  * all, so it stays `undefined` there (anti-shim: never fabricate a declared
  * tier that was never actually declared). Both embed-only degradation points
@@ -772,7 +771,7 @@ export async function enterIngestMode(store: EditorStore, gameId: string): Promi
  * world id too, for the in-tree fixtures — same namespace, different origin).
  *
  * `gameVersion` (T7.7/D9): `resolveIngestDescriptor` only has a
- * `ResolvedWorldEntry`, not the manifest's top-level `version` — so the caller
+ * `ResolvedAdapterRoot`, not the manifest's top-level `version` — so the caller
  * (`tryManifestIngestRoute` below, which fetched the full `ResolvedGameManifest`)
  * passes it here explicitly, threaded straight through to `enterIngestModeWithGame`.
  *
@@ -783,7 +782,7 @@ export async function enterIngestMode(store: EditorStore, gameId: string): Promi
  */
 export async function enterIngestModeFromManifestWorld(
   store: EditorStore,
-  world: ResolvedWorldEntry,
+  world: ResolvedAdapterRoot,
   projectRoot: string,
   gameVersion?: string,
   upstreamPin?: string | null,
@@ -996,7 +995,7 @@ export async function enterIngestModeWithGame2D(
     throw new Error(
       `enterIngestModeWithGame2D: world2d ingest game "${game.id}" has neither \`load\` nor ` +
         '`bundleUrl` — only shared/deduped (load) or iframe-reachable (bundleUrl) ingest-pixi ' +
-        'worlds are mountable this slice (resolveIngest2DDescriptor).',
+        'roots are mountable this slice (resolveIngest2DDescriptor).',
     );
   }
 
@@ -1105,7 +1104,7 @@ export async function enterIngestModeWithGame2D(
  */
 export async function enterIngestModeFromManifestWorld2D(
   store: EditorStore,
-  world: ResolvedWorldEntry,
+  world: ResolvedAdapterRoot,
   projectRoot: string,
 ): Promise<void> {
   const game = resolveIngest2DDescriptor(world, projectRoot);
@@ -1141,7 +1140,9 @@ function disposePixiSession(s: IngestSession2D): void {
   // timeline (mirrors `IngestAuthoringAdapter` — see disposeThreejsSession's
   // identical call above), so this session's entries must be dropped the same
   // way on exit. Absent for a D-W2 opaque-embed session (no adapter, no undo entries).
-  if (s.adapter) unregisterUndoAdapter(s.adapter);
+  if (s.adapter) {
+    s.adapter.dispose();
+  }
   setActiveAuthoring(null);
   setActiveSystems(null);
   setMountFailureReport(null); // D-W3: no session -> no banner to show (mirrors setActiveOverlayReport(null) above)
@@ -1176,9 +1177,7 @@ interface IngestSessionReact {
   /** The runtime Game's real play-state control — the F26 play surface. */
   setPaused: (paused: boolean) => void;
   stop: () => void;
-  /** D-K4 (wave 10 Slice A): the live DOM-authoring adapter both routes now
-   *  install — self-registered with the global undo timeline at construction,
-   *  so teardown must unregister it (mirrors `IngestSession2D.adapter`). */
+  /** Live DOM-authoring adapter; owns a session history resource. */
   adapter: ReactDomAuthoringAdapter;
 }
 
@@ -1229,17 +1228,17 @@ function reactDomEvidence(
  * `?ingest=<id>` URL route's react fallback, tried after the three/pixi
  * fixture globs — see `autoLaunchIngestFromURL` below). Mounts through the
  * EXACT SAME T6.2 react-world host stack `default-react`/multi-world react
- * worlds use — NOT the capture-based three/pixi bridge (there is no scene to
+ * roots use — NOT the capture-based three/pixi bridge (there is no scene to
  * capture; the mounted tree IS React, D-N1).
  *
  * Reuses `resolveAllWorlds` + the WORLDS-PATH `createGameRuntime` (not the
  * legacy single-`{canvas,adapter}` path, which is three-only and has no
  * `ReactWorldHost`/`container` concept — see `create-runtime.ts`'s
  * `HostContext`) rather than hand-building a `ReactWorldHost`/`Game`: a
- * single-element `worlds` array gets EVERY host concern for free (the
+ * single-element `roots` array gets EVERY host concern for free (the
  * absolutely-positioned DOM-root layer, a real `Game`, dispose via
  * `session.stop()`) with zero reinvention — `resolveAllWorlds`'s
- * `MULTI_WORLD_ALLOWED_IDENTITIES` gate only fires for `worlds.length > 1`
+ * `MULTI_WORLD_ALLOWED_IDENTITIES` gate only fires for `roots.length > 1`
  * (see that function's doc comment), so a ONE-element manifest containing an
  * `ingest-react` world resolves cleanly through it despite that identity
  * being excluded from real multi-world manifests.
@@ -1295,7 +1294,7 @@ export async function enterIngestModeReact(store: EditorStore, folderId: string)
   const h = gameContainer.clientHeight;
   const session = await createGameRuntime({
     container: gameContainer,
-    worlds: specs,
+    roots: specs,
     width: w,
     height: h,
   });
@@ -1307,7 +1306,7 @@ export async function enterIngestModeReact(store: EditorStore, folderId: string)
   // adapter with none — it is installed directly, never `withStoreSelection`-wrapped.
   const worldId = game.worldId;
   const overlay = await loadWorldOverlay<ReactDomOverlay>(worldId);
-  const root = session.game.worlds[0]!.reactRoot();
+  const root = session.game.roots[0]!.reactRoot();
   const adapter = new ReactDomAuthoringAdapter(root, store, {
     overlay,
     persist: (o) => saveWorldOverlay(worldId, o),
@@ -1367,8 +1366,8 @@ export async function enterIngestModeReact(store: EditorStore, folderId: string)
  * manifest-route sibling of {@link enterIngestModeReact} above: an
  * EXTERNAL-FOLDER `ingest-react` world (the opened project's OWN
  * `vgai.game.json`, not the vendored `games-react/<id>` discovery glob)
- * enters the same react ingest session. Exactly the same worlds-path recipe
- * (one-element `resolveAllWorlds` + worlds-path `createGameRuntime`) and the
+ * enters the same react ingest session. Exactly the same roots-path recipe
+ * (one-element `resolveAllWorlds` + roots-path `createGameRuntime`) and the
  * same `ReactDomAuthoringAdapter` D-K4 wiring (see that function's doc
  * comment) — only the SOURCE of `world`/`projectRoot` differs (the opened project's manifest +
  * `project.rootPath`, via `tryManifestIngestRouteReact` below, instead of
@@ -1382,7 +1381,7 @@ export async function enterIngestModeReact(store: EditorStore, folderId: string)
 export async function enterIngestModeFromManifestWorldReact(
   store: EditorStore,
   manifest: ResolvedGameManifest,
-  world: ResolvedWorldEntry,
+  world: ResolvedAdapterRoot,
   projectRoot: string,
 ): Promise<void> {
   if (getEditorMode() === 'browser') {
@@ -1411,12 +1410,12 @@ export async function enterIngestModeFromManifestWorldReact(
   // above) makes — an external-folder game may declare the game contract too.
   (window as unknown as { __vgaiMountCold?: boolean }).__vgaiMountCold = true;
   const { createGameRuntime } = await import('@engine/runtime/create-runtime');
-  const specs = await resolveAllWorlds({ ...manifest, worlds: [world] }, projectRoot);
+  const specs = await resolveAllWorlds({ ...manifest, roots: [world] }, projectRoot);
   const w = gameContainer.clientWidth;
   const h = gameContainer.clientHeight;
   const session = await createGameRuntime({
     container: gameContainer,
-    worlds: specs,
+    roots: specs,
     width: w,
     height: h,
   });
@@ -1426,7 +1425,7 @@ export async function enterIngestModeFromManifestWorldReact(
   // not `game.worldId` (the vendored-fixture wrapper's field).
   const worldId = world.id;
   const overlay = await loadWorldOverlay<ReactDomOverlay>(worldId);
-  const root = session.game.worlds[0]!.reactRoot();
+  const root = session.game.roots[0]!.reactRoot();
   const adapter = new ReactDomAuthoringAdapter(root, store, {
     overlay,
     persist: (o) => saveWorldOverlay(worldId, o),
@@ -1476,12 +1475,8 @@ export async function enterIngestModeFromManifestWorldReact(
  */
 function disposeReactSession(s: IngestSessionReact): void {
   setGameInputGate(() => true);
-  // D-K4: this session's ReactDomAuthoringAdapter self-registered with the
-  // global undo timeline at construction (mirrors `IngestAuthoringAdapter`/
-  // `World2DAuthoringAdapter`/`ReactWorldAuthoringAdapter`) — drop it so any
-  // of its entries still on the global stack are dropped (with a warn), not
-  // undone against a torn-down DOM.
-  unregisterUndoAdapter(s.adapter);
+  // Disposal expires its session history and releases listeners.
+  s.adapter.dispose();
   setActiveAuthoring(null);
   setActiveSystems(null);
   setMountFailureReport(null); // D-W3: no session -> no banner to show (mirrors disposeThreejsSession's identical call)
@@ -1521,10 +1516,11 @@ function disposeThreejsSession(s: IngestSession): void {
   // way on exit.
   setGameInputGate(() => true);
 
-  // T3.2 slice 2: this ingest session's authoring adapter is done recording —
-  // drop it from the undo timeline's live set so any of its entries still on the
-  // global stack are dropped (with a warn), not undone against a torn-down scene.
-  if (s.mount?.authoring) unregisterUndoAdapter(s.mount.authoring);
+  // The concrete ingest adapter owns a session history resource. Dispose it
+  // when present; minimal/custom authoring implementations need no teardown.
+  if (s.mount?.authoring) {
+    s.mount.authoring.dispose?.();
+  }
   setActiveAuthoring(null);
   setActiveSystems(null);
   setActiveOverlayReport(null); // D9: no session -> no banner to show
@@ -1629,7 +1625,7 @@ if (import.meta.env.DEV) {
  * Wait for the Game-tab container (registered via a callback ref at layout
  * mount) — poll a bounded number of rAF ticks so we don't race the first
  * paint. Exported (T3.4 slice 2) so `module-mode.ts`'s manifest-route auto-
- * mount for `{ module }` worlds — the sibling of `tryManifestIngestRoute`
+ * mount for `{ module }` roots — the sibling of `tryManifestIngestRoute`
  * below — can reuse the SAME wait rather than duplicating it.
  */
 export async function waitForGameContainer(): Promise<boolean> {
@@ -1646,17 +1642,17 @@ export async function waitForGameContainer(): Promise<boolean> {
 
 /**
  * D-V2 (docs/WAVE5-MULTIWORLD-INGEST-DESIGN.md, F24 composite): every world
- * in `manifest.worlds` whose adapter is `{ ingest }` — a composite manifest
+ * in `manifest.roots` whose adapter is `{ ingest }` — a composite manifest
  * caps this at exactly one (see each `tryManifestIngestRoute*` below); ≥2 is
  * a loud named error via {@link reportTooManyIngestWorlds}, never a silent
  * first-wins pick (mirrors `run-bundle.ts`'s fail-on-ambiguity pattern).
  */
-function findIngestWorlds(manifest: ResolvedGameManifest): ResolvedWorldEntry[] {
-  return manifest.worlds.filter((w) => w.adapter.type === 'ingest');
+function findIngestWorlds(manifest: ResolvedGameManifest): ResolvedAdapterRoot[] {
+  return manifest.roots.filter((w) => w.adapter.type === 'ingest');
 }
 
 /**
- * D-V2: the "composite declares ≥2 ingest worlds" violation — named, listing
+ * D-V2: the "composite declares ≥2 ingest roots" violation — named, listing
  * every offending world id, reported once (into BOTH `editorConsole` and the
  * D-V5 multi-entry mount-failure report, one entry per offending world so
  * the banner names all of them) by whichever `tryManifestIngestRoute*`
@@ -1664,7 +1660,7 @@ function findIngestWorlds(manifest: ResolvedGameManifest): ResolvedWorldEntry[]
  * `autoLaunchIngestFromURL`) — the caller returns `true` right after this
  * (claims the route), so the other two ingest routes never also report it.
  */
-function reportTooManyIngestWorlds(ingestWorlds: ResolvedWorldEntry[]): void {
+function reportTooManyIngestWorlds(ingestWorlds: ResolvedAdapterRoot[]): void {
   const ids = ingestWorlds.map((w) => `"${w.id}"`).join(', ');
   const message =
     'a composite manifest declares exactly ONE ingest world in this slice — found ' +
@@ -1673,7 +1669,7 @@ function reportTooManyIngestWorlds(ingestWorlds: ResolvedWorldEntry[]): void {
   for (const world of ingestWorlds) {
     addMountFailureReport({
       worldId: world.id,
-      kind: world.kind,
+      kind: world.surface,
       identity: world.adapter.identity,
       message,
     });
@@ -1746,17 +1742,17 @@ async function mountCompositeSiblings(
  */
 function promoteToCompositeAuthoring(
   manifest: ResolvedGameManifest,
-  ingestWorld: ResolvedWorldEntry,
+  ingestWorld: ResolvedAdapterRoot,
   siblings: readonly SiblingMount[],
 ): void {
   if (siblings.length === 0) return;
   const primaryAdapter = getAuthoringOverride();
   if (!primaryAdapter) return;
   const children: CompositeChild[] = [
-    { worldId: ingestWorld.id, kind: ingestWorld.kind, adapter: primaryAdapter },
+    { worldId: ingestWorld.id, kind: ingestWorld.surface, adapter: primaryAdapter },
     ...siblings.map((s) => ({
       worldId: s.worldId,
-      kind: manifest.worlds.find((w) => w.id === s.worldId)?.kind ?? 'unknown',
+      kind: manifest.roots.find((w) => w.id === s.worldId)?.surface ?? 'unknown',
       // D-E1: every successfully-mounted SiblingMount gets an honest
       // `authoring` whenever a store was supplied — every composite route
       // below supplies one, so this is never actually undefined in
@@ -1776,8 +1772,8 @@ function promoteToCompositeAuthoring(
  * ingest world at all, or the one ingest world isn't ingest-three", so the
  * next route (pixi, react, then the URL route) still gets a chance.
  *
- * D-V2 (F24 composite): scans ALL worlds for `{ ingest }` adapters, not just
- * `worlds[0]` — 0 ingest worlds declines (unchanged non-ingest-manifest
+ * D-V2 (F24 composite): scans ALL roots for `{ ingest }` adapters, not just
+ * `roots[0]` — 0 ingest roots declines (unchanged non-ingest-manifest
  * behavior); ≥2 claims the route and fails loudly
  * ({@link reportTooManyIngestWorlds}), mounting nothing; exactly 1 whose
  * identity is `ingest-three` mounts THAT world (wherever it sits in the
@@ -1815,7 +1811,7 @@ async function tryManifestIngestRoute(store: EditorStore): Promise<boolean> {
   try {
     // D9/T7.7: thread the manifest's OWN version through — resolveIngestDescriptor
     // (called inside enterIngestModeFromManifestWorld) only sees the per-world
-    // ResolvedWorldEntry, not this top-level field.
+    // ResolvedAdapterRoot, not this top-level field.
     // R5 (§4(c)): best-effort read of this project's UPSTREAM.md pin, same
     // spirit — resolveIngestDescriptor has no way to discover one either.
     const upstreamPin = await readVendoredUpstreamPin();
@@ -1849,7 +1845,7 @@ async function tryManifestIngestRoute(store: EditorStore): Promise<boolean> {
     // Populate the loud banner slot too.
     setMountFailureReport({
       worldId: ingestWorld.id,
-      kind: ingestWorld.kind,
+      kind: ingestWorld.surface,
       identity: ingestWorld.adapter.identity,
       message: formatMountFailureMessage(err),
     });
@@ -1910,7 +1906,7 @@ async function tryManifestIngestRoute2D(store: EditorStore): Promise<boolean> {
     // D-W3 (F9) — see tryManifestIngestRoute's identical comment above.
     setMountFailureReport({
       worldId: ingestWorld.id,
-      kind: ingestWorld.kind,
+      kind: ingestWorld.surface,
       identity: ingestWorld.adapter.identity,
       message: formatMountFailureMessage(err),
     });
@@ -1973,7 +1969,7 @@ async function tryManifestIngestRouteReact(store: EditorStore): Promise<boolean>
     // D-W3 (F9) — see tryManifestIngestRoute's identical comment above.
     setMountFailureReport({
       worldId: ingestWorld.id,
-      kind: ingestWorld.kind,
+      kind: ingestWorld.surface,
       identity: ingestWorld.adapter.identity,
       message: formatMountFailureMessage(err),
     });
@@ -1999,8 +1995,7 @@ async function tryManifestIngestRouteReact(store: EditorStore): Promise<boolean>
  *  2. Manifest route, three (T3.3 slice 3, docs/CLI-ON-FOLDER-DESIGN.md §1E,
  *     `tryManifestIngestRoute` above) — the CLI-on-folder AC ("point the CLI
  *     at an ingest game folder never registered in source -> opens, plays,
- *     edits"). Browser-mode builds and legacy `project.json`-only projects
- *     both fall straight through to route 5, unchanged.
+ *     edits"). Browser-mode builds fall straight through to route 5.
  *  3. Manifest route, pixi (T6.1 slice 4, `tryManifestIngestRoute2D` above) —
  *     the world2d silo retirement's replacement discovery path for an
  *     `ingest-pixi` world.
@@ -2040,7 +2035,7 @@ export async function autoLaunchIngestFromURL(store: EditorStore): Promise<void>
     } catch (err) {
       editorConsole.error(`Auto-ingest failed: ${err}`, 'ingest');
       // D-W3 (F9): the `?ingest=<id>` URL-fallback route has no
-      // `ResolvedWorldEntry` to read a world id/kind from (it resolves
+      // `ResolvedAdapterRoot` to read a world id/kind from (it resolves
       // straight off the in-tree fixture globs) — `gameId` and the fixed
       // 'threejs'/'ingest-three' vocabulary are the closest honest analog.
       setMountFailureReport({