@vgai/editor 0.2.0

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

@@ -0,0 +1,643 @@
+/**
+ * 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
+ * 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);
+ * every other declared world gets a read-only {@link BoundaryAuthoringAdapter}
+ * 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.
+ */
+
+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 { 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,
+} from './composite-authoring-adapter';
+import { UIAuthoringAdapter } from './ui-authoring-adapter';
+import { type UndoAdapter, unregisterUndoAdapter } from './undo-timeline';
+import { VgaiSceneAuthoringAdapter } from './vgai-scene-authoring-adapter';
+
+/**
+ * C3 (docs/unified-world-editor/26-unified-editor-spec.md §4 C3) — dispatched
+ * (on `window`) when the open scene's `ui` roots change in a way that
+ * requires REINSTALLING the edit-mode composite (today: only the "Add UI
+ * Canvas" hierarchy-menu action, `ui-hierarchy-menu.ts` — going from zero UI
+ * roots to one flips whether the scene-UI child exists at all, §3.1's
+ * install-gate). Mirrors `root-activation.ts`'s
+ * `ROOT_ACTIVATION_REQUEST_EVENT` window-CustomEvent decoupling pattern.
+ * `ViewportPanel.tsx` listens and reruns its `installAll()`.
+ */
+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
+ * (#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
+ * (defect 2).
+ */
+export interface EditModeWorldSpec {
+  readonly id: string;
+  readonly kind: string;
+  readonly adapter?: string | undefined;
+  readonly scene?: string | undefined;
+  readonly entry?: string | undefined;
+  readonly zOrder?: number | undefined;
+  readonly pausable?: boolean | undefined;
+}
+
+export interface EditModeManifest {
+  readonly worlds: readonly EditModeWorldSpec[];
+}
+
+const KNOWN_WORLD_KINDS = new Set(['threejs', 'pixijs', 'react']);
+
+function asString(v: unknown): string | undefined {
+  return typeof v === 'string' ? v : undefined;
+}
+
+/** Display string for a raw `adapter` field — informational only (the Boundary
+ *  inspector's read-only `adapter` property). Read defensively: the raw JSON
+ *  may be a string ('default'), a `{ module }`/`{ ingest }` object, or absent. */
+function displayAdapter(adapter: unknown): string | undefined {
+  if (adapter === undefined || adapter === null) return undefined;
+  if (typeof adapter === 'string') return adapter;
+  if (typeof adapter === 'object') {
+    const obj = adapter as Record<string, unknown>;
+    if (typeof obj['module'] === 'string') return `module:${obj['module']}`;
+    const ingest = obj['ingest'];
+    if (ingest && typeof ingest === 'object') {
+      const strategy = asString((ingest as Record<string, unknown>)['strategy']);
+      return strategy ? `ingest:${strategy}` : 'ingest';
+    }
+  }
+  return undefined;
+}
+
+/**
+ * LENIENT parse (defect 2): read a raw `vgai.game.json` object's `worlds[]`
+ * defensively into `EditModeWorldSpec[]`, so a single bad world (unknown
+ * `kind`, 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
+ * 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) —
+ * `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'];
+  if (!Array.isArray(worldsRaw) || worldsRaw.length === 0) return null;
+  const worlds: 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
+      // resolveWorldFailureReason names it, rather than crashing on undefined.
+      kind: asString(w['kind']) ?? '(missing kind)',
+      adapter: displayAdapter(w['adapter']),
+      scene: asString(w['scene']),
+      entry: asString(w['entry']),
+      zOrder: typeof zOrderRaw === 'number' ? zOrderRaw : undefined,
+      pausable: typeof pausableRaw === 'boolean' ? pausableRaw : undefined,
+    };
+  });
+  return { worlds };
+}
+
+/**
+ * Structural resolvability (#18) — NOT a filesystem check: "missing entry/scene
+ * file" here means the world declares NEITHER field (mirrors the manifest
+ * schema's own `checkAdapterSceneEntryRules`, `manifest/load.ts`). A live "does
+ * the file actually exist on disk" probe is B1 territory (the design-time mount
+ * attempt itself degrades to this same error-node floor when a layer throws) —
+ * 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 (!world.scene && !world.entry) {
+    return `World "${world.id}" declares neither \`scene\` nor \`entry\` — nothing to mount.`;
+  }
+  return null;
+}
+
+function normalizeScenePath(path: string): string {
+  return path.startsWith('/') ? path.slice(1) : path;
+}
+
+/**
+ * Which threejs world is FOCUSED — its scene is the one already loaded into
+ * 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
+ * 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[],
+  focusScenePath: string | null | undefined,
+): string | null {
+  const threejsWorlds = worlds.filter((w) => w.kind === 'threejs');
+  if (threejsWorlds.length === 0) return null;
+  if (focusScenePath) {
+    const normalized = normalizeScenePath(focusScenePath);
+    const match = threejsWorlds.find(
+      (w) => w.scene !== undefined && normalizeScenePath(w.scene) === normalized,
+    );
+    if (match) return match.id;
+  }
+  return threejsWorlds[0]!.id;
+}
+
+// ---------------------------------------------------------------------------
+// A4 (D8) — ManifestAuthoring: the game root's read-modify-write manifest surface
+// ---------------------------------------------------------------------------
+
+/** 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,
+  );
+}
+
+/**
+ * ManifestAuthoring (A4, D8) — the game root's manifest-backed
+ * {@link GameRootManifestProvider}: 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,
+ * `editor-server.ts`).
+ *
+ * Two write modes:
+ *  - a REAL manifest (`synthesized: false`) writes through on every edit —
+ *    the acceptance's "round-trips vgai.game.json on disk" needs no separate
+ *    save step.
+ *  - 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.
+ *
+ * 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 {
+  private readonly raw: Record<string, unknown>;
+  readonly synthesized: boolean;
+  private readonly store: EditorStore;
+
+  constructor(raw: Record<string, unknown>, synthesized: boolean, store: EditorStore) {
+    this.raw = raw;
+    this.synthesized = synthesized;
+    this.store = store;
+  }
+
+  getGameName(): string {
+    const name = this.raw['name'];
+    return typeof name === 'string' ? name : '';
+  }
+
+  setGameName(name: string): void {
+    this.raw['name'] = name;
+    this.persist();
+  }
+
+  getWorldZOrder(worldId: string): number {
+    const z = findRawWorld(this.raw, worldId)?.['zOrder'];
+    return typeof z === 'number' ? z : 0;
+  }
+
+  setWorldZOrder(worldId: string, value: number): void {
+    const world = findRawWorld(this.raw, worldId);
+    if (!world) return;
+    world['zOrder'] = value;
+    this.persist();
+  }
+
+  getWorldPausable(worldId: string): boolean {
+    const p = findRawWorld(this.raw, worldId)?.['pausable'];
+    return typeof p === 'boolean' ? p : true;
+  }
+
+  setWorldPausable(worldId: string, value: boolean): void {
+    const world = findRawWorld(this.raw, worldId);
+    if (!world) return;
+    world['pausable'] = value;
+    this.persist();
+  }
+
+  /** 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();
+  }
+
+  private persist(): void {
+    if (this.synthesized) return; // buffered only — wait for materialize()
+    void this.write();
+  }
+
+  private async write(): Promise<boolean> {
+    const content = JSON.stringify(this.raw, null, 2);
+    try {
+      // 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
+      // all, so this used to silently fail every manifest edit there (caught
+      // below, logged, never surfaced beyond the console). Browser mode goes
+      // straight through `getStorageBackend()` (OPFS/FSA root at the TRUE
+      // project folder, no `public/` insertion); server mode is unchanged.
+      if (getEditorMode() === 'browser') {
+        await getStorageBackend().write('vgai.game.json', content);
+      } else {
+        const res = await fetch('/__editor/manifest', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ path: 'vgai.game.json', content }),
+        });
+        if (!res.ok) return false;
+      }
+      // No SSE for a project-root write (file-watcher only covers `public/`)
+      // — notify directly so the hierarchy panel's badges refresh in place.
+      this.store.notifyIngestEdit();
+      return true;
+    } catch (err) {
+      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);
+}
+
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * `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.
+ */
+export function installEditModeAuthoring(
+  store: EditorStore,
+  manifest: EditModeManifest,
+  rawManifestInfo?: { raw: Record<string, unknown>; synthesized: boolean },
+): CompositeAuthoringAdapter {
+  const urlParams = new URLSearchParams(window.location.search);
+  const sceneParam = urlParams.get('scene');
+  const defaultScene = getCurrentProject()?.config.defaultScene ?? undefined;
+  const focusScenePath = sceneParam ?? defaultScene ?? null;
+  const focusedWorldId = resolveFocusedThreejsWorldId(manifest.worlds, focusScenePath);
+
+  const children: CompositeChild[] = manifest.worlds.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
+    // off ANY child, including the focused threejs world.
+    const zOrder = world.zOrder ?? 0;
+    if (world.id === focusedWorldId) {
+      return {
+        worldId: world.id,
+        kind: world.kind,
+        adapter: new VgaiSceneAuthoringAdapter(store),
+        zOrder,
+      };
+    }
+    const reason = resolveWorldFailureReason(world);
+    const info: BoundaryWorldInfo = {
+      id: world.id,
+      kind: world.kind,
+      adapter: world.adapter,
+      entryOrScenePath: world.scene ?? world.entry,
+      zOrder,
+      pausable: world.pausable ?? true,
+    };
+    return {
+      worldId: world.id,
+      kind: world.kind,
+      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
+      ? 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)) {
+    // 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).
+    markEditModeOverride(composite);
+    setActiveAuthoring(composite);
+    store.notifyIngestEdit();
+  }
+
+  return composite;
+}
+
+/** 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. */
+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);
+  }
+  _editModeUIStores = [];
+}
+
+/**
+ * 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.
+ */
+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.',
+  );
+}
+
+/**
+ * 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).
+ * 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> }`
+ * 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
+ * (`ViewportPanel.tsx`).
+ */
+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 };
+  try {
+    const raw = await fetchRawGameManifest();
+    const parsed = raw !== null && parseEditModeManifest(raw);
+    if (parsed) {
+      manifest = parsed;
+      rawManifestInfo = { raw: raw as Record<string, unknown>, synthesized: false };
+    } else {
+      manifest = synthesizeSingleWorldManifest();
+      rawManifestInfo = { raw: synthesizeRawManifest(manifest), synthesized: true };
+    }
+  } 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 };
+  }
+  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,
+    })),
+  };
+}