@vgai/editor 0.2.0

package/src/authoring/mount-failure-report.ts

@@ -0,0 +1,112 @@
+/**
+ * Mount-failure report — D-W3 (docs/WAVE4-FTUE-HARDENING-DESIGN.md §D-W3,
+ * F9): every manifest world's auto-launch route degrades to exactly one
+ * `editorConsole.error` line today (§0.4 — ground truth: the console panel
+ * isn't even the default bottom tab, and the default Untitled scene is
+ * already showing by the time a manifest route fails, so a broken world
+ * mounts to what LOOKS like a normal empty project). This module is the
+ * loud, structured half of the fix: a global "last mount failure" slot every
+ * manifest-route catch block populates, that a dismissible banner
+ * (`../components/MountFailureBanner.tsx`) reads.
+ *
+ * D-V5 (docs/WAVE5-MULTIWORLD-INGEST-DESIGN.md, F24 composite): a composite
+ * manifest (one ingest world + siblings, `ingest-siblings.ts`) can fail
+ * SEVERAL worlds independently in one mount attempt (a `default-three`
+ * sibling, a throwing `default-react` sibling, …) — a single-slot "last
+ * failure wins" model would silently drop every failure but the latest, the
+ * exact F9 anti-pattern this module exists to close. This generalizes the
+ * single slot to an ORDERED LIST (`addMountFailureReport`, deduped by
+ * `worldId` — a re-attempt for the SAME world replaces that world's entry in
+ * place, keeping list order stable — and `getMountFailureReports()`), while
+ * freezing the ORIGINAL single-slot surface byte-for-byte for every existing
+ * (wave-4) call site: `setMountFailureReport(report)` still means "replace
+ * EVERYTHING with this one entry", `setMountFailureReport(null)` still means
+ * "clear everything", and `getMountFailureReport()` still returns the LAST
+ * entry (or `null`) — so no wave-4 caller or test needed to change meaning
+ * when this module gained multi-entry support.
+ *
+ * Same plain module-level-singleton shape as `./overlay-report.ts`'s
+ * "current report" slot (that file's header comment has the full rationale
+ * for why a bare get/set needs no subscribe of its own): the banner
+ * re-renders off `EditorStore.subscribe`, which `ingest-mode.ts`/
+ * `module-mode.ts` already broadcast via `store.notifyIngestEdit()` right
+ * after every successful mount — and a FAILED mount still runs inside the
+ * same routing functions that call `store.notifyIngestEdit()` on the
+ * success path, so the store is always live and subscribed-to by the time a
+ * route's catch block runs. No new broadcast channel needed.
+ */
+
+/** One manifest world's mount failure — the exact fields the banner shows. */
+export interface MountFailureReport {
+  /** The failing world's manifest id (`ResolvedWorldEntry.id`), or the
+   *  `?ingest=<id>` URL-fallback route's discovered game/folder id. */
+  readonly worldId: string;
+  /** The world's render substrate kind (`ResolvedWorldEntry.kind`, e.g.
+   *  `'threejs'`/`'pixijs'`/`'react'`) — or, for the URL-fallback route
+   *  (which has no `ResolvedWorldEntry` to read a kind from), the same
+   *  vocabulary inferred from which fixture glob resolved the id. */
+  readonly kind: string;
+  /** The resolved adapter identity (`ResolvedAdapter['identity']` — e.g.
+   *  `'ingest-three'`/`'ingest-pixi'`/`'ingest-react'`/`'module'`). */
+  readonly identity: string;
+  /** The caught error's message — never the raw `Error` object (never
+   *  fabricated; empty only if the thrown value truly stringifies empty). */
+  readonly message: string;
+}
+
+/** D-V5: an ORDERED list now backs the slot (insertion order — the order
+ *  worlds actually failed in, which for a composite's sibling loop is
+ *  manifest order). Every existing (wave-4) accessor below is a thin view
+ *  over this same array — never a second, parallel source of truth. */
+let _reports: MountFailureReport[] = [];
+
+/**
+ * D-V5: append one world's failure, deduped by `worldId` — a re-attempt for
+ * a world that already has an entry REPLACES it in place (keeps list order
+ * stable: retrying world B in `[A, B]` yields `[A, B']`, never `[A, B]` moved
+ * to the end). The multi-entry sibling-mount surface
+ * (`MountFailureBanner`/`getMountFailureReports`) reads this.
+ */
+export function addMountFailureReport(report: MountFailureReport): void {
+  const index = _reports.findIndex((r) => r.worldId === report.worldId);
+  if (index === -1) {
+    _reports.push(report);
+  } else {
+    _reports[index] = report;
+  }
+}
+
+/** D-V5: every mount failure from the current attempt, oldest first. */
+export function getMountFailureReports(): readonly MountFailureReport[] {
+  return _reports;
+}
+
+/**
+ * BACK-COMPAT FROZEN (D-V5): every existing (wave-4) call site's meaning is
+ * unchanged — `report` REPLACES the entire list with that one entry;
+ * `null` clears it. Composite routes that can fail more than one world use
+ * {@link addMountFailureReport} instead; single-world routes (unmodified
+ * this wave) keep calling this exactly as before.
+ */
+export function setMountFailureReport(report: MountFailureReport | null): void {
+  _reports = report ? [report] : [];
+}
+
+/** BACK-COMPAT FROZEN (D-V5): the LAST entry (wave-4's "latest failure
+ *  wins" semantics), or `null` when the list is empty. New callers that want
+ *  every failure should read {@link getMountFailureReports} instead. */
+export function getMountFailureReport(): MountFailureReport | null {
+  return _reports.length > 0 ? _reports[_reports.length - 1]! : null;
+}
+
+/**
+ * Build a `MountFailureReport['message']` from a caught value the same way
+ * every route's existing `editorConsole.error` line already stringifies it
+ * (`` `...failed: ${err}` `` — kept byte-for-byte at each call site so the
+ * console's full trace is unchanged) — an `Error`'s own `.message` reads
+ * better in a one-line banner than its `String(err)` form (`"Error: <msg>"`),
+ * so the banner uses this instead of the console's template-literal form.
+ */
+export function formatMountFailureMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}

