@vgai/editor 0.4.0 → 0.4.1

package/src/components/WorkspaceDock.tsx

@@ -26,6 +26,7 @@ import {
 } from '../harness-chat-layout';
 import type { HotkeyScope } from '../hotkeys';
 import {
+  closeWorkspaceUtility,
   installWorkspaceDockCommands,
   type WorkspaceDockCommands,
 } from '../workspace-dock-controller';
@@ -80,6 +81,20 @@ type WorkspacePanelParams =
   | { kind: 'document'; documentId: string; closeable: boolean }
   | { kind: 'utility'; utilityId: string; closeable: boolean };
 
+type UtilityRevealOrigin = { previousPanelId: string | null; wasCollapsed: boolean };
+
+function rememberUtilityReveal(
+  panel: NonNullable<ReturnType<DockviewApi['getPanel']>>,
+  origins: Map<string, UtilityRevealOrigin>,
+  utilityId: string,
+): void {
+  if (panel.api.isActive) return;
+  origins.set(utilityId, {
+    previousPanelId: panel.api.group.activePanel?.id ?? null,
+    wasCollapsed: panel.api.location.type === 'edge' && panel.api.group.api.isCollapsed(),
+  });
+}
+
 function hotkeyScopeForPanel(params: WorkspacePanelParams): HotkeyScope {
   if (params.kind === 'utility') return 'workspace';
   if (params.kind === 'document') {
@@ -144,6 +159,7 @@ function WorkspacePanel({ api, params }: IDockviewPanelProps<WorkspacePanelParam
     workspaceUtilityRegistryVersion,
     workspaceUtilityRegistryVersion,
   );
+  useSyncExternalStore(subscribeAvailabilityTick, availabilityTickVersion, availabilityTickVersion);
 
   if (params.kind === 'static') {
     return (
@@ -160,7 +176,7 @@ function WorkspacePanel({ api, params }: IDockviewPanelProps<WorkspacePanelParam
   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>;
+      return <UnavailableUtilityPanel utilityId={params.utilityId} />;
     }
     const Content = utility.Content;
     return (
@@ -204,6 +220,13 @@ function WorkspacePanel({ api, params }: IDockviewPanelProps<WorkspacePanelParam
   );
 }
 
+function UnavailableUtilityPanel({ utilityId }: { utilityId: string }) {
+  useEffect(() => {
+    closeWorkspaceUtility(utilityId);
+  }, [utilityId]);
+  return null;
+}
+
 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}`;
@@ -278,6 +301,7 @@ function closeDockviewDocumentTab(
   return true;
 }
 
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: one tab renderer owns Dockview activation, accessible close, dirty-save confirmation, badges, and resource-family metadata.
 function WorkspaceTab(props: IDockviewPanelHeaderProps<WorkspacePanelParams>) {
   const { api, params } = props;
   const [confirmingClose, setConfirmingClose] = useState(false);
@@ -300,16 +324,18 @@ function WorkspaceTab(props: IDockviewPanelHeaderProps<WorkspacePanelParams>) {
   const badge = useWorkspaceUtilityBadge(params.kind === 'utility' ? params.utilityId : null);
   const testId = workspaceTabTestId(params, api.id);
   const tabFamily = documentTabFamily(params);
+  const requestDocumentClose = () => {
+    if (params.kind !== 'document') return;
+    if (document?.dirty) {
+      setConfirmingClose(true);
+      return;
+    }
+    closeDockviewDocumentTab(props, params.documentId);
+  };
   const closeProps =
     params.kind === 'document' && params.closeable
       ? {
-          closeActionOverride: () => {
-            if (document?.dirty) {
-              setConfirmingClose(true);
-              return;
-            }
-            closeDockviewDocumentTab(props, params.documentId);
-          },
+          closeActionOverride: requestDocumentClose,
         }
       : params.kind === 'static' && params.staticKind === 'agent'
         ? {
@@ -364,8 +390,35 @@ function WorkspaceTab(props: IDockviewPanelHeaderProps<WorkspacePanelParams>) {
       data-dirty={document?.dirty || undefined}
       data-document-family={tabFamily}
       data-editor-hotkey-scope={hotkeyScopeForPanel(params)}
+      onPointerDownCapture={() => {
+        // A bottom edge panel can remain Dockview's globally active panel
+        // while a center-group tab visibly changes. Select the semantic
+        // document at the tab boundary so its contributed context always
+        // follows the tab the user actually chose.
+        if (params.kind === 'document') activateWorkspaceDocument(params.documentId);
+      }}
     >
-      <DockviewDefaultTab {...props} hideClose={!params.closeable} {...closeProps} />
+      <DockviewDefaultTab
+        {...props}
+        hideClose={params.kind === 'document' || !params.closeable}
+        {...closeProps}
+      />
+      {params.kind === 'document' && params.closeable && (
+        <Button
+          type="button"
+          variant="ghost"
+          size="compact"
+          className="vgai-dock-tab-close"
+          aria-label={`Close ${document?.title ?? params.documentId}`}
+          onPointerDown={(event) => event.stopPropagation()}
+          onClick={(event) => {
+            event.stopPropagation();
+            requestDocumentClose();
+          }}
+        >
+          <span aria-hidden="true">×</span>
+        </Button>
+      )}
       {document?.dirty && (
         <span className="vgai-dock-tab-dirty" title="Unsaved" aria-hidden="true" />
       )}
@@ -395,7 +448,6 @@ function addStaticPanel(
     title: options.title,
     component: COMPONENT_ID,
     tabComponent: TAB_COMPONENT_ID,
-    renderer: 'always',
     inactive: options.inactive ?? false,
     position: { referenceGroup: options.groupId },
     params: {
@@ -680,11 +732,10 @@ function ensureUtilityPanel(
 
 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);
-  }
+  // Every panel uses renderer:'always', so an unavailable registration's
+  // `UnavailableUtilityPanel` closes through the semantic controller. That
+  // path can restore the previous tab/collapsed state; deleting it here would
+  // discard that lifecycle information and leave an expanded empty drawer.
   for (const utility of utilities) {
     if (utility.visibleByDefault !== false) ensureUtilityPanel(api, utility);
   }
@@ -701,9 +752,11 @@ function reconcileWorkspace(api: DockviewApi): void {
 
 export function WorkspaceDock({ onOpenScene }: { onOpenScene: (assetPath: string) => void }) {
   const store = useEditorStore();
+  const dockRootRef = useRef<HTMLElement | null>(null);
   const apiRef = useRef<DockviewApi | null>(null);
   const readyCleanupRef = useRef<(() => void) | null>(null);
   const lastSyncedDocumentRef = useRef<string | null>(null);
+  const utilityRevealOriginsRef = useRef(new Map<string, UtilityRevealOrigin>());
   const documentVersion = useSyncExternalStore(
     subscribeWorkspaceDocuments,
     workspaceDocumentRegistryVersion,
@@ -766,6 +819,15 @@ export function WorkspaceDock({ onOpenScene }: { onOpenScene: (assetPath: string
     ({ api }: { api: DockviewApi }) => {
       apiRef.current = api;
       reconcileWorkspace(api);
+      const dockRoot = dockRootRef.current;
+      const resizeObserver =
+        dockRoot && typeof ResizeObserver !== 'undefined'
+          ? new ResizeObserver(([entry]) => {
+              if (!entry) return;
+              api.layout(entry.contentRect.width, entry.contentRect.height, true);
+            })
+          : null;
+      if (dockRoot) resizeObserver?.observe(dockRoot);
       const uninstallPersistence = installWorkspaceStatePersistence(store, api, () =>
         reconcileWorkspace(api),
       );
@@ -774,8 +836,12 @@ export function WorkspaceDock({ onOpenScene }: { onOpenScene: (assetPath: string
       if (initialDocumentId) api.getPanel(initialDocumentId)?.api.setActive();
 
       const activeDisposable = api.onDidActivePanelChange((event) => {
-        if (event.origin !== 'user' || !event.panel) return;
+        if (!event.panel) return;
         const params = event.panel.api.getParameters<WorkspacePanelParams>();
+        // Dockview does not report every tab click with `origin: 'user'`
+        // (notably after an edge utility owned focus). The panel kind is the
+        // semantic boundary we actually need: document panels select the
+        // active document, while utilities/navigators leave it untouched.
         if (params.kind === 'document') activateWorkspaceDocument(params.documentId);
       });
 
@@ -797,6 +863,7 @@ export function WorkspaceDock({ onOpenScene }: { onOpenScene: (assetPath: string
           ensureUtilityPanel(api, utility, false);
           const panel = api.getPanel(`utility:${id}`);
           if (!panel) return;
+          rememberUtilityReveal(panel, utilityRevealOriginsRef.current, id);
           panel.api.setActive();
           if (panel.api.location.type === 'edge') panel.api.group.api.expand();
         },
@@ -811,10 +878,27 @@ export function WorkspaceDock({ onOpenScene }: { onOpenScene: (assetPath: string
           if (panel.api.isActive && panel.api.location.type === 'edge' && !group.isCollapsed()) {
             group.collapse();
           } else {
+            rememberUtilityReveal(panel, utilityRevealOriginsRef.current, id);
             panel.api.setActive();
             if (panel.api.location.type === 'edge') group.expand();
           }
         },
+        closeUtility(id) {
+          const panel = api.getPanel(`utility:${id}`);
+          const origin = utilityRevealOriginsRef.current.get(id);
+          utilityRevealOriginsRef.current.delete(id);
+          if (!panel) return;
+          const wasActive = panel.api.isActive;
+          const group = panel.api.group;
+          const wasEdgePanel = panel.api.location.type === 'edge';
+          panel.api.close();
+          if (!wasActive) return;
+          const previous = origin?.previousPanelId
+            ? api.getPanel(origin.previousPanelId)
+            : undefined;
+          previous?.api.setActive();
+          if (wasEdgePanel && (!previous || origin?.wasCollapsed !== false)) group.api.collapse();
+        },
         showAuxiliary(id) {
           if (id !== 'undo-history') return;
           if (!api.getPanel(HISTORY_PANEL_ID)) {
@@ -847,6 +931,7 @@ export function WorkspaceDock({ onOpenScene }: { onOpenScene: (assetPath: string
       const uninstallCommands = installWorkspaceDockCommands(commands);
       readyCleanupRef.current?.();
       readyCleanupRef.current = () => {
+        resizeObserver?.disconnect();
         activeDisposable.dispose();
         uninstallPersistence();
         uninstallCommands();
@@ -861,6 +946,7 @@ export function WorkspaceDock({ onOpenScene }: { onOpenScene: (assetPath: string
 
   return (
     <main
+      ref={dockRootRef}
       className="vgai-workspace-dock"
       aria-label="Editor workspace"
       data-testid="workspace-dock"
@@ -873,7 +959,7 @@ export function WorkspaceDock({ onOpenScene }: { onOpenScene: (assetPath: string
           tabComponents={tabs}
           onReady={onReady}
           theme={vgaiDockviewTheme}
-          defaultRenderer="always"
+          defaultRenderer="onlyWhenVisible"
           keyboardNavigation
           disableFloatingGroups={false}
           singleTabMode="fullwidth"

package/src/components/asset-documents.tsx

@@ -12,7 +12,8 @@
  * open-asset`) keeps its meaning unchanged:
  *
  *   - project asset  → the serving path itself (`/textures/crate.png`)
- *   - legacy entity editor key → `asset-lab:entity:<entityId>`
+ *   - Asset Editor → `asset-editor:entity:<entityId>`; the legacy entity editor key
+ *     `asset-lab:entity:<entityId>` remains an input compatibility alias
  *   - online asset   → `online:<source>:<id>`
  *
  * Titles are source-owned file names as authored (§8 — `crate.png`, never a
@@ -60,11 +61,13 @@ import './asset-workflow.css';
 export interface AssetDocumentSpec {
   readonly assetPath: string;
   readonly kind: AssetKind;
-  /** Entity source for a session-only live-object Asset Editor. Never serialized. */
+  /** Entity source for a session-only Asset Editor document. Never serialized. */
   readonly entityId?: string;
   /** Present while this document shows an online (not-yet-downloaded) asset. */
   readonly online?: OnlineAssetInfo;
   readonly unavailableReason?: string;
+  /** Incremented when the file bytes change at the same path. */
+  readonly revision?: number;
 }
 
 export interface AssetDocumentMutation {
@@ -81,6 +84,7 @@ const _specs =
 const _pathAliases =
   (hotData?.['vgai:asset-document-path-aliases'] as Map<string, string> | undefined) ??
   new Map<string, string>();
+const _focusReturnTargets = new Map<string, HTMLElement>();
 if (hotData) {
   // Workspace descriptors intentionally survive compatible Fast Refreshes.
   // Their specs must survive with them or the next persistence snapshot drops
@@ -111,13 +115,20 @@ export function assetDocumentsVersion(): number {
 
 /** The spec behind an open asset document id, or `undefined`. */
 export function assetDocumentSpec(id: string): AssetDocumentSpec | undefined {
-  return _specs.get(id);
+  return _specs.get(migrateAssetEditorDocumentId(id));
+}
+
+/** Compatibility window: old session/control ids resolve to the canonical Asset Editor id. */
+export function migrateAssetEditorDocumentId(id: string): string {
+  return id.startsWith('asset-lab:entity:')
+    ? `asset-editor:entity:${id.slice('asset-lab:entity:'.length)}`
+    : id;
 }
 
 /** Whether `id` is one of this module's asset documents (used by
  *  `command-listener.ts` to report the legacy `activeTabKey` facet). */
 export function isAssetDocumentId(id: string): boolean {
-  return _specs.has(id);
+  return _specs.has(migrateAssetEditorDocumentId(id));
 }
 
 /** The narrow store surface asset documents need (T6.3 gate hand-off). */
@@ -125,7 +136,7 @@ export interface AssetDocumentStore {
   setActiveViewportTab(tab: 'scene' | 'game'): void;
 }
 
-/** A live-entity Asset Editor additionally needs the object map for its §8 title. */
+/** The Asset Editor additionally needs the live object map for its §8 title. */
 export interface EntityAssetDocumentStore extends AssetDocumentStore {
   readonly objectMap: Map<string, THREE.Object3D>;
 }
@@ -137,6 +148,9 @@ function openSpecDocument(
   spec: AssetDocumentSpec,
   provenance?: WorkspaceDocumentDescriptor['provenance'],
 ): string {
+  if (typeof document !== 'undefined' && document.activeElement instanceof HTMLElement) {
+    _focusReturnTargets.set(id, document.activeElement);
+  }
   if (!_specs.has(id)) {
     _specs.set(id, spec);
     notifyChanged();
@@ -151,6 +165,9 @@ function openSpecDocument(
     onActivate: () => store.setActiveViewportTab('scene'),
     onDispose: (documentId) => {
       if (_specs.delete(documentId)) notifyChanged();
+      const focusTarget = _focusReturnTargets.get(documentId);
+      _focusReturnTargets.delete(documentId);
+      if (focusTarget?.isConnected) setTimeout(() => focusTarget.focus(), 0);
     },
   };
   return openWorkspaceDocument(descriptor);
@@ -171,7 +188,7 @@ export function openAssetDocument(
   return openSpecDocument(store, id, title, { assetPath, kind }, { sourcePath: assetPath });
 }
 
-/** Open the typed Asset Editor for a live entity (legacy id retained for API compatibility). */
+/** Open the Asset Editor document for a live entity. */
 export function openEntityAssetDocument(store: EntityAssetDocumentStore, entityId: string): void {
   const object = store.objectMap.get(entityId);
   if (!object) return;
@@ -182,7 +199,7 @@ export function openEntityAssetDocument(store: EntityAssetDocumentStore, entityI
   const title = entity?.name ?? object.name ?? entityId;
   openSpecDocument(
     store,
-    `asset-lab:entity:${entityId}`,
+    `asset-editor:entity:${entityId}`,
     title,
     { assetPath: '', kind: 'model', entityId },
     { origin: `entity:${entityId}` },
@@ -221,6 +238,7 @@ export function resolveOnlineAssetDocument(id: string, localPath: string): void
 export function __resetAssetDocumentsForTest(): void {
   _specs.clear();
   _pathAliases.clear();
+  _focusReturnTargets.clear();
   notifyChanged();
 }
 
@@ -252,6 +270,12 @@ export function applyAssetDocumentMutation(
       unavailableReason: `The source ${spec.assetPath} was deleted. Undo the deletion or close this editor.`,
     });
     notifyChanged();
+  } else if (
+    detail.type === 'change' &&
+    detail.paths?.some((path) => normalizeAssetPath(path) === current)
+  ) {
+    _specs.set(documentId, { ...spec, revision: (spec.revision ?? 0) + 1 });
+    notifyChanged();
   }
 }
 
@@ -321,26 +345,29 @@ function AssetViewerBody({
     );
   }
   const title = spec.assetPath.split('/').pop() || spec.entityId || 'Asset';
+  const viewerKey = `${id}:${spec.revision ?? 0}`;
   if (route === 'model')
     return (
       <ModelViewer
         documentId={id}
+        key={viewerKey}
         assetPath={spec.assetPath || undefined}
         entityId={spec.entityId}
         active={active}
       />
     );
-  if (route === 'source') return <SourceAssetViewer assetPath={spec.assetPath} active={active} />;
+  if (route === 'source')
+    return <SourceAssetViewer key={viewerKey} assetPath={spec.assetPath} active={active} />;
   let viewer: ReactNode;
   switch (route) {
     case 'image':
-      viewer = <ImageViewer assetPath={spec.assetPath} />;
+      viewer = <ImageViewer key={viewerKey} assetPath={spec.assetPath} />;
       break;
     case 'audio':
-      viewer = <AudioViewer assetPath={spec.assetPath} />;
+      viewer = <AudioViewer key={viewerKey} assetPath={spec.assetPath} />;
       break;
     case 'material':
-      viewer = <MaterialAssetEditor assetPath={spec.assetPath} documentId={id} />;
+      viewer = <MaterialAssetEditor key={viewerKey} assetPath={spec.assetPath} documentId={id} />;
       break;
     case 'input-map':
       viewer = <InputMapViewer assetPath={spec.assetPath} documentId={id} />;