@vgai/editor 0.2.0 → 0.4.0-canary.20260715.0

package/src/authoring/design-time-layers.ts

@@ -1,11 +1,9 @@
 /**
  * Design-time layer stack (B1, docs/unified-world-editor/26-unified-editor-spec.md
- * §3 B1 · D3/D9) — mounts a DESIGN-TIME layer for every non-focused react/pixi
- * world so edit mode composites the viewport exactly like the runtime does
- * (`@engine/runtime/create-runtime.ts`'s `createWorldsGameRuntime`, mirrored
- * below): a z-ordered DOM stack, the threejs canvas keeping its existing,
- * UNTOUCHED slot, each react/pixi world getting an absolutely-positioned
- * layer above it. Layers default `pointer-events:none`; the eye
+ * §3 B1 · D3/D9) — mounts one or more DESIGN-TIME React/Pixi worlds into a
+ * caller-owned authoring host. Runtime still uses a z-ordered composite, but
+ * the editor supplies a distinct host per world document; only Game presents
+ * the composed result. Layers default `pointer-events:none`; the eye
  * (`world-session-state.ts`'s `hidden`) hides a layer; `interactive` forwards
  * real pointer events for design-time hover/press testing; `pickLock` is
  * stored only (B4 consumes it in the pick walk). A layer that throws on
@@ -21,47 +19,74 @@
  * WHOLE S-B effort — display layer + (B4) stage hit-test only, no
  * hierarchy/stories — see `mountPixiLayer`'s doc comment.
  *
- * Only NON-focused `react`/`pixijs` children are candidates for a layer: the
- * focused threejs world already renders through `ViewportPanel`'s own
- * `<canvas>` (its existing slot, deliberately untouched here — a plain,
- * un-z-indexed, `position:static` element always paints below every
- * POSITIONED layer this module adds, "canvas keeps its slot / accept
- * canvas-bottom" per this task's own allowance). A non-focused THREEJS world
- * (there is no live scene to show it, and switching focus is out of B1's
- * scope — see `edit-mode-authoring.ts`'s `switchFocusedWorld` stub) simply
- * keeps its existing Boundary node, untouched by this module.
+ * Only `react`/`pixijs` children are candidates for these hosts: the focused
+ * threejs world renders through `ViewportPanel`'s own `<canvas>`. A non-focused THREEJS world
+ * (there is no live scene to show it — `switchFocusedWorld` in
+ * `edit-mode-authoring.ts` changes which world is focused, via a full
+ * rebuild, rather than mounting a second live one) simply keeps its existing
+ * Boundary node, untouched by this module.
  */
 
 import type { AuthoringAdapter, PickProvider } from '@engine/adapter';
 import { createAssetCache } from '@engine/assets';
 import { createGameLoop } from '@engine/core/game-loop';
-import type { ResolvedWorldEntry } from '@engine/manifest/load';
+import type { ResolvedAdapterRoot } from '@engine/manifest/load';
 import { createGame, type Game } from '@engine/runtime/game';
 import { stackOrder } from '@engine/runtime/input-router';
 import { PixiSceneGameAdapter } from '@engine/world2d/pixi-game-adapter';
-import { createDataSource } from '@vgai/scene-ui/data-source';
-import { storiesFromRegistry, type UIStory } from '@vgai/scene-ui/registry';
-import { UIDataProvider } from '@vgai/scene-ui/ui-data-context';
 import { Component, type ReactNode } from 'react';
 import {
   fetchScene2DFile,
-  loadProjectUIRegistry,
+  loadPixiComponentRegistryForProject,
   resolveGameProviderForProject,
-  resolveReactWorldEntryComponent,
+  resolveReactAdapterRootComponent,
   resolveReactWorldMountRuntime,
 } from '../adapter-resolver';
 import { editorConsole } from '../editor-console';
 import type { EditorStore } from '../editor-store';
 import { getCurrentProject } from '../project-manager';