package/src/authoring/overlay-report.ts

@@ -0,0 +1,52 @@
+/**
+ * Overlay apply report — D9 (docs/DECISIONS-PENDING.md §D9): decide + surface
+ * what happens when a saved ingest overlay is reapplied onto a scene that may
+ * have moved on since the overlay was authored (a vendored game bump, or a
+ * dynamic subtree that never respawned).
+ *
+ * The report TYPE + pure build/format/log helpers moved engine-side (T3.8) —
+ * `@engine/adapter/ingest/overlay-report.ts` is now the canonical, dependency-
+ * free module (its header has the full design rationale); this file
+ * re-exports them unchanged so every existing import site here keeps working
+ * byte-for-byte, and adds the one genuinely editor-only piece: the reactive
+ * "active report" slot the ingest hierarchy's inline banner reads.
+ */
+
+import {
+  buildOverlayApplyReport,
+  formatOverlayApplyReportMessage,
+  logOverlayApplyReport,
+  OVERLAY_REPORT_PREFIX,
+  type OverlayApplyReport,
+  overlayReportWarrants,
+} from '@engine/adapter/ingest/overlay-report';
+
+export {
+  buildOverlayApplyReport,
+  formatOverlayApplyReportMessage,
+  logOverlayApplyReport,
+  OVERLAY_REPORT_PREFIX,
+  overlayReportWarrants,
+  type OverlayApplyReport,
+};
+
+// ---------------------------------------------------------------------------
+// Reactive "current report" slot for the editor's inline banner (design §5).
+// A plain module-level singleton — same shape as `./active-systems.ts`'s
+// `setActiveSystems`/`getActiveSystems`. The banner component re-renders off
+// the SAME `store.notifyIngestEdit()` broadcast `ingest-mode.ts` already
+// fires right after install, so this slot needs no separate subscribe/notify
+// of its own.
+// ---------------------------------------------------------------------------
+
+let _current: OverlayApplyReport | null = null;
+
+/** Install (or clear, with `null`) the report for the ingest session the UI banner reads. */
+export function setActiveOverlayReport(report: OverlayApplyReport | null): void {
+  _current = report;
+}
+
+/** The active ingest session's overlay report, or `null` (no session / nothing to report). */
+export function getActiveOverlayReport(): OverlayApplyReport | null {
+  return _current;
+}

package/src/authoring/project-scenes.ts

