@vgai/editor 0.2.0

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

@@ -0,0 +1,776 @@
+/**
+ * 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
+ * (`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
+ * mount degrades to its A1 `BoundaryAuthoringAdapter` error node (#18) via
+ * `mount-failure-report.ts` — never a blank editor; every OTHER world (and
+ * the focused threejs world in particular) keeps working regardless.
+ *
+ * On a successful mount, the world's read-only Boundary adapter is REPLACED
+ * in the composite by a live one (`CompositeAuthoringAdapter.replaceChild`,
+ * B1) — react: the EXISTING, fully-featured `ReactWorldAuthoringAdapter`
+ * (spec-27's work; this file only produces the DOM it reflects, it never
+ * implements a second react adapter). Pixi stays Boundary-grade for the
+ * 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.
+ */
+
+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 { 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,
+  resolveGameProviderForProject,
+  resolveReactWorldEntryComponent,
+  resolveReactWorldMountRuntime,
+} from '../adapter-resolver';
+import { editorConsole } from '../editor-console';
+import type { EditorStore } from '../editor-store';
+import { getCurrentProject } from '../project-manager';
+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 { 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 {
+  getWorldPan,
+  panTransformValue,
+  resetWorldPan,
+  subscribeWorldPan,
+} 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
+ *  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
+ *  manifest surface — see that adapter's own inspector). */
+interface LayerCandidate {
+  readonly worldId: string;
+  readonly kind: 'react' | 'pixijs';
+  readonly path: string | undefined;
+  readonly zOrder: number;
+  readonly pausable: boolean;
+}
+
+function readCandidates(composite: CompositeAuthoringAdapter): LayerCandidate[] {
+  const out: LayerCandidate[] = [];
+  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;
+    if (kind !== 'react' && kind !== 'pixijs') continue; // B1 scope: react/pixi layers only
+    const reason = adapter.inspector.get(worldId, 'reason');
+    if (reason !== undefined) continue; // already an error node — nothing new to attempt
+    out.push({
+      worldId,
+      kind,
+      path: adapter.inspector.get(worldId, 'path') as string | undefined,
+      zOrder: Number(adapter.inspector.get(worldId, 'zOrder') ?? 0),
+      pausable: adapter.inspector.get(worldId, 'pausable') !== false,
+    });
+  }
+  return out;
+}
+
+/**
+ * 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
+ * `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`
+ *    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
+ * reaches for those is out of scope for a design-time stand-in and SHOULD
+ * throw loudly, caught by `DesignTimeErrorBoundary` below, degrading to the
+ * #18 error node rather than silently faking a value.
+ *
+ * B2 swaps this stand-in's DATA for story-sourced data (a `data`/services
+ * seam) — this function is the seam B2 replaces/extends, not a permanent
+ * fixture; it never constructs a live Game/GameComponents/sockets.
+ */
+function createDesignTimeGame(): Game {
+  const loop = createGameLoop({ fixedTimestep: 1 / 60, maxSubSteps: 8, update: () => {} });
+  return createGame({ loop, assets: createAssetCache() });
+}
+
+/** Minimal class-component error boundary — the only way React lets a host
+ *  catch a synchronous render-time throw (there is no hook equivalent).
+ *  Mirrors `ingest-siblings.ts`'s `SiblingErrorBoundary` (not exported from
+ *  that file, so re-declared here rather than reached into across an
+ *  unrelated module). */
+class DesignTimeErrorBoundary 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;
+  }
+}
+
+/**
+ * A minimal `ResolvedWorldEntry` satisfying `resolveReactWorldEntryComponent`
+ * (`../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 {
+  return {
+    id: worldId,
+    kind: 'react',
+    description: undefined,
+    adapter: { type: 'default', identity: 'default-react' },
+    scene: undefined,
+    entry,
+    zOrder: 0,
+    pausable: true,
+    loop: 'gated',
+    capabilities: { local: 'first-party', hosted: 'first-party' },
+  };
+}
+
+/** Re-applies session-local layer CSS (eye + interactive) — cheap, called on
+ *  every store notification, never triggers a remount. */
+function applySessionStyle(layer: HTMLElement, worldId: string): void {
+  layer.style.display = isWorldHidden(worldId) ? 'none' : 'block';
+  layer.style.pointerEvents = isWorldInteractive(worldId) ? 'auto' : 'none';
+}
+
+function createLayerElement(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);
+  applySessionStyle(layer, worldId);
+  // D4 (spec27 §8 "space-pan" row) — seed this layer with whatever pan is
+  // currently in effect (normally none — `mountDesignTimeLayers` resets pan
+  // on every fresh install, see its own doc comment — but re-applying here
+  // too keeps this function correct standalone). See `world-pan-state.ts`'s
+  // doc comment for the full lockstep-translate soundness argument: THIS
+  // element is exactly `this.root`/`hostRect()` in
+  // `react-world-authoring-adapter.ts`, i.e. the host `RectProvider.rect(id)`
+  // subtracts — panning it is what keeps `rect(id)` pan-invariant.
+  applyPanTransform(layer);
+  container.appendChild(layer);
+  return layer;
+}
+
+/** Re-applies the current shared world-pan transform to one layer element —
+ *  called at creation and by `mountDesignTimeLayers`' pan subscription on
+ *  every subsequent pan change (see `world-pan-state.ts`). */
+function applyPanTransform(layer: HTMLElement): void {
+  layer.style.transform = panTransformValue(getWorldPan()) ?? '';
+}
+
+interface LayerMountResult {
+  readonly adapter?: AuthoringAdapter;
+  /**
+   * D12 (B4) — a stage hit-test over this layer's mounted content, in CLIENT
+   * (browser) px, `PickProvider['pick']`-shaped. Only `mountPixiLayer`
+   * produces one (react layers get their pick via the FULL
+   * `ReactWorldAuthoringAdapter.pickable` the `adapter` field above already
+   * carries) — see the success handler below for how a pixi layer's `pick`
+   * (with no `adapter` of its own) gets wired onto its still-Boundary-grade
+   * authoring adapter.
+   */
+  readonly pick?: PickProvider['pick'];
+  dispose(): void;
+}
+
+/**
+ * B3 — the layer's current render target: EITHER the world's `entry`
+ * (the world's own entry component, against whatever story `stories.apply`
+ * last applied — B1/B2's original render), OR a single catalog component
+ * `isolate`d against a story (the storybook canvas, §0/§3 B3). Exactly one
+ * of these is "current" at a time; `apply`/`isolate` write into their OWN
+ * slot independently (`entryStory`/`isolation` below) so applying an
+ * entry-level story WHILE isolated updates the entry's story in the
+ * background WITHOUT restoring the entry render (RISKS: "apply-while-isolated
+ * must NOT restore entry") — the render picks `isolation` over `entryStory`
+ * whenever `isolation` is set.
+ */
+interface LayerRenderState {
+  entryStory: (UIStory & { id: string }) | null;
+  isolation: { componentKey: string; story: (UIStory & { id: string }) | null } | null;
+}
+
+/**
+ * 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
+ * `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.
+ * `flushSync` forces the initial render/commit/error-boundary-recovery to
+ * finish before this call returns (mirrors `ingest-siblings.ts`'s
+ * `mountDefaultReactSibling`), so a throwing entry is caught HERE —
+ * synchronously — rather than discovered later on react's own schedule.
+ *
+ * B2 — stories: `storySources` is `[storiesFromRegistry(registry)`, the
+ * project's `src/ui/registry.ts` (`states` folded in as an alias) — `,
+ * getStoryOverlay(worldId) ?? {}]`, an editor-side overlay (Q2 decoupling,
+ * `story-overlay.ts`) — the overlay LAST so it wins on an id collision. No
+ * story is applied at mount (`render(…)`, matching B1's original empty-data
+ * render byte-for-byte when no story exists yet); `stories.apply` (routed
+ * here from the story picker via `onStoryApplied`) RE-RENDERS this SAME root
+ * in place against the applied story's `data`/`props` — never a remount,
+ * never a second `createDesignTimeGame()`/`GameProvider` (the inert Game
+ * stand-in stays the SAME instance across every story switch AND every
+ * isolate/exit, exactly as B1 left it — story data rides `UIDataProvider`/
+ * entry-or-component props ONLY, never `game.state`/`queryByComponent`, see
+ * this module's own crux doc comment — the `30-composition-render` "Ticks: 0"
+ * tripwire is the proof).
+ *
+ * B3 — `catalogComponents: registry?.components` gates
+ * `ReactWorldAuthoringAdapter`'s catalog hierarchy ON for this world (§0's
+ * reconciliation: THIS is the one site that turns it on — `play-mode.ts`'s
+ * `installMultiWorldAuthoring` never passes it, so play mode's hierarchy is
+ * untouched by construction). `onIsolate` re-renders the SAME root against
+ * the isolated component (alone) instead of the entry — `render()` below is
+ * `renderStory`'s generalization: it picks `isolation` over `entryStory`
+ * whenever an isolation is active (see {@link LayerRenderState}'s doc
+ * comment).
+ *
+ * On success, mints the world's live `ReactWorldAuthoringAdapter` (the SAME
+ * construction recipe as `play-mode.ts`'s `installMultiWorldAuthoring`, plus
+ * the new `storySources`/`onStoryApplied`/`catalogComponents`/`onIsolate`/
+ * `worldId` options) over this layer's now-mounted DOM — the adapter reflects
+ * an already-mounted root, it never mounts one itself; this function is the
+ * design-time MOUNT B1/B2/B3 add, the adapter class itself is wholesale
+ * reused.
+ */
+async function mountReactLayer(
+  candidate: LayerCandidate,
+  layer: HTMLElement,
+  projectRoot: string,
+  store: EditorStore,
+): Promise<LayerMountResult> {
+  if (!candidate.path) {
+    throw new Error(
+      `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',
+  );
+  // 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
+  // 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 root = createRoot(layer);
+  const renderState: LayerRenderState = { entryStory: null, isolation: null };
+
+  /** Render the CURRENT layer state (entry or isolated — see
+   *  {@link LayerRenderState}) against the mounted root. Shared by the
+   *  initial mount and every subsequent `stories.apply`/`stories.isolate` —
+   *  React reconciles in place, never a remount (the inert `game`/
+   *  `GameProvider` stay the SAME instances — the inert-Game invariant). */
+  const render = (onCaught: (error: unknown) => void): void => {
+    const { entryStory, isolation } = renderState;
+    const story = isolation ? isolation.story : entryStory;
+    // An isolated key the catalog doesn't actually have is defensive-only —
+    // the adapter itself refuses to `isolate` an unregistered key — so
+    // `Component` falling through to `null` here should never observably
+    // happen; it's a safe degrade rather than a crash if it somehow did.
+    const Component = isolation ? catalogComponents?.[isolation.componentKey] : undefined;
+    const view = isolation
+      ? Component
+        ? createElement(Component, { ...(story?.props ?? {}) })
+        : null
+      : createElement(Entry, { ...(story?.props ?? {}) });
+    root.render(
+      createElement(DesignTimeErrorBoundary, {
+        // Key by the current view + applied story so switching stories, OR
+        // switching entry<->isolated, REMOUNTS the boundary (React unmounts a
+        // differently-keyed element at the same position), resetting its
+        // `crashed` latch — otherwise a story/isolation whose data makes the
+        // render throw would stick `crashed` and blank the world for the rest
+        // of the session even after picking a good story/exiting again.
+        key: isolation
+          ? `isolate:${isolation.componentKey}:${isolation.story?.id ?? ''}`
+          : story
+            ? `story:${story.id}`
+            : '__none__',
+        onCaught,
+        children: createElement(
+          UIDataProvider,
+          { data: createDataSource(story?.data ?? {}) },
+          createElement(GameProvider, { game }, view),
+        ),
+      }),
+    );
+  };
+
+  let caught: unknown = null;
+  flushSync(() => {
+    render((error: unknown) => {
+      caught = error;
+    });
+  });
+  if (caught !== null) {
+    root.unmount();
+    throw caught instanceof Error ? caught : new Error(String(caught));
+  }
+
+  const adapter = new ReactWorldAuthoringAdapter(layer, store, {
+    ...(import.meta.env.DEV ? { writeBackend: createHttpSourceWriteBackend() } : {}),
+    storySources,
+    worldId: candidate.worldId,
+    catalogComponents,
+    onStoryApplied: (story) => {
+      renderState.entryStory = story;
+      render((error: unknown) => {
+        editorConsole.error(
+          `[design-time-layers] world "${candidate.worldId}" crashed applying story ` +
+            `"${story?.id ?? '(cleared)'}": ${formatMountFailureMessage(error)}`,
+          'authoring',
+        );
+      });
+    },
+    onIsolate: (v) => {
+      renderState.isolation = v;
+      render((error: unknown) => {
+        editorConsole.error(
+          `[design-time-layers] world "${candidate.worldId}" crashed isolating ` +
+            `"${v?.componentKey ?? '(cleared)'}": ${formatMountFailureMessage(error)}`,
+          'authoring',
+        );
+      });
+    },
+  });
+  return {
+    adapter,
+    dispose: () => {
+      // A4 (spec 27 §3) — release the adapter's `vite:afterUpdate` echo-reconcile
+      // 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();
+      root.unmount();
+    },
+  };
+}
+
+/** Best-effort layer pixel size — the container should already be laid out
+ *  by the time this runs (mounted after `loadInitialScene` + the manifest
+ *  fetch both resolve), but falls back to a fixed floor rather than handing
+ *  Pixi/WebGL a degenerate 0×0 surface if it somehow isn't yet. */
+function measure(container: HTMLElement): { width: number; height: number } {
+  const rect = container.getBoundingClientRect();
+  return {
+    width: Math.max(1, Math.round(rect.width) || container.clientWidth || 300),
+    height: Math.max(1, Math.round(rect.height) || container.clientHeight || 200),
+  };
+}
+
+/**
+ * Pixi display-only design-time mount (B1) — `.scn2d` load
+ * (`fetchScene2DFile`, reused verbatim) + a ONE-SHOT render (no ongoing
+ * simulation/ticking at design time: this is a static disclosure, not a live
+ * preview). Reuses the exact production recipe (`PixiSceneGameAdapter.mount`,
+ * `transparent:true`, `autoStart:false` — the adapter's own default) rather
+ * than hand-rolling a leaner physics-free path: `loadScene2DFromData` still
+ * requires a full, real `World2DContext` (a real Rapier `World` +
+ * `ComponentManager` + `SystemRunner` — `packages/engine/src/world2d/types.ts`
+ * has no optional/physics-free fields), so there is no genuinely cheaper
+ * primitive available — this pays the one-time Rapier-wasm-init +
+ * component-attach cost once per pixi world, at design-time-layer-mount time.
+ * This is the explicitly chosen display-only depth for B1.
+ *
+ * Pixi is NOT upgraded to a live authoring adapter here: it stays
+ * Boundary-grade for the WHOLE S-B effort (display layer + B4's stage
+ * 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
+ * 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,
+  layer: HTMLElement,
+  container: HTMLElement,
+): 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`).',
+    );
+  }
+  const sceneData = await fetchScene2DFile(candidate.path);
+  const canvas = document.createElement('canvas');
+  canvas.style.width = '100%';
+  canvas.style.height = '100%';
+  canvas.style.display = 'block';
+  layer.appendChild(canvas);
+
+  const { width, height } = measure(container);
+  const adapter = new PixiSceneGameAdapter({ id: candidate.worldId, sceneData });
+  const mounted = await adapter.mount({ canvas, width, height, transparent: true });
+  mounted.update?.(0); // one-shot render — see doc comment above
+
+  // D12 (B4) — stage hit-test: client (browser) px -> the stage's own
+  // coordinate space (pixi's logical/CSS-pixel `renderer.screen`, NOT the
+  // resolution-scaled device-pixel framebuffer size) via the canvas's OWN
+  // rect, so a post-mount CSS resize (this layer's canvas is styled
+  // 100%/100%, `measure()` only runs once at mount time) is scaled correctly
+  // rather than assuming a 1:1 client-px-to-stage-unit mapping forever. A
+  // world with no live rect (e.g. torn down between the event and this call)
+  // degrades to `null` — never a stale/garbage hit.
+  const pick: PickProvider['pick'] = (clientX, clientY) => {
+    const rect = canvas.getBoundingClientRect();
+    if (rect.width === 0 || rect.height === 0) return null;
+    const screen = mounted.ctx.app.renderer.screen;
+    const localX = ((clientX - rect.left) / rect.width) * screen.width;
+    const localY = ((clientY - rect.top) / rect.height) * screen.height;
+    for (const child of mounted.stage.children) {
+      if (child.getBounds().containsPoint(localX, localY)) return candidate.worldId;
+    }
+    return null;
+  };
+
+  return { dispose: () => mounted.dispose(), pick };
+}
+
+/**
+ * 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.
+ *
+ * A no-op (returns a no-op disposer) when there is nothing to layer: a
+ * single-world project (back-compat floor, matches `installEditModeAuthoring`'s
+ * own single-world floor) or no resolvable current project.
+ *
+ * Play-mode handoff: the editor's Scene and Game tabs are BOTH always
+ * mounted (only one is `display`-visible at a time — the Game tab hosts
+ * `play-mode.ts`'s OWN, entirely separate composite/mount over a REAL,
+ * ticking `Game`). The instant play starts, this module tears its
+ * design-time layers down for the rest of THIS edit session: two
+ * independent DOM trees for the SAME react world (this inert stand-in,
+ * play-mode's live one) would otherwise carry the SAME `data-testid`s
+ * (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.
+ */
+export function mountDesignTimeLayers(
+  container: HTMLElement,
+  composite: CompositeAuthoringAdapter,
+  store: EditorStore,
+): () => 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
+  // `'editor:edit-mode-rebuild'` re-install — see `ViewportPanel.tsx`'s
+  // `installAll`), so a stale pan offset from a PREVIOUS layer stack must
+  // never carry over onto a different one.
+  resetWorldPan();
+  const projectRoot = getCurrentProject()?.rootPath;
+  const candidates = 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) {
+    return () => {};
+  }
+
+  // Bottom-to-top paint order — mirrors `create-runtime.ts`'s own stacking
+  // pass, over exactly the worlds 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 })));
+  const orderedCandidates = sorted.map((s) => candidates.find((c) => c.worldId === s.id)!);
+
+  const candidateByWorld = new Map(orderedCandidates.map((c) => [c.worldId, c]));
+  const layers = new Map<string, HTMLElement>();
+  const disposers: Array<() => void> = [];
+  // Worlds whose Boundary child we upgraded to a LIVE design-time adapter
+  // (successful react mounts). Tracked so the one-way play handoff can put an
+  // HONEST disclosure node back in the composite instead of leaving a live
+  // adapter over torn-down DOM (which renders silently empty — a #18 violation).
+  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,
+    );
+  }
+
+  function disposeEverything(): void {
+    for (const dispose of disposers.splice(0)) {
+      try {
+        dispose();
+      } catch (err) {
+        editorConsole.error(`[design-time-layers] dispose failed: ${err}`, 'authoring');
+      }
+    }
+    for (const layer of layers.values()) layer.remove();
+    layers.clear();
+  }
+
+  /**
+   * One-way 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
+   * 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
+   * 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;
+      const info: BoundaryWorldInfo = {
+        id: c.worldId,
+        kind: c.kind,
+        entryOrScenePath: c.path,
+        zOrder: c.zOrder,
+        pausable: c.pausable,
+      };
+      composite.replaceChild(
+        worldId,
+        new BoundaryAuthoringAdapter(
+          store,
+          info,
+          'Design-time layer suspended by play mode — reload the editor to restore it.',
+        ),
+      );
+    }
+    upgraded.clear();
+    store.notifyIngestEdit();
+  }
+
+  orderedCandidates.forEach((candidate, i) => {
+    const layer = createLayerElement(container, candidate.worldId, BASE_Z_INDEX + i);
+    layers.set(candidate.worldId, layer);
+
+    const mountPromise: Promise<LayerMountResult> =
+      candidate.kind === 'react'
+        ? mountReactLayer(candidate, layer, projectRoot, store)
+        : mountPixiLayer(candidate, layer, container);
+
+    mountPromise
+      .then((result) => {
+        if (torndown || playTeardownDone) {
+          result.dispose();
+          return;
+        }
+        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
+          // (pixi stays Boundary-grade for the whole S-B effort). Re-wrap the
+          // existing Boundary with the pick attached, and track it in
+          // `upgraded` too: `suspendForPlay` must revert THIS one back to a
+          // plain pick-less Boundary same as a react upgrade — a pick closing
+          // over a disposed pixi stage must not survive into play mode.
+          const info: BoundaryWorldInfo = {
+            id: candidate.worldId,
+            kind: candidate.kind,
+            entryOrScenePath: candidate.path,
+            zOrder: candidate.zOrder,
+            pausable: candidate.pausable,
+          };
+          composite.replaceChild(
+            candidate.worldId,
+            new BoundaryAuthoringAdapter(store, info, undefined, result.pick),
+          );
+          upgraded.add(candidate.worldId);
+        }
+        disposers.push(result.dispose);
+        store.notifyIngestEdit();
+      })
+      .catch((err: unknown) => {
+        layer.remove();
+        layers.delete(candidate.worldId);
+        if (torndown || playTeardownDone) return;
+        const message = formatMountFailureMessage(err);
+        editorConsole.error(
+          `[design-time-layers] world "${candidate.worldId}" (${candidate.kind}) failed to ` +
+            `mount: ${message}`,
+          'authoring',
+        );
+        const info: BoundaryWorldInfo = {
+          id: candidate.worldId,
+          kind: candidate.kind,
+          entryOrScenePath: candidate.path,
+          zOrder: candidate.zOrder,
+          pausable: candidate.pausable,
+        };
+        composite.replaceChild(
+          candidate.worldId,
+          new BoundaryAuthoringAdapter(store, info, message),
+        );
+        addMountFailureReport({
+          worldId: candidate.worldId,
+          kind: candidate.kind,
+          identity: candidate.kind === 'react' ? 'default-react' : 'default-pixi',
+          message,
+        });
+        store.notifyIngestEdit();
+      });
+  });
+
+  // D4 (spec27 §8 "space-pan" row) — the lockstep half of the pan feature:
+  // re-apply the current shared transform to every currently-mounted layer
+  // the instant it changes (`WorldSelectionOverlay`'s own outer wrapper binds
+  // the SAME `subscribeWorldPan`/`panTransformValue` pair independently — see
+  // `world-pan-state.ts`'s doc comment for why applying the identical value
+  // at both mount points is what keeps `rect(id)` pan-invariant). A cheap
+  // style write, never a remount.
+  const unsubPan = subscribeWorldPan(() => {
+    for (const layer of layers.values()) applyPanTransform(layer);
+  });
+
+  const unsubStore = store.subscribe(() => {
+    if (!playTeardownDone && store.playState !== 'stopped') {
+      playTeardownDone = true;
+      suspendForPlay();
+      return;
+    }
+    // Session toggles (eye/interactive) change via `store.notifyIngestEdit()`
+    // (`GameHierarchy.tsx`'s row affordances) — this is a cheap style
+    // re-apply, never a remount.
+    if (!playTeardownDone) {
+      for (const [worldId, layer] of layers) applySessionStyle(layer, worldId);
+      // B3 — "select elsewhere restores the entry": any-panel selection
+      // change (hierarchy row click, viewport pick, …) that no longer
+      // includes the isolated node exits isolation. Every store notification
+      // runs this (cheap — one hierarchy.node lookup per upgraded react
+      // world), covering every selection surface uniformly rather than
+      // wiring each one individually.
+      for (const { worldId, adapter } of composite.childAdapters()) {
+        if (!upgraded.has(worldId) || !(adapter instanceof ReactWorldAuthoringAdapter)) continue;
+        const isolatedId = adapter.isolatedNodeId;
+        if (isolatedId && !store.selectedEntityIds.has(isolatedId)) {
+          adapter.stories.isolate?.(null);
+        }
+      }
+    }
+  });
+
+  return () => {
+    torndown = true;
+    unsubStore();
+    unsubPan();
+    disposeEverything();
+    disposeUILayer?.();
+  };
+}