+import { mountIsolatedStory } from '../stories/StoryPreviewMount';
+import {
+  getDefaultRootPreviewStory,
+  getRootPreviewStories,
+  type RootPreviewStory,
+  refreshProjectStories,
+} from '../stories/story-registry';
+
+/** D20: Play tears the design-time adapter down, so the selected CSF state
+ * must live one level above that adapter to survive Stop's rebuild. Keyed by
+ * project + root so equal root ids in different projects never bleed. */
+const selectedPortableStoryByRoot = new Map<string, string>();
+
+function portableStorySelectionKey(projectRoot: string, rootId: string): string {
+  return `${projectRoot}\0${rootId}`;
+}
+
+function portableDocumentLabel(story: RootPreviewStory): string {
+  const authoredTitle = story.title?.split('/').filter(Boolean).at(-1)?.trim();
+  if (authoredTitle) return authoredTitle;
+  const file = story.modulePath.split('/').pop() ?? story.modulePath;
+  const stem = file.replace(/\.stories\.[^.]+$/i, '');
+  const words = stem
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .replace(/[-_]+/g, ' ')
+    .trim();
+  return words || file;
+}
+
 import { createHttpSourceWriteBackend } from '../ui-source/source-write-backend';
 import { BoundaryAuthoringAdapter, type BoundaryWorldInfo } from './boundary-authoring-adapter';
 import type { CompositeAuthoringAdapter } from './composite-authoring-adapter';
-import { registerEditModeChild } from './edit-mode-authoring';
+import { EDIT_MODE_REBUILD_EVENT } from './edit-mode-authoring';
 import { addMountFailureReport, formatMountFailureMessage } from './mount-failure-report';
 import { ReactWorldAuthoringAdapter } from './react-world-authoring-adapter';
-import { mountSceneUILayer } from './scene-ui-layer';
 import { getStoryOverlay } from './story-overlay';
