@vgai/editor 0.2.0 → 0.4.0-canary.20260715.0

package/src/authoring/edit-mode-authoring.ts

@@ -2,9 +2,8 @@
  * Edit-mode authoring (A1, docs/unified-world-editor/26-unified-editor-spec.md
  * §2 A1) — project open loads `vgai.game.json` and installs a
  * {@link CompositeAuthoringAdapter} over EVERY declared world, so a
- * multi-world project's composition is disclosed in edit mode (#28) instead
- * of only in play mode (`play-mode.ts`'s `installMultiWorldAuthoring`, the
- * pattern this mirrors). Unlike play mode, worlds are NOT running here: only
+ * project's composition is disclosed in edit mode (#28). Unlike play mode,
+ * roots are NOT running here: only
  * the FOCUSED threejs world is live (the existing `VgaiSceneAuthoringAdapter`
  * over the store's already-loaded document — `loadInitialScene` is
  * untouched, still the only thing that ever loads a scene into the store);
@@ -12,47 +11,30 @@
  * describing it from the manifest, upgraded to a live adapter only once its
  * design-time layer actually mounts (B1).
  *
- * **Back-compat floor (exact, not "equivalent"):** a single-world project —
- * whether there is no manifest at all (synthesized in memory, see
- * `installEditModeAuthoringForProject` below) or a manifest that happens to
- * declare exactly one world — has NOTHING new to disclose (#28 is a
- * multi-world problem), so `installEditModeAuthoring` deliberately does NOT
- * touch the shared `setActiveAuthoring` slot in that case. `getActiveAuthoring`'s
- * existing default (`new VgaiSceneAuthoringAdapter(store)`, `active-adapter.ts`)
- * keeps serving every call site that reads it (the viewport's
- * transforms/selection, `SaveStatus`, `DefaultEditorLayout`'s hierarchy/
- * inspector panel choice, the autosave guard, undo dispatch) completely
- * untouched — `hasAuthoringOverride()` stays `false`, exactly as today. Only
- * a GENUINE multi-world manifest (2+ declared worlds) installs the composite
- * as the active override, the same "a composite is active -> route through
- * the contract-driven panels" pattern `installMultiWorldAuthoring` already
- * established for play mode (verified precedent: `19-multi-world.spec.ts` /
- * `22-tri-world.spec.ts` assert on `ingest-row`/`ingest-position-*` testids
- * once a composite is installed) — A2's `GameHierarchy` replaces that
- * temporary routing wholesale; until then this is the honest, already-proven
- * mechanism for disclosing a composition #28 says must not stay invisible.
+ * D19 completes the migration: a project with one world and a project with
+ * many roots use the SAME game/world authoring tree. Cardinality may affect
+ * presentation density, never hierarchy semantics, routing, or persistence.
+ * Manifest-less projects still synthesize the conventional `main` world, so
+ * every project reaches this one path.
  */
 
-import type { AuthoringAdapter } from '@engine/adapter';
 import { editorConsole } from '../editor-console';
 import { getEditorMode } from '../editor-mode';
 import type { EditorStore } from '../editor-store';
-import { resolveInitialScenePathForManifestSynthesis } from '../initial-scene';
+import { hierarchyProjectionFromProjectConfig } from '../hierarchy-projection';
+import { getProjectFileHistory, type ProjectFileHistory } from '../history/project-file-history';
+import { getManifestHistoryBackend } from '../history/project-root-history-backends';
 import { fetchRawGameManifest } from '../manifest-project';
 import { getCurrentProject } from '../project-manager';
 import { getStorageBackend } from '../storage';
-import { UIEditStore } from '../ui-editor/ui-edit-store';
-import { createHttpSourceWriteBackend } from '../ui-source/source-write-backend';
 import { getAuthoringOverride, markEditModeOverride, setActiveAuthoring } from './active-adapter';
 import { BoundaryAuthoringAdapter, type BoundaryWorldInfo } from './boundary-authoring-adapter';
 import {
   CompositeAuthoringAdapter,
   type CompositeChild,
-  type GameRootManifestProvider,
+  type RootManifestProvider,
 } from './composite-authoring-adapter';
