@vgai/editor 0.4.0 → 0.4.1

package/src/components/OnlineAssetBrowser.tsx

@@ -1,24 +1,34 @@
 import { faSpinner } from '@fortawesome/free-solid-svg-icons';
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { clearSelectedAsset, getSelectedAsset, setSelectedAsset } from '../asset-selection';
+import { beginAssetImportJob, updateAssetImportJob } from '../asset-workflow/asset-import-jobs';
 import {
   type AssetLibrarySort,
   assetLibraryStateKey,
   onlineAssetKey,
   queryAssetLibrary,
 } from '../asset-workflow/asset-library-query';
+import { confirmAssetAction } from '../asset-workflow/asset-workflow-quality';
 import { Button, Checkbox, EditorIcon, Select, StateSurface, TextInput } from '../design-system';
 import { useEditorStore } from '../EditorContext';
 import {
+  type DownloadOnlineAssetResult,
+  downloadOnlineAsset,
   getAssetLibraryCategories,
   getDownloadedAssetPath,
+  getOnlineAssetFiles,
   loadDownloadedAssets,
   type OnlineAsset,
   onAssetDownloaded,
   searchOnlineAssets,
 } from '../editor-api';
 import { getCurrentProject } from '../project-manager';
+import { AssetImportJobStatus } from './AssetImportJobStatus';
 import { openOnlineAssetDocument } from './asset-documents';
+import {
+  downloadOnlineAssetWithHistory,
+  recordAppliedAssetImportsWithHistory,
+} from './asset-editor-persistence';
 import './asset-workflow.css';
 
 type Source = 'local' | 'polyhaven' | 'ambientcg';
@@ -107,6 +117,95 @@ function toOnlineInfo(asset: OnlineAsset) {
   };
 }
 