@@ -0,0 +1,111 @@
+/**
+ * Project scene-file discovery (A4, D8 — docs/unified-world-editor/
+ * 26-unified-editor-spec.md §2 A4). Every `*.vscn.json` under the project is a
+ * potential hierarchy root; `VgaiSceneAuthoringAdapter.rootGroups` needs the
+ * full list to build its "Scenes" radio group.
+ *
+ * `RootGroupsProvider.groups()` is SYNCHRONOUS (the contract), so this module
+ * fetches the list ONCE, caches it at MODULE scope, and lets a caller register
+ * a callback to run when the async result actually lands (the adapter passes
+ * `store.notifyIngestEdit`, so the hierarchy panel re-renders once the list
+ * arrives instead of showing an empty group forever).
+ *
+ * The module-scope cache is deliberately shared, not per-adapter-instance:
+ * `active-adapter.ts` memoizes ONE bare `VgaiSceneAuthoringAdapter` per store,
+ * but `edit-mode-authoring.ts`'s composite construction builds its OWN
+ * SEPARATE `VgaiSceneAuthoringAdapter` instance for the focused world — a
+ * per-instance cache would mean two independent fetches (and, in principle,
+ * two different in-flight results racing each other) for the exact same
+ * project. A single module-scope cache means both agree, and only one fetch
+ * ever goes out per project session.
+ *
+ * Browser-mode floor: no `/__editor/*` server exists, so this recursively
+ * walks the active `StorageBackend` (OPFS/File-System-Access) instead —
+ * mirrors the server's own `findFiles` recursive walk, just through the
+ * backend-agnostic seam instead of `node:fs`.
+ */
+
+import { getEditorMode } from '../editor-mode';
+import { getStorageBackend } from '../storage';
+
+let cache: string[] | null = null;
+let pending: Promise<string[]> | null = null;
+const pendingListeners = new Set<() => void>();
+
+/** Synchronous cached read — `[]` until the first load resolves. */
+export function getCachedProjectScenes(): string[] {
+  return cache ?? [];
+}
+
+/**
+ * Kick off (idempotently) loading the project's `*.vscn.json` list. Safe to
+ * call on every render/every `rootGroups.groups()` call: a no-op once
+ * cached, and de-dupes a fetch already in flight. `onLoaded` fires exactly
+ * once, only for a call that actually had to wait (never for an
+ * already-cached read, and never more than once per registered listener).
+ */
+export function ensureProjectScenesLoaded(onLoaded: () => void): void {
+  if (cache !== null) return;
+  pendingListeners.add(onLoaded);
+  if (pending) return;
+  pending = fetchProjectScenes()
+    .then((scenes) => {
+      cache = scenes;
+      return scenes;
+    })
+    .finally(() => {
+      pending = null;
+      const listeners = [...pendingListeners];
+      pendingListeners.clear();
+      for (const l of listeners) l();
+    });
+}
+
+/**
+ * Drop the cached list. Not currently wired into any production project-open
+ * path (every existing call site re-navigates the page on project switch, so
+ * the module cache always starts fresh for a new session) — exported for
+ * tests and as the correct hook for a future in-session project-switch flow.
+ */
+export function resetProjectScenesCache(): void {
+  cache = null;
+  pending = null;
+  pendingListeners.clear();
+}
+
+async function fetchProjectScenes(): Promise<string[]> {
+  return getEditorMode() === 'browser' ? listFromStorageBackend() : listFromServer();
+}
+
+async function listFromServer(): Promise<string[]> {
+  try {
+    const res = await fetch('/__editor/scenes');
+    if (!res.ok) return [];
+    const data = (await res.json()) as { scenes?: unknown };
+    return Array.isArray(data.scenes)
+      ? data.scenes.filter((s): s is string => typeof s === 'string')
+      : [];
+  } catch {
+    return [];
+  }
+}
+
+async function listFromStorageBackend(): Promise<string[]> {
+  const backend = getStorageBackend();
+  const results: string[] = [];
+  const walk = async (dir: string): Promise<void> => {
+    let entries: Awaited<ReturnType<typeof backend.list>>;
+    try {
+      entries = await backend.list(dir);
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      if (e.name.startsWith('.')) continue;
+      if (e.type === 'dir') await walk(e.path);
+      else if (e.name.endsWith('.vscn.json')) results.push(e.path);
+    }
+  };
+  await walk('');
+  return results.sort();
+}