-import { UIAuthoringAdapter } from './ui-authoring-adapter';
-import { type UndoAdapter, unregisterUndoAdapter } from './undo-timeline';
-import { VgaiSceneAuthoringAdapter } from './vgai-scene-authoring-adapter';
+import { fetchSceneDoc, VgaiSceneAuthoringAdapter } from './vgai-scene-authoring-adapter';
 
 /**
  * C3 (docs/unified-world-editor/26-unified-editor-spec.md §4 C3) — dispatched
@@ -68,9 +50,9 @@ export const EDIT_MODE_REBUILD_EVENT = 'editor:edit-mode-rebuild';
 
 /**
  * The display-relevant slice of a manifest world entry this module needs —
- * deliberately LOOSE (a bare `string` `kind`, not the engine's validated
- * `WorldEntry['kind']` union) so a world that fails schema validation
- * (an unknown kind) can still be represented and surfaced as an error node
+ * deliberately LOOSE (a bare `string` `surface`, not the engine's validated
+ * `AdapterRoot['surface']` union) so a world that fails schema validation
+ * (an unknown surface) can still be represented and surfaced as an error node
  * (#18). Built by the LENIENT parse below (`parseEditModeManifest`), reachable
  * from the production project-open path — NOT gated on strict Zod, which would
  * reject the whole file for one bad world and make every declared world vanish
@@ -78,7 +60,7 @@ export const EDIT_MODE_REBUILD_EVENT = 'editor:edit-mode-rebuild';
  */
 export interface EditModeWorldSpec {
   readonly id: string;
-  readonly kind: string;
+  readonly surface: string;
   readonly adapter?: string | undefined;
   readonly scene?: string | undefined;
   readonly entry?: string | undefined;
@@ -87,7 +69,7 @@ export interface EditModeWorldSpec {
 }
 
 export interface EditModeManifest {
-  readonly worlds: readonly EditModeWorldSpec[];
+  readonly roots: readonly EditModeWorldSpec[];
 }
 
 const KNOWN_WORLD_KINDS = new Set(['threejs', 'pixijs', 'react']);
@@ -115,30 +97,38 @@ function displayAdapter(adapter: unknown): string | undefined {
 }
 
 /**
- * LENIENT parse (defect 2): read a raw `vgai.game.json` object's `worlds[]`
+ * LENIENT parse (defect 2): read a raw `vgai.game.json` object's `roots[]`
  * defensively into `EditModeWorldSpec[]`, so a single bad world (unknown
- * `kind`, missing `scene`+`entry`) becomes an error node (#18) while its VALID
+ * `surface`, missing `scene`+`entry`) becomes an error node (#18) while its VALID
  * siblings still open — never the strict-Zod all-or-nothing of
- * `loadGameManifest`. Returns `null` when there is no usable `worlds` array at
+ * `loadGameManifest`. Returns `null` when there is no usable `roots` array at
  * all (a present-but-unusable manifest, distinct from an ABSENT one) so the
  * caller can fall back to the synthesized single-world floor. A world missing
  * an `id` gets a positional placeholder so it still surfaces rather than
- * vanishing. `kind` is carried through verbatim (even a bogus string) —
+ * vanishing. `surface` is carried through verbatim (even a bogus string) —
  * `resolveWorldFailureReason` decides resolvability downstream.
  */
 export function parseEditModeManifest(raw: unknown): EditModeManifest | null {
   if (!raw || typeof raw !== 'object') return null;
-  const worldsRaw = (raw as Record<string, unknown>)['worlds'];
+  const worldsRaw = (raw as Record<string, unknown>)['roots'];
+  if (worldsRaw === undefined) return null;
   if (!Array.isArray(worldsRaw) || worldsRaw.length === 0) return null;
-  const worlds: EditModeWorldSpec[] = worldsRaw.map((entry, i) => {
+  const roots: EditModeWorldSpec[] = worldsRaw.map((entry, i) => {
     const w = (entry && typeof entry === 'object' ? entry : {}) as Record<string, unknown>;
     const zOrderRaw = w['zOrder'];
     const pausableRaw = w['pausable'];
     return {
       id: asString(w['id']) ?? `(world ${i})`,
-      // Missing/non-string kind is itself unresolvable — carry a sentinel so
+      // Missing/non-string surface is itself unresolvable — carry a sentinel so
       // resolveWorldFailureReason names it, rather than crashing on undefined.
-      kind: asString(w['kind']) ?? '(missing kind)',
+      surface:
+        (typeof w['adapter'] === 'string' ? asString(w['adapter']) : undefined) ??
+        asString(
+          w['adapter'] && typeof w['adapter'] === 'object'
+            ? (w['adapter'] as Record<string, unknown>)['surface']
+            : undefined,
+        ) ??
+        '(missing adapter surface)',
       adapter: displayAdapter(w['adapter']),
       scene: asString(w['scene']),
       entry: asString(w['entry']),
@@ -146,7 +136,7 @@ export function parseEditModeManifest(raw: unknown): EditModeManifest | null {
       pausable: typeof pausableRaw === 'boolean' ? pausableRaw : undefined,
     };
   });
-  return { worlds };
+  return { roots };
 }
 
 /**
@@ -158,8 +148,8 @@ export function parseEditModeManifest(raw: unknown): EditModeManifest | null {
  * out of scope here, where nothing but the focused world is ever fetched.
  */
 export function resolveWorldFailureReason(world: EditModeWorldSpec): string | null {
-  if (!KNOWN_WORLD_KINDS.has(world.kind)) {
-    return `Unknown world kind "${world.kind}" — expected one of: threejs, pixijs, react.`;
+  if (!KNOWN_WORLD_KINDS.has(world.surface)) {
+    return `Unknown world surface "${world.surface}" — expected one of: threejs, pixijs, react.`;
   }
   if (!world.scene && !world.entry) {
     return `World "${world.id}" declares neither \`scene\` nor \`entry\` — nothing to mount.`;
@@ -176,17 +166,21 @@ function normalizeScenePath(path: string): string {
  * the live store by `loadInitialScene`. Mirrors that function's OWN
  * resolution order (`initial-scene.ts`: `?scene=` URL param wins, else the
  * project's `defaultScene`); if neither names one of the manifest's threejs
- * worlds (or the manifest declares none), falls back to the first threejs
+ * roots (or the manifest declares none), falls back to the first threejs
  * world (matches the synthesized single-world manifest, which only ever has
  * exactly one). Exported (pure — no `window`/store reads) so it's directly
  * unit-testable; `installEditModeAuthoring` supplies the ambient
  * `focusScenePath` from `window.location`/the current project.
  */
 export function resolveFocusedThreejsWorldId(
-  worlds: readonly EditModeWorldSpec[],
+  roots: readonly {
+    readonly id: string;
+    readonly surface: string;
+    readonly scene?: string | undefined;
+  }[],
   focusScenePath: string | null | undefined,
 ): string | null {
-  const threejsWorlds = worlds.filter((w) => w.kind === 'threejs');
+  const threejsWorlds = roots.filter((w) => w.surface === 'threejs');
   if (threejsWorlds.length === 0) return null;
   if (focusScenePath) {
     const normalized = normalizeScenePath(focusScenePath);
@@ -199,26 +193,32 @@ export function resolveFocusedThreejsWorldId(
 }
 
 // ---------------------------------------------------------------------------
-// A4 (D8) — ManifestAuthoring: the game root's read-modify-write manifest surface
+// A4 (D8) — ManifestAuthoring: read-modify-write root composition properties
 // ---------------------------------------------------------------------------
 
 /** A raw `vgai.game.json` world entry, read/written defensively — same
  *  looseness as {@link EditModeWorldSpec}, but this is the RAW (unknown)
  *  object, never Zod-parsed, so unrelated fields survive a round trip. */
-type RawWorldEntry = Record<string, unknown>;
-
-function findRawWorld(raw: Record<string, unknown>, worldId: string): RawWorldEntry | undefined {
-  const worlds = raw['worlds'];
-  if (!Array.isArray(worlds)) return undefined;
-  return worlds.find(
-    (w): w is RawWorldEntry =>
-      !!w && typeof w === 'object' && (w as RawWorldEntry)['id'] === worldId,
+type RawAdapterRoot = Record<string, unknown>;
+
+function findRawWorld(raw: Record<string, unknown>, worldId: string): RawAdapterRoot | undefined {
+  const roots = raw['roots'];
+  if (!Array.isArray(roots)) return undefined;
+  return roots.find(
+    (w): w is RawAdapterRoot =>
+      !!w && typeof w === 'object' && (w as RawAdapterRoot)['id'] === worldId,
   );
 }
 
+/** Materialize D19's inferred world only when a user edits one of its
+ * manifest-backed properties. Until then the raw file remains minimal. */
+function ensureRawWorld(raw: Record<string, unknown>, worldId: string): RawAdapterRoot | undefined {
+  return findRawWorld(raw, worldId);
+}
+
 /**
- * ManifestAuthoring (A4, D8) — the game root's manifest-backed
- * {@link GameRootManifestProvider}: holds the RAW parsed `vgai.game.json`
+ * ManifestAuthoring (A4, D8) — authored roots' manifest-backed
+ * {@link RootManifestProvider}: holds the RAW parsed `vgai.game.json`
  * object (read-modify-write — NEVER round-tripped through the strict Zod
  * schema, so fields this module doesn't know about survive untouched) and
  * writes it back via `POST /__editor/manifest` (the one manifest-write verb,
@@ -231,30 +231,44 @@ function findRawWorld(raw: Record<string, unknown>, worldId: string): RawWorldEn
  *  - a SYNTHESIZED manifest (`synthesized: true`, no `vgai.game.json` on disk
  *    yet) BUFFERS edits in memory only; nothing is written until the
  *    explicit `materialize()` call (the generic inspector's "Create
- *    vgai.game.json" action). In production this branch is currently
- *    UNREACHABLE end-to-end: `installEditModeAuthoring` only ever installs a
- *    game root when 2+ worlds are declared, and `synthesizeSingleWorldManifest`
- *    (the only source of a `synthesized: true` manifest) always produces
- *    exactly ONE world — so a synthesized manifest never gets a game root
- *    through today's wiring. The buffering logic is still implemented and
- *    unit-tested for correctness/forward-compatibility (see this module's
- *    tests), and the limitation is called out explicitly rather than silently
- *    assumed away.
+ *    vgai.game.json" action). D19 makes this branch reachable for a
+ *    manifest-less conventional project because its inferred root is always
+ *    present.
  *
  * File-watcher landmine: `chokidar` only watches `public/` (`editor-server.ts`),
  * so a manifest write at the PROJECT ROOT emits no SSE — `notifyIngestEdit()`
  * after every successful write is what keeps the hierarchy panel's badges
  * live instead of stale until reopen.
  */
-export class ManifestAuthoring implements GameRootManifestProvider {
+export class ManifestAuthoring implements RootManifestProvider {
   private readonly raw: Record<string, unknown>;
-  readonly synthesized: boolean;
+  private synthesizedValue: boolean;
   private readonly store: EditorStore;
+  private readonly fileHistory: ProjectFileHistory | null;
+  private readonly unsubscribeHistory: (() => void) | null;
 
   constructor(raw: Record<string, unknown>, synthesized: boolean, store: EditorStore) {
     this.raw = raw;
-    this.synthesized = synthesized;
+    this.synthesizedValue = synthesized;
     this.store = store;
+    const history = store.projectHistory;
+    this.fileHistory = history
+      ? getProjectFileHistory(history, getManifestHistoryBackend(), 'project-manifest')
+      : null;
+    this.unsubscribeHistory = this.fileHistory
+      ? this.fileHistory.subscribeAll((path) => {
+          if (path !== 'vgai.game.json') return;
+          void getManifestHistoryBackend()
+            .readBytes(path)
+            .then((bytes) => JSON.parse(new TextDecoder().decode(bytes)) as Record<string, unknown>)
+            .then((next) => {
+              for (const key of Object.keys(this.raw)) delete this.raw[key];
+              Object.assign(this.raw, next);
+              this.store.notifyIngestEdit();
+            })
+            .catch(() => {});
+        })
+      : null;
   }
 
   getGameName(): string {
@@ -262,9 +276,23 @@ export class ManifestAuthoring implements GameRootManifestProvider {
     return typeof name === 'string' ? name : '';
   }
 
+  get synthesized(): boolean {
+    return this.synthesizedValue;
+  }
+
   setGameName(name: string): void {
     this.raw['name'] = name;
-    this.persist();
+    this.persist('Rename Game');
+  }
+
+  getWorldContentSource(worldId: string): string | undefined {
+    const world = findRawWorld(this.raw, worldId);
+    if (!world) return undefined;
+    const scene = world['scene'];
+    if (typeof scene === 'string') return `Scene · ${scene}`;
+    const entry = world['entry'];
+    if (typeof entry === 'string') return `Entry · ${entry}`;
+    return 'Adapter-owned runtime content';
   }
 
   getWorldZOrder(worldId: string): number {
@@ -273,10 +301,10 @@ export class ManifestAuthoring implements GameRootManifestProvider {
   }
 
   setWorldZOrder(worldId: string, value: number): void {
-    const world = findRawWorld(this.raw, worldId);
+    const world = ensureRawWorld(this.raw, worldId);
     if (!world) return;
     world['zOrder'] = value;
-    this.persist();
+    this.persist('Change World Order');
   }
 
   getWorldPausable(worldId: string): boolean {
@@ -285,27 +313,42 @@ export class ManifestAuthoring implements GameRootManifestProvider {
   }
 
   setWorldPausable(worldId: string, value: boolean): void {
-    const world = findRawWorld(this.raw, worldId);
+    const world = ensureRawWorld(this.raw, worldId);
     if (!world) return;
     world['pausable'] = value;
-    this.persist();
+    this.persist('Change World Pausing');
   }
 
   /** The "Create vgai.game.json" action (generic inspector, while
    *  `synthesized`) — materializes the buffered edits to disk. Also safe to
    *  call on a non-synthesized instance (equivalent to an explicit re-save). */
   async materialize(): Promise<boolean> {
-    return this.write();
+    const written = await this.write('Create Game Manifest');
+    if (written) this.synthesizedValue = false;
+    return written;
+  }
+
+  dispose(): void {
+    this.unsubscribeHistory?.();
   }
 
-  private persist(): void {
+  private persist(label: string): void {
     if (this.synthesized) return; // buffered only — wait for materialize()
-    void this.write();
+    void this.write(label);
   }
 
-  private async write(): Promise<boolean> {
+  private async write(label: string): Promise<boolean> {
     const content = JSON.stringify(this.raw, null, 2);
     try {
+      if (this.fileHistory) {
+        await this.fileHistory.write('vgai.game.json', content, {
+          label,
+          kind: 'manifest',
+          contentType: 'application/json',
+        });
+        this.store.notifyIngestEdit();
+        return true;
+      }
       // Phase A cleanup: `vgai.game.json` is project-root-relative, the same
       // namespace `authoring/world-overlay.ts`/`authoring/ingest-overlay.ts`
       // already mode-branch on — browser mode has no `/__editor/*` server at
@@ -328,106 +371,44 @@ export class ManifestAuthoring implements GameRootManifestProvider {
       this.store.notifyIngestEdit();
       return true;
     } catch (err) {
+      if (this.fileHistory) {
+        void getManifestHistoryBackend()
+          .readBytes('vgai.game.json')
+          .then((bytes) => JSON.parse(new TextDecoder().decode(bytes)) as Record<string, unknown>)
+          .then((next) => {
+            for (const key of Object.keys(this.raw)) delete this.raw[key];
+            Object.assign(this.raw, next);
+            this.store.notifyIngestEdit();
+          })
+          .catch(() => {});
+      }
       editorConsole.error(`Failed to write vgai.game.json: ${err}`, 'project');
       return false;
     }
   }
 }
 
-/** Children built by the last `installEditModeAuthoring` call — tracked so
- *  `exitEditModeAuthoring` can unregister any that self-registered with the
- *  undo timeline (mirrors `play-mode.ts`'s `_multiWorldChildren`/
- *  `exitMultiWorldAuthoring`). Boundary adapters never register (no `undo`/
- *  `redo`); the focused `VgaiSceneAuthoringAdapter` delegates undo/redo to
- *  the store, which registers ITSELF once at construction
- *  (`editor-store.ts`) — so this is currently always a no-op in practice,
- *  kept for the same defensive reason `play-mode.ts`'s guard is: a future
- *  live child adapter (B1's `ReactWorldAuthoringAdapter`) DOES self-register. */
-let _editModeChildren: AuthoringAdapter[] = [];
-
-/**
- * C3 / R2 — the `UIEditStore`(s) built for this session's scene-UI child(ren)
- * (today: at most one, the focused world's). Tracked SEPARATELY from
- * `_editModeChildren`: the undo timeline registers the `UIEditStore` itself
- * (`ui-edit-store.ts`'s constructor, `registerUndoAdapter(this)`), NOT the
- * `UIAuthoringAdapter` wrapping it — `exitEditModeAuthoring`'s generic
- * `_editModeChildren` loop below unregisters the ADAPTER, which was never in
- * the undo timeline's `live` set (a harmless no-op for it), so the real store
- * needs its OWN explicit unregister here, exactly what the retired standalone
- * UI-edit mode's own teardown used to do.
- */
-let _editModeUIStores: UIEditStore[] = [];
-
-/**
- * C3 — build the scene-UI child for `focusedWorldId`'s composite when the
- * open scene has authored UI roots (`store.getSceneUI().length > 0`,
- * §3.1's install gate — a ui-less scene gets no child at all, keeping the
- * A1 single-world back-compat floor byte-identical). Mirrors the retired
- * standalone UI-edit mode's store/adapter construction, minus its
- * demo-fixture fallback (Q3: "should never have existed" — dropped by
- * design, not lost; see the harness/15/16 for the demo fixture's only
- * remaining home) and its own `setActiveAuthoring` call (the shared
- * composite install below already does that once, for every child).
- */
-function buildUIChild(store: EditorStore, focusedWorldId: string, zOrder: number): CompositeChild {
-  const uiStore = new UIEditStore(store.getSceneUI(), {
-    // Persist every committed edit back into the open scene's `ui` + autosave
-    // (C9) — the exact same commit path the retired standalone UI-edit
-    // mode's `onCommit` used.
-    onCommit: (next) => store.setSceneUI(next),
-  });
-  _editModeUIStores.push(uiStore);
-  const adapter = new UIAuthoringAdapter(uiStore, {
-    ...(import.meta.env.DEV ? { writeBackend: createHttpSourceWriteBackend() } : {}),
-  });
-  return {
-    worldId: `${focusedWorldId}:ui`,
-    kind: 'scene-ui',
-    adapter,
-    zOrder,
-    parentWorldId: focusedWorldId,
-  };
-}
-
-/**
- * B1 — register a child adapter minted AFTER `installEditModeAuthoring`
- * already ran (a design-time layer's successful mount, which upgrades a
- * world's Boundary adapter to a live one via `CompositeAuthoringAdapter.
- * replaceChild` — `design-time-layers.ts`). Mirrors the constructor-time
- * seeding above (`_editModeChildren = children.map(...)`) so `exitEditModeAuthoring`
- * unregisters this adapter from the undo timeline too, exactly like every
- * child present at install time. A no-op call with an adapter that never
- * self-registered (no `undo`/`redo`) is harmless — `exitEditModeAuthoring`'s
- * loop already guards on that pair being present.
- */
-export function registerEditModeChild(adapter: AuthoringAdapter): void {
-  _editModeChildren.push(adapter);
-}
+let _manifestAuthoring: ManifestAuthoring | null = null;
 
 /**
- * Build the composite over every declared world and — ONLY when there is
- * more than one world to disclose — install it as the active authoring
- * override (see this module's header comment for why the single-world case
- * deliberately leaves the shared slot untouched). Always returns the built
- * composite so callers (tests) can inspect it regardless of whether it was
- * installed as the override.
+ * Build the composite over every declared world and install it as the active
+ * authoring override for every non-empty composition
+ * (D19). Always returns the built composite so callers can inspect it.
  *
- * The focused threejs world is whichever one's scene `loadInitialScene`
- * already loaded into the store (URL `?scene=` / `defaultScene` order); it
- * gets the real `VgaiSceneAuthoringAdapter`. A1 deliberately ships NO
- * focus-SWITCH (loading a DIFFERENT world's scene into the store) — that
- * requires a dirty-check-before-switch prompt + the scene-load path and lands
- * in A4 ({@link switchFocusedWorld} is the explicit, loud stub). Accepting a
- * "focus this other world" override here would label the new world's identity
- * onto the OLD world's still-loaded document — a silent misattribution
- * (defect 5) — so that parameter was removed.
+ * The focused threejs world is whichever one's scene the store currently
+ * holds (URL `?scene=` / `defaultScene` order — `loadInitialScene` at open,
+ * {@link switchFocusedWorld} thereafter); it gets the real
+ * `VgaiSceneAuthoringAdapter`. This function still accepts NO "focus this
+ * other world" parameter — that would label the new world's identity onto
+ * the OLD world's still-loaded document (defect 5). A focus change happens
+ * ONLY through {@link switchFocusedWorld}, which changes the document and
+ * the `?scene=` truth together and then rebuilds through this function.
  *
  * `rawManifestInfo` (A4, D8, optional) — the RAW parsed `vgai.game.json` +
- * whether it was synthesized (never written to disk); when given AND the
- * composite ends up with 2+ children, a `ManifestAuthoring` is built over it
- * and passed to `CompositeAuthoringAdapter` as its game-root manifest
- * surface. Omitted (every existing unit-test call site) ⇒ no game root, the
- * exact pre-A4 shape — see `CompositeAuthoringAdapter`'s own doc comment.
+ * whether it was synthesized (never written to disk); when given and the
+ * composite has a world, a `ManifestAuthoring` is built over it
+ * and passed to `CompositeAuthoringAdapter` as its root-property manifest
+ * surface. When omitted, composition properties are read-only.
  */
 export function installEditModeAuthoring(
   store: EditorStore,
@@ -438,9 +419,17 @@ export function installEditModeAuthoring(
   const sceneParam = urlParams.get('scene');
   const defaultScene = getCurrentProject()?.config.defaultScene ?? undefined;
   const focusScenePath = sceneParam ?? defaultScene ?? null;
-  const focusedWorldId = resolveFocusedThreejsWorldId(manifest.worlds, focusScenePath);
+  const focusedWorldId = resolveFocusedThreejsWorldId(manifest.roots, focusScenePath);
+
+  // A4 — rebuild the focus-candidate map WHOLE (install time is the recompute
+  // point): every unfocused threejs world with a loadable manifest scene.
+  _focusCandidates = new Map(
+    manifest.roots
+      .filter((w) => w.surface === 'threejs' && w.id !== focusedWorldId && w.scene !== undefined)
+      .map((w) => [w.id, w.scene as string]),
+  );
 
-  const children: CompositeChild[] = manifest.worlds.map((world) => {
+  const children: CompositeChild[] = manifest.roots.map((world) => {
     // D12 (B4) — install-time zOrder for every child, not just the Boundary's
     // own inspector-displayed value: `childAdapters()`'s pick/paint-order
     // consumers (the layered pick walk, the hierarchy zOrder badge) need it
@@ -449,7 +438,7 @@ export function installEditModeAuthoring(
     if (world.id === focusedWorldId) {
       return {
         worldId: world.id,
-        kind: world.kind,
+        kind: world.surface,
         adapter: new VgaiSceneAuthoringAdapter(store),
         zOrder,
       };
@@ -457,7 +446,7 @@ export function installEditModeAuthoring(
     const reason = resolveWorldFailureReason(world);
     const info: BoundaryWorldInfo = {
       id: world.id,
-      kind: world.kind,
+      kind: world.surface,
       adapter: world.adapter,
       entryOrScenePath: world.scene ?? world.entry,
       zOrder,
@@ -465,54 +454,24 @@ export function installEditModeAuthoring(
     };
     return {
       worldId: world.id,
-      kind: world.kind,
+      kind: world.surface,
       adapter: new BoundaryAuthoringAdapter(store, info, reason ?? undefined),
       zOrder,
     };
   });
 
-  // C3 — the focused world's scene-UI child (§3.1): only when the open scene
-  // actually has UI roots to disclose, and only when there IS a focused
-  // threejs world to nest it under (a manifest declaring zero threejs worlds
-  // has nowhere to attach one — an edge case `resolveFocusedThreejsWorldId`
-  // already surfaces as `null`). Counts toward the `children.length > 1`
-  // install gate below BY DESIGN (R5): a single-world project that already
-  // authored UI content gets the composite + the nested "ui (scene-ui)" row;
-  // a ui-less single-world project's hierarchy shape is untouched.
-  if (focusedWorldId && store.getSceneUI().length > 0) {
-    const focusedChild = children.find((c) => c.worldId === focusedWorldId);
-    children.push(buildUIChild(store, focusedWorldId, focusedChild?.zOrder ?? 0));
-  }
-
-  // A4 (D8) — the game root only makes sense once there IS a composition to
-  // disclose (2+ worlds); a single-world project (synthesized or a real
-  // 1-world manifest) never installs the composite as the override at all
-  // (below), so it would never be reachable regardless.
-  const gameRoot =
-    rawManifestInfo && children.length > 1
+  // D19 — every composition, including one root, uses the same adapter projection.
+  // A synthesized manifest uses the same tree; its manifest-backed
+  // edits remain buffered until an explicit project change materializes it.
+  const manifestAuthoring =
+    rawManifestInfo && children.length >= 1
       ? new ManifestAuthoring(rawManifestInfo.raw, rawManifestInfo.synthesized, store)
       : undefined;
-  const composite = new CompositeAuthoringAdapter(children, gameRoot);
-  _editModeChildren = children.map((c) => c.adapter);
-
-  // A1 delta (Wave-1 Phase-A close-out, spec:232-235, spec §3) — the ORIGINAL
-  // floor here was bare `children.length > 1`: a manifest whose only world is
-  // react (or any world-set with NO focused threejs world at all) never met
-  // it, so that world never entered the composite/hierarchy and
-  // `WorldSelectionOverlay` self-gated off, even though a real world exists
-  // to disclose. `focusedWorldId === null` (see `resolveFocusedThreejsWorldId`'s
-  // own doc comment: it returns `null` exactly when the manifest declares NO
-  // threejs world) with at least one child is that no-threejs case — install
-  // the composite there too. The single-threejs-world floor above (`children.
-  // length === 1` AND that one world IS the focused threejs world, so
-  // `focusedWorldId` is non-null) is UNCHANGED and must stay so — see the doc
-  // comment at this file's top (~:15-33) explaining why that back-compat
-  // floor is exact, not "equivalent". `mountDesignTimeLayers` already handles
-  // the layer mount for the newly-activated no-threejs case unchanged — no
-  // parallel react-only entry point is added here (spec-27 E3 all-worlds
-  // generalization).
-  const noFocusedThreejsWorld = focusedWorldId === null;
-  if (children.length > 1 || (children.length >= 1 && noFocusedThreejsWorld)) {
+  _manifestAuthoring = manifestAuthoring ?? null;
+  const projection = hierarchyProjectionFromProjectConfig(getCurrentProject()?.config);
+  const composite = new CompositeAuthoringAdapter(children, manifestAuthoring, projection);
+
+  if (children.length >= 1) {
     // Brand BEFORE installing so the store's save guard sees it the instant
     // the override is live (defect 1: the focused first-party child must be
     // able to Ctrl+S/autosave through the store, unlike a foreign override).
@@ -527,51 +486,115 @@ export function installEditModeAuthoring(
 /** Teardown symmetric to `installEditModeAuthoring` — clears the override
  *  ONLY if it is still exactly the composite this module last installed
  *  (never clobbers a DIFFERENT session, e.g. ingest/play, that took over
- *  afterward), and unregisters any child that self-registered with the undo
- *  timeline. */
+ *  afterward). */
 export function exitEditModeAuthoring(installed?: CompositeAuthoringAdapter): void {
   if (installed && getAuthoringOverride() === installed) {
     setActiveAuthoring(null);
   }
-  for (const adapter of _editModeChildren) {
-    if (adapter.undo && adapter.redo) {
-      unregisterUndoAdapter(adapter as AuthoringAdapter & UndoAdapter);
-    }
-  }
-  _editModeChildren = [];
-  // R2 — see `_editModeUIStores`'s doc comment: the real undo-timeline
-  // registrant for a scene-UI child is its `UIEditStore`, not the
-  // `UIAuthoringAdapter` the loop above already (harmlessly, no-op) tried.
-  for (const uiStore of _editModeUIStores) {
-    unregisterUndoAdapter(uiStore);
+  _manifestAuthoring?.dispose();
+  _manifestAuthoring = null;
+}
+
+// ---------------------------------------------------------------------------
+// A4 — focus-SWITCH: make a different threejs world the live/focused one
+// ---------------------------------------------------------------------------
+
+/**
+ * A4 — which UNFOCUSED threejs roots can become focused, captured by the
+ * last `installEditModeAuthoring` run (worldId → manifest scene path).
+ * Install time IS the recompute point — the map is rebuilt whole on every
+ * install/rebuild, never patched. A threejs world with no `scene` (entry-only)
+ * is genuinely unswitchable — there is nothing to load into the store — so it
+ * never enters the map and the shell shows no affordance for it (spec 28:
+ * hide when the subject is absent).
+ */
+let _focusCandidates = new Map<string, string>();
+
+/** The manifest scene path `switchFocusedWorld` would load for `worldId`, or
+ *  `null` when that world is not a switchable unfocused threejs world. The
+ *  shell gates its focus-switch affordances on this (never advertise a switch
+ *  that will refuse — spec 29 §3). */
+export function worldFocusScenePath(worldId: string): string | null {
+  return _focusCandidates.get(worldId) ?? null;
+}
+
+/** Dispatched (on `window`) when a focus-switch needs the dirty-gate
+ *  confirmation dialog — same decoupling pattern as `root-activation.ts`'s
+ *  `ROOT_ACTIVATION_REQUEST_EVENT`; `DefaultEditorLayout` listens. */
+export const WORLD_FOCUS_REQUEST_EVENT = 'editor:request-world-focus';
+
+export interface WorldFocusRequest {
+  readonly worldId: string;
+  readonly scenePath: string;
+}
+
+/**
+ * Focus-SWITCH (A4, closing defect 5's deferral): make `worldId` the live
+ * threejs world by doing exactly what the initial load does, in its order —
+ * flush pending edits (`saveNow`, same as `rootGroups.activate`), load the
+ * target world's manifest scene into the store (this clears undo/redo and
+ * retargets autosave — `loadDocument`'s own proven semantics), point the
+ * ambient focus truth at it (`?scene=`, the SAME param `loadInitialScene`
+ * and `installEditModeAuthoring` read — so any later rebuild, and a browser
+ * refresh, re-derive THIS focus), then fire the C3 rebuild event so
+ * `ViewportPanel.installAll()` reinstalls the composite: the target world
+ * gets the real `VgaiSceneAuthoringAdapter`, the previously-focused world
+ * downgrades to a Boundary. No identity misattribution is possible because
+ * the document and the focus truth change together, before the rebuild.
+ */
+export async function switchFocusedWorld(
+  store: EditorStore,
+  worldId: string,
+  scenePath: string,
+): Promise<void> {
+  if (store.isDirty) await store.saveNow();
+  const path = normalizeScenePath(scenePath);
+  let doc: Awaited<ReturnType<typeof fetchSceneDoc>>;
+  try {
+    doc = await fetchSceneDoc(path);
+  } catch (err) {
+    editorConsole.error(
+      `Focus-switch to world "${worldId}" failed — could not load its scene "${path}": ${err}`,
+      'project',
+    );
+    return;
   }
-  _editModeUIStores = [];
+  store.loadDocument(doc, path);
+  const url = new URL(window.location.href);
+  url.searchParams.set('scene', path);
+  window.history.replaceState(null, '', url.toString());
+  window.dispatchEvent(new CustomEvent(EDIT_MODE_REBUILD_EVENT));
 }
 
 /**
- * Focus-SWITCH (A4, defect 5): switching which threejs world is live requires
- * (a) a dirty-check-before-switch prompt and (b) LOADING the target world's
- * scene into the store — neither of which A1 ships. This explicit stub exists
- * so a future caller gets a loud, named failure instead of A1 silently
- * rebuilding a composite that labels the target world's identity onto the
- * currently-loaded document. A1's composite always focuses the world
- * `loadInitialScene` already loaded.
+ * Request focusing `worldId` — the shell's ONE entry point (both the world
+ * row double-click and its context-menu item), mirroring
+ * `requestRootActivation`'s dirty-gate: a dirty store gets the shell-rendered
+ * confirmation dialog (`DefaultEditorLayout` listens for
+ * {@link WORLD_FOCUS_REQUEST_EVENT} and calls {@link switchFocusedWorld} on
+ * confirm); a clean store switches immediately.
  */
-export function switchFocusedWorld(): never {
-  throw new Error(
-    'Focus-switch (loading a different threejs world into the store, with a ' +
-      'dirty-check prompt) is not implemented in A1 — it lands in A4. A1 installs the ' +
-      'composite over the world loadInitialScene already loaded.',
-  );
+export function requestWorldFocus(store: EditorStore, worldId: string): void {
+  const scenePath = worldFocusScenePath(worldId);
+  if (scenePath === null) return;
+  if (store.isDirty) {
+    window.dispatchEvent(
+      new CustomEvent(WORLD_FOCUS_REQUEST_EVENT, {
+        detail: { worldId, scenePath } satisfies WorldFocusRequest,
+      }),
+    );
+    return;
+  }
+  void switchFocusedWorld(store, worldId, scenePath);
 }
 
 /**
  * Project-open wiring: fetch the RAW `vgai.game.json` and install the edit-mode
  * composite via the LENIENT parse (defect 2) — a manifest with one bad world
- * still opens its valid worlds, surfacing the bad one as an error node (#18).
+ * still opens its valid roots, surfacing the bad one as an error node (#18).
  * ONLY a genuinely ABSENT manifest (the route 404s → `fetchRawGameManifest`
- * returns `null`), or one so malformed it has no usable `worlds` array,
- * synthesizes a single `{ id: 'main', kind: 'threejs', scene: <resolved> }`
+ * returns `null`), or one so malformed it has no usable `roots` array,
+ * synthesizes a single `{ id: 'main', surface: 'threejs', scene: <resolved> }`
  * game IN MEMORY (never written to disk), where `<resolved>` mirrors
  * `loadInitialScene`'s OWN resolution order. This is the only call site that
  * should call `installEditModeAuthoring` at ordinary project open
@@ -581,13 +604,10 @@ export async function installEditModeAuthoringForProject(
   store: EditorStore,
 ): Promise<CompositeAuthoringAdapter> {
   let manifest: EditModeManifest;
-  // A4 (D8) — the RAW object backing `ManifestAuthoring` (read-modify-write,
-  // never round-tripped through Zod). `synthesized: true` when there is no
-  // real `vgai.game.json` on disk (a 404, or one so malformed it has no
-  // usable `worlds` array) — see `ManifestAuthoring`'s doc comment for why
-  // this branch is unreachable end-to-end today (synthesis always produces
-  // exactly one world; a game root only installs for 2+).
-  let rawManifestInfo: { raw: Record<string, unknown>; synthesized: boolean };
+  // The RAW object backing `ManifestAuthoring` (read-modify-write, never
+  // round-tripped through Zod). An omitted roots field is a real manifest
+  // using D19's convention, not a synthesized/unsaved manifest.
+  let rawManifestInfo: { raw: Record<string, unknown>; synthesized: boolean } | undefined;
   try {
     const raw = await fetchRawGameManifest();
     const parsed = raw !== null && parseEditModeManifest(raw);
@@ -595,49 +615,14 @@ export async function installEditModeAuthoringForProject(
       manifest = parsed;
       rawManifestInfo = { raw: raw as Record<string, unknown>, synthesized: false };
     } else {
-      manifest = synthesizeSingleWorldManifest();
-      rawManifestInfo = { raw: synthesizeRawManifest(manifest), synthesized: true };
+      throw new Error('manifest must declare a non-empty roots array');
     }
   } catch (err) {
-    editorConsole.error(
-      `Failed to load vgai.game.json, falling back to a synthesized single-world game: ${err}`,
-      'project',
-    );
-    manifest = synthesizeSingleWorldManifest();
-    rawManifestInfo = { raw: synthesizeRawManifest(manifest), synthesized: true };
+    const detail = err instanceof Error ? err.message : String(err);
+    editorConsole.error(`Failed to load vgai.game.json: ${detail}`, 'project');
+    manifest = {
+      roots: [{ id: 'manifest', surface: '(invalid manifest)', adapter: detail }],
+    };
   }
   return installEditModeAuthoring(store, manifest, rawManifestInfo);
 }
-
-function synthesizeSingleWorldManifest(): EditModeManifest {
-  return {
-    worlds: [
-      {
-        id: 'main',
-        kind: 'threejs',
-        scene: resolveInitialScenePathForManifestSynthesis(getCurrentProject()) ?? undefined,
-      },
-    ],
-  };
-}
-
-/** A minimally-valid RAW manifest object matching a synthesized in-memory
- *  game (A4) — never written to disk on its own; only feeds `ManifestAuthoring`
- *  for the (currently unreachable, see that class's doc comment) 1-world
- *  "Create vgai.game.json" path. */
-function synthesizeRawManifest(manifest: EditModeManifest): Record<string, unknown> {
-  return {
-    manifestVersion: 1,
-    name: getCurrentProject()?.config.name ?? 'My Game',
-    version: '0.1.0',
-    engine: { version: '0.0.0' },
-    worlds: manifest.worlds.map((w) => ({
-      id: w.id,
-      kind: w.kind,
-      ...(w.scene !== undefined ? { scene: w.scene } : {}),
-      ...(w.entry !== undefined ? { entry: w.entry } : {}),
-      zOrder: w.zOrder ?? 0,
-      pausable: w.pausable ?? true,
-    })),
-  };
-}