@vgai/editor 0.2.0

package/src/ingest-siblings.ts

@@ -0,0 +1,466 @@
+/**
+ * Composite sibling mounts — D-V2/D-V3/D-V4/D-V7
+ * (docs/WAVE5-MULTIWORLD-INGEST-DESIGN.md, F24 residual), extended by D-B1/
+ * D-B3 (docs/WAVE6-DOCTOR-DESIGN.md Slice B, wave-5 residual closure): when a
+ * manifest declares exactly one `{ ingest }` world alongside OTHER worlds
+ * ("siblings"), `ingest-mode.ts`'s composite routes mount the ingest world
+ * through their existing enter path and then call {@link mountIngestSiblings}
+ * here to mount every OTHER world in manifest order (already z-sorted by the
+ * loader), degrading loudly per world rather than silently ignoring them
+ * (the F24/F9 anti-pattern this closes):
+ *
+ *  - `default-react` — a bare (no `<GameProvider>`) DOM layer, D-V3. There is
+ *    no native `Game` beside an ingest world, so wrapping one would fabricate
+ *    first-party data (anti-shim) — the sibling's own `useGameState`/
+ *    `useGame` calls are simply unavailable, and this says so once per world.
+ *    Has no loop at all, so its `SiblingMount.setPaused` stays `undefined`
+ *    (D-B1) — never a fabricated no-op.
+ *  - `{ module }` (any kind) OR a native `default-three`/`default-pixi` world
+ *    (D-B3 — the wave-5 residual this closes: a second `{ ingest }` world is
+ *    structurally unreachable here, D-V2 already fails the whole route
+ *    before any sibling loop runs, so `resolveAllWorlds`'s one-element call
+ *    below never hits its `MULTI_WORLD_ALLOWED_IDENTITIES` guard, which only
+ *    applies for `worlds.length > 1`) — a SCOPED single-world runtime, D-V4:
+ *    the exact resolve+mount `module-mode.ts`'s `enterModuleModeWorldsPath`
+ *    proves out, reused via `mountModuleWorldRuntime`, but with NONE of that
+ *    route's global side effects (no `setActiveAuthoring`/`setActiveSystems`,
+ *    no viewport-tab switch, no `__vgaiModule` hook, no play-surface writes).
+ *    Its `SiblingMount.setPaused` (D-B1) is wired straight from the scoped
+ *    `GameSession.pause()`/`.resume()` `mountModuleWorldRuntime` hands back —
+ *    the SAME honest, already-existing capability `play-mode.ts`'s own
+ *    `pausePlayMode`/`resumePlayMode` call on the PRIMARY route's session
+ *    (`create-runtime.ts`'s `Game.play.pause()`/`.resume()`, gated per
+ *    `pausable` world) — never a fabricated pause.
+ *  - anything else — `rejectUnmountableSibling`'s named, loud non-goal for a
+ *    genuinely unroutable shape (there is none known today; every currently
+ *    resolvable identity is handled above): a per-world mount-failure entry,
+ *    never silence.
+ *
+ * A failing sibling NEVER unmounts the ingest world: each failure is caught
+ * individually and appended to the (D-V5) multi-entry mount-failure report;
+ * the loop continues to the next sibling. Every successfully-mounted
+ * sibling's handle is returned so `ingest-mode.ts` can store it on the
+ * unified `_active` slot, dispose it (reverse order) on exit, and fan pause/
+ * resume out to it (D-B2, `getIngestPlayControl()`).
+ */
+
+import type { AuthoringAdapter } from '@engine/adapter';
+import type { ResolvedGameManifest, ResolvedWorldEntry } from '@engine/manifest/load';
+import type { Overlay2D } from '@engine/world2d/authoring-2d';
+import { createPhysics2DRegistry } from '@engine/world2d/physics2d-registry';
+import { createPhysicsAdapter2D } from '@engine/world2d/system-adapters-2d';
+import { Component, createElement, type ReactNode } from 'react';
+import { flushSync } from 'react-dom';
+import { createRoot } from 'react-dom/client';
+import { resolveReactWorldEntryComponent } from './adapter-resolver';
+import { makeEmbedOnlyAdapter } from './authoring/embed-only-adapter';
+import { IngestAuthoringAdapter } from './authoring/ingest-authoring-adapter';
+import type { IngestOverlay } from './authoring/ingest-overlay';
+import { addMountFailureReport, formatMountFailureMessage } from './authoring/mount-failure-report';
+import {
+  ReactDomAuthoringAdapter,
+  type ReactDomOverlay,
+} from './authoring/react-dom-authoring-adapter';
+import { ReactWorldAuthoringAdapter, walkOidTree } from './authoring/react-world-authoring-adapter';
+import { unregisterUndoAdapter } from './authoring/undo-timeline';
+import { loadWorldOverlay, saveWorldOverlay, worldOverlayPath } from './authoring/world-overlay';
+import { World2DAuthoringAdapter } from './authoring/world2d-authoring-adapter';
+import { editorConsole } from './editor-console';
+import type { EditorStore } from './editor-store';
+import { mountModuleWorldRuntime, withStoreSelection } from './module-mode';
+import { createHttpSourceWriteBackend } from './ui-source/source-write-backend';
+
+/** One mounted sibling world's handle — stored on `ingest-mode.ts`'s unified
+ *  `_active` slot and disposed (reverse order) by `exitActiveIngest()`. */
+export interface SiblingMount {
+  readonly worldId: string;
+  /**
+   * D-B1 (docs/WAVE6-DOCTOR-DESIGN.md Slice B): an OPTIONAL, honest pause
+   * capability — present only when this sibling's own mounted session
+   * exposes a REAL pause (today: every `mountScopedRuntimeSibling` kind, via
+   * its scoped `GameSession.pause()`/`.resume()`). Absent (never a fake
+   * no-op) for a kind with no loop to gate at all — the bare `default-react`
+   * sibling. `getIngestPlayControl()` (`ingest-mode.ts`, D-B2) calls this
+   * `?.`-optionally after its own primary-surface call, mirroring the
+   * reverse-order dispose fan-out below.
+   */
+  setPaused?(paused: boolean): void;
+  /**
+   * D-E1 (docs/WAVE8-SIBLING-AUTHORING-DESIGN.md): an OPTIONAL, HONEST
+   * authoring surface for this sibling — present iff `store` was supplied to
+   * {@link mountIngestSiblings} (every production caller supplies one; the
+   * parameter stays optional only so the one pre-existing test that calls
+   * this module directly without a store keeps compiling/running unchanged).
+   * When present, it is NEVER a fabricated stand-in:
+   *  - a scoped-runtime sibling (`{ module }`, or a native
+   *    `default-three`/`default-pixi` world) gets its OWN mounted
+   *    `AuthoringAdapter` (`mounted.authoring`), store-selection-wrapped
+   *    (`withStoreSelection`) — or, when it exposes none, the SAME named
+   *    embed-only floor `enterModuleModeWorldsPath` uses
+   *    (`makeEmbedOnlyAdapter`), so the world still appears in the hierarchy
+   *    as a group with its honest label, never silently omitted.
+   *  - a bare `default-react` sibling gets a {@link ReactWorldAuthoringAdapter}
+   *    over its own layer DOM root — an un-instrumented entry (no
+   *    `data-oid`) yields an EMPTY subtree under its group node, never
+   *    fabricated nodes.
+   * `ingest-mode.ts`'s composite routes promote to a `CompositeAuthoringAdapter`
+   * over the primary + every sibling's `authoring` once any sibling mounts
+   * (D-E2); a `SiblingMount` with no `authoring` (store omitted) simply
+   * cannot participate in that promotion.
+   */
+  readonly authoring?: AuthoringAdapter;
+  dispose(): void;
+}
+
+/**
+ * Minimal class-component error boundary (D-V3): a react sibling mounts with
+ * NO `<GameProvider>` (there is no native `Game` beside an ingest world), so
+ * a sibling component that calls `useGame`/`useGameState` anyway throws
+ * synchronously at first render — an error boundary is the only way React
+ * lets a HOST catch that (there is no hook equivalent), and it lets ONE
+ * misbehaving sibling fail loudly (via `onCaught`) without ever throwing out
+ * of `root.render()` uncaught or crashing any OTHER sibling / the ingest
+ * world itself.
+ */
+class SiblingErrorBoundary extends Component<
+  { onCaught: (error: unknown) => void; children: ReactNode },
+  { crashed: boolean }
+> {
+  override state = { crashed: false };
+  static getDerivedStateFromError(): { crashed: boolean } {
+    return { crashed: true };
+  }
+  override componentDidCatch(error: unknown): void {
+    this.props.onCaught(error);
+  }
+  override render(): ReactNode {
+    return this.state.crashed ? null : this.props.children;
+  }
+}
+
+/** Position/size/z-order every sibling layer shares — same absolute-fill
+ *  convention `create-runtime.ts`'s own react-world DOM layer uses
+ *  (`mountOneReactWorld`), so a sibling stacks exactly like a native world
+ *  would have. `pointerEvents` differs per sibling kind below (module worlds
+ *  own real canvases that need real hit-testing; the react sibling's layer
+ *  stays `none` by the same HUD-overlay convention `mountOneReactWorld` uses,
+ *  its rendered content opts back in per-element). */
+function styleSiblingLayer(
+  layer: HTMLElement,
+  world: ResolvedWorldEntry,
+  pointerEvents: string,
+): void {
+  layer.style.position = 'absolute';
+  layer.style.top = '0';
+  layer.style.left = '0';
+  layer.style.width = '100%';
+  layer.style.height = '100%';
+  layer.style.zIndex = String(world.zOrder ?? 0);
+  layer.style.pointerEvents = pointerEvents;
+}
+
+/**
+ * D-V3: mount a `default-react` sibling as a bare DOM layer — no
+ * `<GameProvider>` wrap (anti-shim: there is no native `Game` to hand it).
+ * Reuses `adapter-resolver.ts`'s exact entry-loading step
+ * (`resolveReactWorldEntryComponent` — the same D4 `scene`-forbidden/
+ * `entry`-required checks and default-export validation
+ * `resolveDefaultReactAdapter` itself uses) rather than duplicating it.
+ *
+ * If the entry component throws at mount/first render (most commonly: it
+ * calls `useGame`/`useGameState` with no provider in the tree), the error
+ * boundary above catches it, this function removes the layer it just
+ * created, and RETHROWS so the caller's uniform per-sibling catch
+ * (`mountOneIngestSibling`'s caller, {@link mountIngestSiblings}) can turn it
+ * into a named mount-failure-report entry for THIS world, exactly like any
+ * other sibling failure — the ingest world stays mounted regardless.
+ */
+async function mountDefaultReactSibling(
+  world: ResolvedWorldEntry,
+  gameContainer: HTMLElement,
+  projectRoot: string,
+  store: EditorStore | undefined,
+): Promise<SiblingMount> {
+  const Entry = await resolveReactWorldEntryComponent(world, projectRoot);
+
+  const layer = document.createElement('div');
+  styleSiblingLayer(layer, world, 'none');
+  gameContainer.appendChild(layer);
+
+  // D-V3: one structured note per world naming the degrade — never silent
+  // about the missing bridge.
+  editorConsole.log(
+    `react sibling "${world.id}": no native Game beside an ingest world — useGameState unavailable`,
+    'ingest',
+  );
+
+  const root = createRoot(layer);
+  let caught: unknown = null;
+  // `flushSync` forces the initial mount (render + commit + error-boundary
+  // recovery, if the entry throws) to complete SYNCHRONOUSLY, so `caught` is
+  // reliably populated by the time this call returns — react-dom's default
+  // scheduler does not guarantee that for a bare `root.render()` call (a
+  // production API, not a test-only affordance: this host needs the throw/
+  // no-throw outcome immediately, to decide whether to keep the layer or
+  // tear it down and report a named failure).
+  flushSync(() => {
+    root.render(
+      createElement(SiblingErrorBoundary, {
+        onCaught: (error: unknown) => {
+          caught = error;
+        },
+        children: createElement(Entry),
+      }),
+    );
+  });
+
+  if (caught !== null) {
+    root.unmount();
+    layer.remove();
+    throw caught instanceof Error ? caught : new Error(String(caught));
+  }
+
+  // D-M1 (docs/WAVE11-REACT-SIBLING-DOM-FALLBACK-DESIGN.md): once mounted,
+  // probe the REAL committed layer with `walkOidTree` — a partially-stamped
+  // tree counts as stamped (the walk's transparent-skip contract already
+  // handles instrumentation gaps), so this is a single "any node at all?"
+  // check, not a completeness one. A non-empty tree keeps the exact D-E1
+  // construction below (a STAMPED first-party entry — the sanctioned JSX
+  // write-back seam). A genuinely EMPTY tree (no `data-oid` reachable at
+  // all — e.g. an ingest-REACT sibling swept into the D-Y4 foreign-game
+  // exclusion, or an entry that rendered nothing yet) falls back to
+  // `ReactDomAuthoringAdapter`: an overlay-only surface over the live DOM,
+  // no `SourceWriteBackend` of any kind — never a write seam over source the
+  // stamping pipeline declined to instrument. Only computed when a store was
+  // supplied (see `SiblingMount.authoring`'s doc comment) — never fabricated.
+  let authoring: ReactWorldAuthoringAdapter | ReactDomAuthoringAdapter | undefined;
+  if (store) {
+    const stamped = walkOidTree(layer).nodes.size > 0;
+    authoring = stamped
+      ? // D-E1: the exact play-mode react-branch construction (`play-mode.ts`
+        // `installMultiWorldAuthoring` :341-347) over THIS sibling's own layer
+        // DOM root — no `<GameProvider>`/`ReactWorldHost` required.
+        new ReactWorldAuthoringAdapter(layer, store, {
+          ...(import.meta.env.DEV ? { writeBackend: createHttpSourceWriteBackend() } : {}),
+        })
+      : new ReactDomAuthoringAdapter(layer, store, {
+          overlay: await loadWorldOverlay<ReactDomOverlay>(world.id),
+          persist: (o) => saveWorldOverlay(world.id, o),
+          destination: worldOverlayPath(world.id),
+        });
+  }
+
+  return {
+    worldId: world.id,
+    ...(authoring ? { authoring } : {}),
+    dispose(): void {
+      // D-M3: both branches above self-register with the global undo
+      // timeline at construction (`registerUndoAdapter`, in each adapter's
+      // own constructor) — drop it here so any of its entries still on the
+      // global stack are dropped (with a warn) rather than misapplied to a
+      // torn-down layer, mirroring every other undo-registering adapter's
+      // teardown in this codebase (`disposeReactSession`/`disposeThreejsSession`
+      // in `ingest-mode.ts`, the scene-UI child's `UIEditStore` unregister
+      // in `edit-mode-authoring.ts`'s `exitEditModeAuthoring`).
+      if (authoring) unregisterUndoAdapter(authoring);
+      root.unmount();
+      layer.remove();
+    },
+  };
+}
+
+/**
+ * D-V4/D-B3: mount a `{ module }` sibling (any kind) OR a native
+ * `default-three`/`default-pixi` sibling through the SCOPED single-world
+ * runtime `module-mode.ts`'s `mountModuleWorldRuntime` provides — the exact
+ * resolve+mount `enterModuleModeWorldsPath` performs, reused here with NONE
+ * of that route's global side effects: no `setActiveAuthoring`/
+ * `setActiveSystems`, no viewport-tab switch, no `__vgaiModule` hook, no
+ * mount-failure-report clear. Mounts into its OWN layer div (never straight
+ * into the shared `gameContainer` the way the primary/single-world routes
+ * do) so its internal canvas/DOM stacking never collides with the ingest
+ * world's own canvas/DOM layer already in that container.
+ *
+ * `mountModuleWorldRuntime` is kind-agnostic BY CONSTRUCTION here, not just
+ * for `{ module }` adapters: it calls `resolveAllWorlds` with a ONE-element
+ * `worlds` array, and `resolveAllWorlds`'s `MULTI_WORLD_ALLOWED_IDENTITIES`
+ * scope guard only fires for `worlds.length > 1` — so `resolveWorldAdapter`'s
+ * full identity switch (including `default-three`/`default-pixi`) is reached
+ * directly, unmodified, with the guard never consulted (D-B3's ground-truth
+ * finding; `MULTI_WORLD_ALLOWED_IDENTITIES` itself stays byte-identical).
+ *
+ * D-B1: the returned `SiblingMount.setPaused` calls the scoped
+ * `GameSession.pause()`/`.resume()` `mountModuleWorldRuntime` hands back —
+ * the SAME honest, already-existing capability `play-mode.ts`'s own
+ * `pausePlayMode`/`resumePlayMode` call on the PRIMARY route's session
+ * (`create-runtime.ts`'s `Game.play.pause()`/`.resume()`, gated per
+ * `pausable` world within this scoped, single-world `Game`) — never a
+ * fabricated no-op.
+ *
+ * D-G1 (docs/WAVE9-SIBLING-PERSISTENCE-DOCTOR-DESIGN.md §1, closing the
+ * wave-8 residual this doc comment used to name): the mounted world's
+ * authoring surface converges with play-mode's own multi-world construction
+ * (`play-mode.ts`'s `installMultiWorldAuthoring`, verbatim per branch):
+ *  1. `mounted.authoring` present (a `{ module }` adapter that ships its own
+ *     surface, with its own persistence if any) — kept byte-for-byte,
+ *     store-selection-wrapped, exactly as before this slice. NEVER wrapped
+ *     in an editor overlay: the module's own choice wins.
+ *  2. Else `worldInstance.kind === 'threejs'` (a native `default-three`
+ *     sibling, or a `{ module }` sibling that mounted a threejs world with no
+ *     authoring of its own) — a real `IngestAuthoringAdapter` over
+ *     `worldInstance.threeRoot()`, with REAL `.vgai/overlays/<world-id>.json`
+ *     persistence (D-G2: the SAME overlay identity play-mode would use for
+ *     this same world id — one persisted document either route converges
+ *     on). D-G4: `loadWorldOverlay` already returns `{}` on miss/error — no
+ *     new swallowing added here.
+ *  3. Else `kind === 'pixijs'` — the pixijs analog through
+ *     `World2DAuthoringAdapter`, physics wired via
+ *     `createPhysicsAdapter2D(worldInstance.physics2d ??
+ *     createPhysics2DRegistry())` exactly like play-mode's own branch.
+ *  4. Else (no mounted.authoring, not a first-party-authorable kind) — the
+ *     named `makeEmbedOnlyAdapter` floor, unchanged.
+ * D-G3: `composite-authoring-adapter.ts`'s persistence routing (OR-dirty,
+ * per-child save, `' + '`-joined destinations) needs NO changes — once this
+ * function hands back an adapter with `capabilities.persist` +
+ * `persistence`, the composite's existing routing picks it up automatically.
+ */
+async function mountScopedRuntimeSibling(
+  manifest: ResolvedGameManifest,
+  world: ResolvedWorldEntry,
+  gameContainer: HTMLElement,
+  projectRoot: string,
+  store: EditorStore | undefined,
+): Promise<SiblingMount> {
+  const layer = document.createElement('div');
+  styleSiblingLayer(layer, world, 'auto');
+  gameContainer.appendChild(layer);
+
+  try {
+    const w = gameContainer.clientWidth || 800;
+    const h = gameContainer.clientHeight || 600;
+    const { session } = await mountModuleWorldRuntime(manifest, world, projectRoot, layer, w, h);
+    // D-G1: `session.game.worlds[0]` is the SAME `WorldInstance` shape
+    // play-mode iterates (`kind`, `threeRoot()`, `pixiRoot()`, `physics2d`) —
+    // a single-element `resolveAllWorlds` call always registers exactly one.
+    const worldInstance = session.game.worlds[0]!;
+    const mountedAuthoring = worldInstance.mounted.authoring;
+    let authoring: AuthoringAdapter | undefined;
+    if (store) {
+      if (mountedAuthoring) {
+        // D-E1 (byte-stable, docs/WAVE8-SIBLING-AUTHORING-DESIGN.md): the
+        // module's own surface (and its own persistence, if any) wins —
+        // never wrap an editor overlay around it.
+        authoring = withStoreSelection(mountedAuthoring, store);
+      } else if (worldInstance.kind === 'threejs') {
+        authoring = new IngestAuthoringAdapter(store, worldInstance.threeRoot(), {
+          overlay: await loadWorldOverlay<IngestOverlay>(worldInstance.id),
+          persist: (o) => saveWorldOverlay(worldInstance.id, o),
+          destination: worldOverlayPath(worldInstance.id),
+        });
+      } else if (worldInstance.kind === 'pixijs') {
+        const physics = createPhysicsAdapter2D(
+          worldInstance.physics2d ?? createPhysics2DRegistry(),
+        );
+        authoring = new World2DAuthoringAdapter(worldInstance.pixiRoot(), physics, store, {
+          overlay: await loadWorldOverlay<Overlay2D>(worldInstance.id),
+          persist: (o) => saveWorldOverlay(worldInstance.id, o),
+          destination: worldOverlayPath(worldInstance.id),
+        });
+      } else {
+        authoring = makeEmbedOnlyAdapter(store, `${world.id} (no authoring surface)`);
+      }
+    }
+    return {
+      worldId: world.id,
+      ...(authoring ? { authoring } : {}),
+      setPaused(paused: boolean): void {
+        if (paused) session.pause();
+        else session.resume();
+      },
+      dispose(): void {
+        session.stop();
+        layer.remove();
+      },
+    };
+  } catch (err) {
+    layer.remove();
+    throw err;
+  }
+}
+
+/**
+ * D-V7 (updated by D-B3): a sibling reaching here is neither `default-react`
+ * nor routable through the scoped runtime above (`{ module }` of any kind,
+ * or a native `default-three`/`default-pixi` world) — a genuinely unroutable
+ * shape. No such shape is known to exist today (every currently-resolvable
+ * adapter identity is handled above); this is a named, loud non-goal for a
+ * hypothetical future one, never silently ignored (the F24 anti-pattern) and
+ * never half-mounted. (A second `{ ingest }` world is structurally
+ * unreachable here — D-V2's route-level guard already fails the whole
+ * composite before any sibling loop runs.)
+ */
+function rejectUnmountableSibling(world: ResolvedWorldEntry): never {
+  throw new Error(
+    `sibling world "${world.id}" (kind: ${world.kind}, adapter identity: ` +
+      `"${world.adapter.identity}") has no known composite-sibling mount path — every ` +
+      'currently-resolvable identity (default-three/default-pixi/default-react/module) is ' +
+      'routed above; this is reached only for a genuinely unroutable shape ' +
+      '(docs/WAVE5-MULTIWORLD-INGEST-DESIGN.md D-V7, updated by docs/WAVE6-DOCTOR-DESIGN.md D-B3).',
+  );
+}
+
+async function mountOneIngestSibling(
+  manifest: ResolvedGameManifest,
+  world: ResolvedWorldEntry,
+  gameContainer: HTMLElement,
+  projectRoot: string,
+  store: EditorStore | undefined,
+): Promise<SiblingMount> {
+  if (
+    world.adapter.type === 'module' ||
+    world.adapter.identity === 'default-three' ||
+    world.adapter.identity === 'default-pixi'
+  ) {
+    return mountScopedRuntimeSibling(manifest, world, gameContainer, projectRoot, store);
+  }
+  if (world.adapter.identity === 'default-react') {
+    return mountDefaultReactSibling(world, gameContainer, projectRoot, store);
+  }
+  rejectUnmountableSibling(world);
+}
+
+/**
+ * D-V2: mount every world in `manifest.worlds` OTHER than the primary ingest
+ * world (`ingestWorldId`), in manifest order (already z-sorted by the
+ * loader). A failing sibling never unmounts the ingest world or stops the
+ * loop — it is caught, reported (D-V5's multi-entry mount-failure report,
+ * deduped by worldId), and the loop continues to the next sibling.
+ */
+export async function mountIngestSiblings(
+  manifest: ResolvedGameManifest,
+  ingestWorldId: string,
+  gameContainer: HTMLElement,
+  projectRoot: string,
+  // D-E1: optional ONLY so the one pre-existing direct caller
+  // (`ingest-composite-sibling-pause.test.ts`, which never inspects
+  // `SiblingMount.authoring`) keeps compiling/running unchanged — every
+  // production caller (`ingest-mode.ts`'s composite routes) supplies one.
+  store?: EditorStore,
+): Promise<SiblingMount[]> {
+  const mounted: SiblingMount[] = [];
+  for (const world of manifest.worlds) {
+    if (world.id === ingestWorldId) continue;
+    try {
+      mounted.push(await mountOneIngestSibling(manifest, world, gameContainer, projectRoot, store));
+    } catch (err) {
+      editorConsole.error(`Composite sibling "${world.id}" failed to mount: ${err}`, 'ingest');
+      addMountFailureReport({
+        worldId: world.id,
+        kind: world.kind,
+        identity: world.adapter.identity,
+        message: formatMountFailureMessage(err),
+      });
+    }
+  }
+  return mounted;
+}

