@vgai/editor 0.2.0

package/src/authoring/root-activation.ts

@@ -0,0 +1,61 @@
+/**
+ * D8 root activation — the SHARED dirty-gate choke point (A4,
+ * docs/unified-world-editor/26-unified-editor-spec.md §2 A4). Both
+ * `GameHierarchy`'s radio-row double-click and the asset-browser's scene
+ * double-click (`DefaultEditorLayout.tsx`'s `handleOpenScene`) call
+ * {@link requestRootActivation} instead of `adapter.rootGroups.activate()`
+ * directly, so the confirmation UX can never drift between the two call
+ * sites (map §4).
+ *
+ * `window.confirm()` is banned (editor-wide convention — see CLAUDE.md's
+ * "Dialogs" note): adapters can't render UI at all, and the shell must not
+ * block synchronously either. When the active adapter is dirty, this
+ * dispatches a `window` `CustomEvent` (the same decoupling pattern
+ * `first-party-hierarchy-menu.ts` already uses for
+ * `editor:save-as-prefab`/`editor:open-asset`) for `DefaultEditorLayout` to
+ * show {@link RootActivateDialog} and perform the actual activation only once
+ * the user confirms. When the adapter is NOT dirty, this activates
+ * immediately — no dialog, no round trip, no race.
+ */
+
+import type { AuthoringAdapter } from '@engine/adapter';
+
+export interface RootActivationRequest {
+  readonly groupId: string;
+  readonly rootId: string;
+  /** Display label for the confirmation dialog — resolved by THIS module via
+   *  `hierarchy.node(rootId)?.label` so callers never need to format one
+   *  themselves (and never need to know the id's shape). */
+  readonly label: string;
+}
+
+export const ROOT_ACTIVATION_REQUEST_EVENT = 'editor:request-root-activation';
+
+/**
+ * Request activating `rootId` within `groupId` on `adapter`. Dirty-gates
+ * through a shell-rendered confirmation dialog; otherwise activates directly.
+ */
+export function requestRootActivation(
+  adapter: AuthoringAdapter,
+  groupId: string,
+  rootId: string,
+): void {
+  if (adapter.persistence?.isDirty()) {
+    const label = adapter.hierarchy.node(rootId)?.label ?? rootId;
+    window.dispatchEvent(
+      new CustomEvent(ROOT_ACTIVATION_REQUEST_EVENT, {
+        detail: { groupId, rootId, label } satisfies RootActivationRequest,
+      }),
+    );
+    return;
+  }
+  void adapter.rootGroups?.activate(groupId, rootId);
+}
+
+/** Find the `RootGroup` (of `adapter`'s own `rootGroups`) that owns `rootId`,
+ *  or `null` if none does. Shared by the asset-browser reroute and any other
+ *  caller that only has a root id, not the owning group id, in hand. */
+export function findOwningRootGroupId(adapter: AuthoringAdapter, rootId: string): string | null {
+  const group = adapter.rootGroups?.groups().find((g) => g.memberRootIds.includes(rootId));
+  return group?.id ?? null;
+}

package/src/authoring/scene-ui-layer.ts

