@vgai/editor 0.2.0 → 0.4.0-canary.20260715.0

package/src/components/WorkspaceDock.tsx

@@ -0,0 +1,891 @@
+import {
+  type DockviewApi,
+  DockviewDefaultTab,
+  type DockviewPanelApi,
+  DockviewReact,
+  type DockviewTheme,
+  type IDockviewPanelHeaderProps,
+  type IDockviewPanelProps,
+} from 'dockview-react';
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useRef,
+  useState,
+  useSyncExternalStore,
+} from 'react';
+import { availabilityTickVersion, subscribeAvailabilityTick } from '../availability-tick';
+import { Button } from '../design-system';
+import { useEditorStore } from '../EditorContext';
+import {
+  harnessChat,
+  harnessChatLayoutVersion,
+  setHarnessChatCollapsed,
+  subscribeHarnessChatLayout,
+} from '../harness-chat-layout';
+import type { HotkeyScope } from '../hotkeys';
+import {
+  installWorkspaceDockCommands,
+  type WorkspaceDockCommands,
+} from '../workspace-dock-controller';
+import {
+  activateWorkspaceDocument,
+  activeWorkspaceDocumentId,
+  closeWorkspaceDocument,
+  openWorkspaceDocuments,
+  saveWorkspaceDocument,
+  subscribeWorkspaceDocuments,
+  workspaceDocumentRegistryVersion,
+} from '../workspace-document-registry';
+import { installWorkspaceStatePersistence } from '../workspace-state-persistence';
+import {
+  availableWorkspaceUtilities,
+  registeredWorkspaceUtilities,
+  subscribeWorkspaceUtilities,
+  type WorkspaceUtilityRegistration,
+  workspaceUtilityBadge,
+  workspaceUtilityRegistryVersion,
+} from '../workspace-utility-registry';
+import { AssetBrowser } from './AssetBrowser';
+import { AssetLibraryPanel } from './AssetLibraryPanel';
+import { GameHierarchy } from './GameHierarchy';
+import { HarnessChatPanel } from './HarnessChatPanel';
+import { HistoryPanel } from './HistoryPanel';
+import { Inspector } from './Inspector';
+import 'dockview-react/dist/styles/dockview.css';
+import './workspace-dock.css';
+
+const COMPONENT_ID = 'vgai-workspace-panel';
+const TAB_COMPONENT_ID = 'vgai-workspace-tab';
+
+const HIERARCHY_PANEL_ID = 'navigator:hierarchy';
+const AGENT_PANEL_ID = 'workspace:agent';
+const ASSETS_PANEL_ID = 'navigator:assets';
+const ASSET_LIBRARY_PANEL_ID = 'navigator:asset-library';
+const INSPECTOR_PANEL_ID = 'workspace:inspector';
+const HISTORY_PANEL_ID = 'aux:undo-history';
+
+const LEFT_GROUP_ID = 'vgai:left';
+const AGENT_GROUP_ID = 'vgai:agent';
+const ASSETS_GROUP_ID = 'vgai:assets';
+const RIGHT_GROUP_ID = 'vgai:right';
+const BOTTOM_GROUP_ID = 'vgai:bottom';
+const CENTER_GROUP_ID = 'vgai:center';
+const normalizedAgentGroups = new WeakSet<object>();
+
+type StaticPanelKind = 'agent' | 'hierarchy' | 'assets' | 'asset-library' | 'inspector' | 'history';
+type WorkspacePanelParams =
+  | { kind: 'static'; staticKind: StaticPanelKind; closeable: boolean }
+  | { kind: 'document'; documentId: string; closeable: boolean }
+  | { kind: 'utility'; utilityId: string; closeable: boolean };
+
+function hotkeyScopeForPanel(params: WorkspacePanelParams): HotkeyScope {
+  if (params.kind === 'utility') return 'workspace';
+  if (params.kind === 'document') {
+    return isWorldSurfaceDocument(params.documentId) ? 'viewport' : 'workspace';
+  }
+  switch (params.staticKind) {
+    case 'hierarchy':
+      return 'hierarchy';
+    case 'assets':
+    case 'asset-library':
+      return 'asset-browser';
+    case 'inspector':
+      return 'inspector';
+    case 'agent':
+    case 'history':
+      return 'workspace';
+  }
+}
+
+const OpenSceneContext = createContext<(assetPath: string) => void>(() => undefined);
+
+export const vgaiDockviewTheme: DockviewTheme = {
+  name: 'vgai',
+  className: 'dockview-theme-vgai',
+  colorScheme: 'dark',
+  gap: 1,
+  edgeGroupCollapsedSize: 28,
+  dndOverlayMounting: 'absolute',
+  dndPanelOverlay: 'group',
+  dndTabIndicator: 'line',
+  dndOverlayBorder: '1px solid var(--dv-active-sash-color)',
+  tabGroupIndicator: 'none',
+  tabAnimation: 'smooth',
+};
+
+function usePanelActive(api: DockviewPanelApi): boolean {
+  const [active, setActive] = useState(api.isActive);
+  useEffect(() => {
+    setActive(api.isActive);
+    const disposable = api.onDidActiveChange((event) => setActive(event.isActive));
+    return () => disposable.dispose();
+  }, [api]);
+  return active;
+}
+
+function StaticPanelContent({ staticKind }: { staticKind: StaticPanelKind }) {
+  const onOpenScene = useContext(OpenSceneContext);
+  switch (staticKind) {
+    case 'agent':
+      return <HarnessChatPanel />;
+    case 'hierarchy':
+      return <GameHierarchy />;
+    case 'assets':
+      return <AssetBrowser onOpenScene={onOpenScene} />;
+    case 'asset-library':
+      return <AssetLibraryPanel />;
+    case 'inspector':
+      return <Inspector />;
+    case 'history':
+      return <HistoryPanel />;
+  }
+}
+
+function WorkspacePanel({ api, params }: IDockviewPanelProps<WorkspacePanelParams>) {
+  const active = usePanelActive(api);
+  useSyncExternalStore(
+    subscribeWorkspaceDocuments,
+    workspaceDocumentRegistryVersion,
+    workspaceDocumentRegistryVersion,
+  );
+  useSyncExternalStore(
+    subscribeWorkspaceUtilities,
+    workspaceUtilityRegistryVersion,
+    workspaceUtilityRegistryVersion,
+  );
+
+  if (params.kind === 'static') {
+    return (
+      <div
+        className="vgai-dock-panel"
+        data-testid={`dock-panel:${api.id}`}
+        data-editor-hotkey-scope={hotkeyScopeForPanel(params)}
+      >
+        <StaticPanelContent staticKind={params.staticKind} />
+      </div>
+    );
+  }
+
+  if (params.kind === 'utility') {
+    const utility = availableWorkspaceUtilities().find((item) => item.id === params.utilityId);
+    if (!utility) {
+      return <div className="vgai-dock-empty">This utility is not available in this session.</div>;
+    }
+    const Content = utility.Content;
+    return (
+      <div
+        className="vgai-dock-panel"
+        data-testid={`bottom-panel-utility-${params.utilityId}`}
+        data-editor-hotkey-scope={hotkeyScopeForPanel(params)}
+      >
+        <Content />
+      </div>
+    );
+  }
+
+  const document = openWorkspaceDocuments().find(
+    (item) => item.descriptor.id === params.documentId,
+  );
+  if (!document) return <div className="vgai-dock-empty">Restoring document…</div>;
+  const Content = document.descriptor.Content;
+  const Toolbar = document.descriptor.Toolbar;
+  return (
+    <div
+      className="vgai-dock-document"
+      data-testid={`workspace-doc:${params.documentId}`}
+      data-editor-hotkey-scope={hotkeyScopeForPanel(params)}
+    >
+      {Toolbar && (
+        <div className="vgai-dock-document-toolbar">
+          <Toolbar documentId={params.documentId} active={active} />
+        </div>
+      )}
+      <div className="vgai-dock-document-content">
+        <Content documentId={params.documentId} active={active} />
+      </div>
+    </div>
+  );
+}
+
+function workspaceTabTestId(params: WorkspacePanelParams, panelId: string): string {
+  if (params.kind === 'document') return `workspace-tab:${params.documentId}`;
+  if (params.kind === 'utility') return `bottom-tab-utility-${params.utilityId}`;
+  return `dock-tab:${panelId}`;
+}
+
+function isWorldSurfaceDocument(documentId: string): boolean {
+  const kind = openWorkspaceDocuments().find((item) => item.descriptor.id === documentId)
+    ?.descriptor.kind;
+  return kind === 'game' || kind === 'scene' || kind === 'world';
+}
+
+function documentTabFamily(params: WorkspacePanelParams): 'world' | 'resource' | undefined {
+  if (params.kind !== 'document') return undefined;
+  return isWorldSurfaceDocument(params.documentId) ? 'world' : 'resource';
+}
+
+/** An older saved layout can restore resource tabs before world documents
+ * that did not exist when it was written. Stable-partition only that upgrade
+ * case; ordinary user ordering inside each family remains untouched. */
+function normalizeDocumentSectionOrder(
+  api: DockviewApi,
+  centerGroupId: string,
+  documentIds: readonly string[],
+): void {
+  const centerDocumentIds = documentIds.filter(
+    (documentId) => api.getPanel(documentId)?.api.group.id === centerGroupId,
+  );
+  const firstDocumentId = centerDocumentIds[0];
+  const group = firstDocumentId ? api.getPanel(firstDocumentId)?.api.group : undefined;
+  if (!group) return;
+  for (const [index, documentId] of centerDocumentIds.entries()) {
+    const panel = api.getPanel(documentId);
+    if (!panel) continue;
+    if (group.panels[index]?.id === documentId) continue;
+    panel.api.moveTo({ group, index, skipSetActive: true });
+  }
+}
+
+const subscribeToNothing = () => () => undefined;
+const staticBadgeSnapshot = () => 0;
+
+/** Badge values often come from a store independent of the registration
+ * registry (the editor console is the first-party example). Keep that live
+ * source attached to the tab even while its utility panel is collapsed. */
+function useWorkspaceUtilityBadge(utilityId: string | null) {
+  const utility = utilityId
+    ? registeredWorkspaceUtilities().find((item) => item.id === utilityId)
+    : undefined;
+  useSyncExternalStore(
+    utility?.subscribeBadge ?? subscribeToNothing,
+    utility?.badgeSnapshot ?? staticBadgeSnapshot,
+    utility?.badgeSnapshot ?? staticBadgeSnapshot,
+  );
+  return utilityId ? workspaceUtilityBadge(utilityId) : null;
+}
+
+function closeDockviewDocumentTab(
+  props: IDockviewPanelHeaderProps<WorkspacePanelParams>,
+  documentId: string,
+  discardDirty = false,
+): boolean {
+  if (!closeWorkspaceDocument(documentId, { discardDirty })) return false;
+  // Close through Dockview immediately so its physical tab order—including
+  // user moves—chooses the visible neighbor. If that neighbor is another
+  // document, mirror it back after the registry's generic fallback ran.
+  props.api.close();
+  const next = props.containerApi.activePanel;
+  if (!next) return true;
+  const nextParams = next.api.getParameters<WorkspacePanelParams>();
+  if (nextParams.kind === 'document') activateWorkspaceDocument(nextParams.documentId);
+  return true;
+}
+
+function WorkspaceTab(props: IDockviewPanelHeaderProps<WorkspacePanelParams>) {
+  const { api, params } = props;
+  const [confirmingClose, setConfirmingClose] = useState(false);
+  const [savingClose, setSavingClose] = useState(false);
+  useSyncExternalStore(
+    subscribeWorkspaceDocuments,
+    workspaceDocumentRegistryVersion,
+    workspaceDocumentRegistryVersion,
+  );
+  useSyncExternalStore(
+    subscribeWorkspaceUtilities,
+    workspaceUtilityRegistryVersion,
+    workspaceUtilityRegistryVersion,
+  );
+
+  const document =
+    params.kind === 'document'
+      ? openWorkspaceDocuments().find((item) => item.descriptor.id === params.documentId)
+      : null;
+  const badge = useWorkspaceUtilityBadge(params.kind === 'utility' ? params.utilityId : null);
+  const testId = workspaceTabTestId(params, api.id);
+  const tabFamily = documentTabFamily(params);
+  const closeProps =
+    params.kind === 'document' && params.closeable
+      ? {
+          closeActionOverride: () => {
+            if (document?.dirty) {
+              setConfirmingClose(true);
+              return;
+            }
+            closeDockviewDocumentTab(props, params.documentId);
+          },
+        }
+      : params.kind === 'static' && params.staticKind === 'agent'
+        ? {
+            closeActionOverride: () => {
+              setHarnessChatCollapsed(true);
+              props.api.close();
+            },
+          }
+        : {};
+  if (params.kind === 'document' && document && confirmingClose) {
+    return (
+      <div
+        className="vgai-dock-tab vgai-dock-tab-unsaved"
+        data-testid={`workspace-tab-unsaved:${params.documentId}`}
+        data-document-family={tabFamily}
+        role="group"
+        aria-label={`Save changes to ${document.title}?`}
+        onPointerDown={(event) => event.stopPropagation()}
+      >
+        <span className="vgai-dock-tab-unsaved-label">Unsaved</span>
+        <Button
+          type="button"
+          disabled={savingClose}
+          onClick={() => {
+            setSavingClose(true);
+            void saveWorkspaceDocument(params.documentId).then((saved) => {
+              setSavingClose(false);
+              if (saved) closeDockviewDocumentTab(props, params.documentId);
+            });
+          }}
+        >
+          {savingClose ? 'Saving…' : 'Save'}
+        </Button>
+        <Button
+          type="button"
+          disabled={savingClose}
+          onClick={() => closeDockviewDocumentTab(props, params.documentId, true)}
+        >
+          Discard
+        </Button>
+        <Button type="button" disabled={savingClose} onClick={() => setConfirmingClose(false)}>
+          Cancel
+        </Button>
+      </div>
+    );
+  }
+
+  return (
+    <div
+      className="vgai-dock-tab"
+      data-testid={testId}
+      data-dirty={document?.dirty || undefined}
+      data-document-family={tabFamily}
+      data-editor-hotkey-scope={hotkeyScopeForPanel(params)}
+    >
+      <DockviewDefaultTab {...props} hideClose={!params.closeable} {...closeProps} />
+      {document?.dirty && (
+        <span className="vgai-dock-tab-dirty" title="Unsaved" aria-hidden="true" />
+      )}
+      {badge && badge.count > 0 && (
+        <span className={`vgai-dock-tab-badge vgai-dock-tab-badge-${badge.severity}`}>
+          {badge.count}
+        </span>
+      )}
+    </div>
+  );
+}
+
+function addStaticPanel(
+  api: DockviewApi,
+  options: {
+    id: string;
+    title: string;
+    staticKind: StaticPanelKind;
+    groupId: string;
+    inactive?: boolean;
+    closeable?: boolean;
+  },
+): void {
+  if (api.getPanel(options.id)) return;
+  api.addPanel<WorkspacePanelParams>({
+    id: options.id,
+    title: options.title,
+    component: COMPONENT_ID,
+    tabComponent: TAB_COMPONENT_ID,
+    renderer: 'always',
+    inactive: options.inactive ?? false,
+    position: { referenceGroup: options.groupId },
+    params: {
+      kind: 'static',
+      staticKind: options.staticKind,
+      closeable: options.closeable ?? false,
+    },
+  });
+}
+
+/** Permanent editor columns are normal Dockview grid groups. Edge groups put
+ * their headers on the outside edge, producing rotated vertical labels and a
+ * second rail beside the actual panel. Grid groups preserve all Dockview
+ * resize/drag/float behavior while using the conventional horizontal header. */
+function ensureSideGroups(api: DockviewApi, centerGroupId: string): void {
+  let addedLeft = false;
+  let addedRight = false;
+  if (!api.getGroup(LEFT_GROUP_ID)) {
+    api.addGroup({
+      id: LEFT_GROUP_ID,
+      referenceGroup: centerGroupId,
+      direction: 'left',
+      initialWidth: 260,
+      constraints: { minimumWidth: 220, maximumWidth: 320 },
+    });
+    addedLeft = true;
+  }
+  if (!api.getGroup(RIGHT_GROUP_ID)) {
+    api.addGroup({
+      id: RIGHT_GROUP_ID,
+      referenceGroup: centerGroupId,
+      direction: 'right',
+      initialWidth: 280,
+      constraints: { minimumWidth: 240, maximumWidth: 340 },
+    });
+    addedRight = true;
+  }
+  // Adding the second sibling can redistribute the first split before the
+  // root has completed its initial layout. Set the intended editor widths
+  // after both groups exist; Dockview queues these values if still unmeasured.
+  if (addedLeft) api.getGroup(LEFT_GROUP_ID)?.api.setSize({ width: 260 });
+  if (addedRight) api.getGroup(RIGHT_GROUP_ID)?.api.setSize({ width: 280 });
+}
+
+function ensureAgentGroup(api: DockviewApi): void {
+  const existing = api.getGroup(AGENT_GROUP_ID);
+  if (existing) {
+    // Dockview keeps an empty group after the optional Agent panel is hidden.
+    // Refresh its constraints before reusing it: serialized/older constraints
+    // can otherwise let a 360px chat regrow to ~450px on restore.
+    existing.api.setConstraints({ minimumWidth: 300, maximumWidth: 380 });
+    existing.api.setSize({ width: 360 });
+    normalizedAgentGroups.add(existing);
+    requestAnimationFrame(() => {
+      api.getGroup(AGENT_GROUP_ID)?.api.setSize({ width: 360 });
+    });
+    return;
+  }
+  // Absolute `right` makes Agent a sibling of the entire existing grid tree.
+  // Referencing the Hierarchy group here is subtly wrong: once Assets splits
+  // below Hierarchy, Dockview expands that lower split beneath Agent too and
+  // leaves chat occupying only one corner instead of a full-height column.
+  const agentGroup = api.addGroup({
+    id: AGENT_GROUP_ID,
+    direction: 'right',
+    initialWidth: 360,
+    constraints: { minimumWidth: 300, maximumWidth: 380 },
+  });
+  normalizedAgentGroups.add(agentGroup);
+  // Agent is added after the navigator and inspector. Reassert their semantic
+  // defaults after Dockview introduces the fourth column so the root split
+  // does not redistribute every tool surface toward equal widths.
+  api.getGroup(AGENT_GROUP_ID)?.api.setSize({ width: 360 });
+  api.getGroup(LEFT_GROUP_ID)?.api.setSize({ width: 260 });
+  api.getGroup(RIGHT_GROUP_ID)?.api.setSize({ width: 280 });
+  // Adding the Agent panel after this group returns causes Dockview to run one
+  // more root layout pass. Reapply once that pass has landed; otherwise the
+  // inspector absorbs the spare width (observed as ~399px at a 1280px
+  // viewport) and leaves the authored document narrower than every tool.
+  requestAnimationFrame(() => {
+    if (!api.getGroup(AGENT_GROUP_ID)) return;
+    api.getGroup(AGENT_GROUP_ID)?.api.setSize({ width: 360 });
+    api.getGroup(LEFT_GROUP_ID)?.api.setSize({ width: 260 });
+    api.getGroup(RIGHT_GROUP_ID)?.api.setSize({ width: 280 });
+  });
+}
+
+function ensureBottomEdgeGroup(api: DockviewApi): void {
+  if (!api.getEdgeGroup('bottom')) {
+    api.addEdgeGroup('bottom', {
+      id: BOTTOM_GROUP_ID,
+      initialSize: 260,
+      minimumSize: 120,
+      collapsedSize: 28,
+      collapsed: true,
+    });
+  }
+}
+
+function ensureCenterGroup(api: DockviewApi): string {
+  // Restored layouts contain several grid groups. "First grid group" is
+  // usually the Hierarchy navigator, so resolving generically would append
+  // every newly discovered world document there and leave the real center
+  // empty. The semantic group id is the durable layout contract.
+  const existing = api.getGroup(CENTER_GROUP_ID);
+  if (existing) return existing.id;
+  return api.addGroup({ id: CENTER_GROUP_ID, direction: 'right' }).id;
+}
+
+function ensureAssetNavigators(api: DockviewApi): void {
+  if (!api.getPanel(ASSETS_PANEL_ID)) {
+    if (!api.getGroup(ASSETS_GROUP_ID)) {
+      const hierarchyGroup = api.getPanel(HIERARCHY_PANEL_ID)?.api.group;
+      api.addGroup({
+        id: ASSETS_GROUP_ID,
+        referenceGroup: hierarchyGroup ?? LEFT_GROUP_ID,
+        direction: 'below',
+        initialHeight: 340,
+        constraints: { minimumHeight: 180 },
+      });
+    }
+    addStaticPanel(api, {
+      id: ASSETS_PANEL_ID,
+      title: 'Assets',
+      staticKind: 'assets',
+      groupId: ASSETS_GROUP_ID,
+    });
+  }
+  const assetsPanel = api.getPanel(ASSETS_PANEL_ID);
+  if (!api.getPanel(ASSET_LIBRARY_PANEL_ID)) {
+    addStaticPanel(api, {
+      id: ASSET_LIBRARY_PANEL_ID,
+      title: 'Library',
+      staticKind: 'asset-library',
+      groupId: assetsPanel?.api.group.id ?? ASSETS_GROUP_ID,
+      inactive: true,
+    });
+  }
+  const libraryPanel = api.getPanel(ASSET_LIBRARY_PANEL_ID);
+  if (assetsPanel && libraryPanel && libraryPanel.api.group.id !== assetsPanel.api.group.id) {
+    libraryPanel.api.moveTo({ group: assetsPanel.api.group, index: 1, skipSetActive: true });
+  }
+}
+
+function reconcileStaticPanels(api: DockviewApi): void {
+  // The scene-UI insertion catalog used to be promoted to a permanent
+  // navigator tab by the first Dockview migration. Creation now comes from
+  // the selected node's adapter through Hierarchy's one generic Add menu;
+  // discard any older layout that restores the legacy blank panel.
+  const legacyUIPalette = api.getPanel('navigator:ui-palette');
+  if (legacyUIPalette) api.removePanel(legacyUIPalette);
+  const legacyProject = api.getPanel('navigator:project');
+  if (legacyProject) api.removePanel(legacyProject);
+  const restoredAgentGroup = api.getGroup(AGENT_GROUP_ID);
+  if (restoredAgentGroup && !normalizedAgentGroups.has(restoredAgentGroup)) {
+    // `fromJSON` restores the constraints serialized by the version that
+    // wrote the layout. Refresh them so v7's width correction also applies
+    // to an already-present panel, not only to a newly created/restored one.
+    restoredAgentGroup.api.setConstraints({ minimumWidth: 300, maximumWidth: 380 });
+    restoredAgentGroup.api.setSize({ width: 360 });
+    normalizedAgentGroups.add(restoredAgentGroup);
+    requestAnimationFrame(() => {
+      api.getGroup(AGENT_GROUP_ID)?.api.setSize({ width: 360 });
+    });
+  }
+  const agentPanel = api.getPanel(AGENT_PANEL_ID);
+  if (harnessChat().collapsed) {
+    if (agentPanel) api.removePanel(agentPanel);
+  } else if (!agentPanel) {
+    ensureAgentGroup(api);
+    addStaticPanel(api, {
+      id: AGENT_PANEL_ID,
+      title: 'Agent',
+      staticKind: 'agent',
+      groupId: AGENT_GROUP_ID,
+      closeable: true,
+    });
+  }
+  addStaticPanel(api, {
+    id: HIERARCHY_PANEL_ID,
+    title: 'Hierarchy',
+    staticKind: 'hierarchy',
+    groupId: LEFT_GROUP_ID,
+  });
+  // Local Assets and the external Library are permanent peer navigators below
+  // Hierarchy. Opening a Library result creates a center asset document; the
+  // acquisition surface itself never disappears from the shell.
+  ensureAssetNavigators(api);
+  addStaticPanel(api, {
+    id: INSPECTOR_PANEL_ID,
+    title: 'Inspector',
+    staticKind: 'inspector',
+    groupId: RIGHT_GROUP_ID,
+  });
+}
+
+function reconcileDocumentPanels(api: DockviewApi, centerGroupId: string): void {
+  const documents = openWorkspaceDocuments();
+  const documentIds = new Set(documents.map((item) => item.descriptor.id));
+  let structureChanged = false;
+  for (const panel of api.panels) {
+    const params = panel.api.getParameters<WorkspacePanelParams>();
+    if (params.kind === 'document' && !documentIds.has(params.documentId)) {
+      api.removePanel(panel);
+      structureChanged = true;
+    }
+  }
+  let previousPanel = undefined as ReturnType<DockviewApi['getPanel']>;
+  for (const document of documents) {
+    const existing = api.getPanel(document.descriptor.id);
+    if (existing) {
+      if (existing.api.title !== document.title) existing.api.setTitle(document.title);
+      previousPanel = existing;
+      continue;
+    }
+    previousPanel = api.addPanel<WorkspacePanelParams>({
+      id: document.descriptor.id,
+      title: document.title,
+      component: COMPONENT_ID,
+      tabComponent: TAB_COMPONENT_ID,
+      renderer: 'always',
+      inactive: true,
+      position: previousPanel
+        ? { referencePanel: previousPanel }
+        : { referenceGroup: centerGroupId },
+      params: {
+        kind: 'document',
+        documentId: document.descriptor.id,
+        closeable: document.descriptor.closeable !== false,
+      },
+    });
+    structureChanged = true;
+  }
+
+  // Reordering an already-correct rail on every availability/utility tick
+  // causes Dockview to visibly rotate active tabs despite `skipSetActive`.
+  // The family partition only needs repair after the document structure
+  // changes; ordinary reconciliation and user tab focus are read-only.
+  if (structureChanged) {
+    const orderedDocumentIds = [
+      ...documents.filter((document) => isWorldSurfaceDocument(document.descriptor.id)),
+      ...documents.filter((document) => !isWorldSurfaceDocument(document.descriptor.id)),
+    ].map((document) => document.descriptor.id);
+    normalizeDocumentSectionOrder(api, centerGroupId, orderedDocumentIds);
+  }
+
+  // Game is a pinned player-facing anchor, not just whichever document was
+  // restored first. Keep it at index zero in its current tab group while
+  // leaving user-chosen group placement/docking intact.
+  const gamePanel = api.getPanel('workspace:game');
+  if (gamePanel && gamePanel.api.group.panels[0]?.id !== gamePanel.id) {
+    gamePanel.api.moveTo({ group: gamePanel.api.group, index: 0, skipSetActive: true });
+  }
+}
+
+function ensureUtilityPanel(
+  api: DockviewApi,
+  utility: WorkspaceUtilityRegistration,
+  inactive = true,
+): void {
+  const panelId = `utility:${utility.id}`;
+  const existing = api.getPanel(panelId);
+  if (existing) {
+    if (existing.api.title !== utility.title) existing.api.setTitle(utility.title);
+    return;
+  }
+  api.addPanel<WorkspacePanelParams>({
+    id: panelId,
+    title: utility.title,
+    component: COMPONENT_ID,
+    tabComponent: TAB_COMPONENT_ID,
+    renderer: 'always',
+    inactive,
+    position: { referenceGroup: BOTTOM_GROUP_ID },
+    params: {
+      kind: 'utility',
+      utilityId: utility.id,
+      closeable: utility.closeable ?? false,
+    },
+  });
+}
+
+function reconcileUtilityPanels(api: DockviewApi): void {
+  const utilities = availableWorkspaceUtilities();
+  const utilityIds = new Set(utilities.map((item) => item.id));
+  for (const panel of api.panels) {
+    const params = panel.api.getParameters<WorkspacePanelParams>();
+    if (params.kind === 'utility' && !utilityIds.has(params.utilityId)) api.removePanel(panel);
+  }
+  for (const utility of utilities) {
+    if (utility.visibleByDefault !== false) ensureUtilityPanel(api, utility);
+  }
+}
+
+function reconcileWorkspace(api: DockviewApi): void {
+  const centerGroupId = ensureCenterGroup(api);
+  ensureSideGroups(api, centerGroupId);
+  ensureBottomEdgeGroup(api);
+  reconcileStaticPanels(api);
+  reconcileDocumentPanels(api, centerGroupId);
+  reconcileUtilityPanels(api);
+}
+
+export function WorkspaceDock({ onOpenScene }: { onOpenScene: (assetPath: string) => void }) {
+  const store = useEditorStore();
+  const apiRef = useRef<DockviewApi | null>(null);
+  const readyCleanupRef = useRef<(() => void) | null>(null);
+  const lastSyncedDocumentRef = useRef<string | null>(null);
+  const documentVersion = useSyncExternalStore(
+    subscribeWorkspaceDocuments,
+    workspaceDocumentRegistryVersion,
+    workspaceDocumentRegistryVersion,
+  );
+  const utilityVersion = useSyncExternalStore(
+    subscribeWorkspaceUtilities,
+    workspaceUtilityRegistryVersion,
+    workspaceUtilityRegistryVersion,
+  );
+  const availabilityVersion = useSyncExternalStore(
+    subscribeAvailabilityTick,
+    availabilityTickVersion,
+    availabilityTickVersion,
+  );
+  const agentLayoutVersion = useSyncExternalStore(
+    subscribeHarnessChatLayout,
+    harnessChatLayoutVersion,
+    harnessChatLayoutVersion,
+  );
+  const activeDocumentId = activeWorkspaceDocumentId();
+
+  const resetLayout = useCallback(() => {
+    const api = apiRef.current;
+    if (!api) return;
+    api.clear();
+    // Dockview disposes panel renderers after `clear()` returns. Reusing the
+    // same panel ids in that call stack can therefore leave fresh headers
+    // attached to renderers that are about to be torn down. Rebuild on the
+    // next frame, once the cleared React panel tree has unmounted.
+    requestAnimationFrame(() => {
+      if (apiRef.current !== api) return;
+      reconcileWorkspace(api);
+      api.getEdgeGroup('bottom')?.collapse();
+      const activeDocumentId = activeWorkspaceDocumentId();
+      if (activeDocumentId) api.getPanel(activeDocumentId)?.api.setActive();
+    });
+  }, []);
+
+  useEffect(() => {
+    if (apiRef.current) reconcileWorkspace(apiRef.current);
+  }, [documentVersion, utilityVersion, availabilityVersion, agentLayoutVersion]);
+
+  useEffect(() => {
+    const api = apiRef.current;
+    if (!api || activeDocumentId === lastSyncedDocumentRef.current) return;
+    lastSyncedDocumentRef.current = activeDocumentId;
+    if (activeDocumentId) api.getPanel(activeDocumentId)?.api.setActive();
+  }, [activeDocumentId, documentVersion]);
+
+  useEffect(
+    () => () => {
+      readyCleanupRef.current?.();
+      readyCleanupRef.current = null;
+    },
+    [],
+  );
+
+  const onReady = useCallback(
+    ({ api }: { api: DockviewApi }) => {
+      apiRef.current = api;
+      reconcileWorkspace(api);
+      const uninstallPersistence = installWorkspaceStatePersistence(store, api, () =>
+        reconcileWorkspace(api),
+      );
+      const initialDocumentId = activeWorkspaceDocumentId();
+      lastSyncedDocumentRef.current = initialDocumentId;
+      if (initialDocumentId) api.getPanel(initialDocumentId)?.api.setActive();
+
+      const activeDisposable = api.onDidActivePanelChange((event) => {
+        if (event.origin !== 'user' || !event.panel) return;
+        const params = event.panel.api.getParameters<WorkspacePanelParams>();
+        if (params.kind === 'document') activateWorkspaceDocument(params.documentId);
+      });
+
+      const commands: WorkspaceDockCommands = {
+        showNavigator(id) {
+          const panelId =
+            id === 'hierarchy'
+              ? HIERARCHY_PANEL_ID
+              : id === 'asset-library'
+                ? ASSET_LIBRARY_PANEL_ID
+                : ASSETS_PANEL_ID;
+          const panel = api.getPanel(panelId);
+          panel?.api.setActive();
+        },
+        showUtility(id) {
+          reconcileWorkspace(api);
+          const utility = availableWorkspaceUtilities().find((item) => item.id === id);
+          if (!utility) return;
+          ensureUtilityPanel(api, utility, false);
+          const panel = api.getPanel(`utility:${id}`);
+          if (!panel) return;
+          panel.api.setActive();
+          if (panel.api.location.type === 'edge') panel.api.group.api.expand();
+        },
+        toggleUtility(id) {
+          reconcileWorkspace(api);
+          const utility = availableWorkspaceUtilities().find((item) => item.id === id);
+          if (!utility) return;
+          ensureUtilityPanel(api, utility, false);
+          const panel = api.getPanel(`utility:${id}`);
+          if (!panel) return;
+          const group = panel.api.group.api;
+          if (panel.api.isActive && panel.api.location.type === 'edge' && !group.isCollapsed()) {
+            group.collapse();
+          } else {
+            panel.api.setActive();
+            if (panel.api.location.type === 'edge') group.expand();
+          }
+        },
+        showAuxiliary(id) {
+          if (id !== 'undo-history') return;
+          if (!api.getPanel(HISTORY_PANEL_ID)) {
+            addStaticPanel(api, {
+              id: HISTORY_PANEL_ID,
+              title: 'Undo History',
+              staticKind: 'history',
+              groupId: RIGHT_GROUP_ID,
+              closeable: true,
+            });
+          }
+          api.getPanel(HISTORY_PANEL_ID)?.api.setActive();
+          api.getPanel(HISTORY_PANEL_ID)?.api.group.api.expand();
+        },
+        toggleFocus() {
+          if (api.hasMaximizedGroup()) {
+            api.exitMaximizedGroup();
+            api.setEdgeGroupVisible('bottom', true);
+          } else {
+            const activeDocument = activeWorkspaceDocumentId();
+            const focusPanel =
+              (activeDocument ? api.getPanel(activeDocument) : undefined) ?? api.activePanel;
+            if (!focusPanel) return;
+            api.setEdgeGroupVisible('bottom', false);
+            api.maximizeGroup(focusPanel);
+          }
+        },
+        resetLayout,
+      };
+      const uninstallCommands = installWorkspaceDockCommands(commands);
+      readyCleanupRef.current?.();
+      readyCleanupRef.current = () => {
+        activeDisposable.dispose();
+        uninstallPersistence();
+        uninstallCommands();
+        if (apiRef.current === api) apiRef.current = null;
+      };
+    },
+    [resetLayout, store],
+  );
+
+  const components = useRef({ [COMPONENT_ID]: WorkspacePanel }).current;
+  const tabs = useRef({ [TAB_COMPONENT_ID]: WorkspaceTab }).current;
+
+  return (
+    <main
+      className="vgai-workspace-dock"
+      aria-label="Editor workspace"
+      data-testid="workspace-dock"
+      data-editor-hotkey-scope="workspace"
+      data-editor-hotkey-fallback
+    >
+      <OpenSceneContext.Provider value={onOpenScene}>
+        <DockviewReact
+          components={components}
+          tabComponents={tabs}
+          onReady={onReady}
+          theme={vgaiDockviewTheme}
+          defaultRenderer="always"
+          keyboardNavigation
+          disableFloatingGroups={false}
+          singleTabMode="fullwidth"
+          tabGroupAccent="off"
+        />
+      </OpenSceneContext.Provider>
+    </main>
+  );
+}