@vgai/editor 0.2.0 → 0.4.0-canary.20260715.0

package/src/adapter-resolver.ts

@@ -9,7 +9,7 @@
  * (docs/REACT-INGEST-LANDING-DESIGN.md D-N2/D-N3/D-N4) for `ingest-react`
  * (vendored native-React game ingestion — the deduped-only mount).
  *
- * Turns one manifest world (`ResolvedWorldEntry`, from `@engine/manifest/load`)
+ * Turns one manifest world (`ResolvedAdapterRoot`, from `@engine/manifest/load`)
  * into a mountable {@link GameAdapter} (or, for a pixijs world, a structurally
  * distinct {@link Pixi2DGameAdapter} — see the default-pixi section below).
  * Lives editor-side, not in the engine package: it needs `/@fs/` dynamic-import
@@ -34,11 +34,11 @@
  *    slice 4) — same two-layer shape as ingest-three (descriptor builder +
  *    a named-stub `GameAdapter`; the real mount is `ingest-mode.ts`'s
  *    `enterIngestModeFromManifestWorld2D`).
- *  - `default-react` -> a `ReactWorldAdapter` (T6.2, see
+ *  - `default-react` -> a `ReactRootAdapter` (T6.2, see
  *    `resolveDefaultReactAdapter` below for the `entry`-only rule — `scene`
  *    is a named error, D4 — and the two engine-seam findings its doc
  *    comment reports).
- *  - `ingest-react` -> also a `ReactWorldAdapter` (Track N, N1 —
+ *  - `ingest-react` -> also a `ReactRootAdapter` (Track N, N1 —
  *    docs/REACT-INGEST-LANDING-DESIGN.md D-N2/D-N3, see
  *    `resolveIngestReactAdapter` below): same T6.2 mount machinery as
  *    `default-react`, restricted to the `'deduped'` strategy rung (a named
@@ -51,7 +51,7 @@
  *    ingest embed-only degradation path's retrofit (`ingest-mode.ts`).
  *
  * `resolveAllWorlds` (T6.1 slice 2, extended T6.2 for react) is the
- * multi-world sibling of `resolveWorldAdapter`: it resolves every world in a
+ * multi-world sibling of `resolveRootAdapter`: it resolves every world in a
  * `ResolvedGameManifest` into slice-1 `WorldMountSpec`s, enforcing the v1
  * scope rule for manifests with more than one world (docs/MULTI-WORLD-
  * DESIGN.md §3 slice 4, docs/REACT-WORLD-DESIGN.md §3 for react's admission).
@@ -59,14 +59,15 @@
 
 import type { GameAdapter } from '@engine/adapter';
 import { VgaiSceneGameAdapter } from '@engine/adapter';
-import { assertNever } from '@engine/adapter/world-kind';
+import { assertNever } from '@engine/adapter/adapter-surface';
+import type { GameComponentClass } from '@engine/ecs/game-component';
 import { resolveUrl } from '@engine/loader';
-import type { ResolvedGameManifest, ResolvedWorldEntry } from '@engine/manifest/load';
+import type { ResolvedAdapterRoot, ResolvedGameManifest } from '@engine/manifest/load';
 import { GameProvider as EngineGameProvider } from '@engine/react/game-state';
 import type {
   MountedReactGame,
   Pixi2DGameAdapter,
-  ReactWorldAdapter,
+  ReactRootAdapter,
   ReactWorldHost,
   WorldMountSpec,
 } from '@engine/runtime/create-runtime';
@@ -78,11 +79,10 @@ import { SceneParseError } from '@engine/scene/parse';
 import type { IngestGame2D } from '@engine/world2d/ingest2d';
 import { PixiSceneGameAdapter, type World2DSetupFn } from '@engine/world2d/pixi-game-adapter';
 import { type Scene2DFile, Scene2DSchema } from '@engine/world2d/schema/entity2d';
-import type { ProjectUIRegistry } from '@vgai/scene-ui/registry';
+import type { Component2DRegistry } from '@engine/world2d/types';
 import { type ComponentType, createElement } from 'react';
 import { flushSync } from 'react-dom';
 import { createRoot } from 'react-dom/client';
-import { reactWorldProviderImportSpecifier } from '../vite-plugin-react-world-provider';
 import { REACT_WORLD_RUNTIME_PATH } from '../vite-plugin-react-world-runtime';
 import {
   computeAchievedTier,
@@ -126,8 +126,8 @@ export function fsImportPath(projectRoot: string, relativePath: string): string
   return root.startsWith('/') ? `/@fs${root}/${rel}` : `/@fs/${root}/${rel}`;
 }
 
-/** Optional editor-session context for {@link resolveWorldAdapter}. */
-export interface ResolveWorldAdapterOptions {
+/** Optional editor-session context for {@link resolveRootAdapter}. */
+export interface ResolveRootAdapterOptions {
   /**
    * The editor's play-launch context (live in-memory scene document +
    * viewport-camera spawn) — supplied by `play-mode.ts` when the resolver is
@@ -150,6 +150,51 @@ export interface ResolveWorldAdapterOptions {
 // Part B — componentRegistry via the project's script registry
 // ---------------------------------------------------------------------------
 
+/**
+ * Fresh component constructors imported by the dev-server HMR path, scoped to
+ * their project and registry key. Vite correctly lets us import the edited
+ * leaf module with a cache-busting URL for live prototype swapping, but a
+ * later game-only restart can still resolve the cached registry module and
+ * therefore reconstruct instances with the pre-edit constructor/field
+ * initializers. Keeping the exact fresh constructor at this existing editor
+ * boundary makes `Restart Game` a real remount without reloading the editor.
+ *
+ * Overrides never fabricate registry entries: they replace only keys the
+ * project's current registry still exports. A registry edit clears the map,
+ * so deleting/remapping a key remains authoritative.
+ */
+const componentHotOverridesByProject = new Map<string, Map<string, GameComponentClass>>();
+
+export function registerProjectComponentHotOverride(
+  projectRoot: string,
+  key: string,
+  component: GameComponentClass,
+): void {
+  let overrides = componentHotOverridesByProject.get(projectRoot);
+  if (!overrides) {
+    overrides = new Map();
+    componentHotOverridesByProject.set(projectRoot, overrides);
+  }
+  overrides.set(key, component);
+}
+
+export function clearProjectComponentHotOverrides(projectRoot: string): void {
+  componentHotOverridesByProject.delete(projectRoot);
+}
+
+export function applyProjectComponentHotOverrides(
+  projectRoot: string,
+  registry: ComponentRegistry,
+): ComponentRegistry {
+  const overrides = componentHotOverridesByProject.get(projectRoot);
+  if (!overrides || overrides.size === 0) return registry;
+  const next = { ...registry };
+  for (const [key, component] of overrides) {
+    if (Object.hasOwn(registry, key)) next[key] = component;
+  }
+  return next;
+}
+
 /**
  * Load the project's component registry (`src/scripts/registry.ts`'s
  * `componentRegistry` export) via the same `/@fs/` dev-server route
@@ -173,98 +218,29 @@ export async function loadComponentRegistryForProject(
     const mod = (await import(/* @vite-ignore */ modulePath)) as {
       componentRegistry?: ComponentRegistry;
     };
-    return mod.componentRegistry ?? {};
+    return applyProjectComponentHotOverrides(projectRoot, mod.componentRegistry ?? {});
   } catch {
     return {};
   }
 }
 
-// ---------------------------------------------------------------------------
-// Part B.2 — the project's scene-UI registry (design/24-scene-ui.md D9/D11)
-// ---------------------------------------------------------------------------
-
-/**
- * Load the project's scene-UI registry (`src/ui/registry.ts`'s `uiRegistry`
- * export) via the same `/@fs/` dev-server route as {@link
- * loadComponentRegistryForProject} above — but with ONE deliberate departure
- * from that loader's behavior: an import FAILURE (the file exists but throws
- * — a syntax error, a bad import, a thrown top-level expression) logs a loud
- * `editorConsole.warn` naming the real error before falling back to `null`.
- * `loadComponentRegistryForProject` folds "absent" and "broken" into the same
- * silent `{}` because most projects simply have no `src/scripts/registry.ts`
- * at all; a scene-UI registry is different — the whole point of this PR is
- * project-authored UI, so a registry with a typo silently demoting the
- * editor back to demo fixtures (D10) is exactly the confusing failure mode
- * this loader exists to make loud instead.
- *
- * The common "no registry file" case (every scaffolded project, by design —
- * D10: the template does NOT ship one) stays silent: the editor server's
- * `/__editor/project` response carries `hasUiRegistry` (a server-side stat of
- * `src/ui/registry.ts`), which distinguishes "the file doesn't exist" (no
- * warning, resolves `null`) from "the file exists but the import threw"
- * (warns). Probing the `/@fs/` URL itself cannot make that call: a dev server
- * answers 200 for missing files (SPA fallback), and the doomed dynamic import
- * that follows logs an unsuppressible browser network error on every
- * registry-less project — which strict harnesses
- * (scripts/check-vgai-generated-project-p2p.ts) rightly fail on.
- * Returns `null` for both "absent" and "present but empty" (`uiRegistry`
- * undefined) — D10 treats both the same (demo mode).
- */
-export async function loadProjectUIRegistry(
+/** Pixi sibling of {@link loadComponentRegistryForProject}. A project may
+ * export both registries from the same conventional module; each world kind
+ * receives only the classes valid for its native node type. */
+export async function loadPixiComponentRegistryForProject(
   projectRoot: string,
-): Promise<ProjectUIRegistry | null> {
-  const modulePath = fsImportPath(projectRoot, 'src/ui/registry.ts');
-  // Inline fetch rather than editor-api's getCurrentServerProject(): this
-  // module must stay importable by headless Node/vitest suites, and
-  // editor-api's module top level pulls in ./storage.
-  let exists: boolean;
-  try {
-    const res = await fetch('/__editor/project');
-    const data = (await res.json()) as { project?: { hasUiRegistry?: boolean } | null };
-    exists = Boolean(data.project?.hasUiRegistry);
-  } catch {
-    exists = false;
-  }
-  if (!exists) return null;
+): Promise<Component2DRegistry> {
+  const modulePath = fsImportPath(projectRoot, 'src/scripts/registry.ts');
   try {
     const mod = (await import(/* @vite-ignore */ modulePath)) as {
-      uiRegistry?: ProjectUIRegistry;
+      pixiComponentRegistry?: Component2DRegistry;
     };
-    return mod.uiRegistry ?? null;
-  } catch (err) {
-    // Lazy dynamic import — see withAchievedTierCheck's doc comment above:
-    // this resolver is imported by headless Node/vitest suites with no
-    // `window`, and editor-console.ts's module top level touches `window`
-    // unconditionally.
-    const { editorConsole } = await import('./editor-console');
-    editorConsole.warn(
-      `src/ui/registry.ts failed to import — UI mode falls back to demo fixtures: ${String(err)}`,
-      'ui-mode',
-    );
-    return null;
+    return mod.pixiComponentRegistry ?? {};
+  } catch {
+    return {};
   }
 }
 
-let _cachedProjectUIRegistry: ProjectUIRegistry | null = null;
-
-/**
- * Cache slot for the project's scene-UI registry (D9/D11) — populated by
- * `authoring/scene-ui-layer.ts`'s design-time layer mount (once per project
- * open, when the scene has a `ui` root to disclose — C3) and read by
- * `resolveDefaultThreeAdapter` below so the editor-play path doesn't
- * reload/re-parse the same module a second time per play. A headless/CLI-
- * on-folder resolve (no editor session, no scene-UI layer ever mounts)
- * simply reads the initial `null` — zero behavior change there.
- */
-export function setCachedProjectUIRegistry(registry: ProjectUIRegistry | null): void {
-  _cachedProjectUIRegistry = registry;
-}
-
-/** @see setCachedProjectUIRegistry */
-export function getCachedProjectUIRegistry(): ProjectUIRegistry | null {
-  return _cachedProjectUIRegistry;
-}
-
 // ---------------------------------------------------------------------------
 // Named errors for identities not yet resolvable (report the task, not just fail)
 // ---------------------------------------------------------------------------
@@ -274,9 +250,9 @@ export function getCachedProjectUIRegistry(): ProjectUIRegistry | null {
 // ---------------------------------------------------------------------------
 
 async function resolveDefaultThreeAdapter(
-  world: ResolvedWorldEntry,
+  world: ResolvedAdapterRoot,
   projectRoot: string,
-  opts?: ResolveWorldAdapterOptions,
+  opts?: ResolveRootAdapterOptions,
 ): Promise<GameAdapter> {
   const editorPreview = opts?.editorPreview;
 
@@ -337,27 +313,24 @@ async function resolveDefaultThreeAdapter(
     // populated (e.g. a headless/CLI-on-folder resolve, or a scene with no
     // `ui` root) so the spread below omits the key entirely rather than
     // passing an explicit `uiRegistry: null`.
-    const uiRegistry = getCachedProjectUIRegistry() ?? undefined;
     if (editorPreview) {
       return new VgaiSceneGameAdapter({
         id: world.id,
         sceneData: editorPreview.sceneData,
         editorPreview,
         componentRegistry,
-        uiRegistry,
       });
     }
     return new VgaiSceneGameAdapter({
       id: world.id,
       scenePath: world.scene,
       componentRegistry,
-      uiRegistry,
     });
   }
   // Unreachable in practice: `load.ts`'s `checkAdapterSceneEntryRules` requires
   // `scene` or `entry` for every 'default' adapter world at manifest-load time.
   throw new Error(
-    `resolveWorldAdapter: world "${world.id}" is default-three with neither \`scene\` nor ` +
+    `resolveRootAdapter: world "${world.id}" is default-three with neither \`scene\` nor ` +
       '`entry` — this should have been rejected by manifest validation.',
   );
 }
@@ -389,7 +362,7 @@ export async function fetchScene2DFile(path: string): Promise<Scene2DFile> {
   const res = await fetch(resolveUrl(path));
   if (!res.ok) {
     throw new Error(
-      `resolveWorldAdapter: failed to load world2d scene "${path}" (${res.status} ${res.statusText}).`,
+      `resolveRootAdapter: failed to load world2d scene "${path}" (${res.status} ${res.statusText}).`,
     );
   }
   const result = Scene2DSchema.safeParse(await res.json());
@@ -411,7 +384,7 @@ export async function fetchScene2DFile(path: string): Promise<Scene2DFile> {
  * pixi-game-adapter.ts`) is an established, exported config shape (`PixiSceneConfig.setup`,
  * re-exported from `@engine/world2d`'s barrel) structurally parallel to
  * `default-three`'s `GameSetupFn`; it simply has no production caller YET
- * (only hand-built test wiring, e.g. `create-runtime-worlds.test.ts`'s pixi
+ * (only hand-built test wiring, e.g. `create-runtime-roots.test.ts`'s pixi
  * world). So `entry` resolves via the SAME `/@fs/` dynamic-import route
  * `loadProjectScripts` uses for `default-three`'s entry branch — no new
  * mechanism invented, just a different exported shape (`setup(ctx:
@@ -422,7 +395,7 @@ export async function fetchScene2DFile(path: string): Promise<Scene2DFile> {
  * is shape-agnostic.
  */
 async function resolveDefaultPixiAdapter(
-  world: ResolvedWorldEntry,
+  world: ResolvedAdapterRoot,
   projectRoot: string,
 ): Promise<GameAdapter> {
   if (world.entry !== undefined) {
@@ -436,8 +409,8 @@ async function resolveDefaultPixiAdapter(
     // instead of letting `undefined` silently reach `PixiSceneGameAdapter`.
     if (!setup) {
       throw new Error(
-        `resolveWorldAdapter: world "${world.id}"'s entry "${world.entry}" exports \`adapter\` ` +
-          `but no \`setup\` — default-pixi worlds only accept a \`setup(ctx: World2DContext)\` ` +
+        `resolveRootAdapter: world "${world.id}"'s entry "${world.entry}" exports \`adapter\` ` +
+          `but no \`setup\` — default-pixi roots only accept a \`setup(ctx: World2DContext)\` ` +
           `export${adapter ? ' (an `adapter` export is default-three/R3F-only, W1b)' : ''}.`,
       );
     }
@@ -448,12 +421,17 @@ async function resolveDefaultPixiAdapter(
   }
   if (world.scene !== undefined) {
     const sceneData = await fetchScene2DFile(world.scene);
-    return new PixiSceneGameAdapter({ id: world.id, sceneData }) as unknown as GameAdapter;
+    const registry = await loadPixiComponentRegistryForProject(projectRoot);
+    return new PixiSceneGameAdapter({
+      id: world.id,
+      sceneData,
+      registry,
+    }) as unknown as GameAdapter;
   }
   // Unreachable in practice: `load.ts`'s `checkAdapterSceneEntryRules` requires
   // `scene` or `entry` for every 'default' adapter world at manifest-load time.
   throw new Error(
-    `resolveWorldAdapter: world "${world.id}" is default-pixi with neither \`scene\` nor ` +
+    `resolveRootAdapter: world "${world.id}" is default-pixi with neither \`scene\` nor ` +
       '`entry` — this should have been rejected by manifest validation.',
   );
 }
@@ -476,13 +454,13 @@ async function resolveDefaultPixiAdapter(
  * shim is still just a module default-exporting a component).
  */
 function loadReactEntryComponent(
-  world: ResolvedWorldEntry,
+  world: ResolvedAdapterRoot,
   mod: { default?: unknown },
-  identityLabel: 'default-react' | 'ingest-react' = 'default-react',
+  identityLabel: 'react' | 'ingest-react' = 'react',
 ): ComponentType {
   if (typeof mod.default !== 'function') {
     throw new Error(
-      `resolveWorldAdapter: world "${world.id}" (${identityLabel}) entry module does not ` +
+      `resolveRootAdapter: world "${world.id}" (${identityLabel}) entry module does not ` +
         `default-export a component — got ${typeof mod.default}. A react world's \`entry\` must ` +
         'default-export a React component (docs/REACT-WORLD-DESIGN.md §1.B).',
     );
@@ -565,7 +543,7 @@ async function loadPackagedReactWorldMountRuntime(): Promise<ReactWorldMountRunt
     typeof mod.EngineGameProvider !== 'function'
   ) {
     throw new Error(
-      "resolveWorldAdapter: the packaged runtime's synthetic react-world-runtime module " +
+      "resolveRootAdapter: the packaged runtime's synthetic react-world-runtime module " +
         `("${REACT_WORLD_RUNTIME_PATH}") did not export createElement/createRoot/flushSync/` +
         'EngineGameProvider as functions — see vite-plugin-react-world-runtime.ts.',
     );
@@ -618,13 +596,13 @@ let cachedPackagedReactWorldMountRuntime: Promise<ReactWorldMountRuntime> | null
  * BYTE-IDENTICAL to the pre-C1 behavior. Memoized: `isPackagedRuntime()` is
  * itself session-memoized, and the packaged module load below is cached here
  * too, so this only ever performs at most one `/__editor/project` fetch and
- * one dynamic import per editor session, however many react worlds mount.
+ * one dynamic import per editor session, however many react roots mount.
  *
  * Exported: `design-time-layers.ts`'s OWN, separate react-world layer mount
  * (`mountReactLayer` — the edit-mode composite's live preview of a non-
  * focused react/pixi world, B1) needs this SAME resolution — it is a second
  * mount call site with the identical dual-instance exposure, not routed
- * through this file's `ReactWorldAdapter.mount()` at all.
+ * through this file's `ReactRootAdapter.mount()` at all.
  */
 export async function resolveReactWorldMountRuntime(): Promise<ReactWorldMountRuntime> {
   const packaged = await isPackagedRuntime();
@@ -643,20 +621,9 @@ export function resetReactWorldMountRuntimeCacheForTest(): void {
 }
 
 /**
- * SECOND FINDING (report prominently): `GameProvider` is not an engine or
- * editor export — by design (`docs/REACT-STATE-BRIDGE.md` §2: "colocated
- * with `mountUI`… rather than under `packages/engine/src/runtime/` — that
- * directory stays react-free"), it lives PER-PROJECT at
- * `src/ui/game-state.tsx` (`packages/editor/template/src/ui/
- * game-state.tsx`, copied verbatim into every scaffolded project by
- * `create-vgai-project`'s `scaffoldProject` — see that package's README:
- * "Copies the template into the target directory"). There is no engine-side
- * canonical `GameProvider` this resolver could import once and reuse for
- * every project — it has to load the SAME project's own copy the entry
- * module's OWN `../ui/game-state` import resolves to (a resolver-local
- * `createContext()` would be a SECOND, non-identical Context: `useGame()`
- * would throw "no Game in context" against it even though `<GameProvider>`
- * genuinely wrapped the tree).
+ * `GameProvider` is the canonical engine export from
+ * `@vgai/engine/react/game-state`. Hosts and game entries share that module,
+ * preserving a single React context identity.
  *
  * THIRD FINDING, and the actual engine-adjacent-tooling gap this slice
  * closes (T6.2 slice 3 — verified empirically, not assumed): a hand-built
@@ -677,38 +644,12 @@ export function resetReactWorldMountRuntimeCacheForTest(): void {
  * transform-time resolver a react-world entry's own static import goes
  * through, converging both on the identical final module.
  *
- * D-Z5 (`docs/WAVE3-ADAPTER-PLUMBING-DESIGN.md` §D-Z5) revises what happens
- * when `src/ui/game-state.tsx` is simply ABSENT: this function is now only
- * ever called after a caller has confirmed (via `probeGameStateFileExists`)
- * that the file genuinely exists, so the hard throw below is reserved for
- * the file EXISTING but not exporting `GameProvider` correctly — a real bug,
- * never swallowed. Absence itself degrades to the engine-published
- * `GameProvider` (`@engine/react/game-state`) instead, at both call sites
- * (`resolveDefaultReactAdapter` and `resolveIngestReactAdapter` below) — see
- * `resolveGameProviderForProject`, the shared probe-then-load-or-fallback
- * helper this revision introduces.
+ * `resolveGameProviderForProject` below supplies that canonical provider for
+ * both first-party and ingested React roots.
  */
-async function loadProjectGameProvider(
-  projectRoot: string,
-): Promise<ComponentType<{ game: Game; children?: unknown }>> {
-  const modulePath = reactWorldProviderImportSpecifier(projectRoot);
-  const mod = (await import(/* @vite-ignore */ modulePath)) as {
-    GameProvider?: ComponentType<{ game: Game; children?: unknown }>;
-  };
-  if (typeof mod.GameProvider !== 'function') {
-    throw new Error(
-      'resolveWorldAdapter: could not find `GameProvider` at ' +
-        `"src/ui/game-state.tsx" under project root "${projectRoot}" — a react world's ` +
-        "mount needs the project's own GameProvider (docs/REACT-STATE-BRIDGE.md §2) so " +
-        "useGameState/useGame resolve against the SAME React context the entry's own code uses.",
-    );
-  }
-  return mod.GameProvider;
-}
-
 /**
  * Resolve a `kind: 'react'` + `adapter: 'default'` world into a
- * `ReactWorldAdapter` (docs/REACT-WORLD-DESIGN.md §1.B, T6.2 slice 1 task
+ * `ReactRootAdapter` (docs/REACT-WORLD-DESIGN.md §1.B, T6.2 slice 1 task
  * list's "Mount" item) — the react sibling of `resolveDefaultThreeAdapter`/
  * `resolveDefaultPixiAdapter`. `entry` resolves via the SAME `/@fs/`
  * dynamic-import route `loadProjectScripts` uses (`resolveDefaultPixiAdapter`'s
@@ -724,16 +665,8 @@ async function loadProjectGameProvider(
  * honest gaps this depends on (the engine-merged `ReactWorldHost` not yet
  * carrying `game`; `GameProvider` being a per-project file, not an export).
  *
- * D-Z5: `GameProvider` here comes from `resolveGameProviderForProject`, which
- * now falls back to the engine-PUBLISHED `GameProvider`
- * (`@engine/react/game-state`) plus a loud once-per-world report when the
- * project ships no `src/ui/game-state.tsx` at all — this retires the former
- * hard throw for that case (a project whose file EXISTS but is broken still
- * throws for real; only genuine absence degrades). Safe by construction: the
- * template's own `src/ui/game-state.tsx` is now itself a thin re-export of
- * this same engine module (D-Z5 step 3), so a freshly scaffolded project's
- * "present" and "absent" paths converge on the identical `GameProvider`
- * either way.
+ * `GameProvider` here comes from the canonical engine React entry via
+ * `resolveGameProviderForProject`.
  *
  * `scene` on a react world is a NAMED error (JSX-as-truth, D4 —
  * docs/REACT-WORLD-DESIGN.md §1.A: "A react WORLD's truth is JSX source —
@@ -742,7 +675,7 @@ async function loadProjectGameProvider(
  * `checkAdapterSceneEntryRules` only requires ONE of `scene`/`entry` for a
  * `default`-adapter world (it does not forbid `scene` on a react world
  * specifically — see `load.ts`), so this resolver is where the D4 rule is
- * actually enforced for react worlds.
+ * actually enforced for react roots.
  */
 
 /**
@@ -756,14 +689,14 @@ async function loadProjectGameProvider(
  * `Game` beside an ingest world), while `resolveDefaultReactAdapter` wraps
  * it in `<GameProvider>` as it always has. Exported for that one caller.
  */
-export async function resolveReactWorldEntryComponent(
-  world: ResolvedWorldEntry,
+export async function resolveReactAdapterRootComponent(
+  world: ResolvedAdapterRoot,
   projectRoot: string,
 ): Promise<ComponentType> {
   if (world.scene !== undefined) {
     throw new Error(
-      `resolveWorldAdapter: world "${world.id}" (default-react) declares \`scene\` — react ` +
-        'worlds have no scene-file format: JSX source is the truth for a react world (D4, ' +
+      `resolveRootAdapter: world "${world.id}" (default-react) declares \`scene\` — react ` +
+        'roots have no scene-file format: JSX source is the truth for a react world (D4, ' +
         'docs/REACT-WORLD-DESIGN.md §1.A). Use `entry` (a .tsx module default-exporting a ' +
         'component) instead.',
     );
@@ -774,7 +707,7 @@ export async function resolveReactWorldEntryComponent(
     // and the check above already rejects `scene` for a react world — so a real
     // manifest can never reach this branch. Still fails loudly, not silently.
     throw new Error(
-      `resolveWorldAdapter: world "${world.id}" is default-react with no \`entry\` — this should ` +
+      `resolveRootAdapter: world "${world.id}" is default-react with no \`entry\` — this should ` +
         'have been rejected by manifest validation.',
     );
   }
@@ -785,19 +718,19 @@ export async function resolveReactWorldEntryComponent(
 }
 
 async function resolveDefaultReactAdapter(
-  world: ResolvedWorldEntry,
+  world: ResolvedAdapterRoot,
   projectRoot: string,
 ): Promise<GameAdapter> {
-  const Entry = await resolveReactWorldEntryComponent(world, projectRoot);
-  const GameProvider = await resolveGameProviderForProject(projectRoot, world.id, 'default-react');
+  const Entry = await resolveReactAdapterRootComponent(world, projectRoot);
+  const GameProvider = await resolveGameProviderForProject(projectRoot, world.id, 'react');
 
-  const adapter: ReactWorldAdapter = {
+  const adapter: ReactRootAdapter = {
     id: world.id,
     async mount(host: ReactWorldHost): Promise<MountedReactGame> {
       const game = hostGame(host);
       if (!game) {
         throw new Error(
-          `resolveWorldAdapter: world "${world.id}" (default-react) mount() received a ` +
+          `resolveRootAdapter: world "${world.id}" (default-react) mount() received a ` +
             'ReactWorldHost with no `game` — GameProvider needs a live Game at mount time and ' +
             "this host did not carry one (see adapter-resolver.ts's `hostGame` doc comment for " +
             'the engine-side gap this indicates).',
@@ -810,9 +743,14 @@ async function resolveDefaultReactAdapter(
       // entry component's own hooks. See that function's doc comment.
       const runtime = await resolveReactWorldMountRuntime();
       const root = runtime.createRoot(host.container);
-      root.render(
-        runtime.createElement(GameProvider, { game, children: runtime.createElement(Entry) }),
-      );
+      // The play authoring adapter is installed immediately after mount()
+      // resolves. Commit the initial DOM before returning so its first
+      // hierarchy snapshot sees the OID tree instead of an empty container.
+      runtime.flushSync(() => {
+        root.render(
+          runtime.createElement(GameProvider, { game, children: runtime.createElement(Entry) }),
+        );
+      });
       return {
         kind: 'react',
         container: host.container,
@@ -833,7 +771,7 @@ async function resolveDefaultReactAdapter(
 
 /**
  * Resolve a `kind: 'react'` + `{ ingest: { strategy: 'deduped' } }` world into
- * a `ReactWorldAdapter` — the ingest sibling of `resolveDefaultReactAdapter`
+ * a `ReactRootAdapter` — the ingest sibling of `resolveDefaultReactAdapter`
  * immediately above. Mounts through the EXACT SAME T6.2 react host stack:
  * the same `/@fs/` `entry`-module dynamic import, the same default-export-
  * component validation (`loadReactEntryComponent`), the same per-project
@@ -873,183 +811,44 @@ async function resolveDefaultReactAdapter(
  * ever runs against a REAL manifest: `load.ts`'s `checkAdapterSceneEntryRules`
  * forbids `scene` on any `{ ingest }`-adapter world, kind-agnostic. This
  * function still guards it defensively (never trust a hand-built
- * `ResolvedWorldEntry` a unit test — or a future caller — might construct
+ * `ResolvedAdapterRoot` a unit test — or a future caller — might construct
  * past that check), with the same message shape `resolveDefaultReactAdapter`'s
  * own `scene` check uses.
  *
  * D-N8 ("no authoring in v1") and D-N4 item 1 (no `writeBackend` for an
- * ingest-react world): this function's return value is `{ id, mount }` only
- * — structurally identical in shape to `resolveDefaultReactAdapter`'s return
- * — there is no authoring/write-back hook anywhere on a `ReactWorldAdapter`
- * for EITHER react identity. `ReactWorldAuthoringAdapter`/`writeBackend`
- * wiring lives entirely outside this file, in `play-mode.ts`'s
- * `installMultiWorldAuthoring`, keyed on `world.kind === 'react'` — not on
- * adapter identity. That function is structurally unreachable for
- * `ingest-react` today: `resolveAllWorlds`'s `MULTI_WORLD_ALLOWED_IDENTITIES`
- * (below) deliberately excludes `'ingest-react'`, so an ingest-react world
- * can only ever be the LONE world of a single-world manifest — and
- * `play-mode.ts`'s single-world play branch calls `installPlayAuthoring`
- * (wraps `getActiveAuthoring(store)`, the first-party
- * `VgaiSceneAuthoringAdapter`) instead, for every world kind, never
- * `installMultiWorldAuthoring`. So "no write-capable authoring surface" holds
- * for `ingest-react` today by construction, not by an extra guard this
- * function adds — recorded honestly here rather than claimed as this
- * function's own achievement; see the N1 report for the residual this
- * implies for N2 if react ingestion ever needs to join a multi-world
- * manifest.
+ * ingest-react world): this function's return value is `{ id, mount }` only.
+ * Composition resolution is cardinality-neutral, so play mode enforces the
+ * write boundary explicitly by installing a read-only BoundaryAuthoringAdapter
+ * whenever the declaration identity is `ingest-react`. Universal hierarchy
+ * membership does not imply write authority over vendored source.
  *
- * D-Y3 (wave 2, docs/EXTERNAL-REACT-AND-MODULE-DESIGN.md §1) introduced ONE
- * piece of the above: `loadProjectGameProvider`'s hard throw when
- * `src/ui/game-state.tsx` is absent was right for `default-react` (a
- * vgai-native world legitimately depends on the bridge) but wrong for
- * `ingest-react` — a foreign tree ingested as-is has no reason to ship that
- * file at all (it calls no vgai hooks unless its own shim explicitly wants
- * them). `probeGameStateFileExists` checks (via a plain `fetch()` of the
- * exact `/@fs/` path `loadProjectGameProvider` would import, mirroring
- * `fetchScene2DFile`'s existing fetch-based existence check elsewhere in
- * this file) whether the file is even THERE before ever calling the real
- * loader.
- *
- * D-Z5 (`docs/WAVE3-ADAPTER-PLUMBING-DESIGN.md` §D-Z5) revises what D-Y3's
- * "absent" branch DOES, for both react identities: absence now wraps with
- * the engine-PUBLISHED `GameProvider` (`@engine/react/game-state`) instead
- * of mounting unwrapped — safe because an unmodified foreign entry (or a
- * project with no bridge file of its own) imports no vgai hooks bound to a
- * DIFFERENT context, so there is no context-identity split to cause (see
- * `packages/engine/src/react/game-state.tsx`'s module doc comment, and
- * `game-state-context-split.test.tsx`'s red proof of what WOULD happen if a
- * project's own copy were wrapped by the wrong provider). Presence still
- * runs the real loader (so a game-state.tsx that EXISTS but is broken still
- * throws its own real error loudly — the probe never swallows that, it only
- * distinguishes "not there" from "there"). See `resolveGameProviderForProject`
- * below, the shared probe-then-load-or-fallback helper both `default-react`
- * and `ingest-react` now call.
- */
-async function probeGameStateFileExists(projectRoot: string): Promise<boolean> {
-  const path = fsImportPath(projectRoot, 'src/ui/game-state.tsx');
-  const relative = resolveUrl(path);
-  // `fetch()` needs an absolute URL when there is no implicit browser
-  // document base to resolve a leading-slash path against (a real dev-server
-  // session always has one; a headless Node/vitest caller does not) — build
-  // one explicitly rather than relying on an environment-specific implicit
-  // base, so this probe behaves identically (and is mockable) in both.
-  const origin =
-    typeof window !== 'undefined' && window.location ? window.location.origin : 'http://localhost';
-  try {
-    const res = await fetch(new URL(relative, origin).toString());
-    // `res.ok` alone is NOT "the file exists": Vite's SPA fallback answers
-    // any unknown GET — including a missing `/@fs/…` path — with index.html
-    // and a 200, so on a real dev server the absence branch below was
-    // unreachable and a project genuinely shipping no `src/ui/game-state.tsx`
-    // crashed later inside `loadProjectGameProvider`'s synthetic re-export
-    // instead of degrading to the engine provider (found by the first such
-    // project: alien-stories' proto). A real hit comes back as transformed
-    // JS; only the fallback is `text/html`. (`headers` is optional-chained
-    // for partial `Response` stubs in tests.)
-    const contentType = res.headers?.get?.('content-type') ?? '';
-    return res.ok && !contentType.includes('text/html');
-  } catch {
-    // Fetch itself failing (network hiccup, no dev server route, …) is
-    // treated the same as "absent" — the honest fallback here is the
-    // engine-provider-plus-loud-report degrade (`resolveGameProviderForProject`),
-    // never a silent crash on an ambiguous probe failure.
-    return false;
-  }
-}
-
-/** Dedup key set for {@link reportEngineProviderFallbackOnce} — one
- *  structured warning per (identity, world id) per session, mirroring
- *  `runtime/game.ts`'s `reportGateShortfallOnce` "once per (kind, id)" idiom
- *  (`docs/CAPABILITY-TIERS.md` §d's reporting precedent) rather than
- *  re-logging on every mount of a session that re-enters the same world. */
-const REPORTED_ENGINE_PROVIDER_FALLBACK = new Set<string>();
-
-/**
- * Greppable prefix for the D-Z5 "wrapped with the engine-published
- * GameProvider" report — the renamed successor to wave-2's
- * `INGEST_REACT_NO_PROVIDER_PREFIX` ("ingest-react-no-provider"), retired
- * because that name described the OLD "mounted unwrapped" behavior; this
- * fallback always wraps now, so the honest name says what actually happens.
- * Shared by both `default-react` and `ingest-react` (D-Z5 extends the D-Y3
- * ingest-only degrade to `default-react` too, since the template re-export
- * — D-Z5 step 3 — landed in the same slice).
+ * Ingested and first-party React roots use the same canonical engine
+ * provider. Unmodified foreign entries need no project-local bridge file.
  */
-export const ENGINE_GAME_PROVIDER_FALLBACK_PREFIX = 'engine-game-provider-fallback';
-
-/** Plain `console.warn` (not `editorConsole`) — same reasoning + idiom as
- *  `runtime/game.ts`'s `reportGateShortfallOnce`: this resolver is imported
- *  by headless Node/vitest suites with no `window`, and `editor-console.ts`
- *  touches `window` unconditionally at its module top level, so a
- *  first-class report here stays environment-neutral rather than forcing
- *  every caller (test or real) to stub `window` just to see it. */
-function reportEngineProviderFallbackOnce(
-  identity: 'default-react' | 'ingest-react',
-  worldId: string,
-): void {
-  const key = `${identity}:${worldId}`;
-  if (REPORTED_ENGINE_PROVIDER_FALLBACK.has(key)) return;
-  REPORTED_ENGINE_PROVIDER_FALLBACK.add(key);
-  const locationText = identity === 'ingest-react' ? 'beside the manifest' : 'in this project';
-  // biome-ignore lint/suspicious/noConsole: structured, greppable — mirrors runtime/game.ts's reportGateShortfallOnce
-  console.warn(
-    `${ENGINE_GAME_PROVIDER_FALLBACK_PREFIX} world "${worldId}" (${identity}): no ` +
-      `src/ui/game-state.tsx ${locationText} — wrapping the entry with the engine-published ` +
-      'GameProvider (@engine/react/game-state) instead. useGameState/useGame work against the ' +
-      'engine bridge; ship your own src/ui/game-state.tsx to override with a custom bridge ' +
-      '(docs/WAVE3-ADAPTER-PLUMBING-DESIGN.md D-Z5, docs/REACT-STATE-BRIDGE.md §2/addendum). ' +
-      `${ENGINE_GAME_PROVIDER_FALLBACK_PREFIX} ${JSON.stringify({ worldId, identity })}`,
-  );
-}
-
 /**
- * Shared probe-then-load-or-fallback helper (D-Z5) for both react
- * identities: if the project ships `src/ui/game-state.tsx`, load it for real
- * (`loadProjectGameProvider` — a file that exists but is broken still throws
- * its own real error, never swallowed); if it's genuinely absent, fall back
- * to the engine-published `GameProvider` and report once per (identity,
- * world id). See the doc comment on `probeGameStateFileExists` above for the
- * full D-Y3 -> D-Z5 history of this behavior.
- *
- * Exported (B1): `design-time-layers.ts` needs this SAME per-project
- * resolution (a project's own `src/ui/game-state.tsx`, when present, has its
- * own `createContext()` — wrapping it with the wrong `GameProvider` splits
- * context and `useGame()` throws even though a provider IS in the tree, see
- * `@engine/react/game-state`'s module doc comment) for its design-time react
- * layer mount, rather than re-deriving project-vs-engine provider resolution.
+ * Resolve the canonical engine provider for both React adapter identities.
+ * Exported because design-time React layers use the identical provider.
  */
 export async function resolveGameProviderForProject(
-  projectRoot: string,
-  worldId: string,
-  identity: 'default-react' | 'ingest-react',
+  _projectRoot: string,
+  _worldId: string,
+  _identity: 'react' | 'ingest-react',
 ): Promise<ComponentType<{ game: Game; children?: unknown }>> {
-  const hasGameProvider = await probeGameStateFileExists(projectRoot);
-  if (hasGameProvider) {
-    return loadProjectGameProvider(projectRoot);
-  }
-  reportEngineProviderFallbackOnce(identity, worldId);
-  // C1: the engine-published `GameProvider` fallback itself must come from
-  // the SAME react instance the mount's `createRoot`/the entry component's
-  // hooks use — under the packaged runtime that is the PROJECT's react, not
-  // this module's own static `EngineGameProvider` import (the editor's
-  // separately-bundled copy). `resolveReactWorldMountRuntime` already
-  // encapsulates the dev/Electron-vs-packaged gate (byte-identical to the
-  // old `EngineGameProvider as unknown as …` cast when not packaged); reuse
-  // it here instead of re-deriving the gate.
   const runtime = await resolveReactWorldMountRuntime();
   return runtime.engineGameProvider;
 }
 
 async function resolveIngestReactAdapter(
-  world: ResolvedWorldEntry,
+  world: ResolvedAdapterRoot,
   projectRoot: string,
 ): Promise<GameAdapter> {
   const { adapter } = world;
   if (adapter.type !== 'ingest') {
-    throw new Error(`resolveWorldAdapter: world "${world.id}" is not an { ingest } world.`);
+    throw new Error(`resolveRootAdapter: world "${world.id}" is not an { ingest } world.`);
   }
   if (adapter.strategy !== 'deduped') {
     throw new Error(
-      `resolveWorldAdapter: world "${world.id}" (ingest-react) declares strategy ` +
+      `resolveRootAdapter: world "${world.id}" (ingest-react) declares strategy ` +
         `"${adapter.strategy}" — react ingestion v1 supports ONLY the 'deduped' rung (loud ` +
         'degrade, no silent floor: docs/REACT-INGEST-LANDING-DESIGN.md D-N3). An iframe-' +
         'reachable/opaque-embed floor is explicitly out of scope for v1.',
@@ -1057,15 +856,15 @@ async function resolveIngestReactAdapter(
   }
   if (world.scene !== undefined) {
     throw new Error(
-      `resolveWorldAdapter: world "${world.id}" (ingest-react) declares \`scene\` — react ` +
-        'worlds have no scene-file format: JSX source is the truth for a react world (D4, ' +
+      `resolveRootAdapter: world "${world.id}" (ingest-react) declares \`scene\` — react ` +
+        'roots have no scene-file format: JSX source is the truth for a react world (D4, ' +
         'docs/REACT-WORLD-DESIGN.md §1.A), and an ingested react world doubly so — the vendored ' +
         'game is never modified. Use `entry` (the host-shim module, D-N2) instead.',
     );
   }
   if (world.entry === undefined) {
     throw new Error(
-      `resolveWorldAdapter: world "${world.id}" (ingest-react) has no \`entry\` — an ingested ` +
+      `resolveRootAdapter: world "${world.id}" (ingest-react) has no \`entry\` — an ingested ` +
         "react world's `entry` MUST point at a host-shim module that imports the vendored " +
         "game's own component and default-exports it (D-N2, docs/REACT-INGEST-LANDING-DESIGN.md).",
     );
@@ -1079,13 +878,13 @@ async function resolveIngestReactAdapter(
   // `resolveGameProviderForProject`'s doc comment for the full history.
   const GameProvider = await resolveGameProviderForProject(projectRoot, world.id, 'ingest-react');
 
-  const reactAdapter: ReactWorldAdapter = {
+  const reactAdapter: ReactRootAdapter = {
     id: world.id,
     async mount(host: ReactWorldHost): Promise<MountedReactGame> {
       const game = hostGame(host);
       if (!game) {
         throw new Error(
-          `resolveWorldAdapter: world "${world.id}" (ingest-react) mount() received a ` +
+          `resolveRootAdapter: world "${world.id}" (ingest-react) mount() received a ` +
             'ReactWorldHost with no `game` — GameProvider needs a live Game at mount time and ' +
             "this host did not carry one (see adapter-resolver.ts's `hostGame` doc comment for " +
             'the engine-side gap this indicates).',
@@ -1159,8 +958,8 @@ async function fetchProjectStaticText(entryHtmlPath: string): Promise<string> {
  * `threeModuleUrl` field: "no consumer exists").
  */
 function buildIframeReachableIngestDescriptor(
-  world: ResolvedWorldEntry,
-  adapter: Extract<ResolvedWorldEntry['adapter'], { type: 'ingest' }>,
+  world: ResolvedAdapterRoot,
+  adapter: Extract<ResolvedAdapterRoot['adapter'], { type: 'ingest' }>,
   base: Pick<
     IngestGame,
     'id' | 'name' | 'description' | 'assets' | 'domStubs' | 'captureTimeoutMs'
@@ -1201,8 +1000,8 @@ function buildIframeReachableIngestDescriptor(
  * actually mounted (`enterIngestModeWithGame` awaits `game.embedHtml()`).
  */
 function buildOpaqueEmbedIngestDescriptor(
-  world: ResolvedWorldEntry,
-  adapter: Extract<ResolvedWorldEntry['adapter'], { type: 'ingest' }>,
+  world: ResolvedAdapterRoot,
+  adapter: Extract<ResolvedAdapterRoot['adapter'], { type: 'ingest' }>,
   base: Pick<
     IngestGame,
     'id' | 'name' | 'description' | 'assets' | 'domStubs' | 'captureTimeoutMs'
@@ -1248,7 +1047,7 @@ function buildOpaqueEmbedIngestDescriptor(
  * SHARED-instance-mounted string has no wired mechanism this wave.
  */
 export function resolveIngestDescriptor(
-  world: ResolvedWorldEntry,
+  world: ResolvedAdapterRoot,
   projectRoot: string,
 ): IngestGame {
   const { adapter } = world;
@@ -1277,7 +1076,7 @@ export function resolveIngestDescriptor(
     if (!world.entry) {
       throw new Error(
         `resolveIngestDescriptor: world "${world.id}" (strategy "${adapter.strategy}") has no ` +
-          "`entry` — shared/deduped ingest worlds need the game module's path there.",
+          "`entry` — shared/deduped ingest roots need the game module's path there.",
       );
     }
     const modulePath = fsImportPath(projectRoot, world.entry);
@@ -1339,8 +1138,8 @@ export function resolveIngestDescriptor(
  * `buildIframeReachableGame2D` already uses for its in-tree-fixture sibling.
  */
 function buildIframeReachableDescriptor2D(
-  world: ResolvedWorldEntry,
-  adapter: Extract<ResolvedWorldEntry['adapter'], { type: 'ingest' }>,
+  world: ResolvedAdapterRoot,
+  adapter: Extract<ResolvedAdapterRoot['adapter'], { type: 'ingest' }>,
   base: Pick<IngestGame2D, 'id' | 'name' | 'description' | 'captureTimeoutMs'>,
 ): IngestGame2D {
   if (!adapter.bundleUrl) {
@@ -1367,7 +1166,7 @@ function buildIframeReachableDescriptor2D(
 }
 
 export function resolveIngest2DDescriptor(
-  world: ResolvedWorldEntry,
+  world: ResolvedAdapterRoot,
   projectRoot: string,
 ): IngestGame2D {
   const { adapter } = world;
@@ -1388,7 +1187,7 @@ export function resolveIngest2DDescriptor(
     if (!world.entry) {
       throw new Error(
         `resolveIngest2DDescriptor: world "${world.id}" (strategy "${adapter.strategy}") has no ` +
-          "`entry` — shared/deduped ingest-pixi worlds need the game module's path there.",
+          "`entry` — shared/deduped ingest-pixi roots need the game module's path there.",
       );
     }
     const modulePath = fsImportPath(projectRoot, world.entry);
@@ -1432,7 +1231,7 @@ export function resolveIngest2DDescriptor(
  * and a container — exactly `enterIngestModeFromManifestWorld`'s three-side
  * counterpart.
  */
-function resolveIngestPixiAdapter(world: ResolvedWorldEntry, projectRoot: string): GameAdapter {
+function resolveIngestPixiAdapter(world: ResolvedAdapterRoot, projectRoot: string): GameAdapter {
   const descriptor = resolveIngest2DDescriptor(world, projectRoot);
   return {
     id: world.id,
@@ -1440,7 +1239,7 @@ function resolveIngestPixiAdapter(world: ResolvedWorldEntry, projectRoot: string
     descriptor,
     async mount() {
       throw new Error(
-        `resolveWorldAdapter: world "${world.id}" (ingest-pixi) cannot mount through the ` +
+        `resolveRootAdapter: world "${world.id}" (ingest-pixi) cannot mount through the ` +
           'generic GameAdapter/HostContext contract — the world2d ingest machinery ' +
           '(mountIngestGame2D + World2DAuthoringAdapter) requires an EditorStore and a ' +
           'dedicated game-container element that HostContext does not provide (mirrors the ' +
@@ -1482,7 +1281,7 @@ function resolveIngestPixiAdapter(world: ResolvedWorldEntry, projectRoot: string
  * opens, plays, edits" — docs/CLI-ON-FOLDER-DESIGN.md §4) for the
  * `shared`/`deduped` strategies this function builds.
  */
-function resolveIngestThreeAdapter(world: ResolvedWorldEntry, projectRoot: string): GameAdapter {
+function resolveIngestThreeAdapter(world: ResolvedAdapterRoot, projectRoot: string): GameAdapter {
   const descriptor = resolveIngestDescriptor(world, projectRoot);
   return {
     id: world.id,
@@ -1490,7 +1289,7 @@ function resolveIngestThreeAdapter(world: ResolvedWorldEntry, projectRoot: strin
     descriptor,
     async mount() {
       throw new Error(
-        `resolveWorldAdapter: world "${world.id}" (ingest-three) cannot mount through the ` +
+        `resolveRootAdapter: world "${world.id}" (ingest-three) cannot mount through the ` +
           'generic GameAdapter/HostContext contract — the existing ingest machinery ' +
           '(mountIngestGame/mountIngestGameIframeReachable) requires an EditorStore and a ' +
           'dedicated game-container element that HostContext does not provide (T3.3 slice 2 ' +
@@ -1519,10 +1318,10 @@ function resolveIngestThreeAdapter(world: ResolvedWorldEntry, projectRoot: strin
  * canonicalization for the storage backends, not a trust-boundary check).
  * Returns the normalized (slash-joined, no leading/trailing slash) path.
  */
-export function guardModulePath(world: ResolvedWorldEntry, moduleId: string): string {
+export function guardModulePath(world: ResolvedAdapterRoot, moduleId: string): string {
   const fail = (reason: string): never => {
     throw new Error(
-      `resolveWorldAdapter: world "${world.id}" declares { module: "${moduleId}" } — ${reason} ` +
+      `resolveRootAdapter: world "${world.id}" declares { module: "${moduleId}" } — ${reason} ` +
         '(docs/ADAPTER-AUTHORING-DESIGN.md §1.A: the module path must be game-folder-relative, ' +
         'normalized, with no `..` escape — the same rule the save-file endpoint enforces).',
     );
@@ -1547,13 +1346,13 @@ export function guardModulePath(world: ResolvedWorldEntry, moduleId: string): st
 /** Runtime shape every `GameAdapter` must satisfy — the module branch cannot
  *  trust TypeScript alone (the imported value is `unknown` until checked). */
 function guardModuleShape(
-  world: ResolvedWorldEntry,
+  world: ResolvedAdapterRoot,
   moduleId: string,
   candidate: unknown,
 ): asserts candidate is GameAdapter {
   const fail = (reason: string): never => {
     throw new Error(
-      `resolveWorldAdapter: world "${world.id}"'s custom adapter module "${moduleId}" ${reason} ` +
+      `resolveRootAdapter: world "${world.id}"'s custom adapter module "${moduleId}" ${reason} ` +
         '— a { module } adapter must default-export an object shaped like `GameAdapter`: ' +
         '`{ id: string, mount(host): Promise<MountedGame> }` (docs/ADAPTER-AUTHORING-DESIGN.md §1.A).',
     );
@@ -1593,7 +1392,7 @@ function guardModuleShape(
  * `window` is expected to exist — the module-adapter mount path only runs
  * inside the editor's dev-server browser session, per the note above).
  */
-function withAchievedTierCheck(world: ResolvedWorldEntry, adapter: GameAdapter): GameAdapter {
+function withAchievedTierCheck(world: ResolvedAdapterRoot, adapter: GameAdapter): GameAdapter {
   return {
     id: adapter.id,
     async mount(host) {
@@ -1625,7 +1424,7 @@ function withAchievedTierCheck(world: ResolvedWorldEntry, adapter: GameAdapter):
  * `mount` is wrapped with the achieved-tier check (§1.C, `withAchievedTierCheck`).
  */
 export async function resolveModuleAdapter(
-  world: ResolvedWorldEntry,
+  world: ResolvedAdapterRoot,
   projectRoot: string,
 ): Promise<GameAdapter> {
   const { adapter } = world;
@@ -1652,19 +1451,19 @@ export async function resolveModuleAdapter(
  * adapter is not yet mounted; call `.mount(host)` to run it (see each
  * identity's doc comment above for what that does or doesn't support today).
  */
-export async function resolveWorldAdapter(
-  world: ResolvedWorldEntry,
+export async function resolveRootAdapter(
+  world: ResolvedAdapterRoot,
   projectRoot: string,
-  opts?: ResolveWorldAdapterOptions,
+  opts?: ResolveRootAdapterOptions,
 ): Promise<GameAdapter> {
   const { adapter } = world;
 
   switch (adapter.identity) {
-    case 'default-three':
+    case 'threejs':
       return resolveDefaultThreeAdapter(world, projectRoot, opts);
-    case 'default-pixi':
+    case 'pixijs':
       return resolveDefaultPixiAdapter(world, projectRoot);
-    case 'default-react':
+    case 'react':
       return resolveDefaultReactAdapter(world, projectRoot);
     case 'module':
       return resolveModuleAdapter(world, projectRoot);
@@ -1677,111 +1476,40 @@ export async function resolveWorldAdapter(
     default: {
       const exhaustive: never = adapter;
       throw new Error(
-        `resolveWorldAdapter: unhandled adapter identity ${JSON.stringify(exhaustive)}`,
+        `resolveRootAdapter: unhandled adapter identity ${JSON.stringify(exhaustive)}`,
       );
     }
   }
 }
 
 // ---------------------------------------------------------------------------
-// Multi-world entry point (T6.1 slice 2 — docs/MULTI-WORLD-DESIGN.md §3 slice 2)
+// Composition entry points
 // ---------------------------------------------------------------------------
 
-/**
- * Adapter identities a manifest with MORE THAN ONE world may mix in this
- * slice (docs/MULTI-WORLD-DESIGN.md §3 slice 4's scope rule, extended by
- * docs/REACT-WORLD-DESIGN.md §3 slice 1/3 to admit `default-react`): only
- * `'default'`-adapter threejs/pixijs/react worlds. `ingest-three`/
- * `ingest-pixi` and `{ module }` still join a multi-world manifest in a
- * LATER slice (slice 4's ingest-pixi + retirement work, T3.4's module
- * adapters) — a worlds>1 manifest naming any of them today gets a named
- * scope-rule error instead of a silent/confusing failure deep inside
- * `createGameRuntime`'s worlds path. `default-react` is admitted here
- * because `resolveAllWorlds`/`createWorldsGameRuntime` is exactly the host
- * path a react world mounts through (docs/REACT-WORLD-DESIGN.md §1.B: a
- * react world's DOM-root layer is "one stacking model, no special case" —
- * `packages/engine/test/create-runtime-worlds.test.ts` and `-react-world
- * .test.ts` already prove N worlds, including react, mounting through this
- * exact host) — the AC fixture in that design (§2: 1 threejs + 2 react
- * worlds) is a worlds>1 manifest by construction, so react could not stay
- * scope-barred here without contradicting the design it is implementing.
- *
- * `ingest-react` (Track N, N1) stays OUT of this set on purpose — it is an
- * `{ ingest }`-adapter identity like `ingest-three`/`ingest-pixi`, both of
- * which are already excluded here, and docs/REACT-INGEST-LANDING-DESIGN.md
- * ships single-world manifests only ("Track N ships single-world manifests
- * and does not touch this", per that design's §2 seam table). This exclusion
- * also does load-bearing work for D-N4/D-N8 (no authoring surface for an
- * ingested react world): `installMultiWorldAuthoring` (`play-mode.ts`) is
- * the ONLY place a `ReactWorldAuthoringAdapter`/`writeBackend` gets
- * constructed, and it is only reachable via THIS multi-world path — keeping
- * `ingest-react` out of it keeps that constructor permanently unreachable
- * for a vendored game, not just unreachable today.
- */
-const MULTI_WORLD_ALLOWED_IDENTITIES: ReadonlySet<string> = new Set([
-  'default-three',
-  'default-pixi',
-  'default-react',
-]);
-
-function throwMultiWorldScopeViolation(world: ResolvedWorldEntry): never {
-  throw new Error(
-    `resolveAllWorlds: world "${world.id}" resolved to adapter identity ` +
-      `"${world.adapter.identity}" — a manifest with more than one world may only mix ` +
-      "'default'-adapter threejs/pixijs/react worlds in this slice (docs/MULTI-WORLD-DESIGN.md " +
-      '§3 slice 4 reserves ingest/module worlds out of THIS path permanently, not just for a ' +
-      'later slice: a composite manifest (one { ingest } world + siblings) mounts via ' +
-      "`ingest-mode.ts`'s own composite route instead (docs/WAVE5-MULTIWORLD-INGEST-DESIGN.md " +
-      'D-V2..D-V7), never resolveAllWorlds/installMultiWorldAuthoring — the play path stays out ' +
-      'of scope for ingest worlds by design (docs/REACT-WORLD-DESIGN.md §3 admits default-react ' +
-      'here).',
-  );
-}
-
-/**
- * Resolve EVERY world in a manifest into slice-1 `WorldMountSpec`s
- * (docs/MULTI-WORLD-DESIGN.md §1.A's host-facing shape), in the manifest's
- * already-z-sorted `worlds` order (`@engine/manifest/load`'s
- * `loadGameManifest` sorts by `zOrder` before returning — this function does
- * not re-sort). No `editorPreview` threading here (v1 scope decision, T6.1
- * slice 2's report): `default-pixi` has none by design (§1.D), and a
- * multi-world manifest's live editor document corresponds to no single one
- * of N worlds today (the editor is still a single-scene store) — EVERY
- * world in the worlds path mounts from its own on-disk `scene`/`entry`,
- * matching how `default-pixi` already behaves. Single-world manifests never
- * call this function (see `play-mode.ts`'s routing) — resolveWorldAdapter's
- * own editorPreview threading there is completely unaffected.
- *
- * Called only for manifests with more than one world (the play path's own
- * routing decision) but written to work for any `worlds.length >= 1` so a
- * caller (or a unit test) can exercise it directly.
- */
-
 /**
  * Shared per-world resolution loop behind {@link resolveAllWorlds} and
- * {@link resolveAllWorldEntries} (E4.R2 reopen fix, split out so the two
- * never re-derive the multi-world scope check or the `resolveWorldAdapter`
- * fan-out independently): enforces the v1 scope rule (module/ingest worlds
- * banned from a >1-world manifest — `MULTI_WORLD_ALLOWED_IDENTITIES`), then
- * resolves every world's adapter, in manifest order.
+ * {@link resolveAllWorldEntries}. Every world is resolved independently in
+ * manifest order. An optional editor preview is scoped to the focused Three
+ * world only. D19 deliberately has no cardinality gate: an adapter's capability
+ * or mount failure belongs to that world, not to the number of siblings beside it.
  */
-async function resolveAllWorldAdapters(
+async function resolveAllRootAdapters(
   manifest: ResolvedGameManifest,
   projectRoot: string,
-): Promise<{ world: ResolvedWorldEntry; adapter: GameAdapter }[]> {
-  const { worlds } = manifest;
-
-  if (worlds.length > 1) {
-    for (const world of worlds) {
-      if (!MULTI_WORLD_ALLOWED_IDENTITIES.has(world.adapter.identity)) {
-        throwMultiWorldScopeViolation(world);
-      }
-    }
-  }
-
-  const resolved: { world: ResolvedWorldEntry; adapter: GameAdapter }[] = [];
-  for (const world of worlds) {
-    resolved.push({ world, adapter: await resolveWorldAdapter(world, projectRoot) });
+  opts?: ResolveAllWorldEntriesOptions,
+): Promise<{ world: ResolvedAdapterRoot; adapter: GameAdapter }[]> {
+  const { roots } = manifest;
+
+  const resolved: { world: ResolvedAdapterRoot; adapter: GameAdapter }[] = [];
+  for (const world of roots) {
+    const worldOptions =
+      opts?.editorPreview && world.id === opts.editorPreviewWorldId
+        ? { editorPreview: opts.editorPreview }
+        : undefined;
+    resolved.push({
+      world,
+      adapter: await resolveRootAdapter(world, projectRoot, worldOptions),
+    });
   }
   return resolved;
 }
@@ -1790,34 +1518,42 @@ export async function resolveAllWorlds(
   manifest: ResolvedGameManifest,
   projectRoot: string,
 ): Promise<WorldMountSpec[]> {
-  const resolved = await resolveAllWorldAdapters(manifest, projectRoot);
+  const resolved = await resolveAllRootAdapters(manifest, projectRoot);
 
   const specs: WorldMountSpec[] = [];
   for (const { world, adapter } of resolved) {
     const base = { id: world.id, zOrder: world.zOrder, pausable: world.pausable, loop: world.loop };
-    if (world.kind === 'pixijs') {
+    if (world.surface === 'pixijs') {
       specs.push({ ...base, kind: 'pixijs', adapter: adapter as unknown as Pixi2DGameAdapter });
-    } else if (world.kind === 'react') {
-      specs.push({ ...base, kind: 'react', adapter: adapter as unknown as ReactWorldAdapter });
-    } else if (world.kind === 'threejs') {
+    } else if (world.surface === 'react') {
+      specs.push({ ...base, kind: 'react', adapter: adapter as unknown as ReactRootAdapter });
+    } else if (world.surface === 'threejs') {
       specs.push({ ...base, kind: 'threejs', adapter });
     } else {
-      // Exhaustiveness guard (§7.4-2): `world.kind` is `WorldEntry['kind']`,
-      // the same closed `'threejs' | 'pixijs' | 'react'` union as `WorldKind`
-      // (schema.ts's `WorldEntrySchema.kind` is `z.enum([...])`, so this is
+      // Exhaustiveness guard (§7.4-2): `world.surface` is `AdapterRoot['kind']`,
+      // the same closed `'threejs' | 'pixijs' | 'react'` union as `AdapterSurface`
+      // (schema.ts's `AdapterRootSchema.kind` is `z.enum([...])`, so this is
       // NOT a plain-`string` field) — a hypothetical 4th kind must fail to
       // compile here rather than silently default to 'threejs' as the old
       // catch-all `else` did.
-      assertNever(world.kind, 'resolveAllWorlds');
+      assertNever(world.surface, 'resolveAllWorlds');
     }
   }
   return specs;
 }
 
+/** Editor-only context for resolving a manifest composition. The live scene
+ * document belongs to exactly one focused threejs world; every sibling still
+ * resolves from its own manifest-owned content. */
+export interface ResolveAllWorldEntriesOptions {
+  readonly editorPreview?: EditorPreview | undefined;
+  readonly editorPreviewWorldId?: string | undefined;
+}
+
 /**
  * E4.R2 (reopen fix — design/26 S-D D2's "editor play mode calls it"):
  * `resolveAllWorlds`'s composer-path sibling. Resolves every world's adapter
- * through the SAME scope-checked loop ({@link resolveAllWorldAdapters}) but
+ * through the SAME scope-checked loop ({@link resolveAllRootAdapters}) but
  * returns `mountManifestWorlds`'s own `entries` shape (`{ kind, adapter }`
  * per world id, `@engine/runtime/mount-manifest`) instead of a hand-built
  * `WorldMountSpec[]` — so `zOrder`/`pausable`/`loop` and the per-kind
@@ -1826,32 +1562,31 @@ export async function resolveAllWorlds(
  * rather than being hand-duplicated a second time here AND at the
  * `mountManifestWorlds` call site (the exact duplication a reopen review
  * found in `play-mode.ts`'s prior `resolveAllWorlds` + `createGameRuntime
- * ({ container, worlds })` call shape).
+ * ({ container, roots })` call shape).
  *
- * `resolveAllWorlds` itself is UNCHANGED/byte-stable for its other callers
- * (`ingest-mode.ts`, `module-mode.ts`, its own unit tests) — this is purely
- * an additional entry point for `play-mode.ts`'s multi-world branch, which
- * now calls `mountManifestWorlds({ manifest, container, entries, ... })`
- * directly instead of `createGameRuntime({ container, worlds })`.
+ * `resolveAllWorlds` remains the `WorldMountSpec[]` form used by other callers;
+ * editor play uses this entries form for every manifest composition and lets
+ * `mountManifestWorlds` remain the authoritative declaration-to-mount translator.
  */
 export async function resolveAllWorldEntries(
   manifest: ResolvedGameManifest,
   projectRoot: string,
+  opts?: ResolveAllWorldEntriesOptions,
 ): Promise<Record<string, MountEntry>> {
-  const resolved = await resolveAllWorldAdapters(manifest, projectRoot);
+  const resolved = await resolveAllRootAdapters(manifest, projectRoot, opts);
 
   const entries: Record<string, MountEntry> = {};
   for (const { world, adapter } of resolved) {
-    if (world.kind === 'pixijs') {
+    if (world.surface === 'pixijs') {
       entries[world.id] = { kind: 'pixijs', adapter: adapter as unknown as Pixi2DGameAdapter };
-    } else if (world.kind === 'react') {
-      entries[world.id] = { kind: 'react', adapter: adapter as unknown as ReactWorldAdapter };
-    } else if (world.kind === 'threejs') {
+    } else if (world.surface === 'react') {
+      entries[world.id] = { kind: 'react', adapter: adapter as unknown as ReactRootAdapter };
+    } else if (world.surface === 'threejs') {
       entries[world.id] = { kind: 'threejs', adapter };
     } else {
       // Exhaustiveness guard (§7.4-2) — same reasoning as `resolveAllWorlds`'s
       // own identical guard above.
-      assertNever(world.kind, 'resolveAllWorldEntries');
+      assertNever(world.surface, 'resolveAllWorldEntries');
     }
   }
   return entries;