@@ -0,0 +1,485 @@
+/**
+ * Scene-UI design-time layer (C3, docs/unified-world-editor/26-unified-
+ * editor-spec.md §4 C3) — the box-model overlay + stage guides "in the
+ * normal viewport" the spec calls for, replacing the retired standalone
+ * UI-edit mode's fullscreen `#ui-edit-mode-layer`. Sibling of
+ * `design-time-layers.ts`, but
+ * mounts the scene-UI composite child (`edit-mode-authoring.ts`'s `kind:
+ * 'scene-ui'` child) instead of a react/pixi world: that child already
+ * carries a LIVE `UIAuthoringAdapter` at composite-install time (there is no
+ * Boundary-to-live upgrade dance here, unlike react/pixi) — this module only
+ * gives it a DOM layer, a pick surface (D12/B4), and keeps the shared
+ * `EditorStore` and the child's own `UIEditStore` in lockstep.
+ *
+ * Reuses EVERY existing building block — no new UI runtime, no fork:
+ *  - `SceneUITree` (the exact runtime that renders at game-time) in `editMode`.
+ *  - `SelectionOverlay` (`ui-editor/overlay.tsx`) — hover/selection/marquee/
+ *    resize boxes + the `Measure` spacing guide — IS the box-model overlay;
+ *    it renders boxes only while `store.selection` is non-empty, so it
+ *    "activates contextually on UI-node selection" for free.
+ *  - `UIAuthoringAdapter.pickable` (added by C3) backed by `hitTest`
+ *    (`ui-editor/react-store.ts`), the same geometric primitive the overlay
+ *    itself uses for hover/click.
+ */
+
+import type { UIRoot } from '@engine/scene/schema';
+import type { UIAnimationController } from '@vgai/scene-ui/animation';
+import { SceneUITree } from '@vgai/scene-ui/mount';
+import type { ProjectUIRegistry } from '@vgai/scene-ui/registry';
+import { createElement, useEffect, useRef, useState } from 'react';
+import { createRoot } from 'react-dom/client';
+import {
+  getCachedProjectUIRegistry,
+  loadProjectUIRegistry,
+  setCachedProjectUIRegistry,
+} from '../adapter-resolver';
+import type { EditorStore } from '../editor-store';
+import { getCurrentProject } from '../project-manager';
+import { findNode } from '../ui-editor/node-ops';
+import { SelectionOverlay } from '../ui-editor/overlay';
+import { useUIStore } from '../ui-editor/react-store';
+import type { UIEditStore } from '../ui-editor/ui-edit-store';
+import type { UIAuthoringAdapter } from './ui-authoring-adapter';
+import { isWorldHidden, isWorldInteractive } from './world-session-state';
+
+/** Container-ish UI kinds (mirrors `ui-editor/palette.tsx`'s own unexported
+ *  `isContainer` — a project-registry component insert (below) targets the
+ *  primary selection when it's one of these, else the first root, exactly
+ *  like the harness palette's own "add under selected container" rule. */
+const CONTAINER_KINDS = new Set([
+  'canvas',
+  'box',
+  'grid',
+  'stack',
+  'scroll',
+  'panel',
+  'center',
+  'wrap',
+  'aspect',
+  'sizebox',
+  'tab',
+]);
+
+/** Pure (DOM-free) equality check for the R3 echo guard — exported for unit
+ *  testing without a browser: `uiStore.onCommit -> store.setSceneUI -> store
+ *  notify -> this module's sync sees "changed" -> uiStore.load()` would wipe
+ *  selection + undo after every edit unless the sync SKIPS a no-op round
+ *  trip (the just-committed content already matches). */
+export function sceneUIChanged(a: readonly UIRoot[], b: readonly UIRoot[]): boolean {
+  return JSON.stringify(a) !== JSON.stringify(b);
+}
+
+/**
+ * The content-sync decision for the viewport layer's `EditorStore`
+ * subscription (C3 skeptic fix): reload the UI child from the committed
+ * document ONLY when it genuinely diverged AND no interactive gesture owns the
+ * preview `_roots`. During a live drag/resize `uiStore.serialize()` reflects
+ * uncommitted preview state, so `sceneUIChanged` is true and a naive reload
+ * would revert the drag and wipe selection/local-undo mid-motion (reachable
+ * whenever any `EditorStore` notify — e.g. the previous commit's async
+ * autosave — lands inside the gesture window). `endEdit()` commits through
+ * `setSceneUI`, after which content matches and no reload is needed. Exported
+ * so the wiring in `mountSceneUILayer` is unit-testable against a real
+ * `UIEditStore`'s gesture state (the subscription closure otherwise is not).
+ */
+export function shouldReloadUIChild(
+  sceneUI: readonly UIRoot[],
+  uiStore: Pick<UIEditStore, 'inGesture' | 'serialize'>,
+): boolean {
+  return !uiStore.inGesture && sceneUIChanged(sceneUI, uiStore.serialize());
+}
+
+/** E1 "lose nothing" migration (§8 "board-state/responsive/locale preview") —
+ *  the harness's fixed-resolution device presets (`UIEditor.tsx`'s
+ *  `RES_PRESETS`/`I3`), ported verbatim so the unified editor's scene-UI
+ *  chrome doesn't drop the responsive-preview affordance. `fit` (the default)
+ *  keeps today's full-bleed `inset:0` stage untouched — only picking an
+ *  explicit preset switches the stage to a centered, fixed-size box. */
+const RES_PRESETS: Record<string, { width: number; height: number } | null> = {
+  fit: null,
+  '1920×1080': { width: 1920, height: 1080 },
+  '1280×720': { width: 1280, height: 720 },
+  '375×812 (phone)': { width: 375, height: 812 },
+};
+
+/** Fit a fixed preset's ASPECT into a capped display box (verbatim from
+ *  `UIEditor.tsx`) so a resolution preview never clips against the
+ *  design-time layer's own (usually much larger) bounds. */
+function fitDisplaySize(res: { width: number; height: number }): { width: number; height: number } {
+  const maxW = 960;
+  const maxH = 560;
+  const s = Math.min(maxW / res.width, maxH / res.height, 1);
+  return { width: Math.round(res.width * s), height: Math.round(res.height * s) };
+}
+
+function createStageLayer(container: HTMLElement, worldId: string, zIndex: number): HTMLElement {
+  const layer = document.createElement('div');
+  layer.dataset['worldId'] = worldId;
+  layer.style.position = 'absolute';
+  layer.style.top = '0';
+  layer.style.left = '0';
+  layer.style.width = '100%';
+  layer.style.height = '100%';
+  layer.style.zIndex = String(zIndex);
+  layer.style.display = isWorldHidden(worldId) ? 'none' : 'block';
+  // B1 semantics: `pointer-events:none` at rest — plain click-select goes
+  // through B4 (`layered-pick.ts`, via `UIAuthoringAdapter.pickable`)
+  // instead, so the overlay's own drag/resize/marquee handlers only need to
+  // receive real pointer events while the layer's `interactive` toggle is on.
+  layer.style.pointerEvents = isWorldInteractive(worldId) ? 'auto' : 'none';
+  container.appendChild(layer);
+  return layer;
+}
+
+interface SceneUILayerRootProps {
+  uiStore: UIEditStore;
+  projectRoot: string | undefined;
+  /** E1.b — the child's ONE animation controller, owned by `UIAuthoringAdapter`
+   *  (shared with the timeline panel, `scene-ui-mode/scene-ui-timeline-tab.tsx`)
+   *  instead of a `useMemo`'d local instance — see that adapter field's doc
+   *  comment for why the two mounts must share one instance. */
+  anim: UIAnimationController;
+}
+
+/** The stage + overlay, composed exactly like `UIEditor.tsx`'s center stage
+ *  (`:259-283`), minus the chrome — plus a project-registry load (§3.3),
+ *  mirroring the retired standalone UI-edit mode's own registry resolution
+ *  (components/strings/states) without its demo-fixture fallback branch
+ *  (dropped by design, Q3). */
+function SceneUILayerRoot({ uiStore, projectRoot, anim }: SceneUILayerRootProps): React.ReactNode {
+  useUIStore(uiStore);
+  const stageRef = useRef<HTMLDivElement>(null);
+  const [registry, setRegistry] = useState<ProjectUIRegistry | null>(() =>
+    getCachedProjectUIRegistry(),
+  );
+  // I3/G5 "lose nothing" migration — resolution/locale preview (see
+  // `RES_PRESETS`'s doc comment above); session-local UI state (not
+  // persisted), same as the harness toolbar's own `useState`.
+  const [resKey, setResKey] = useState('fit');
+  const previewRes = RES_PRESETS[resKey] ?? null;
+  const display = previewRes ? fitDisplaySize(previewRes) : null;
+
+  // E1.R2 review follow-up: this used to also call `uiStore.setPreviewResolution
+  // (previewRes)` on every `previewRes` change. `UIEditStore.previewResolution`
+  // (the field that write feeds) has ZERO readers anywhere in the repo — the
+  // stage resize below is driven entirely by the LOCAL `display`/`resKey` React
+  // state, never by that store field — so the write was dead-ported state left
+  // over from the harness (`UIEditor.tsx`, which still calls it, unreviewed
+  // here) and has been dropped rather than pinned by a test that could never
+  // observe anything.
+
+  useEffect(() => {
+    if (!projectRoot) return;
+    let cancelled = false;
+    void loadProjectUIRegistry(projectRoot).then((r) => {
+      // Cache regardless of the registry's outcome (present/absent/broken) —
+      // the SAME cache slot the broken-registry loud warn reads from
+      // (`adapter-resolver.ts`), preserving 24-ui-registry's assertion.
+      setCachedProjectUIRegistry(r);
+      if (cancelled) return;
+      setRegistry(r);
+      if (r?.states) {
+        for (const [name, data] of Object.entries(r.states)) uiStore.defineState(name, data);
+        // 'default' (else the first entry) seeds the binding preview — same
+        // resolution order the retired standalone UI-edit mode used.
+        const first = r.states['default'] ? 'default' : Object.keys(r.states)[0];
+        if (first) uiStore.loadState(first);
+      }
+    });
+    return () => {
+      cancelled = true;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- one-shot load per mount
+  }, [projectRoot]);
+
+  // Board-state switching (C12) — a minimal always-on strip (NOT the richer
+  // harness toolbar, `UIEditor.tsx`'s `state-${s}` buttons, which stays
+  // harness-only): the registry's named states need SOME surface in the
+  // unified editor so a binding preview is actually reachable, per §6's
+  // "24-ui-registry" testing note. Kept `pointer-events: auto` explicitly —
+  // out of the B1 `interactive` toggle's scope (that gates the SelectionOverlay's
+  // drag/resize/marquee, spec-27 Phase B/C/D territory; a state switcher is a
+  // small, always-on affordance, not that).
+  const stateNames = registry?.states ? Object.keys(registry.states) : [];
+  const stateStrip =
+    stateNames.length > 0
+      ? createElement(
+          'div',
+          {
+            'data-testid': 'scene-ui-states',
+            style: {
+              position: 'absolute',
+              top: 0,
+              left: 0,
+              zIndex: 20,
+              display: 'flex',
+              gap: 4,
+              padding: 4,
+              pointerEvents: 'auto',
+            },
+          },
+          ...stateNames.map((name) =>
+            createElement(
+              'button',
+              {
+                key: name,
+                'data-testid': `scene-ui-state-${name}`,
+                onClick: () => uiStore.loadState(name),
+                style: { fontSize: 10 },
+              },
+              name,
+            ),
+          ),
+        )
+      : null;
+
+  // Registry-component insertion — a minimal always-on strip, same rationale
+  // as the state strip above: `structure.creatableKinds` (the hierarchy's
+  // "Create ▸" menu) only knows the fixed built-in kinds (`CREATABLE_KINDS`,
+  // `ui-authoring-adapter.ts`), never a project's OWN named registry
+  // components — inserting one needs SOME surface (the harness has none
+  // either; both a project registry AND a component-insert UI are new to
+  // this task). Targets the primary selection when it's a container, else
+  // the first root — the same rule `ui-editor/palette.tsx`'s own `add` uses.
+  const componentNames = registry?.components ? Object.keys(registry.components) : [];
+  const componentStrip =
+    componentNames.length > 0
+      ? createElement(
+          'div',
+          {
+            'data-testid': 'scene-ui-components',
+            style: {
+              position: 'absolute',
+              top: 0,
+              right: 0,
+              zIndex: 20,
+              display: 'flex',
+              gap: 4,
+              padding: 4,
+              pointerEvents: 'auto',
+            },
+          },
+          ...componentNames.map((name) =>
+            createElement(
+              'button',
+              {
+                key: name,
+                'data-testid': `scene-ui-insert-${name}`,
+                onClick: () => {
+                  const primary = uiStore.primary;
+                  const primaryLoc = primary ? findNode(uiStore.roots, primary) : null;
+                  const parentId =
+                    primaryLoc && CONTAINER_KINDS.has(primaryLoc.node.kind)
+                      ? primary!
+                      : ((uiStore.roots[0]?.id as string | undefined) ?? null);
+                  if (parentId) {
+                    uiStore.addNodeValue(parentId, { kind: 'component', name, component: name });
+                  }
+                },
+                style: { fontSize: 10 },
+              },
+              name,
+            ),
+          ),
+        )
+      : null;
+
+  // I3/G5 — a minimal always-on strip for the responsive/locale preview
+  // (§8's "board-state/responsive/locale preview" MIGRATE row), same
+  // rationale/placement discipline as `stateStrip`/`componentStrip` above:
+  // the harness's richer toolbar (`UIEditor.tsx`'s `tb-res`/`tb-locale`)
+  // stays harness-only; the unified editor needs SOME surface so the
+  // affordance isn't silently dropped. Locale options come from the
+  // registry's own `strings` tables — the same source the harness reads
+  // (`Object.keys(strings ?? { en: {} })`).
+  const localeNames = registry?.strings ? Object.keys(registry.strings) : ['en'];
+  const previewStrip = createElement(
+    'div',
+    {
+      'data-testid': 'scene-ui-preview-controls',
+      style: {
+        position: 'absolute',
+        top: 0,
+        left: '50%',
+        transform: 'translateX(-50%)',
+        zIndex: 20,
+        display: 'flex',
+        gap: 4,
+        padding: 4,
+        pointerEvents: 'auto',
+      },
+    },
+    createElement(
+      'select',
+      {
+        'data-testid': 'scene-ui-res-preset',
+        value: resKey,
+        onChange: (e: React.ChangeEvent<HTMLSelectElement>) => setResKey(e.target.value),
+        style: { fontSize: 10 },
+      },
+      ...Object.keys(RES_PRESETS).map((k) => createElement('option', { key: k, value: k }, k)),
+    ),
+    createElement(
+      'select',
+      {
+        'data-testid': 'scene-ui-locale',
+        value: uiStore.locale,
+        onChange: (e: React.ChangeEvent<HTMLSelectElement>) => uiStore.setLocale(e.target.value),
+        style: { fontSize: 10 },
+      },
+      ...localeNames.map((l) => createElement('option', { key: l, value: l }, l)),
+    ),
+  );
+
+  return createElement(
+    'div',
+    {
+      // Default ('fit', `display === null`) — an unchanged full-bleed box
+      // (byte-identical to pre-migration layout: `position:absolute;inset:0`
+      // containing a 100%x100% stage, no flex). A picked preset instead
+      // centers the fixed-size stage box within the same full-bleed area.
+      style: display
+        ? {
+            position: 'absolute',
+            inset: 0,
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+          }
+        : { position: 'absolute', inset: 0 },
+    },
+    createElement(
+      'div',
+      {
+        ref: stageRef,
+        'data-ui-stage': true,
+        style: display
+          ? {
+              position: 'relative',
+              width: display.width,
+              height: display.height,
+              outline: '1px dashed #4a90d9',
+            }
+          : { position: 'relative', width: '100%', height: '100%' },
+      },
+      createElement(SceneUITree, {
+        roots: uiStore.roots,
+        data: uiStore.data,
+        components: registry?.components,
+        strings: registry?.strings,
+        locale: uiStore.locale,
+        editMode: true,
+        viewportOverride: display ?? undefined,
+        anim,
+      }),
+      createElement(SelectionOverlay, { store: uiStore, stageRef }),
+    ),
+    stateStrip,
+    componentStrip,
+    previewStrip,
+  );
+}
+
+/**
+ * Mount the scene-UI design-time layer for `worldId` (the composite's
+ * `scene-ui` child) into `container` (`ViewportPanel`'s own container — the
+ * same one `design-time-layers.ts`'s react/pixi layers use). Returns a
+ * disposer. Call it once per composite install; `design-time-layers.ts`'s
+ * `mountDesignTimeLayers` is the one production call site.
+ */
+export function mountSceneUILayer(
+  container: HTMLElement,
+  worldId: string,
+  uiAdapter: UIAuthoringAdapter,
+  store: EditorStore,
+  zIndex: number,
+): () => void {
+  const projectRoot = getCurrentProject()?.rootPath;
+  const uiStore = uiAdapter.uiStore;
+  const layer = createStageLayer(container, worldId, zIndex);
+  uiAdapter.attachPickSurface(layer);
+
+  const root = createRoot(layer);
+  root.render(createElement(SceneUILayerRoot, { uiStore, projectRoot, anim: uiAdapter.anim }));
+
+  // R3 (echo guard) + R4-adjacent selection bridge: `uiStore.select()` can be
+  // reached WITHOUT going through `UIAuthoringAdapter.selection.set` (e.g.
+  // `SelectionOverlay`'s own click handler, `UIEditStore.addNode`'s
+  // auto-select) — mirroring `uiStore.selection` outward keeps the SHARED
+  // `EditorStore.selectedEntityIds` (what `Inspector.tsx`/`GameHierarchy`
+  // read) in lockstep no matter which surface drove the change. `suppressing`
+  // breaks the two-way ping-pong: each direction's write happens INSIDE the
+  // flag, so the other direction's listener (which fires synchronously,
+  // re-entrantly) sees it set and no-ops.
+  let suppressing = false;
+  let lastMirroredUiSelectionKey = uiStore.selection.join('\u0000');
+
+  const unsubUI = uiStore.subscribe(() => {
+    if (suppressing) return;
+    const key = uiStore.selection.join('\u0000');
+    if (key === lastMirroredUiSelectionKey) return;
+    lastMirroredUiSelectionKey = key;
+    suppressing = true;
+    try {
+      store.selectMultiple(uiStore.selection);
+    } finally {
+      suppressing = false;
+    }
+  });
+
+  const unsubStore = store.subscribe(() => {
+    // C9 content sync — external changes (undo/redo of the whole document,
+    // scene switch) reload the UI child; the equality check IS the R3 guard
+    // against the commit echo (`onCommit -> setSceneUI -> notify -> here`
+    // sees the just-committed content already matches, skips `load()`).
+    //
+    // The `inGesture` gate is the C3 skeptic fix: during a live drag/resize,
+    // `uiStore.serialize()` reflects the uncommitted preview `_roots`, so it
+    // differs from the committed `getSceneUI()` and this branch would call
+    // `load()` — reverting the drag and wiping selection/local-undo mid-motion.
+    // Any `EditorStore` notify can reach here mid-gesture (most reachably the
+    // previous commit's async autosave resolving inside the next drag's
+    // window). Skip the reload while a gesture owns `_roots`; `endEdit()`
+    // commits through `setSceneUI`, after which content matches and no reload
+    // is needed. (A genuine external doc change arriving mid-gesture — vanishing
+    // rare — is simply deferred, never allowed to destroy the active gesture.)
+    const sceneUI = store.getSceneUI();
+    if (shouldReloadUIChild(sceneUI, uiStore)) {
+      uiStore.load(sceneUI);
+    }
+
+    if (!suppressing) {
+      const ids = [...store.selectedEntityIds];
+      const uiOwnsSelection = ids.length > 0 && ids.every((id) => uiStore.find(id) != null);
+      if (uiOwnsSelection) {
+        // Already reflects (or will reflect, via the mirror above) uiStore's
+        // own selection — nothing to clear, and don't let a stale key here
+        // cause a redundant re-mirror on the next uiStore notify.
+        lastMirroredUiSelectionKey = ids.join('\u0000');
+      } else if (uiStore.selection.length > 0) {
+        // A non-UI (or empty) selection landed on the shared store — the UI
+        // child no longer owns it. Clear the UI selection so a stale
+        // highlighted node doesn't linger and the inspector never
+        // double-matches (R4's "one inspector" discipline).
+        lastMirroredUiSelectionKey = '';
+        suppressing = true;
+        try {
+          uiStore.select([]);
+        } finally {
+          suppressing = false;
+        }
+      }
+    }
+
+    layer.style.display = isWorldHidden(worldId) ? 'none' : 'block';
+    layer.style.pointerEvents = isWorldInteractive(worldId) ? 'auto' : 'none';
+  });
+
+  return () => {
+    unsubUI();
+    unsubStore();
+    uiAdapter.detachPickSurface();
+    root.unmount();
+    layer.remove();
+  };
+}

package/src/authoring/story-overlay.ts

@@ -0,0 +1,48 @@
+/**
+ * Story overlay (Q2 decoupling, D4, `docs/unified-world-editor/26-unified-editor-spec.md`
+ * §3 B2) — a module-level, per-worldId slot for an EDITOR-SIDE stories
+ * source that plugs into `ReactWorldAuthoringAdapter`'s `storySources`
+ * constructor option without the adapter (or `design-time-layers.ts`, which
+ * constructs it) needing to know where the extra source came from. Same
+ * shape as `world-session-state.ts`: a bare get/set slot, no subscribe of
+ * its own — a caller that mutates it re-renders/re-mounts through whatever
+ * already reacts to `store.notifyIngestEdit()`.
+ *
+ * This is the DECOUPLING plumbing only (the spec's Q2 requirement: "the
+ * provider takes stories as a constructor input; the project registry is
+ * merely the default source... add the parameter and a unit test, no UI for
+ * authoring overlays yet"). There is no file-loader or editor UI writing
+ * into this slot in B2 — that is future work; today it exists so an overlay
+ * source can be set programmatically (e.g. by a future authoring UI, or a
+ * test) and observed to WIN over the registry's stories on an id collision
+ * (`mountReactLayer` composes `storySources: [registrySource, overlaySource]`
+ * — later entries win, see `ReactWorldAuthoringAdapter`'s doc comment).
+ *
+ * A process-lifetime singleton (not project-scoped), matching
+ * `world-session-state.ts`'s own stance — nothing here needs a
+ * project-switch reset within a single browser tab.
+ */
+import type { UIStory } from '@vgai/scene-ui/registry';
+
+const _overlays = new Map<string, Record<string, UIStory>>();
+
+/** Set (replacing wholesale) `worldId`'s overlay stories source. */
+export function setStoryOverlay(worldId: string, stories: Record<string, UIStory>): void {
+  _overlays.set(worldId, stories);
+}
+
+/** `worldId`'s overlay stories source, or `undefined` if none was set. */
+export function getStoryOverlay(worldId: string): Record<string, UIStory> | undefined {
+  return _overlays.get(worldId);
+}
+
+export function clearStoryOverlay(worldId: string): void {
+  _overlays.delete(worldId);
+}
+
+/** Test-only: drop every world's overlay so unit tests don't leak state
+ *  across cases (this module is a process-lifetime singleton — see the
+ *  header comment). */
+export function _resetStoryOverlaysForTest(): void {
+  _overlays.clear();
+}