@volter/editor-game 0.5.65

package/src/host/components/scene-document.tsx

@@ -0,0 +1,447 @@
+/**
+ * THE SCENE DOCUMENT (`workspace:scene`): the active Three scene, titled
+ * `Scene` (the subject, not its entry file — see SCENE_DOCUMENT_TITLE),
+ * closeable and discoverable in Content, content = the world root's stage.
+ *
+ * Transcribed from the Scene half of vgai's `components/CenterDocuments.tsx`.
+ * The kit keeps the other half (`@volter/editor-core/components/CenterDocuments`
+ * `useCenterDocuments`): it binds the Game document's tab, reports the
+ * live/stopped edge and closes every document on session teardown. What moved
+ * here is only what the kit no longer does — synthesize the Scene document
+ * the kit still routes every three root's edit document to, and mirror the
+ * store's `activeViewportTab` into registry activation for the Scene/Game pair.
+ *
+ * THE INPUT-GATE CONTRACT (CLAUDE.md T6.3): `store.activeViewportTab`
+ * remains the single source of truth that `play-mode.ts`/`ingest/mount-ingest-root.ts`
+ * read (`playState === 'playing' && activeViewportTab === 'play'`) — this
+ * module NEVER replaces that predicate, it mirrors registry activation into
+ * it (descriptor `onActivate` → `setActiveViewportTab`) and store changes
+ * back into registry activation (`syncSceneDocument`, run on every store
+ * notify).
+ */
+
+import {
+  activeDocumentSourcePath,
+  activeSaveDestination,
+  activeSaveState,
+} from '@volter/editor-core/authoring/shell-document-ops';
+import { Object3DDocumentViewport } from '@volter/editor-core/components/Object3DDocumentViewport';
+import type { DocumentPreviewSource } from '@volter/editor-core/document-preview-source';
+import { editorConsole } from '@volter/editor-core/editor-console';
+import type { EditorShellStore, ViewportTab } from '@volter/editor-core/editor-shell-store';
+import { projectAdapterFacet, subscribeProjectAdapter } from '@volter/editor-core/project-adapter';
+import { getCurrentProject } from '@volter/editor-core/project-manager';
+import { isolationTabsReplaceGenericScene, sceneTabRow } from '@volter/editor-core/scene-document-plan';
+import {
+  registerAvailableWorkspaceDocument,
+  unregisterAvailableWorkspaceDocument,
+} from '@volter/editor-core/workspace-available-documents';
+import { GAME_DOCUMENT_ID, SCENE_DOCUMENT_ID } from '@volter/editor-core/workspace-document-ids';
+import {
+  activateWorkspaceDocument,
+  activeWorkspaceDocumentId,
+  openWorkspaceDocuments,
+  setWorkspaceDocumentDirty,
+  type WorkspaceDocumentContentProps,
+  type WorkspaceDocumentDescriptor,
+} from '@volter/editor-core/workspace-document-registry';
+import { Button, themeVars } from '@volter/editor-sdk/widgets';
+import { Component, type ErrorInfo, type ReactNode, useEffect, useState } from 'react';
+import { scheduleAfterPaint } from '../after-paint';
+
+/**
+ * The scene document's tab title. It is the WORD `Scene`, not the entry file's
+ * name: this document is the project's one three world, and a strip that reads
+ * `Scene · 3D · UI` names four subjects the same way instead of leaking one
+ * root's implementation file (`world.tsx`) into a rail of plain nouns. The
+ * authored source path is still the document's `provenance.sourcePath`, and
+ * the unsaved-changes dot is registry state (`dirty`) rather than title text,
+ * so both survive a fixed title.
+ */
+export const SCENE_DOCUMENT_TITLE = 'Scene';
+
+/** The narrow store surface this module reads/writes — kept minimal so the
+ *  bridge reads against a plain fake (no full EditorStore). */
+export interface CenterDocumentsStore {
+  subscribe(listener: () => void): () => void;
+  readonly playState: 'stopped' | 'playing' | 'paused';
+  readonly activeViewportTab: ViewportTab;
+  /** Where the ACTIVE authoring adapter's edits persist (its
+   *  `PersistenceProvider.destination`), or null when it persists nothing. */
+  readonly savePath: string | null;
+  /** Project-relative source path for an immediate-write document whose
+   *  adapter intentionally exposes no PersistenceProvider. */
+  readonly sourcePath?: string | null;
+  /** Whether the active authoring adapter has unsaved edits. */
+  readonly isDirty: boolean;
+  setActiveViewportTab(tab: ViewportTab): void;
+}
+
+/** The root Scene's preview stays available after its tab closes. Its source
+ * identity is read lazily because the three authoring adapter arrives after
+ * the workspace document is registered on a cold boot. */
+function rootScenePreviewSource(store: CenterDocumentsStore): DocumentPreviewSource {
+  const source = (): { path: string; exportName?: string } | null => {
+    const table = projectAdapterFacet()?.scenes;
+    const row = table
+      ? sceneTabRow(table).find((item) => item.plan.kind === 'root-document')
+      : undefined;
+    const declared = row?.entry.source;
+    const path = declared?.path ?? store.sourcePath ?? store.savePath;
+    return path
+      ? { path, ...(declared?.export === undefined ? {} : { exportName: declared.export }) }
+      : null;
+  };
+  return {
+    revision: () => {
+      const current = source();
+      return current ? `${current.path}:${current.exportName ?? 'default'}` : 'unavailable';
+    },
+    subscribe: (listener) => {
+      let identity = JSON.stringify(source());
+      const changed = () => {
+        const next = JSON.stringify(source());
+        if (next === identity) return;
+        identity = next;
+        listener();
+      };
+      const stopStore = store.subscribe(changed);
+      const stopAdapter = subscribeProjectAdapter(changed);
+      return () => {
+        stopStore();
+        stopAdapter();
+      };
+    },
+    capture: async (request) => {
+      const current = source();
+      if (!current) throw new Error('The Scene has no declared source module to preview.');
+      const owner = await import('./ThreeIsolationSceneContent');
+      return owner.captureThreeIsolationScenePreview(
+        {
+          path: current.path,
+          exportName: current.exportName,
+          label: SCENE_DOCUMENT_TITLE,
+        },
+        request,
+      );
+    },
+  };
+}
+
+interface ViewportErrorBoundaryState {
+  error: Error | null;
+  /** Whether an automatic retry is currently scheduled — tracked as state
+   *  (not inferred from the timer field) so the "retrying…" copy is part of
+   *  the same render pass `componentDidCatch` triggers when it schedules one. */
+  autoRetryPending: boolean;
+}
+
+/** THREE's context-creation failure message for the transient
+ *  Chromium/SwiftShader GPU-channel race that occasionally loses at editor
+ *  boot — distinct from a genuinely dead/unsupported renderer, which fails
+ *  differently. */
+const TRANSIENT_RENDERER_STARTUP_FAILURE_PATTERN = /creating WebGL context/i;
+
+/** The SAME transient class in its other spelling: the context was created but
+ *  came back already dead, so THREE's capability probe reads `precision` off
+ *  the `null` that `getShaderPrecisionFormat` returns on a lost context. Seen
+ *  live while a project's thumbnail sweep was churning short-lived contexts —
+ *  the same renderer boots fine on the retry, exactly like the class above. */
+const TRANSIENT_DEAD_CONTEXT_PATTERN = /null \(reading 'precision'\)/;
+
+/** True when `error` matches the transient renderer-startup failure class. */
+export function isTransientRendererStartupFailure(error: Error): boolean {
+  return (
+    TRANSIENT_RENDERER_STARTUP_FAILURE_PATTERN.test(error.message) ||
+    TRANSIENT_DEAD_CONTEXT_PATTERN.test(error.message)
+  );
+}
+
+/** Bound on automatic retries per boundary instance — see `componentDidCatch`. */
+const MAX_AUTO_RETRIES = 3;
+
+/** A renderer failure must degrade the Scene document, not unmount the whole
+ * workspace. The surrounding hierarchy, Inspector, Console, menus,
+ * and project resources remain usable, with an explicit retry after the old
+ * renderer/context has been torn down.
+ *
+ * A transient WebGL context-creation failure at boot would otherwise kill the
+ * viewport permanently even though the SAME renderer boots fine moments
+ * later. For that specific, recognizable failure class the boundary retries
+ * automatically with backoff BEFORE surfacing the manual button — bounded to
+ * 3 attempts per boundary instance so a genuinely dead renderer still ends up
+ * in front of the user with the manual UI. */
+export class ViewportErrorBoundary extends Component<
+  { children: ReactNode },
+  ViewportErrorBoundaryState
+> {
+  override state: ViewportErrorBoundaryState = { error: null, autoRetryPending: false };
+
+  /** Automatic retries already used by THIS boundary instance — never reset
+   *  by a manual retry click, so a manual click after the auto-budget is
+   *  exhausted does not re-open the budget. */
+  private autoRetryCount = 0;
+  // `window.setTimeout` (DOM lib) returns `number`; typed explicitly rather
+  // than via `ReturnType<typeof setTimeout>` because @types/node's ambient
+  // overload would otherwise mis-widen this to `Timeout`.
+  private retryTimer: number | null = null;
+
+  static getDerivedStateFromError(error: Error): ViewportErrorBoundaryState {
+    return { error, autoRetryPending: false };
+  }
+
+  private clearPendingRetry(): void {
+    if (this.retryTimer !== null) {
+      window.clearTimeout(this.retryTimer);
+      this.retryTimer = null;
+    }
+  }
+
+  override componentDidCatch(error: Error, info: ErrorInfo): void {
+    editorConsole.error(`Viewport failed to start: ${error.message}`, 'editor');
+    // Keep the component stack in the browser console for developer diagnosis.
+    // biome-ignore lint/suspicious/noConsole: renderer startup failures need their React component stack in developer tools as well as the user-facing editor Console entry
+    console.error('[vgai] Viewport failed to start', error, info.componentStack);
+
+    if (isTransientRendererStartupFailure(error) && this.autoRetryCount < MAX_AUTO_RETRIES) {
+      this.clearPendingRetry();
+      const delayMs = 500 * 2 ** this.autoRetryCount;
+      this.autoRetryCount++;
+      this.retryTimer = window.setTimeout(() => {
+        this.retryTimer = null;
+        this.setState({ error: null, autoRetryPending: false });
+      }, delayMs);
+      this.setState({ autoRetryPending: true });
+    }
+  }
+
+  override componentWillUnmount(): void {
+    this.clearPendingRetry();
+  }
+
+  private handleManualRetry = (): void => {
+    // A manual click also cancels any pending auto-retry (the boundary must
+    // not race a scheduled retry against the user's own), but deliberately
+    // does NOT reset `autoRetryCount` — the auto-retry budget is per
+    // boundary instance, not per error occurrence.
+    this.clearPendingRetry();
+    this.setState({ error: null, autoRetryPending: false });
+  };
+
+  override render() {
+    if (!this.state.error) return this.props.children;
+    const retryPending = this.state.autoRetryPending;
+    return (
+      <div
+        data-testid="viewport-startup-error"
+        role="alert"
+        style={{
+          position: 'absolute',
+          inset: 0,
+          display: 'flex',
+          flexDirection: 'column',
+          alignItems: 'center',
+          justifyContent: 'center',
+          gap: 8,
+          padding: 24,
+          background: themeVars.surface.shell,
+          color: themeVars.content.muted,
+          textAlign: 'center',
+        }}
+      >
+        <div style={{ color: themeVars.content.primary, fontSize: 14 }}>
+          {retryPending ? 'Viewport unavailable — retrying…' : 'Viewport unavailable'}
+        </div>
+        <div style={{ maxWidth: 520, color: themeVars.content.dim, fontSize: 11 }}>
+          {this.state.error.message}
+        </div>
+        <Button
+          type="button"
+          className="vgai-btn"
+          data-testid="retry-viewport"
+          onClick={this.handleManualRetry}
+        >
+          Retry Viewport
+        </Button>
+      </div>
+    );
+  }
+}
+
+/**
+ * The Scene document's content: the kit's ONE 3D STAGE HOST, showing the
+ * world root. It is a document like any other — same host, same furniture,
+ * same overlays, same per-stage door — and the ONE thing it says that a
+ * prefab's stage does not is WHAT it shows (`content`): the world, through
+ * this package's world-root binding, loaded only when a Scene stage mounts.
+ *
+ * The after-paint gate owns the mount of everything below it — the viewport
+ * door's binding included — so it may never be scheduled on a bare rAF chain.
+ * A hidden tab fires no frames at all and the editor would boot to a
+ * heartbeating shell that can never start play.
+ */
+const SCENE_CONTENT = {
+  kind: 'world-root',
+  load: () => import('./world-root-stage-binding').then((module) => module.worldRootStageBinding),
+} as const;
+
+function SceneDocumentContent({ documentId, active }: WorkspaceDocumentContentProps) {
+  const [ready, setReady] = useState(false);
+  useEffect(() => scheduleAfterPaint(() => setReady(true)), []);
+  return (
+    <ViewportErrorBoundary>
+      {ready ? (
+        <Object3DDocumentViewport
+          documentId={documentId}
+          active={active}
+          content={SCENE_CONTENT}
+          displayName={SCENE_DOCUMENT_TITLE}
+        />
+      ) : null}
+    </ViewportErrorBoundary>
+  );
+}
+
+/** Build the Scene document descriptor bound to a store. `onActivate` is the
+ *  registry→store half of the bridge: activating the tab (click, open,
+ *  close-neighbor fallback) writes the store's `activeViewportTab`, which is
+ *  what the T6.3 input gate reads. */
+export function createCenterDocumentDescriptors(store: CenterDocumentsStore): {
+  scene: WorkspaceDocumentDescriptor;
+} {
+  const documentPath = store.sourcePath ?? store.savePath;
+  const scene: WorkspaceDocumentDescriptor = {
+    id: SCENE_DOCUMENT_ID,
+    title: SCENE_DOCUMENT_TITLE,
+    kind: 'scene',
+    workspaceRole: 'authored-subject',
+    ...(documentPath ? { provenance: { sourcePath: documentPath } } : {}),
+    Content: SceneDocumentContent,
+    preview: rootScenePreviewSource(store),
+    presentation: () =>
+      store.savePath
+        ? { kind: 'scene', path: store.savePath }
+        : { kind: 'workspace', id: SCENE_DOCUMENT_ID },
+    onActivate: () => store.setActiveViewportTab('edit'),
+  };
+  return { scene };
+}
+
+/**
+ * The store→registry half of the bridge for the Scene/Game pair. Idempotent —
+ * safe (and designed) to run on EVERY store notify; re-entrant calls triggered
+ * by its own `onActivate` → `setActiveViewportTab` → notify chain settle as
+ * no-ops. The Game document's live/stopped edge is the kit's
+ * (`useCenterDocuments`), not repeated here.
+ *
+ *  1. the scene document is available when the manifest has a Three root;
+ *  2. its tab's dirty dot tracks `isDirty` live (the title is fixed);
+ *  3. the active document mirrors `activeViewportTab` (auto-switch on
+ *     play/stop, `set-viewport-tab` control commands, the ingest mount lane's
+ *     direct writes). A `play` tab value with no Game document open (stopped,
+ *     or a transient store state) activates the scene if its tab is open.
+ */
+export function syncCenterDocuments(
+  store: CenterDocumentsStore,
+  docs: { scene: WorkspaceDocumentDescriptor },
+  hasThreeRoot = true,
+): void {
+  const isOpen = (id: string) => openWorkspaceDocuments().some((d) => d.descriptor.id === id);
+  // Opening a registry document activates it. Capture the caller's requested
+  // viewport before touching the open set, then restore that intent below.
+  const requestedViewportTab = store.activeViewportTab;
+
+  const table = projectAdapterFacet()?.scenes;
+  if (hasThreeRoot && !(table && isolationTabsReplaceGenericScene(table))) {
+    const row = table
+      ? sceneTabRow(table).find((item) => item.plan.kind === 'root-document')
+      : undefined;
+    registerAvailableWorkspaceDocument(
+      {
+        ...docs.scene,
+        title: row?.plan.kind === 'root-document' ? row.plan.title : docs.scene.title,
+        provenance: {
+          ...docs.scene.provenance,
+          ...(row?.entry.source?.path ? { sourcePath: row.entry.source.path } : {}),
+          ...(row?.plan.kind === 'root-document' ? { rootId: row.plan.regionId } : {}),
+        },
+      },
+      {
+        category: 'scene',
+        rootId: row?.plan.kind === 'root-document' ? row.plan.regionId : undefined,
+        default: table !== undefined && (row?.isDefault ?? table.entries.length === 0),
+      },
+    );
+    setWorkspaceDocumentDirty(SCENE_DOCUMENT_ID, store.isDirty);
+  } else {
+    unregisterAvailableWorkspaceDocument(SCENE_DOCUMENT_ID);
+  }
+
+  // Mirror the store tab into registry activation. A THIRD-party document
+  // being active is a legitimate state (its own onActivate already asserted
+  // the store's tab, so the T6.3 gate is off). The mirror therefore only
+  // corrects genuine disagreements about the SCENE/GAME pair:
+  //   - tab says 'play' (play auto-switch, `set-viewport-tab play`) → the
+  //     Game document must be active;
+  //   - tab says 'edit' while the GAME document is active (external
+  //     `set-viewport-tab edit` during play) → back to the scene document;
+  //   - no active document at all (first run) → the scene document.
+  // An 'edit' tab with an asset/story document active is CONSISTENT and must
+  // not be "corrected".
+  const activeId = activeWorkspaceDocumentId();
+  if (requestedViewportTab === 'play' && isOpen(GAME_DOCUMENT_ID)) {
+    if (activeId !== GAME_DOCUMENT_ID) activateWorkspaceDocument(GAME_DOCUMENT_ID);
+  } else if (hasThreeRoot && (activeId === GAME_DOCUMENT_ID || activeId === null)) {
+    activateWorkspaceDocument(SCENE_DOCUMENT_ID);
+  }
+}
+
+/**
+ * Installs the Scene document for one session store and keeps it synced. The
+ * returned teardown stops syncing; the service withdraws the Scene document, and the kit's
+ * `useCenterDocuments` closes every open document on session teardown.
+ */
+export function bindSceneDocument(store: EditorShellStore): () => void {
+  // `savePath`/`isDirty` are the ACTIVE authoring adapter's, read live
+  // through getters rather than copied — the shell owns neither.
+  // Keep the authored source identity across Edit → Play: Play deliberately
+  // swaps in a live adapter with no source document, but the Scene
+  // tab still represents the same authored TSX document.
+  let lastSourcePath: string | null = null;
+  const view: CenterDocumentsStore = {
+    subscribe: (listener) => store.subscribe(listener),
+    get playState() {
+      return store.playState;
+    },
+    get activeViewportTab() {
+      return store.activeViewportTab;
+    },
+    get savePath() {
+      return activeSaveDestination(store);
+    },
+    get sourcePath() {
+      const current = activeDocumentSourcePath(store);
+      if (current) lastSourcePath = current;
+      return lastSourcePath;
+    },
+    get isDirty() {
+      return activeSaveState(store) === 'unsaved';
+    },
+    setActiveViewportTab: (tab) => store.setActiveViewportTab(tab),
+  };
+  const docs = createCenterDocumentDescriptors(view);
+  // Missing is the legacy-safe default: manifests read by current editor
+  // versions always carry this derived flag.
+  const run = () =>
+    syncCenterDocuments(view, docs, getCurrentProject()?.config.hasThreeRoot !== false);
+  run();
+  const unsubscribe = store.subscribe(run);
+  const unsubscribeAdapter = subscribeProjectAdapter(run);
+  // Unbinding follows the session's store and leaves the document registered:
+  // a store arriving again at boot must not close a restored Scene tab. The
+  // service withdraws the document when it stops.
+  return () => {
+    unsubscribe();
+    unsubscribeAdapter();
+  };
+}