package/src/initial-scene.ts

@@ -0,0 +1,194 @@
+import { resolveUrl } from '@engine/loader';
+import { parseSceneFile } from '@engine/scene/parse';
+import type { SceneFile } from '@engine/scene/scene-types';
+import { saveFile } from './editor-api';
+import { editorConsole } from './editor-console';
+import { getEditorMode } from './editor-mode';
+import type { EditorStore } from './editor-store';
+import {
+  type ActiveProject,
+  detectServerProject,
+  getCurrentProject,
+  getProjectPathFromURL,
+  openProject,
+} from './project-manager';
+import { getStorageBackend } from './storage';
+
+/** Detect the active project (from URL or server) and log the result. */
+export async function initProject(): Promise<void> {
+  // If the project manager already has a project (set by AppRoot/ProjectScreen),
+  // just log it and return — no need to re-detect.
+  const existing = getCurrentProject();
+  if (existing) {
+    editorConsole.log(`Opened project: ${existing.config.name}`, 'project');
+    return;
+  }
+
+  const projectPath = getProjectPathFromURL();
+  if (projectPath) {
+    try {
+      const project = await openProject(projectPath);
+      editorConsole.log(`Opened project: ${project.config.name}`, 'project');
+    } catch (err) {
+      editorConsole.error(`Failed to open project: ${err}`, 'project');
+    }
+  } else {
+    try {
+      const project = await detectServerProject();
+      if (project) {
+        editorConsole.log(`Opened project: ${project.config.name}`, 'project');
+      }
+    } catch {
+      // No server project — run without a project
+    }
+  }
+}
+
+/** A minimal empty scene — camera + a box to look at. Used both for the
+ *  "no scene declared" in-memory fallback and the "declared scene failed to
+ *  load" on-disk recovery fallback below. */
+function buildFallbackSceneDoc(): SceneFile {
+  return {
+    version: 1,
+    name: 'Untitled',
+    entities: [
+      {
+        name: 'Camera',
+        camera: { type: 'perspective' as const },
+        transform: { position: [0, 2, 5] as [number, number, number] },
+      },
+      {
+        name: 'Box',
+        mesh: { type: 'box' as const },
+        material: { type: 'standard' as const, color: '#888888' },
+      },
+    ],
+  };
+}
+
+/**
+ * A1 (`authoring/edit-mode-authoring.ts`): the scene path `loadInitialScene`
+ * WOULD resolve to, computed with NO I/O — used only to NAME the `scene`
+ * field of the single-world manifest synthesized for a manifest-less project,
+ * so that synthesized world is a faithful (if inert) description of what's
+ * actually loaded. Mirrors `loadInitialScene`'s resolution order exactly
+ * (`?scene=` URL param -> `ProjectConfig.defaultScene` -> legacy
+ * `'scenes/default.vscn.json'` fallback) but never fetches/loads/writes
+ * anything — `loadInitialScene` itself is UNTOUCHED by this addition and
+ * remains the only function that actually loads a scene into the store, so
+ * this can never drift into a second, competing load path.
+ */
+export function resolveInitialScenePathForManifestSynthesis(
+  project: ActiveProject | null,
+): string | null {
+  const sceneParam = new URLSearchParams(window.location.search).get('scene');
+  if (sceneParam) return sceneParam;
+  // A legal "no scene declared" project (§7.1-12, see `loadInitialScene`
+  // below) — an entry-only first world has no scene path to name.
+  if (project && !project.config.defaultScene) return null;
+  return project?.config.defaultScene ?? 'scenes/default.vscn.json';
+}
+
+/** Load the initial scene from URL param, project default, or create a fallback. */
+export async function loadInitialScene(store: EditorStore): Promise<void> {
+  const urlParams = new URLSearchParams(window.location.search);
+  const sceneUrl = urlParams.get('scene');
+  const project = getCurrentProject();
+
+  if (sceneUrl) {
+    try {
+      // Hosted example project (Track H): `?scene=` is PROJECT-RELATIVE —
+      // `resolveUrl` carries the `/examples/<id>/` prefix set at open — and
+      // loads READ-ONLY (no save path ⇒ autosave inert), since the staged
+      // example is not writable storage.
+      if (project?.exampleId && !sceneUrl.startsWith('/')) {
+        const res = await fetch(resolveUrl(sceneUrl));
+        if (!res.ok) {
+          throw new Error(`HTTP ${res.status} fetching ${sceneUrl}`);
+        }
+        store.loadDocument(parseSceneFile(await res.json()));
+        return;
+      }
+
+      const res = await fetch(resolveUrl(sceneUrl));
+      if (!res.ok) {
+        throw new Error(`HTTP ${res.status} fetching ${sceneUrl}`);
+      }
+      const doc = parseSceneFile(await res.json());
+      const savePath = sceneUrl.startsWith('/') ? sceneUrl.slice(1) : sceneUrl;
+      store.loadDocument(doc, savePath);
+      return;
+    } catch (err) {
+      editorConsole.error(`Failed to load scene from URL: ${err}`, 'scene');
+    }
+  }
+
+  // A KNOWN project (readProjectView resolved it — see project-view.ts) that
+  // declares NO scene at all (its `defaultScene` is explicit `null`, or —
+  // legacy `project.json` verbatim pass-through — the key is simply absent)
+  // is a legal shape (an entry-only first world). NEVER guess a path or probe
+  // the network for one here: that is exactly what silently WROTE a
+  // placeholder 'scenes/untitled.vscn.json' for a project the user never
+  // asked to persist anything into (§7.1-12). Build the fallback purely in
+  // memory and hand it to the store WITHOUT a save path — `loadDocument`
+  // sets `savePath` to `null` in that case, which makes `saveNow()`/autosave
+  // an inert no-op (`editor-store.ts`'s `if (!this._savePath || ...) return
+  // false`) until an explicit user save gives it a real, user-visible path.
+  if (project && !project.config.defaultScene) {
+    store.loadDocument(buildFallbackSceneDoc());
+    return;
+  }
+
+  // No project resolved at all (e.g. no project open) — preserve the
+  // pre-existing guess as the last resort for finding SOMETHING to load.
+  const defaultScenePath = project?.config.defaultScene ?? 'scenes/default.vscn.json';
+
+  // Browser-first build: scene files live in the in-browser VFS, not on an HTTP
+  // server, so read through the storage backend instead of fetch(). Bundled
+  // EXAMPLE projects are the exception — their scenes are static files staged
+  // under `/examples/<id>/`, fetched through the asset prefix and loaded
+  // READ-ONLY (no save path), same as the `?scene=` branch above.
+  if (getEditorMode() === 'browser') {
+    if (project?.exampleId) {
+      try {
+        const res = await fetch(resolveUrl(defaultScenePath));
+        if (!res.ok) {
+          throw new Error(`HTTP ${res.status} fetching ${defaultScenePath}`);
+        }
+        store.loadDocument(parseSceneFile(await res.json()));
+        return;
+      } catch (err) {
+        editorConsole.error(`Failed to load example scene: ${err}`, 'scene');
+        store.loadDocument(buildFallbackSceneDoc());
+        return;
+      }
+    }
+    try {
+      const doc = parseSceneFile(JSON.parse(await getStorageBackend().read(defaultScenePath)));
+      store.loadDocument(doc, defaultScenePath);
+      return;
+    } catch (err) {
+      editorConsole.error(`Failed to load scene from storage: ${err}`, 'scene');
+    }
+  }
+
+  try {
+    const res = await fetch(resolveUrl(`/${defaultScenePath}`));
+    if (res.ok) {
+      const doc = parseSceneFile(await res.json());
+      store.loadDocument(doc, defaultScenePath);
+      return;
+    }
+  } catch {
+    // Default scene not found — fall through to fallback
+  }
+
+  // Fallback: create a minimal scene. Reached only when a scene path WAS
+  // resolved (declared, or guessed because no project was known at all) but
+  // failed to load — pre-existing recovery behavior, unchanged: persist a
+  // fresh untitled scene so there is something to edit and save.
+  const fallbackDoc = buildFallbackSceneDoc();
+  const fallbackPath = 'scenes/untitled.vscn.json';
+  await saveFile(fallbackPath, JSON.stringify(fallbackDoc, null, 2));
+  store.loadDocument(fallbackDoc, fallbackPath);
+}