+function retainAvailableSelection(
+  current: ReadonlySet<string>,
+  assets: readonly OnlineAsset[],
+): Set<string> {
+  const available = new Set(assets.map(onlineAssetKey));
+  return new Set([...current].filter((key) => available.has(key)));
+}
+
+function nextOnlineSelection(
+  assets: readonly OnlineAsset[],
+  current: ReadonlySet<string>,
+  asset: OnlineAsset,
+  anchor: string | null,
+  modifiers: { range?: boolean; toggle?: boolean },
+): { keys: Set<string>; anchor: string } {
+  const key = onlineAssetKey(asset);
+  if (modifiers.range && anchor) {
+    const startIndex = assets.findIndex((candidate) => onlineAssetKey(candidate) === anchor);
+    const endIndex = assets.findIndex((candidate) => onlineAssetKey(candidate) === key);
+    if (startIndex >= 0 && endIndex >= 0) {
+      const [start, end] = startIndex < endIndex ? [startIndex, endIndex] : [endIndex, startIndex];
+      return { keys: new Set(assets.slice(start, end + 1).map(onlineAssetKey)), anchor };
+    }
+  }
+  if (!modifiers.toggle) return { keys: new Set([key]), anchor: key };
+  const keys = new Set(current);
+  if (keys.has(key)) keys.delete(key);
+  else keys.add(key);
+  return { keys, anchor: key };
+}
+
+/** Run one catalog acquisition independently of the Library component's
+ * lifetime. A retry journals its successful mutation immediately; the first
+ * pass returns history to the caller so a batch can be one transaction. */
+async function importOnlineAssetJob(
+  asset: OnlineAsset,
+  journalImmediately = false,
+): Promise<DownloadOnlineAssetResult | null> {
+  const jobId = `batch:${onlineAssetKey(asset)}`;
+  const job = beginAssetImportJob(jobId, asset.name);
+  updateAssetImportJob(jobId, {
+    stage: 'fetch',
+    loaded: 0,
+    total: 0,
+    status: 'running',
+  });
+  try {
+    const files = await getOnlineAssetFiles(asset.source, asset.id);
+    const file = files[0];
+    if (!file) throw new Error('No healthy delivery is available for this asset.');
+    const params = {
+      source: asset.source,
+      id: asset.id,
+      name: asset.name,
+      url: file.url,
+      format: file.format,
+      jobId,
+      ...(file.includes ? { includes: file.includes } : {}),
+      signal: job.controller.signal,
+    };
+    const result = journalImmediately
+      ? await downloadOnlineAssetWithHistory(params, `Import ${asset.name}`)
+      : await downloadOnlineAsset(params);
+    if (!result.ok) throw new Error(result.error ?? 'The import was rejected.');
+    updateAssetImportJob(jobId, {
+      stage: 'commit',
+      loaded: file.sizeBytes ?? 1,
+      total: file.sizeBytes ?? 1,
+      status: result.alreadyExists ? 'skipped' : 'imported',
+      ...(result.path ? { message: result.path } : {}),
+    });
+    if (journalImmediately) {
+      await loadDownloadedAssets();
+      window.dispatchEvent(new CustomEvent('editor:assets-changed'));
+    }
+    return result;
+  } catch (cause) {
+    const cancelled = job.controller.signal.aborted;
+    updateAssetImportJob(jobId, {
+      status: cancelled ? 'cancelled' : 'failed',
+      message: `${asset.name} · fetch/convert/validate/commit: ${cause instanceof Error ? cause.message : String(cause)}`,
+      retry: () => {
+        void importOnlineAssetJob(asset, true);
+      },
+    });
+    return null;
+  }
+}
+
 function SourcePane(props: {
   source: Source;
   assetType: string;
@@ -320,9 +419,10 @@ function AssetCardThumbnail({ asset }: { asset: OnlineAsset }) {
 function VirtualAssetList(props: {
   assets: readonly OnlineAsset[];
   selectedId: string | null;
+  selectedKeys: ReadonlySet<string>;
   loading: boolean;
   hasMore: boolean;
-  onSelect(asset: OnlineAsset): void;
+  onSelect(asset: OnlineAsset, modifiers?: { range?: boolean; toggle?: boolean }): void;
   onOpen(asset: OnlineAsset): void;
   onLoadMore(): void;
 }) {
@@ -394,9 +494,10 @@ function VirtualAssetList(props: {
       aria-busy={props.loading}
       tabIndex={0}
       onKeyDown={onKeyDown}
-      onScroll={(event) =>
-        setMetrics((current) => ({ ...current, scrollTop: event.currentTarget.scrollTop }))
-      }
+      onScroll={(event) => {
+        const scrollTop = event.currentTarget.scrollTop;
+        setMetrics((current) => ({ ...current, scrollTop }));
+      }}
     >
       <div
         className="vgai-asset-library-navigator__result-space"
@@ -409,11 +510,16 @@ function VirtualAssetList(props: {
               key={onlineAssetKey(asset)}
               type="button"
               role="option"
-              aria-selected={props.selectedId === asset.id}
+              aria-selected={props.selectedKeys.has(onlineAssetKey(asset))}
               aria-label={`${asset.name}, ${asset.type}, ${asset.source}`}
               className="vgai-asset-library-row"
               style={{ top: index * rowHeight }}
-              onClick={() => props.onSelect(asset)}
+              onClick={(event) =>
+                props.onSelect(asset, {
+                  range: event.shiftKey,
+                  toggle: event.metaKey || event.ctrlKey,
+                })
+              }
               onDoubleClick={() => props.onOpen(asset)}
               onKeyDown={(event) => {
                 if (event.key !== 'Enter') return;
@@ -430,6 +536,9 @@ function VirtualAssetList(props: {
                   {asset.type} · {asset.source === 'local' ? 'Catalog' : asset.source}
                 </span>
               </span>
+              {getDownloadedAssetPath(asset.source, asset.id) && (
+                <span className="vgai-asset-badge">In project</span>
+              )}
             </Button>
           );
         })}
@@ -446,6 +555,7 @@ function VirtualAssetList(props: {
 function NavigatorAssetLibrary(props: {
   assets: readonly OnlineAsset[];
   selectedId: string | null;
+  selectedKeys: ReadonlySet<string>;
   source: Source;
   assetType: string;
   sort: Sort;
@@ -457,11 +567,12 @@ function NavigatorAssetLibrary(props: {
   filtersOpen: boolean;
   filters: React.ReactNode;
   canSaveSearch: boolean;
+  onBatchImport(): void;
   onSource(source: Source): void;
   onType(type: string): void;
   onSort(sort: Sort): void;
   onSearch(query: string): void;
-  onSelect(asset: OnlineAsset): void;
+  onSelect(asset: OnlineAsset, modifiers?: { range?: boolean; toggle?: boolean }): void;
   onOpen(asset: OnlineAsset): void;
   onLoadMore(): void;
   onRetry(): void;
@@ -533,6 +644,12 @@ function NavigatorAssetLibrary(props: {
             ? 'Loading…'
             : `${props.assets.length.toLocaleString()} of ${props.total.toLocaleString()}`}
         </span>
+        {props.selectedKeys.size > 1 && (
+          <Button variant="solid" size="compact" onClick={props.onBatchImport}>
+            Add {props.selectedKeys.size} selected to project
+          </Button>
+        )}
+        <AssetImportJobStatus />
       </div>
       {props.filtersOpen && (
         <div className="vgai-asset-library-navigator__filter-drawer">
@@ -576,6 +693,7 @@ function NavigatorAssetLibrary(props: {
         <VirtualAssetList
           assets={props.assets}
           selectedId={props.selectedId}
+          selectedKeys={props.selectedKeys}
           loading={props.loading}
           hasMore={props.hasMore}
           onSelect={props.onSelect}
@@ -613,8 +731,10 @@ export function OnlineAssetBrowser() {
   const [error, setError] = useState<string | null>(null);
   const [offset, setOffset] = useState(0);
   const [selectedId, setSelectedId] = useState<string | null>(null);
+  const [selectedKeys, setSelectedKeys] = useState<Set<string>>(new Set());
   const [categories, setCategories] = useState<string[]>([]);
   const requestId = useRef(0);
+  const selectionAnchor = useRef<string | null>(null);
 
   useEffect(() => {
     const projectId = getCurrentProject()?.rootPath ?? '__unscoped__';
@@ -657,6 +777,7 @@ export function OnlineAssetBrowser() {
   }, [source, assetType]);
 
   const doSearch = useCallback(
+    // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: one request boundary owns stale-response rejection, paging, retained selection, and offline recovery.
     async (nextOffset: number, append: boolean) => {
       const currentRequest = ++requestId.current;
       setLoading(true);
@@ -673,6 +794,19 @@ export function OnlineAssetBrowser() {
         const result = await searchOnlineAssets(params);
         if (currentRequest !== requestId.current) return;
         setAssets((current) => (append ? [...current, ...result.assets] : result.assets));
+        if (!append) {
+          setSelectedKeys((current) => {
+            const retained = retainAvailableSelection(current, result.assets);
+            if (retained.size === 0) {
+              selectionAnchor.current = null;
+              if (getSelectedAsset()?.origin === 'library') clearSelectedAsset();
+            }
+            return retained;
+          });
+          setSelectedId((current) =>
+            current && result.assets.some((asset) => asset.id === current) ? current : null,
+          );
+        }
         setTotal(result.total);
       } catch {
         if (!append) setAssets([]);
@@ -689,8 +823,6 @@ export function OnlineAssetBrowser() {
   useEffect(() => {
     const timer = window.setTimeout(() => {
       setOffset(0);
-      setSelectedId(null);
-      if (getSelectedAsset()?.origin === 'library') clearSelectedAsset();
       void doSearch(0, false);
     }, 250);
     return () => window.clearTimeout(timer);
@@ -750,8 +882,7 @@ export function OnlineAssetBrowser() {
       health: count(assets.map((asset) => asset.capabilities?.health ?? 'unsupported')),
     };
   }, [assets]);
-  const onSelect = (asset: OnlineAsset) => {
-    setSelectedId(asset.id);
+  const selectForInspector = (asset: OnlineAsset, selectionCount: number) => {
     const localPath = getDownloadedAssetPath(asset.source, asset.id);
     const online = toOnlineInfo(asset);
     setSelectedAsset({
@@ -765,8 +896,27 @@ export function OnlineAssetBrowser() {
             : 'image',
       origin: 'library',
       online,
+      selectionCount,
     });
   };
+  const onSelect = (asset: OnlineAsset, modifiers: { range?: boolean; toggle?: boolean } = {}) => {
+    const key = onlineAssetKey(asset);
+    const { keys: next, anchor } = nextOnlineSelection(
+      filteredAssets,
+      selectedKeys,
+      asset,
+      selectionAnchor.current,
+      modifiers,
+    );
+    selectionAnchor.current = anchor;
+    setSelectedKeys(next);
+    const focused = next.has(key)
+      ? asset
+      : filteredAssets.find((candidate) => next.has(onlineAssetKey(candidate)));
+    setSelectedId(focused?.id ?? null);
+    if (focused) selectForInspector(focused, next.size);
+    else if (getSelectedAsset()?.origin === 'library') clearSelectedAsset();
+  };
   const onOpen = (asset: OnlineAsset) => {
     openOnlineAssetDocument(store, toOnlineInfo(asset));
     const key = onlineAssetKey(asset);
@@ -777,6 +927,40 @@ export function OnlineAssetBrowser() {
     setAssetType(SOURCES.find((entry) => entry.value === nextSource)!.types[0]!.value);
     setCategory('');
   };
+  const onBatchImport = useCallback(async () => {
+    const selectedAssets = filteredAssets.filter((asset) =>
+      selectedKeys.has(onlineAssetKey(asset)),
+    );
+    if (
+      selectedAssets.length < 2 ||
+      !confirmAssetAction(
+        'batch-import',
+        `Add ${selectedAssets.length} selected assets to this project?`,
+      )
+    )
+      return;
+    const results: DownloadOnlineAssetResult[] = [];
+    for (let index = 0; index < selectedAssets.length; index += 2) {
+      const chunk = await Promise.all(
+        selectedAssets.slice(index, index + 2).map((asset) => importOnlineAssetJob(asset)),
+      );
+      results.push(
+        ...chunk.filter((result): result is DownloadOnlineAssetResult => result != null),
+      );
+    }
+    const applied = results.flatMap((result) =>
+      result.ok && result.history ? [result.history] : [],
+    );
+    if (applied.length > 0) {
+      await recordAppliedAssetImportsWithHistory(
+        applied,
+        `Import ${applied.length} asset${applied.length === 1 ? '' : 's'}`,
+      );
+    }
+    await loadDownloadedAssets();
+    setAssets((current) => [...current]);
+    window.dispatchEvent(new CustomEvent('editor:assets-changed'));
+  }, [filteredAssets, selectedKeys]);
   const sourcePane = (
     <SourcePane
       source={source}
@@ -817,6 +1001,7 @@ export function OnlineAssetBrowser() {
     <NavigatorAssetLibrary
       assets={filteredAssets}
       selectedId={selectedId}
+      selectedKeys={selectedKeys}
       source={source}
       assetType={assetType}
       sort={sort}
@@ -828,6 +1013,7 @@ export function OnlineAssetBrowser() {
       filtersOpen={navigatorFiltersOpen}
       filters={sourcePane}
       canSaveSearch={Boolean(searchQuery && !savedSearches.includes(searchQuery))}
+      onBatchImport={() => void onBatchImport()}
       onSource={onSource}
       onType={(value) => {
         setAssetType(value);

package/src/components/ToolHost.tsx

@@ -11,12 +11,12 @@ import { space, themeVars } from '../design-system';
  * also clears a tripped boundary — fix the file, save, retry for free.
  *
  * Chrome stays editor-styled (§3.4): the host provides the scrollable
- * editor-toned container; whatever the tool renders inside is its own
- * business (plain React, the project's choice).
+ * editor-toned container. Contributions use ordinary React for composition
+ * and the public editor widgets for shared interactive controls.
  */
 
 import { Component, type ErrorInfo, type ReactNode } from 'react';
-import type { GlobalTool } from '../tool-loader';
+import { type GlobalToolContribution, getToolContributionClient } from '../tool-loader';
 
 interface ToolErrorBoundaryProps {
   /** Project-relative source file, shown in the crash message. */
@@ -76,15 +76,15 @@ export class ToolErrorBoundary extends Component<ToolErrorBoundaryProps, ToolErr
 /** One project-global tool's content host: editor-styled scroll container +
  *  boundary. Rendered by a center tool DOCUMENT (`tool-documents.tsx`) or a
  *  utility-placement registration (`tool-loader.ts`) since W3. */
-export function ToolHost({ tool }: { tool: GlobalTool }) {
-  const ToolComponent = tool.Component;
+export function ToolHost({ contribution }: { contribution: GlobalToolContribution }) {
+  const ToolComponent = contribution.Component;
   return (
     <div
-      data-testid={`tool-panel-${tool.id}`}
+      data-testid={`tool-panel-${contribution.id}`}
       style={{ flex: 1, minHeight: 0, overflow: 'auto', color: themeVars.content.primary }}
     >
-      <ToolErrorBoundary file={tool.file}>
-        <ToolComponent />
+      <ToolErrorBoundary file={contribution.file}>
+        <ToolComponent tool={contribution.tool} client={getToolContributionClient()} />
       </ToolErrorBoundary>
     </div>
   );

package/src/components/ViewportOverlay.tsx

@@ -8,7 +8,6 @@ import {
 } from '@fortawesome/free-solid-svg-icons';
 import { useEffect, useRef, useState } from 'react';
 import {
-  Button,
   EditorIcon,
   FloatingToolbar,
   IconButton,
@@ -16,21 +15,18 @@ import {
   MenuItem,
   MenuSeparator,
   SplitButtonGroup,
-  Text,
   Tooltip,
 } from '../design-system';
 import { useEditorStore } from '../EditorContext';
-import type { EditorStore, ShadingMode } from '../editor-store';
+import type { EditorStore } from '../editor-store';
+import { ViewportShadingMenu } from './ViewportShadingMenu';
 
-const shadingLabels: Record<ShadingMode, string> = {
-  solid: 'Solid',
-  wireframe: 'Wire',
-  unlit: 'Unlit',
-};
-
-const shadingOrder: ShadingMode[] = ['solid', 'wireframe', 'unlit'];
-
-/** Viewport-level rendering controls. Three-specific controls hide when no 3D world is active. */
+/**
+ * `statsOnly` (spec 28): with no threejs surface showing, the grid, helper,
+ * and shading controls are claims about invisible content — only the stats
+ * toggle (a property of the page, not of any world) survives. The
+ * `ViewportPanel` mount site picks the variant per notify.
+ */
 export function ViewportOverlay({ statsOnly = false }: { statsOnly?: boolean }) {
   const store = useEditorStore();
   return (
@@ -51,20 +47,10 @@ export function ViewportOverlay({ statsOnly = false }: { statsOnly?: boolean })
             </IconButton>
           </Tooltip>
           <HelpersButton store={store} />
-          <Tooltip text={`Shading: ${shadingLabels[store.shadingMode]}`}>
-            <Button
-              variant="ghost"
-              aria-label={`Shading: ${shadingLabels[store.shadingMode]}`}
-              aria-pressed={store.shadingMode !== 'solid'}
-              size="comfortable"
-              onClick={() => {
-                const index = shadingOrder.indexOf(store.shadingMode);
-                store.setShadingMode(shadingOrder[(index + 1) % shadingOrder.length]!);
-              }}
-            >
-              <Text variant="label">{shadingLabels[store.shadingMode]}</Text>
-            </Button>
-          </Tooltip>
+          <ViewportShadingMenu
+            mode={store.shadingMode}
+            onChange={(mode) => store.setShadingMode(mode)}
+          />
         </>
       )}
       <Tooltip text={`Viewport stats: ${store.showStats ? 'On' : 'Off'}`}>
@@ -95,6 +81,7 @@ function HelpersButton({ store }: { store: EditorStore }) {
   }, [open]);
 
   const helperTypes = [
+    { key: 'bounds' as const, label: 'Bounds' },
     { key: 'lights' as const, label: 'Lights' },
     { key: 'cameras' as const, label: 'Cameras' },
     { key: 'colliders' as const, label: 'Colliders' },

package/src/components/ViewportPanel.tsx

@@ -1,5 +1,6 @@
 import { type RenderScope, resolveRenderSettings } from '@engine/render/render-settings';
-import { applyRendererSettings, applyScenePostProcessing } from '@engine/setup/setup-renderer';
+import { ViewportShadingRenderer } from '@engine/render/viewport-shading';
+import { applyRendererSettings, applySceneRenderPipeline } from '@engine/setup/setup-renderer';
 import { EffectComposer } from 'postprocessing';
 import { useEffect, useRef, useSyncExternalStore } from 'react';
 import * as THREE from 'three';
@@ -39,6 +40,7 @@ import { loadInitialScene } from '../initial-scene';
 import { setupNavMeshHandlers } from '../navmesh-handler';
 import { bindPlayMode } from '../play-mode';
 import { resolvePreviewBoneAttachments } from '../scene-sync';
+import { isEditorViewportShadingTarget } from '../viewport-shading-boundary';
 import { CameraInfo } from './CameraInfo';
 import { StatsOverlay } from './StatsOverlay';
 import { ToolStrip } from './Toolbar';
@@ -95,10 +97,10 @@ export function ViewportPanel() {
     applyRendererSettings(renderer, rendering, window.devicePixelRatio);
     renderer.setSize(Math.max(1, container.clientWidth), Math.max(1, container.clientHeight));
     renderer.shadowMap.type = THREE.PCFSoftShadowMap;
-    renderer.toneMapping = THREE.NoToneMapping;
 
     // --- Post-processing ---
     const composer = new EffectComposer(renderer);
+    const viewportShading = new ViewportShadingRenderer();
 
     // --- Scene ---
     const scene = new THREE.Scene();
@@ -126,14 +128,8 @@ export function ViewportPanel() {
 
     // --- Composer rebuild ---
     function rebuildComposer(): void {
-      // Re-apply live renderer settings (shadows, resolutionScale) so env edits
-      // take effect; the post-processing master switch is handled inside
-      // applyScenePostProcessing via env.rendering.
-      applyRendererSettings(
-        renderer,
-        store.environment?.rendering as RenderScope | undefined,
-        window.devicePixelRatio,
-      );
+      // Re-apply the complete authored render pipeline so live environment
+      // edits use the same renderer configuration as Game.
       // World-hidden eye: while the focused threejs world is hidden, its
       // authored post chain (bloom/vignette/…) must not render either — pass
       // no environment so the composer builds bare. `editor-viewport.ts`
@@ -141,14 +137,17 @@ export function ViewportPanel() {
       // hide/show edges, which is what re-runs this rebuild.
       const hiddenWorldId = resolveFocusedViewportWorldId(store);
       const worldHidden = hiddenWorldId !== null && isWorldHidden(hiddenWorldId);
-      applyScenePostProcessing(
+      applySceneRenderPipeline(
         composer,
         renderer,
         store.scene ?? scene,
         viewport.camera,
         worldHidden ? undefined : store.environment,
-        store.objectMap,
-        buildEntityTagMap(store),
+        {
+          basePixelRatio: window.devicePixelRatio,
+          objectMap: store.objectMap,
+          entityTags: buildEntityTagMap(store),
+        },
       );
     }
 
@@ -250,7 +249,12 @@ export function ViewportPanel() {
         tickEditorAnimations(store.objectMap, dt);
       }
       viewport.batchedRenderer.update(dt);
-      composer.render(dt);
+      viewportShading.render(
+        viewport.currentScene,
+        store.shadingMode,
+        () => composer.render(dt),
+        isEditorViewportShadingTarget,
+      );
       viewport.renderViewCube(renderer);
       viewport.renderCameraPreview(renderer);
 
@@ -361,6 +365,7 @@ export function ViewportPanel() {
       window.removeEventListener('error', onError);
       window.removeEventListener('unhandledrejection', onUnhandledRejection);
       viewport.dispose();
+      viewportShading.dispose();
       // EffectComposer owns input/output WebGLRenderTargets + per-pass resources
       // that renderer.dispose() does NOT free — dispose it to avoid leaking GPU
       // render targets on unmount (incl. React StrictMode's mount/unmount/remount).

package/src/components/ViewportShadingMenu.tsx

@@ -0,0 +1,103 @@
+import type { ViewportShadingMode } from '@engine/render/viewport-shading';
+import { faCaretDown, faCheck } from '@fortawesome/free-solid-svg-icons';
+import { useEffect, useRef, useState } from 'react';
+import { Button, EditorIcon, Menu, MenuItem, Tooltip, themeVars, zIndex } from '../design-system';
+
+export const viewportShadingModes: ReadonlyArray<{
+  mode: ViewportShadingMode;
+  label: string;
+  description: string;
+}> = [
+  { mode: 'solid', label: 'Solid', description: 'Authored materials and lighting' },
+  { mode: 'unlit', label: 'Unlit', description: 'Base color without scene lighting' },
+  { mode: 'wireframe', label: 'Wireframe', description: 'Renderable triangle edges' },
+  { mode: 'normals', label: 'Normals', description: 'Surface-normal direction colors' },
+  { mode: 'overdraw', label: 'Overdraw', description: 'Additive overlap visualization' },
+];
+
+export function ViewportShadingMenu({
+  mode,
+  onChange,
+  disabled = false,
+}: {
+  mode: ViewportShadingMode;
+  onChange: (mode: ViewportShadingMode) => void;
+  disabled?: boolean;
+}) {
+  const [open, setOpen] = useState(false);
+  const ref = useRef<HTMLDivElement>(null);
+  const active = viewportShadingModes.find((entry) => entry.mode === mode)!;
+
+  useEffect(() => {
+    if (!open) return;
+    const close = (event: PointerEvent) => {
+      if (!ref.current?.contains(event.target as Node)) setOpen(false);
+    };
+    document.addEventListener('pointerdown', close);
+    return () => document.removeEventListener('pointerdown', close);
+  }, [open]);
+
+  return (
+    <div ref={ref} style={{ position: 'relative' }}>
+      <Tooltip text={`Viewport shading: ${active.label}`}>
+        <Button
+          type="button"
+          size="compact"
+          variant={mode === 'solid' ? 'ghost' : 'secondary'}
+          aria-label={`Viewport shading: ${active.label}`}
+          aria-haspopup="menu"
+          aria-expanded={open}
+          disabled={disabled}
+          onClick={() => setOpen((value) => !value)}
+          style={{ display: 'inline-flex', alignItems: 'center', gap: 5, minWidth: 66 }}
+        >
+          <span>{active.label}</span>
+          <EditorIcon icon={faCaretDown} size="xs" />
+        </Button>
+      </Tooltip>
+      {open && !disabled && (
+        <Menu
+          autoFocusFirst
+          aria-label="Viewport shading modes"
+          onDismiss={() => setOpen(false)}
+          style={{
+            position: 'absolute',
+            top: 'calc(100% + 4px)',
+            right: 0,
+            zIndex: zIndex.sticky,
+            minWidth: 230,
+          }}
+        >
+          {viewportShadingModes.map((entry) => (
+            <MenuItem
+              key={entry.mode}
+              role="menuitemradio"
+              aria-checked={entry.mode === mode}
+              onSelect={() => {
+                onChange(entry.mode);
+                setOpen(false);
+              }}
+              style={{ display: 'grid', gridTemplateColumns: '14px 1fr', gap: 7 }}
+            >
+              <span style={{ opacity: entry.mode === mode ? 1 : 0 }}>
+                <EditorIcon icon={faCheck} size="xs" />
+              </span>
+              <span>
+                <span style={{ display: 'block' }}>{entry.label}</span>
+                <span
+                  style={{
+                    display: 'block',
+                    color: themeVars.content.dim,
+                    fontSize: 10,
+                  }}
+                >
+                  {entry.description}
+                </span>
+              </span>
+            </MenuItem>
+          ))}
+        </Menu>
+      )}
+    </div>
+  );
+}