package/src/host/components/utility-view-state.ts

@@ -0,0 +1,87 @@
+/**
+ * Selected view for each bottom-drawer utility that hosts more than one
+ * instrument.
+ *
+ * Every store is the usual `useSyncExternalStore` triple (subscribe, version,
+ * active) plus `open`, which selects the view AND reveals its own utility
+ * through the semantic dock command. Callers name the utility they mean:
+ * `profilerView` is the engine instrument bench (Profiler/Frame).
+ *
+ * A game's own faces are deliberately not among them. They are PROJECT
+ * contributions — the game's own vendored source, mounted through the
+ * contribution registries — and a contribution owns whatever state it needs
+ * inside its own module, so there is nothing for this editor-owned store to
+ * hold on its behalf. This store survives on the host side only because HOST
+ * chrome reads it: the header heartbeat and the Game toolbar's Capture frame
+ * button both select a view of a bench that now ships in `@volter/editor-game`.
+ */
+
+import { showWorkspaceUtility } from '@volter/editor-core/workspace-host-commands';
+
+export type ProfilerViewId = 'profiler' | 'frame';
+
+export interface UtilityViewState<T extends string> {
+  subscribe(listener: () => void): () => void;
+  /** Monotonic change counter — the `getSnapshot` for `useSyncExternalStore`. */
+  version(): number;
+  active(): T;
+  select(view: T): void;
+  /** Select the view and reveal its utility in the bottom region. */
+  open(view: T): void;
+  /** Re-publish without changing the view (state this store carries beside
+   *  the selected view, e.g. the selected machine, notifies through here). */
+  notify(): void;
+  reset(): void;
+}
+
+function createUtilityViewState<T extends string>(
+  utilityId: string,
+  initial: T,
+): UtilityViewState<T> {
+  let active = initial;
+  let version = 0;
+  const listeners = new Set<() => void>();
+  const notify = () => {
+    version++;
+    for (const listener of listeners) listener();
+  };
+  const select = (view: T) => {
+    if (active === view) return;
+    active = view;
+    notify();
+  };
+  return {
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    version: () => version,
+    active: () => active,
+    select,
+    open(view) {
+      select(view);
+      showWorkspaceUtility(utilityId);
+    },
+    notify,
+    reset() {
+      active = initial;
+      notify();
+    },
+  };
+}
+
+/** Engine instruments: the Profiler and the single-frame draw-call capture. */
+export const profilerView = createUtilityViewState<ProfilerViewId>(
+  // The bench is `@volter/editor-game`'s `profiler.utility` contribution, so its
+  // registered id carries the host's `tool:` namespace. This store stays on
+  // the host side because host chrome reads it (`HeaderTelemetry`'s heartbeat,
+  // the Game toolbar's Capture frame button).
+  'tool:profiler.utility',
+  'profiler',
+);
+
+export function __resetUtilityViewStateForTest(): void {
+  profilerView.reset();
+}

