@vgai/editor 0.2.0 → 0.4.0-canary.20260715.0

package/src/components/CenterDocuments.tsx

@@ -0,0 +1,585 @@
+import { Button, Menu, MenuItem, themeVars } from '../design-system';
+/**
+ * W1 (docs/EDITOR-WORKSPACE-SHELL-TODO.md §9/W1) — the first two workspace
+ * DOCUMENT implementers (§7.1) and the bridge that keeps the document
+ * registry and the editor store's `activeViewportTab` agreeing:
+ *
+ *  - the SCENE document (`workspace:scene`): the active Three scene, titled
+ *    with its source-owned name (§8 — `Default.vscn`, never `Viewport`),
+ *    non-closeable (there is always a center document), content =
+ *    `ViewportPanel` (which keeps owning the renderer/RAF/hotkeys — its
+ *    overlays ToolStrip/ViewportOverlay/CameraInfo/WorldSelectionOverlay
+ *    move WITH it into the document, per inventory rows V5–V7/V11);
+ *  - the GAME document (`workspace:game`): the live player-facing composite,
+ *    titled `Game` (§8), pinned, always open, and always the leftmost anchor.
+ *    While stopped it shows an explicit empty state rather than stale runtime
+ *    pixels. Dockview renders it with
+ *    `renderer: "always"`, so its canvas container exists before Play's
+ *    asynchronous setup and survives tab/group changes.
+ *
+ * THE INPUT-GATE CONTRACT (CLAUDE.md T6.3): `store.activeViewportTab`
+ * remains the single source of truth that `play-mode.ts`/`ingest-mode.ts`
+ * read (`playState === 'playing' && activeViewportTab === 'game'`) — this
+ * module NEVER replaces that predicate, it mirrors registry activation into
+ * it (descriptor `onActivate` → `setActiveViewportTab`) and store changes
+ * back into registry activation (`syncCenterDocuments`, run on every store
+ * notify). Play auto-switch (enter play → Game tab, stop → Scene tab) stays
+ * store-driven (`setPlayState`), so `vgai select-tab`-style control commands
+ * (`command-listener.ts`'s `set-viewport-tab`) and every ingest/module-mode
+ * `setActiveViewportTab` call keep working unchanged.
+ *
+ * Lifecycle: `enterPlayMode` requires the game container to exist BEFORE
+ * play starts (`setGameContainer`). The pinned document plus Dockview's
+ * always-rendered panel mode is the one continuous React instance that
+ * satisfies that requirement.
+ */
+
+import {
+  Component,
+  type ErrorInfo,
+  type ReactNode,
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+  useSyncExternalStore,
+} from 'react';
+import { DisclosureIcon } from '../design-system';
+import { useEditorStore } from '../EditorContext';
+import { editorConsole } from '../editor-console';
+import { getGameProfiler, resizeGame, setGameContainer } from '../play-mode';
+import { GAME_DOCUMENT_ID, SCENE_DOCUMENT_ID } from '../workspace-document-ids';
+import {
+  activateWorkspaceDocument,
+  activeWorkspaceDocumentId,
+  closeAllWorkspaceDocuments,
+  openWorkspaceDocument,
+  openWorkspaceDocuments,
+  setWorkspaceDocumentDirty,
+  setWorkspaceDocumentTitle,
+  type WorkspaceDocumentContentProps,
+  type WorkspaceDocumentDescriptor,
+} from '../workspace-document-registry';
+import { openDebuggerPanel } from './debugger-panel-state';
+import { GamePerformanceOverlay } from './GamePerformanceOverlay';
+import { MuteButton, type Resolution, ResolutionPicker } from './PlayBar';
+import { ViewportPanel } from './ViewportPanel';
+
+/** Stable identity (§7.1) of the single active-scene center document. The
+ *  SLOT is stable while the scene it shows can change (root activation,
+ *  prefab edit) — the tab's title tracks `store.savePath` live via
+ *  `setWorkspaceDocumentTitle`, keeping "there is always a center document"
+ *  true without close/reopen churn. */
+export { GAME_DOCUMENT_ID, SCENE_DOCUMENT_ID } from '../workspace-document-ids';
+/** Stable identity (§7.1) of the Game preview document. */
+
+/** §8 source-owned tab title for the active scene document: the file's own
+ *  basename with the serialization suffix dropped (`scenes/Default.vscn.json`
+ *  → `Default.vscn`, `x/Crate.prefab.json` → `Crate.prefab`) — matching the
+ *  TODO's §4.1 mock. `Untitled` only when no source file exists yet. */
+export function sceneDocumentTitle(savePath: string | null): string {
+  if (!savePath) return 'Untitled';
+  const base = savePath.split('/').pop() ?? savePath;
+  return base.endsWith('.json') ? base.slice(0, -'.json'.length) : base;
+}
+
+/** The narrow store surface this module reads/writes — kept minimal so the
+ *  bridge is unit-testable against a plain fake (no full EditorStore). */
+export interface CenterDocumentsStore {
+  subscribe(listener: () => void): () => void;
+  readonly playState: 'stopped' | 'playing' | 'paused';
+  readonly activeViewportTab: 'scene' | 'game';
+  readonly savePath: string | null;
+  readonly isDirty: boolean;
+  setActiveViewportTab(tab: 'scene' | 'game'): void;
+}
+
+interface ViewportErrorBoundaryState {
+  error: Error | null;
+}
+
+/** A renderer failure must degrade the Scene document, not unmount the whole
+ * Dockview 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. */
+export class ViewportErrorBoundary extends Component<
+  { children: ReactNode },
+  ViewportErrorBoundaryState
+> {
+  override state: ViewportErrorBoundaryState = { error: null };
+
+  static getDerivedStateFromError(error: Error): ViewportErrorBoundaryState {
+    return { error };
+  }
+
+  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);
+  }
+
+  override render() {
+    if (!this.state.error) return this.props.children;
+    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 }}>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.setState({ error: null })}
+        >
+          Retry Viewport
+        </Button>
+      </div>
+    );
+  }
+}
+
+function SceneDocumentContent(_props: WorkspaceDocumentContentProps) {
+  return (
+    <ViewportErrorBoundary>
+      <ViewportPanel />
+    </ViewportErrorBoundary>
+  );
+}
+
+// --- Game document view state (W2, inventory row V4) -----------------------
+// Resolution/scale are shared between the Game document's CONTENT (which
+// owns the canvas resize/scale math) and its document-local TOOLBAR (which
+// hosts the picker + mute, §6.3 "Game mute/resolution controls appear only
+// in the Game document") — a tiny module-scope store in the house
+// `useSyncExternalStore` shape, session-scoped like the old GamePanel state.
+
+let _gameResolution: Resolution = { label: 'Fill', width: null, height: null };
+let _gameScale = 1;
+let _gameStatsVisible = false;
+let _gameViewVersion = 0;
+const _gameViewListeners = new Set<() => void>();
+
+function notifyGameView(): void {
+  _gameViewVersion++;
+  for (const fn of _gameViewListeners) fn();
+}
+
+function subscribeGameView(fn: () => void): () => void {
+  _gameViewListeners.add(fn);
+  return () => {
+    _gameViewListeners.delete(fn);
+  };
+}
+
+const gameViewVersion = () => _gameViewVersion;
+
+/** The Game document's current resolution selection (exported for tests). */
+export function gameDocumentResolution(): Resolution {
+  return _gameResolution;
+}
+
+/** Set the Game document's resolution (exported for tests). */
+export function setGameDocumentResolution(resolution: Resolution): void {
+  _gameResolution = resolution;
+  notifyGameView();
+}
+
+export function gameStatsVisible(): boolean {
+  return _gameStatsVisible;
+}
+
+export function setGameStatsVisible(visible: boolean): void {
+  if (_gameStatsVisible === visible) return;
+  _gameStatsVisible = visible;
+  if (visible) {
+    const profiler = getGameProfiler();
+    if (profiler) profiler.enabled = true;
+  }
+  notifyGameView();
+}
+
+function setGameScale(scale: number): void {
+  if (scale === _gameScale) return;
+  _gameScale = scale;
+  notifyGameView();
+}
+
+function GameStatsMenu() {
+  const [open, setOpen] = useState(false);
+  const ref = useRef<HTMLDivElement>(null);
+  useEffect(() => {
+    if (!open) return;
+    const onPointerDown = (event: PointerEvent) => {
+      if (!ref.current?.contains(event.target as Node)) setOpen(false);
+    };
+    document.addEventListener('pointerdown', onPointerDown);
+    return () => document.removeEventListener('pointerdown', onPointerDown);
+  }, [open]);
+  return (
+    <div ref={ref} style={{ position: 'relative' }}>
+      <Button
+        type="button"
+        variant="outline"
+        size="compact"
+        data-testid="game-stats-menu"
+        aria-expanded={open}
+        onClick={() => setOpen((value) => !value)}
+      >
+        <span>Stats</span>
+        <DisclosureIcon direction="down" />
+      </Button>
+      {open && (
+        <Menu
+          style={{
+            position: 'absolute',
+            right: 0,
+            top: 'calc(100% + 3px)',
+            zIndex: 20,
+            minWidth: 190,
+          }}
+        >
+          <MenuItem onClick={() => setGameStatsVisible(!_gameStatsVisible)}>
+            {_gameStatsVisible ? '✓ ' : '  '}Show live overlay
+          </MenuItem>
+          <MenuItem
+            onClick={() => {
+              const profiler = getGameProfiler();
+              if (profiler) {
+                const recording = profiler.getSnapshot().recording;
+                recording ? profiler.stopRecording() : profiler.startRecording();
+                notifyGameView();
+              }
+            }}
+          >
+            {getGameProfiler()?.getSnapshot().recording ? 'Stop capture' : 'Start capture'}
+          </MenuItem>
+          <MenuItem onClick={() => openDebuggerPanel('profiler')}>Open Profiler</MenuItem>
+          <MenuItem onClick={() => openDebuggerPanel('network')}>Open Network Diagnostics</MenuItem>
+        </Menu>
+      )}
+    </div>
+  );
+}
+
+/**
+ * The Game document's LOCAL toolbar (§7.1 toolbar contribution, rendered by
+ * `WorkspaceDock` inside the Game document only while that panel is
+ * active): resolution picker + mute — the V4 remainder deferred from W1.
+ * Transport (play/pause/stop) deliberately stays in the global `PlayBar`.
+ */
+export function GameDocumentToolbar(_props: WorkspaceDocumentContentProps) {
+  useSyncExternalStore(subscribeGameView, gameViewVersion);
+  return (
+    <div
+      data-testid="game-doc-toolbar"
+      style={{
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'flex-end',
+        gap: 6,
+        padding: '2px 8px',
+      }}
+    >
+      <ResolutionPicker
+        resolution={_gameResolution}
+        onResolutionChange={setGameDocumentResolution}
+        scale={_gameScale}
+        title="Change game resolution"
+      />
+      <MuteButton />
+      <GameStatsMenu />
+    </div>
+  );
+}
+
+/** Game panel — a container div that play-mode.ts fills with a canvas.
+ *  (Moved verbatim from `DefaultEditorLayout.tsx` in W1 — inventory row V3.) */
+function GamePanel({ style }: { style?: React.CSSProperties }) {
+  const store = useEditorStore();
+  const isRunning = store.playState !== 'stopped';
+  const outerRef = useRef<HTMLDivElement>(null);
+  // W2 (V4): resolution comes from the shared game-view store above — the
+  // document-local toolbar writes it, this content applies it.
+  useSyncExternalStore(subscribeGameView, gameViewVersion);
+  const resolution = _gameResolution;
+  const [containerSize, setContainerSize] = useState({ width: 0, height: 0 });
+
+  // Callback ref so setGameContainer is called even when the element swaps (fill ↔ device)
+  const prevRef = useRef<HTMLDivElement | null>(null);
+  const canvasRef = useCallback((el: HTMLDivElement | null) => {
+    if (el === prevRef.current) return;
+    // Move game canvas to new container
+    if (prevRef.current && el) {
+      while (prevRef.current.firstChild) el.appendChild(prevRef.current.firstChild);
+    }
+    prevRef.current = el;
+    setGameContainer(el);
+  }, []);
+
+  // Track outer container size for scale calculation
+  useEffect(() => {
+    const el = outerRef.current;
+    if (!el) return;
+    const observer = new ResizeObserver(([entry]) => {
+      if (!entry) return;
+      setContainerSize({ width: entry.contentRect.width, height: entry.contentRect.height });
+    });
+    observer.observe(el);
+    return () => observer.disconnect();
+  }, []);
+
+  // Resize the game renderer when resolution or container size changes
+  const isFill = resolution.width === null;
+  useEffect(() => {
+    if (isFill) {
+      // Fill mode: resize to match available container space
+      if (containerSize.width > 0 && containerSize.height > 0) {
+        resizeGame(containerSize.width, containerSize.height);
+      }
+    } else {
+      resizeGame(resolution.width!, resolution.height!);
+    }
+  }, [isFill, resolution.width, resolution.height, containerSize.width, containerSize.height]);
+
+  // Scale: fit the device resolution into the available space, never upscale
+  let scale = 1;
+  if (!isFill && containerSize.width > 0 && containerSize.height > 0) {
+    const scaleX = containerSize.width / resolution.width!;
+    const scaleY = containerSize.height / resolution.height!;
+    scale = Math.min(scaleX, scaleY, 1);
+  }
+  // Publish for the toolbar's percentage readout (effect: setState-in-render
+  // on ANOTHER component's store is a React error; post-commit is correct).
+  useEffect(() => {
+    setGameScale(scale);
+  }, [scale]);
+
+  return (
+    <div style={{ overflow: 'hidden', position: 'relative', flexDirection: 'column', ...style }}>
+      <div
+        ref={outerRef}
+        style={{
+          flex: 1,
+          overflow: 'hidden',
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'center',
+          position: 'relative',
+        }}
+      >
+        {isFill ? (
+          <div
+            ref={canvasRef}
+            data-testid="game-runtime-container"
+            aria-hidden="true"
+            style={{ position: 'absolute', inset: 0, visibility: isRunning ? 'visible' : 'hidden' }}
+          />
+        ) : (
+          /* Wrapper sized to the scaled dimensions so flexbox centering works.
+             The inner canvasRef is full device resolution, CSS-scaled down. */
+          <div
+            style={{
+              width: resolution.width! * scale,
+              height: resolution.height! * scale,
+              overflow: 'hidden',
+              visibility: isRunning ? 'visible' : 'hidden',
+            }}
+          >
+            <div
+              ref={canvasRef}
+              data-testid="game-runtime-container"
+              aria-hidden="true"
+              style={{
+                width: resolution.width!,
+                height: resolution.height!,
+                transformOrigin: 'top left',
+                transform: `scale(${scale})`,
+              }}
+            />
+          </div>
+        )}
+        {!isRunning && (
+          <div
+            data-testid="game-stopped-placeholder"
+            style={{
+              position: 'absolute',
+              inset: 0,
+              display: 'flex',
+              flexDirection: 'column',
+              alignItems: 'center',
+              justifyContent: 'center',
+              gap: 6,
+              background: themeVars.surface.shell,
+              color: themeVars.content.dim,
+              fontSize: 11,
+              pointerEvents: 'none',
+            }}
+          >
+            <span style={{ color: themeVars.content.primary, fontSize: 13 }}>Game is stopped</span>
+            <span>Press Play to start the composed runtime.</span>
+          </div>
+        )}
+        {/* Same overlay ViewportPanel renders on the Scene tab (T-R1a #6) — the
+            Game tab is where play auto-switches to, so it must render here too,
+            not only on the Scene-tab viewport it would otherwise be hidden behind. */}
+        {store.playState !== 'stopped' && _gameStatsVisible && <GamePerformanceOverlay />}
+      </div>
+      {/* W4 (V4): the PlayBar copy that rendered here moved to the global
+          command header (`ProjectHeader.tsx`) — transport is now
+          document-independent; resolution/mute stay in this document's
+          local toolbar (`GameDocumentToolbar`). */}
+    </div>
+  );
+}
+
+/** The Game document's content host. Rendered warm (hidden) even while the
+ *  document is closed — see this file's header. */
+function GameDocumentContent(_props: WorkspaceDocumentContentProps) {
+  const store = useEditorStore();
+  useSyncExternalStore(store.subscribe, store.getSnapshot);
+  const isPlaying = store.playState !== 'stopped';
+  return (
+    <GamePanel
+      style={{
+        flex: 1,
+        position: 'relative',
+        display: 'flex',
+        flexDirection: 'column',
+        pointerEvents: 'auto',
+        // L-20 — playing/paused edge treatment from the shared themeVars.semantic.success/themeVars.semantic.warning
+        // tokens (same "healthy"/"attention" semantic SaveStatus uses).
+        ...(store.playState === 'playing'
+          ? { outline: `2px solid ${themeVars.semantic.success}`, outlineOffset: -2 }
+          : isPlaying
+            ? { outline: `2px solid ${themeVars.semantic.warning}`, outlineOffset: -2 }
+            : {}),
+      }}
+    />
+  );
+}
+
+/** Build the W1 document descriptors bound to a store. `onActivate` is the
+ *  registry→store half of the bridge: activating a 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;
+  game: WorkspaceDocumentDescriptor;
+} {
+  const scene: WorkspaceDocumentDescriptor = {
+    id: SCENE_DOCUMENT_ID,
+    title: sceneDocumentTitle(store.savePath),
+    kind: 'scene',
+    ...(store.savePath ? { provenance: { sourcePath: store.savePath } } : {}),
+    Content: SceneDocumentContent,
+    closeable: false,
+    onActivate: () => store.setActiveViewportTab('scene'),
+  };
+  const game: WorkspaceDocumentDescriptor = {
+    id: GAME_DOCUMENT_ID,
+    title: 'Game',
+    kind: 'game',
+    Content: GameDocumentContent,
+    // W2 (V4): the document-local toolbar — resolution + mute appear only
+    // while the Game document is active (§6.3).
+    Toolbar: GameDocumentToolbar,
+    closeable: false,
+    onActivate: () => store.setActiveViewportTab('game'),
+  };
+  return { scene, game };
+}
+
+/**
+ * The store→registry half of the bridge. 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.
+ *
+ *  1. the scene document is always open (opens it on first run);
+ *  2. its tab title/dirty dot track `savePath`/`isDirty` live;
+ *  3. the Game document is always open. Dockview's `renderer: "always"`
+ *     preserves its canvas before play begins and across tab switches;
+ *  4. the active document mirrors `activeViewportTab` (auto-switch on
+ *     play/stop, `set-viewport-tab` control commands, ingest-mode's direct
+ *     writes). A `game` tab value with no Game document open (transient
+ *     store states) falls back to the scene document — there is always an
+ *     active center document.
+ */
+export function syncCenterDocuments(
+  store: CenterDocumentsStore,
+  docs: { scene: WorkspaceDocumentDescriptor; game: WorkspaceDocumentDescriptor },
+): 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 ensuring the permanently mounted Game tab, then restore
+  // that intent below; merely making Game discoverable must not switch a
+  // stopped editor away from Scene.
+  const requestedViewportTab = store.activeViewportTab;
+
+  // Registry order is the canonical tab order for a fresh layout. Game is
+  // permanently first—like the player preview in established game editors—
+  // while Scene remains the initial active authoring document when stopped.
+  if (!isOpen(GAME_DOCUMENT_ID)) openWorkspaceDocument(docs.game);
+  if (!isOpen(SCENE_DOCUMENT_ID)) openWorkspaceDocument(docs.scene);
+  setWorkspaceDocumentTitle(SCENE_DOCUMENT_ID, sceneDocumentTitle(store.savePath));
+  setWorkspaceDocumentDirty(SCENE_DOCUMENT_ID, store.isDirty);
+
+  // Mirror the store tab into registry activation — W2-aware: since asset
+  // and story documents joined the center, a THIRD-party document being
+  // active is a legitimate state (its own onActivate already asserted the
+  // store's 'scene' tab, so the T6.3 gate is off). The mirror therefore only
+  // corrects genuine disagreements about the SCENE/GAME pair:
+  //   - tab says 'game' (play auto-switch, `set-viewport-tab game`) → the
+  //     Game document must be active;
+  //   - tab says 'scene' while the GAME document is active (external
+  //     `set-viewport-tab scene` during play) → back to the scene document;
+  //   - no active document at all (first run) → the scene document.
+  // A 'scene' tab with an asset/story document active is CONSISTENT and must
+  // not be "corrected" — forcing the scene document here (the W1 behavior)
+  // would instantly steal the tab back from every non-Game document on the
+  // next store notify.
+  const activeId = activeWorkspaceDocumentId();
+  if (requestedViewportTab === 'game' && isOpen(GAME_DOCUMENT_ID)) {
+    if (activeId !== GAME_DOCUMENT_ID) activateWorkspaceDocument(GAME_DOCUMENT_ID);
+  } else if (activeId === GAME_DOCUMENT_ID || activeId === null) {
+    // Covers both the external scene-tab write during play AND the
+    // transient "tab says game but no Game document is open" fallback —
+    // there is always an active center document.
+    activateWorkspaceDocument(SCENE_DOCUMENT_ID);
+  }
+}
+
+/**
+ * Layout hook: installs the W1 center documents for this editor session and
+ * keeps them synced to the store. Teardown closes every workspace document
+ * (project switch / return to project screen), firing their dispose hooks.
+ */
+export function useCenterDocuments(store: CenterDocumentsStore): void {
+  useEffect(() => {
+    const docs = createCenterDocumentDescriptors(store);
+    const run = () => syncCenterDocuments(store, docs);
+    run();
+    const unsubscribe = store.subscribe(run);
+    return () => {
+      unsubscribe();
+      closeAllWorkspaceDocuments();
+    };
+  }, [store]);
+}