-import { UIAuthoringAdapter } from './ui-authoring-adapter';
+import type { UIComponentRegistry, UIStory } from './story-types';
+import {
+  getWorldCanvasViewport,
+  resetWorldCanvasViewport,
+  subscribeWorldCanvasViewport,
+} from './world-canvas-viewport-state';
 import {
   getWorldPan,
   panTransformValue,
@@ -70,16 +95,16 @@ import {
 } from './world-pan-state';
 import { isWorldHidden, isWorldInteractive } from './world-session-state';
 
-/** Bottom-to-top layer z-index base — strictly below `PlayBar`'s z100/
- *  `ToolStrip`+`ViewportOverlay`'s z1000, so gizmo/orbit-controls/marquee
+/** Bottom-to-top layer z-index base — strictly below the selection overlay's
+ *  z50 and `ToolStrip`+`ViewportOverlay`'s z1000, so canvas-local editing
  *  chrome is never occluded by a design-time layer. */
 const BASE_Z_INDEX = 1;
 
 /** One candidate world for a design-time layer — read entirely off its
  *  existing `BoundaryAuthoringAdapter` (kind/path/zOrder/pausable are already
- *  exposed there, independent of whether the composite has a game-root
+ *  exposed there, independent of whether the composite has a writable manifest
  *  manifest surface — see that adapter's own inspector). */
-interface LayerCandidate {
+export interface DesignTimeWorldDescriptor {
   readonly worldId: string;
   readonly kind: 'react' | 'pixijs';
   readonly path: string | undefined;
@@ -87,8 +112,8 @@ interface LayerCandidate {
   readonly pausable: boolean;
 }
 
-function readCandidates(composite: CompositeAuthoringAdapter): LayerCandidate[] {
-  const out: LayerCandidate[] = [];
+function readCandidates(composite: CompositeAuthoringAdapter): DesignTimeWorldDescriptor[] {
+  const out: DesignTimeWorldDescriptor[] = [];
   for (const { worldId, adapter } of composite.childAdapters()) {
     if (!(adapter instanceof BoundaryAuthoringAdapter)) continue; // the focused (live) world
     const kind = adapter.inspector.get(worldId, 'kind') as string;
@@ -106,19 +131,29 @@ function readCandidates(composite: CompositeAuthoringAdapter): LayerCandidate[]
   return out;
 }
 
+/** Snapshot the non-Three roots that can own an edit-time document. Capture
+ * this before any root mounts: a successful React mount upgrades its
+ * Boundary adapter in-place, while the document still needs the manifest
+ * path and stacking metadata that Boundary disclosed. */
+export function designTimeWorldDescriptors(
+  composite: CompositeAuthoringAdapter,
+): readonly DesignTimeWorldDescriptor[] {
+  return readCandidates(composite);
+}
+
 /**
  * The inert design-time GameContext stand-in (B1's one genuine design
  * decision). A REAL `Game` — never a hand-typed duck-typed literal, mirroring
  * this repo's own test convention (`packages/editor/test/adapter-conformance-kit.ts`'s
  * `headlessGame()`) — built with a loop that is constructed but NEVER
- * started/ticked, and with NO worlds ever registered. This satisfies
+ * started/ticked, and with NO roots ever registered. This satisfies
  * `useGame`/`useGameState` (`@engine/react/game-state`, and any project's own
  * re-export of it) without throwing, genuinely inertly:
  *  - `state.subscribe` never fires — nothing ever calls
  *    `GameStateBridgeInternal.bump()` (only `GameInternal.runFrame` does, and
  *    this Game's loop never runs a frame);
  *  - `state.frameVersion` stays `0` forever;
- *  - `queryByComponent`/`world()`/`worlds` are empty/`null` because `worlds`
+ *  - `queryByComponent`/`world()`/`roots` are empty/`null` because `roots`
  *    stays `[]` (nothing ever calls `registerWorld`).
  * `defaultWorld`/`components`/`input`/`audio` throw descriptively if touched
  * (same as any fresh `createGame()` before a world registers) — a HUD that
@@ -157,18 +192,18 @@ class DesignTimeErrorBoundary extends Component<
 }
 
 /**
- * A minimal `ResolvedWorldEntry` satisfying `resolveReactWorldEntryComponent`
+ * A minimal `ResolvedAdapterRoot` satisfying `resolveReactAdapterRootComponent`
  * (`../adapter-resolver.ts`, which reads only `id`/`kind`/`scene`/`entry` off
  * it) — the fields below it (`adapter`/`capabilities`/`loop`/`description`)
  * are unused by that function but required by the type; filled with the
  * honest "this is a native default-react world" values.
  */
-function buildResolvedWorldEntryStub(worldId: string, entry: string): ResolvedWorldEntry {
+function buildResolvedAdapterRootStub(worldId: string, entry: string): ResolvedAdapterRoot {
   return {
     id: worldId,
-    kind: 'react',
+    surface: 'react',
     description: undefined,
-    adapter: { type: 'default', identity: 'default-react' },
+    adapter: { type: 'builtin', identity: 'react', surface: 'react' },
     scene: undefined,
     entry,
     zOrder: 0,
@@ -194,6 +229,14 @@ function createLayerElement(container: HTMLElement, worldId: string, zIndex: num
   layer.style.width = '100%';
   layer.style.height = '100%';
   layer.style.zIndex = String(zIndex);
+  // Same containment as the runtime's per-world surfaces (create-runtime.ts,
+  // world-surface cssText): make this layer the containing block for
+  // `position:fixed` descendants and clip to the world's rectangle, so a
+  // game's full-screen UI (`fixed; inset:0` — the natural idiom) renders
+  // inside the viewport instead of floating over the editor chrome. Also
+  // makes behavior pan-invariant: without it, space-pan's transform (below)
+  // suddenly captured `fixed` children that were page-anchored un-panned.
+  layer.style.contain = 'layout paint';
   applySessionStyle(layer, worldId);
   // D4 (spec27 §8 "space-pan" row) — seed this layer with whatever pan is
   // currently in effect (normally none — `mountDesignTimeLayers` resets pan
@@ -213,6 +256,10 @@ function createLayerElement(container: HTMLElement, worldId: string, zIndex: num
  *  every subsequent pan change (see `world-pan-state.ts`). */
 function applyPanTransform(layer: HTMLElement): void {
   layer.style.transform = panTransformValue(getWorldPan()) ?? '';
+  layer.style.transformOrigin = '0 0';
+  const viewport = getWorldCanvasViewport();
+  layer.style.width = viewport.width === null ? '100%' : `${viewport.width}px`;
+  layer.style.height = viewport.height === null ? '100%' : `${viewport.height}px`;
 }
 
 interface LayerMountResult {
@@ -249,11 +296,9 @@ interface LayerRenderState {
 
 /**
  * React design-time mount (B1, story wiring B2 · D4, catalog B3) — the entry
- * via the EXISTING #31 loader (`resolveReactWorldEntryComponent`, reused
- * verbatim), wrapped in the project's own `GameProvider`
- * (`resolveGameProviderForProject` — reused verbatim so a project shipping
- * its own `src/ui/game-state.tsx` is wrapped by ITS OWN provider, never
- * split-context — see that function's doc comment) around the inert
+ * via the EXISTING #31 loader (`resolveReactAdapterRootComponent`, reused
+ * verbatim), wrapped in the canonical engine `GameProvider`
+ * (`resolveGameProviderForProject`) around the inert
  * `createDesignTimeGame()` stand-in (UNTOUCHED by B2/B3 — see that function's
  * own doc comment), inside a `UIDataProvider` (B2 — seeded from the active
  * story's `data`, or `{}` with none applied) and a React error boundary.
@@ -296,7 +341,7 @@ interface LayerRenderState {
  * reused.
  */
 async function mountReactLayer(
-  candidate: LayerCandidate,
+  candidate: DesignTimeWorldDescriptor,
   layer: HTMLElement,
   projectRoot: string,
   store: EditorStore,
@@ -306,38 +351,133 @@ async function mountReactLayer(
       `design-time react layer "${candidate.worldId}": no \`entry\` declared — nothing to mount.`,
     );
   }
-  const worldStub = buildResolvedWorldEntryStub(candidate.worldId, candidate.path);
-  const Entry = await resolveReactWorldEntryComponent(worldStub, projectRoot);
-  const GameProvider = await resolveGameProviderForProject(
-    projectRoot,
-    candidate.worldId,
-    'default-react',
+
+  // D20 — portable Storybook CSF is React's canonical design-time state.
+  // Discovery feeds the first-class hierarchy documents below this world; the
+  // viewport mounts the SAME composed portable story rather than translating
+  // it into a VGAI fixture or constructing a fake runtime Game.
+  await refreshProjectStories({ rootPath: projectRoot });
+  const portableStories = getRootPreviewStories(candidate.worldId);
+  const defaultPortableStory = getDefaultRootPreviewStory(candidate.worldId);
+  if (defaultPortableStory) {
+    const selectionKey = portableStorySelectionKey(projectRoot, candidate.worldId);
+    const rememberedStoryId = selectedPortableStoryByRoot.get(selectionKey);
+    const initialPortableStory =
+      portableStories.find((story) => story.id === rememberedStoryId) ?? defaultPortableStory;
+    let disposed = false;
+    let mounted: Awaited<ReturnType<typeof mountIsolatedStory>> = null;
+
+    const mountPortable = async (
+      story: RootPreviewStory,
+      args: Record<string, unknown> = story.args,
+    ): Promise<void> => {
+      const next = await mountIsolatedStory(
+        layer,
+        story.modulePath,
+        story.name,
+        story.Component,
+        args,
+      );
+      // A newer selection may claim the container while this story's loader
+      // is still in flight. `mountIsolatedStory` reports that supersession as
+      // null; never let the stale completion erase the newer mount handle,
+      // otherwise final teardown could no longer unmount the live React root.
+      if (!next) return;
+      if (disposed) {
+        next.unmount();
+        return;
+      }
+      mounted = next;
+      store.notifyIngestEdit();
+    };
+
+    await mountPortable(initialPortableStory);
+    if (!mounted) {
+      throw new Error(
+        `design-time react root "${candidate.worldId}": default CSF story ` +
+          `"${initialPortableStory.name}" was superseded before it mounted.`,
+      );
+    }
+
+    const byId = new Map(portableStories.map((story) => [story.id, story]));
+    const documentsByPath = new Map<string, RootPreviewStory[]>();
+    for (const story of portableStories) {
+      const siblings = documentsByPath.get(story.modulePath);
+      if (siblings) siblings.push(story);
+      else documentsByPath.set(story.modulePath, [story]);
+    }
+    const adapter = new ReactWorldAuthoringAdapter(layer, store, {
+      ...(import.meta.env.DEV ? { writeBackend: createHttpSourceWriteBackend() } : {}),
+      worldId: candidate.worldId,
+      portableStories: portableStories.map((story) => ({
+        id: story.id,
+        label: story.label,
+        args: story.args,
+      })),
+      portableDocuments: [...documentsByPath.entries()].map(([modulePath, stories]) => ({
+        id: `portable-document:${modulePath}`,
+        label: portableDocumentLabel(stories[0]!),
+        path: modulePath,
+        storyIds: stories.map((story) => story.id),
+      })),
+      activePortableStoryId: initialPortableStory.id,
+      onPortableStoryApplied: (storyId) => {
+        const story = (storyId ? byId.get(storyId) : null) ?? defaultPortableStory;
+        selectedPortableStoryByRoot.set(selectionKey, story.id);
+        void mountPortable(story).catch((error: unknown) => {
+          editorConsole.error(
+            `[design-time-layers] React root "${candidate.worldId}" failed applying portable ` +
+              `story "${story.name}": ${formatMountFailureMessage(error)}`,
+            'authoring',
+          );
+        });
+      },
+      onPortableStoryArgsChanged: (storyId, args) => {
+        const story = byId.get(storyId);
+        if (!story) return;
+        void mountPortable(story, args).catch((error: unknown) => {
+          editorConsole.error(
+            `[design-time-layers] React root "${candidate.worldId}" failed updating portable ` +
+              `story "${story.name}" args: ${formatMountFailureMessage(error)}`,
+            'authoring',
+          );
+        });
+      },
+    });
+
+    return {
+      adapter,
+      dispose: () => {
+        disposed = true;
+        adapter.disposeReactRootAdapter();
+        mounted?.unmount();
+      },
+    };
+  }
+
+  editorConsole.warn(
+    `[design-time-layers] React root "${candidate.worldId}" has no portable CSF preview. ` +
+      'Add a *.stories.tsx module with parameters.vgai.root set to this root id. ' +
+      'Falling back to the deprecated inert-Game preview for compatibility.',
+    'authoring',
   );
+
+  const worldStub = buildResolvedAdapterRootStub(candidate.worldId, candidate.path);
+  const Entry = await resolveReactAdapterRootComponent(worldStub, projectRoot);
+  const GameProvider = await resolveGameProviderForProject(projectRoot, candidate.worldId, 'react');
   // C1 (phase-b/c1-react-mount): this layer's own react-world mount is a
   // SECOND call site with the identical packaged-runtime dual-React-instance
-  // exposure `adapter-resolver.ts`'s `ReactWorldAdapter.mount()` has — under
+  // exposure `adapter-resolver.ts`'s `ReactRootAdapter.mount()` has — under
   // the packaged runtime, `createElement`/`createRoot`/`flushSync` must come
   // from the PROJECT's own react, not this module's (removed) static
   // imports. See `resolveReactWorldMountRuntime`'s doc comment.
   const { createElement, createRoot, flushSync } = await resolveReactWorldMountRuntime();
   const game = createDesignTimeGame();
 
-  // D4 (B2) — story sources: the project's registry (states folded in as
-  // stories) first, an editor-side overlay last (wins on an id collision).
-  // `loadProjectUIRegistry` stays silent for the common no-registry case
-  // (its own `hasUiRegistry` probe) — awaited HERE (not the async cache slot
-  // `scene-ui-layer.ts`'s own registry load populates, which can still be
-  // settling when this layer mounts, since the two mounts race).
-  const registry = await loadProjectUIRegistry(projectRoot);
   const storySources: ReadonlyArray<Record<string, UIStory>> = [
-    storiesFromRegistry(registry ?? {}),
     getStoryOverlay(candidate.worldId) ?? {},
   ];
-  // B3 — the catalog gate: absent/empty `components` (the common project,
-  // and every pre-B3 fixture) keeps `ReactWorldAuthoringAdapter`'s hierarchy
-  // the plain DOM walk, byte-identical (§1's gate — "components NON-EMPTY
-  // specifically").
-  const catalogComponents = registry?.components;
+  const catalogComponents: UIComponentRegistry = {};
 
   const root = createRoot(layer);
   const renderState: LayerRenderState = { entryStory: null, isolation: null };
@@ -374,11 +514,7 @@ async function mountReactLayer(
             ? `story:${story.id}`
             : '__none__',
         onCaught,
-        children: createElement(
-          UIDataProvider,
-          { data: createDataSource(story?.data ?? {}) },
-          createElement(GameProvider, { game }, view),
-        ),
+        children: createElement(GameProvider, { game }, view),
       }),
     );
   };
@@ -398,7 +534,6 @@ async function mountReactLayer(
     ...(import.meta.env.DEV ? { writeBackend: createHttpSourceWriteBackend() } : {}),
     storySources,
     worldId: candidate.worldId,
-    catalogComponents,
     onStoryApplied: (story) => {
       renderState.entryStory = story;
       render((error: unknown) => {
@@ -427,7 +562,7 @@ async function mountReactLayer(
       // subscription before dropping its DOM, so listeners don't accumulate across
       // layer remounts (a leaked one is harmless — it early-returns on an empty echo —
       // but this keeps teardown clean).
-      adapter.disposeReactWorldAdapter();
+      adapter.disposeReactRootAdapter();
       root.unmount();
     },
   };
@@ -464,23 +599,25 @@ function measure(container: HTMLElement): { width: number; height: number } {
  * hit-test only, no hierarchy/stories) — an explicit, out-of-scope-by-design
  * non-goal, not an oversight.
  *
- * B1 supports `scene`-declared pixi worlds only (the `.scn2d` display-only
+ * B1 supports `scene`-declared pixi roots only (the `.scn2d` display-only
  * case named in the spec); an `entry`-based (imperative-setup) pixi world has
  * no scene file to fetch and fails loudly here rather than being silently
  * skipped — degrading to the same #18 error node as any other mount failure.
  */
 async function mountPixiLayer(
-  candidate: LayerCandidate,
+  candidate: DesignTimeWorldDescriptor,
   layer: HTMLElement,
   container: HTMLElement,
+  projectRoot: string,
 ): Promise<LayerMountResult> {
   if (!candidate.path) {
     throw new Error(
       `design-time pixi layer "${candidate.worldId}": no \`scene\` declared — nothing to mount ` +
-        '(B1 display-only mount supports scene-based pixi worlds only, not `entry`).',
+        '(B1 display-only mount supports scene-based pixi roots only, not `entry`).',
     );
   }
   const sceneData = await fetchScene2DFile(candidate.path);
+  const registry = await loadPixiComponentRegistryForProject(projectRoot);
   const canvas = document.createElement('canvas');
   canvas.style.width = '100%';
   canvas.style.height = '100%';
@@ -488,7 +625,7 @@ async function mountPixiLayer(
   layer.appendChild(canvas);
 
   const { width, height } = measure(container);
-  const adapter = new PixiSceneGameAdapter({ id: candidate.worldId, sceneData });
+  const adapter = new PixiSceneGameAdapter({ id: candidate.worldId, sceneData, registry });
   const mounted = await adapter.mount({ canvas, width, height, transparent: true });
   mounted.update?.(0); // one-shot render — see doc comment above
 
@@ -516,12 +653,11 @@ async function mountPixiLayer(
 }
 
 /**
- * Mount a design-time layer for every non-focused react/pixi world declared
- * by `composite` (already installed via `installEditModeAuthoringForProject`)
- * into `container` (`ViewportPanel`'s own containerRef div — the SAME element
- * the editor's threejs `<canvas>` lives in). Returns a disposer; call it from
- * the SAME effect cleanup that tears down the composite
- * (`exitEditModeAuthoring`) — see `ViewportPanel.tsx`'s wiring.
+ * Mount design-time React/Pixi worlds declared by `composite` into a caller's
+ * authoring `container`. `descriptors` narrows the mount to one world for the
+ * per-world document model; omission preserves the original multi-layer
+ * primitive for bounded callers and integration tests. Returns a disposer
+ * that must run before the owning composite is released.
  *
  * A no-op (returns a no-op disposer) when there is nothing to layer: a
  * single-world project (back-compat floor, matches `installEditModeAuthoring`'s
@@ -537,16 +673,26 @@ async function mountPixiLayer(
  * (whatever the entry's own JSX declares, e.g. tri-world's `hud-count`)
  * simultaneously in one document — not just visually confusing, but a
  * genuine test/automation hazard (two elements answering to one testid).
- * Design-time layers do not remount when play stops again — reload picks
- * them back up, exactly like any other edit-mode-only state (undo history,
- * panel layout) that a play session doesn't attempt to preserve. This never
- * touches the FOCUSED threejs world or the rest of the editor, which stay
- * fully functional regardless of play state.
+ * Stop symmetrically rebuilds edit-mode authoring and restores the selected
+ * portable CSF preview. Play and edit roots never coexist, but neither does
+ * Play permanently destroy the authoring surface.
  */
+let rebuildEventQueued = false;
+
+function queueEditModeRebuild(): void {
+  if (rebuildEventQueued) return;
+  rebuildEventQueued = true;
+  queueMicrotask(() => {
+    rebuildEventQueued = false;
+    window.dispatchEvent(new CustomEvent(EDIT_MODE_REBUILD_EVENT));
+  });
+}
+
 export function mountDesignTimeLayers(
   container: HTMLElement,
   composite: CompositeAuthoringAdapter,
   store: EditorStore,
+  descriptors?: readonly DesignTimeWorldDescriptor[],
 ): () => void {
   // D4 (spec27 §8 "space-pan" row) — a fresh layer stack starts un-panned:
   // every call here is a "world switch" (initial edit-mode install, or an
@@ -554,24 +700,66 @@ export function mountDesignTimeLayers(
   // `installAll`), so a stale pan offset from a PREVIOUS layer stack must
   // never carry over onto a different one.
   resetWorldPan();
+  resetWorldCanvasViewport();
+  // ONE-WAY PLAY HANDOFF, ENTRY HALF (the fix for the CI-only
+  // `36-r3f-first-party.spec.ts` "roots: " hang — see below). The handoff
+  // documented in this module's doc comment was only ever implemented as an
+  // EXIT: the `store.subscribe` listener at the bottom of this function flips
+  // `playTeardownDone` and calls `suspendForPlay()` when play STARTS. That
+  // covers "layers were already mounted, then the user hit Play" — but it is
+  // a TRANSITION listener, so it does nothing at all when play is ALREADY
+  // running by the time this function is first called.
+  //
+  // That ordering is real, and it is exactly what CI hits. `ViewportPanel`'s
+  // `installAll()` (the only caller) runs at the tail of an async chain —
+  // `loadInitialScene()` -> `installEditModeAuthoringForProject()` (which
+  // itself fetches `vgai.game.json`) -> here. The e2e clicks Play the moment
+  // the editor shell is interactive, so on a slow/contended host (CI's
+  // 4-core SwiftShader runners) Play wins that race and `store.playState` is
+  // already `'playing'` when we arrive. Without this guard we then mount a
+  // design-time react layer anyway — rendering the project's REAL entry
+  // component (`examples/r3f-probe/src/hud.tsx`, `data-testid="hud-roots"`)
+  // against `createDesignTimeGame()`'s INERT `Game`, whose `roots` array is
+  // `[]` forever and whose loop never ticks (see that function's doc comment).
+  // The HUD therefore renders literally `"roots: "` — an empty list, from a
+  // Game that never registers a world — and, because no further playState
+  // TRANSITION ever arrives, `suspendForPlay()` never fires and the layer is
+  // never torn down. That is precisely the reported CI symptom ("the HUD
+  // element IS mounted; the roots list is EMPTY", for the full 15s budget),
+  // and it also carries the duplicate-`data-testid` hazard this module's own
+  // doc comment already calls out for the transition case.
+  //
+  // Play mode owns the react world outright while it runs (it mounts its own
+  // live tree over a REAL, ticking Game). So the correct behavior when play
+  // is already up is the same one `suspendForPlay()` produces: mount NOTHING.
+  // Stop requests a clean edit-mode rebuild below; this entry guard therefore
+  // needs to listen for Stop even though it mounted no layers itself.
+  if (store.playState !== 'stopped') {
+    let disposed = false;
+    let rebuildRequested = false;
+    const unsubscribe = store.subscribe(() => {
+      if (disposed || rebuildRequested || store.playState !== 'stopped') return;
+      rebuildRequested = true;
+      if (!disposed) queueEditModeRebuild();
+    });
+    return () => {
+      disposed = true;
+      unsubscribe();
+    };
+  }
   const projectRoot = getCurrentProject()?.rootPath;
-  const candidates = readCandidates(composite);
+  const candidates = descriptors ? [...descriptors] : readCandidates(composite);
   // C3 — the scene-UI child (at most one, the focused world's): already a
   // LIVE `UIAuthoringAdapter` at composite-install time (`edit-mode-
   // authoring.ts` — no Boundary-to-live upgrade dance needed here, unlike
   // react/pixi), so it's a mount candidate in its own right rather than one
   // of `readCandidates`'s Boundary-only entries.
-  const uiChildEntry = composite.childAdapters().find((c) => c.kind === 'scene-ui');
-  const uiAdapter =
-    uiChildEntry && uiChildEntry.adapter instanceof UIAuthoringAdapter
-      ? uiChildEntry.adapter
-      : null;
-  if ((candidates.length === 0 && !uiAdapter) || !projectRoot) {
+  if (candidates.length === 0 || !projectRoot) {
     return () => {};
   }
 
   // Bottom-to-top paint order — mirrors `create-runtime.ts`'s own stacking
-  // pass, over exactly the worlds this module lays out (react/pixi
+  // pass, over exactly the roots this module lays out (react/pixi
   // candidates only; the focused threejs world keeps its untouched canvas
   // slot below all of these — see the module doc comment).
   const sorted = stackOrder(candidates.map((c) => ({ id: c.worldId, zOrder: c.zOrder })));
@@ -587,21 +775,7 @@ export function mountDesignTimeLayers(
   const upgraded = new Set<string>();
   let torndown = false; // the whole-module disposer (ViewportPanel unmount) ran
   let playTeardownDone = false; // the one-way play-mode handoff (see doc comment) ran
-
-  // C3 — the scene-UI layer's own disposer, tracked separately from
-  // `disposers`/`layers` (react/pixi's Boundary-upgrade bookkeeping doesn't
-  // apply to it — the UI child's adapter stays live throughout; only its DOM
-  // layer needs tearing down, here and on the play handoff below).
-  let disposeUILayer: (() => void) | undefined;
-  if (uiAdapter && uiChildEntry) {
-    disposeUILayer = mountSceneUILayer(
-      container,
-      uiChildEntry.worldId,
-      uiAdapter,
-      store,
-      BASE_Z_INDEX + orderedCandidates.length,
-    );
-  }
+  let rebuildRequested = false;
 
   function disposeEverything(): void {
     for (const dispose of disposers.splice(0)) {
@@ -616,22 +790,20 @@ export function mountDesignTimeLayers(
   }
 
   /**
-   * One-way play handoff: dispose the design-time layers AND revert every
+   * Play handoff: dispose the design-time layers AND revert every
    * upgraded world back to a `BoundaryAuthoringAdapter` disclosure node
    * (#18 — never silently empty). Not called on the whole-module disposer
    * (`torndown`, ViewportPanel unmount), where the composite is going away
-   * anyway. Design-time layers do not remount when play stops again — reload
-   * restores them (see the module doc comment). The scene-UI layer's DOM is
+   * anyway. Stop dispatches one edit-mode rebuild after the live runtime has
+   * torn down, restoring the CSF-backed design surface. The scene-UI layer's DOM is
    * torn down the same way (play mode renders scene-UI through the real
    * engine's HUD mount instead — two live DOM trees for the same testids
    * would be the same hazard `design-time-layers.ts`'s own doc comment
-   * already calls out for react worlds); its adapter is left alone (still
+   * already calls out for react roots); its adapter is left alone (still
    * live, just without a mounted layer) since there is no Boundary form of it.
    */
   function suspendForPlay(): void {
     disposeEverything();
-    disposeUILayer?.();
-    disposeUILayer = undefined;
     for (const worldId of upgraded) {
       const c = candidateByWorld.get(worldId);
       if (!c) continue;
@@ -647,7 +819,7 @@ export function mountDesignTimeLayers(
         new BoundaryAuthoringAdapter(
           store,
           info,
-          'Design-time layer suspended by play mode — reload the editor to restore it.',
+          'Design-time layer suspended by play mode — Stop restores it.',
         ),
       );
     }
@@ -662,7 +834,7 @@ export function mountDesignTimeLayers(
     const mountPromise: Promise<LayerMountResult> =
       candidate.kind === 'react'
         ? mountReactLayer(candidate, layer, projectRoot, store)
-        : mountPixiLayer(candidate, layer, container);
+        : mountPixiLayer(candidate, layer, container, projectRoot);
 
     mountPromise
       .then((result) => {
@@ -672,7 +844,6 @@ export function mountDesignTimeLayers(
         }
         if (result.adapter) {
           composite.replaceChild(candidate.worldId, result.adapter);
-          registerEditModeChild(result.adapter);
           upgraded.add(candidate.worldId);
         } else if (result.pick) {
           // D12 (B4) — a pixi layer produces a `pick`, not a full adapter
@@ -738,6 +909,9 @@ export function mountDesignTimeLayers(
   const unsubPan = subscribeWorldPan(() => {
     for (const layer of layers.values()) applyPanTransform(layer);
   });
+  const unsubViewport = subscribeWorldCanvasViewport(() => {
+    for (const layer of layers.values()) applyPanTransform(layer);
+  });
 
   const unsubStore = store.subscribe(() => {
     if (!playTeardownDone && store.playState !== 'stopped') {
@@ -745,6 +919,15 @@ export function mountDesignTimeLayers(
       suspendForPlay();
       return;
     }
+    if (playTeardownDone && !rebuildRequested && store.playState === 'stopped' && !torndown) {
+      rebuildRequested = true;
+      // Reuse ViewportPanel's one authoritative reinstall path. The event
+      // causes this mount's disposer to run before the replacement composite
+      // and layers are installed, so no React root or adapter survives across
+      // the Play -> Stop boundary.
+      if (!torndown) queueEditModeRebuild();
+      return;
+    }
     // Session toggles (eye/interactive) change via `store.notifyIngestEdit()`
     // (`GameHierarchy.tsx`'s row affordances) — this is a cheap style
     // re-apply, never a remount.
@@ -770,7 +953,7 @@ export function mountDesignTimeLayers(
     torndown = true;
     unsubStore();
     unsubPan();
+    unsubViewport();
     disposeEverything();
-    disposeUILayer?.();
   };
 }