package/src/host/components/world-root-stage-binding.tsx

@@ -0,0 +1,133 @@
+/**
+ * THE GAME'S WORLD-ROOT BINDING for the kit's stage host
+ * (`@volter/editor-core/components/world-root-binding`): the world's surface,
+ * its stage, and the overlays the stage shows only over a world.
+ *
+ * `Overlays` is the world-root half of vgai's `stage-overlay-set.tsx` — every
+ * part it rendered only when `worldRoot` held (the root selection layer, the
+ * camera-authoring pin, the controls hint while the world mounts, the scene's
+ * surface-state card). The rest of that overlay set is the kit's
+ * `StageOverlays`, which the host renders beside this.
+ */
+import { EDITOR_LAYER } from '@volter/editor-threejs/viewport/editor-layers';
+import { activeAuthoringVersion, subscribeActiveAuthoring } from '@volter/editor-core/authoring/active-adapter';
+import {
+  getMountFailureReports,
+  subscribeToMountFailures,
+} from '@volter/editor-core/authoring/mount-failure-report';
+import {
+  object3DDocumentSessionsVersion,
+  subscribeObject3DDocumentSessions,
+} from '@volter/editor-core/authoring/object3d-document-session-registry';
+import { RootSelectionOverlay } from '@volter/editor-core/components/RootSelectionOverlay';
+import { SurfaceStateOverlay } from '@volter/editor-core/components/SurfaceStateOverlay';
+import { ViewportControlsHint } from '@volter/editor-core/components/ViewportControlsHint';
+import type {
+  WorldRootOverlayProps,
+  WorldRootStageBinding,
+} from '@volter/editor-core/components/world-root-binding';
+import type { EditorShellStore } from '@volter/editor-core/editor-shell-store';
+import { readinessFacet, subscribeRootReadiness } from '@volter/editor-core/readiness';
+import { documentStageContext, threeSelectionToolsApply } from '@volter/editor-core/stage-context';
+import { explainSurface } from '@volter/editor-core/surface-state';
+import {
+  subscribeWorkspaceDocuments,
+  workspaceDocumentRegistryVersion,
+} from '@volter/editor-core/workspace-document-registry';
+import { useMemo, useSyncExternalStore } from 'react';
+import type * as THREE from 'three';
+import { threeSceneHasRenderableContent } from '../surface-content';
+import { CameraAuthoringOverlay } from './CameraAuthoringOverlay';
+import { installWorldRootStage, mountWorldRootSurface } from './world-root-stage';
+
+/**
+ * The scene-status overlay is the sole viewport child whose truth can change
+ * from object-map membership alone (an empty live scene may gain its first
+ * renderable object). Keep that exact broad subscription here so runtime
+ * structure does not rerender the canvas, chrome, or collaboration surface.
+ */
+function SceneViewportStateOverlay({
+  store,
+  rootIds,
+  mountStatus,
+}: {
+  store: EditorShellStore;
+  rootIds: readonly string[];
+  mountStatus: 'mounting' | 'ready';
+}) {
+  useSyncExternalStore(store.subscribe, store.getSnapshot);
+  const rootReadiness = useSyncExternalStore(subscribeRootReadiness, readinessFacet);
+  const mountFailures = useSyncExternalStore(subscribeToMountFailures, getMountFailureReports);
+  const sceneBackground = store.scene?.background as THREE.Color | null | undefined;
+  const sceneBackgroundIsAuthored =
+    sceneBackground !== null &&
+    !(sceneBackground?.isColor === true && sceneBackground.getHex() === 0xaaaaaa);
+  const sceneHasRenderableObjects = useMemo(
+    () =>
+      Boolean(
+        store.scene &&
+          threeSceneHasRenderableContent(store.scene, {
+            includeBackground: false,
+            ignoredLayer: EDITOR_LAYER,
+          }),
+      ),
+    [store.scene, store.contentVersion],
+  );
+  const sceneHasContent = Boolean(
+    store.scene && (sceneBackgroundIsAuthored || sceneHasRenderableObjects),
+  );
+  const explanation = explainSurface({
+    surface: 'Scene',
+    rootIds,
+    phase: mountStatus === 'mounting' ? 'loading' : 'ready',
+    content: sceneHasContent ? 'present' : mountStatus === 'mounting' ? 'unknown' : 'empty',
+    readiness: rootReadiness,
+    failures: mountFailures,
+  });
+  return <SurfaceStateOverlay explanation={explanation} testId="scene-viewport-status" />;
+}
+
+function WorldRootOverlays({
+  store,
+  documentId,
+  cameraPreviewRef,
+  mountStatus,
+  rootIds,
+}: WorldRootOverlayProps) {
+  useSyncExternalStore(store.subscribe, store.getShellSnapshot ?? store.getSnapshot);
+  useSyncExternalStore(subscribeActiveAuthoring, activeAuthoringVersion);
+  useSyncExternalStore(subscribeObject3DDocumentSessions, object3DDocumentSessionsVersion);
+  useSyncExternalStore(subscribeWorkspaceDocuments, workspaceDocumentRegistryVersion);
+  // The world root's stage is the Scene document's: the kit's overlay props
+  // carry no document id, and the Scene document is the one world-root stage.
+  const ctx = documentStageContext(store, documentId, 'document');
+  const showsSelectionTools = threeSelectionToolsApply(ctx);
+  return (
+    <>
+      {/* Three-scene selection overlay. React/Pixi documents mount their own
+          co-located overlay beside the isolated world host, and the worlds it
+          draws over are the manifest's — so its condition is the stage showing
+          them, the same fact the surface-state card reads. */}
+      {ctx.surface !== null ? <RootSelectionOverlay /> : null}
+      {/* A pinned camera preview survives deselection. The camera-authoring
+          host is installed by the world root's own binding
+          (`world-root-stage.ts`), so the pin belongs to the stage that
+          installed it. */}
+      {ctx.surface === 'three' ? <CameraAuthoringOverlay previewRef={cameraPreviewRef} /> : null}
+      {/* The hint also shows WHILE the world is still mounting: a new user
+          reads the screen during those boot seconds and looks for the camera
+          controls exactly then. The kit's overlay set shows it on a three
+          surface; this adds only the mounting case it does not cover. */}
+      {!showsSelectionTools && ctx.surface !== 'three' && mountStatus === 'mounting' ? (
+        <ViewportControlsHint />
+      ) : null}
+      <SceneViewportStateOverlay store={store} rootIds={rootIds} mountStatus={mountStatus} />
+    </>
+  );
+}
+
+export const worldRootStageBinding: WorldRootStageBinding = {
+  mountWorldRootSurface,
+  installWorldRootStage,
+  Overlays: WorldRootOverlays,
+};