@ifc-lite/viewer 1.9.0 → 1.11.0

package/src/components/viewer/hierarchy/treeDataBuilder.ts

@@ -132,7 +132,9 @@ function buildSpatialNodes(
     id: nodeId,
     expressIds: [spatialNode.expressId],
     modelIds: [modelId],
-    name: spatialNode.name || `${nodeType} #${spatialNode.expressId}`,
+    name: (spatialNode.name && spatialNode.name.toLowerCase() !== 'unknown')
+      ? spatialNode.name
+      : nodeType,
     type: nodeType,
     depth,
     hasChildren,

package/src/components/viewer/useAnimationLoop.ts

@@ -8,7 +8,7 @@
  */
 
 import { useEffect, type MutableRefObject, type RefObject } from 'react';
-import type { Renderer } from '@ifc-lite/renderer';
+import type { Renderer, VisualEnhancementOptions } from '@ifc-lite/renderer';
 import type { SectionPlane } from '@/store';
 
 export interface UseAnimationLoopParams {
@@ -24,6 +24,7 @@ export interface UseAnimationLoopParams {
   selectedEntityIdRef: MutableRefObject<number | null>;
   selectedModelIndexRef: MutableRefObject<number | undefined>;
   clearColorRef: MutableRefObject<[number, number, number, number]>;
+  visualEnhancementRef: MutableRefObject<VisualEnhancementOptions>;
   sectionPlaneRef: MutableRefObject<SectionPlane>;
   sectionRangeRef: MutableRefObject<{ min: number; max: number } | null>;
   lastCameraStateRef: MutableRefObject<{
@@ -53,6 +54,7 @@ export function useAnimationLoop(params: UseAnimationLoopParams): void {
     selectedEntityIdRef,
     selectedModelIndexRef,
     clearColorRef,
+    visualEnhancementRef,
     sectionPlaneRef,
     sectionRangeRef,
     lastCameraStateRef,
@@ -87,6 +89,7 @@ export function useAnimationLoop(params: UseAnimationLoopParams): void {
           selectedId: selectedEntityIdRef.current,
           selectedModelIndex: selectedModelIndexRef.current,
           clearColor: clearColorRef.current,
+          visualEnhancement: visualEnhancementRef.current,
           sectionPlane: activeToolRef.current === 'section' ? {
             ...sectionPlaneRef.current,
             min: sectionRangeRef.current?.min,

package/src/components/viewer/useKeyboardControls.ts

@@ -11,6 +11,7 @@ import { useEffect, type MutableRefObject } from 'react';
 import type { Renderer } from '@ifc-lite/renderer';
 import type { MeshData, CoordinateInfo } from '@ifc-lite/geometry';
 import type { SectionPlane } from '@/store';
+import { goHomeFromStore } from '@/store/homeView';
 import { getEntityBounds } from '../../utils/viewportUtils.js';
 
 export interface UseKeyboardControlsParams {
@@ -132,8 +133,7 @@ export function useKeyboardControls(params: UseKeyboardControlsParams): void {
 
       // Home view (H) - reset to isometric
       if (e.key === 'h' || e.key === 'H') {
-        camera.zoomToFit(geometryBoundsRef.current.min, geometryBoundsRef.current.max, 500);
-        calculateScale();
+        goHomeFromStore();
       }
 
       // Fit all / Zoom extents (Z)

package/src/components/viewer/useRenderUpdates.ts

@@ -8,7 +8,7 @@
  */
 
 import { useEffect, type MutableRefObject } from 'react';
-import type { Renderer, CutPolygon2D, DrawingLine2D } from '@ifc-lite/renderer';
+import type { Renderer, CutPolygon2D, DrawingLine2D, VisualEnhancementOptions } from '@ifc-lite/renderer';
 import type { CoordinateInfo } from '@ifc-lite/geometry';
 import type { Drawing2D } from '@ifc-lite/drawing-2d';
 import type { SectionPlane } from '@/store';
@@ -21,6 +21,7 @@ export interface UseRenderUpdatesParams {
   // Theme
   theme: string;
   clearColorRef: MutableRefObject<[number, number, number, number]>;
+  visualEnhancementRef: MutableRefObject<VisualEnhancementOptions>;
 
   // Visibility/selection state (reactive values, not refs)
   hiddenEntities: Set<number>;
@@ -46,6 +47,7 @@ export interface UseRenderUpdatesParams {
   // Drawing 2D
   drawing2D: Drawing2D | null;
   show3DOverlay: boolean;
+  showHiddenLines: boolean;
 }
 
 export function useRenderUpdates(params: UseRenderUpdatesParams): void {
@@ -54,6 +56,7 @@ export function useRenderUpdates(params: UseRenderUpdatesParams): void {
     isInitialized,
     theme,
     clearColorRef,
+    visualEnhancementRef,
     hiddenEntities,
     isolatedEntities,
     selectedEntityId,
@@ -73,6 +76,7 @@ export function useRenderUpdates(params: UseRenderUpdatesParams): void {
     activeToolRef,
     drawing2D,
     show3DOverlay,
+    showHiddenLines,
   } = params;
 
   // Theme-aware clear color update
@@ -88,6 +92,7 @@ export function useRenderUpdates(params: UseRenderUpdatesParams): void {
         selectedId: selectedEntityIdRef.current,
         selectedModelIndex: selectedModelIndexRef.current,
         clearColor: clearColorRef.current,
+        visualEnhancement: visualEnhancementRef.current,
       });
     }
   }, [theme, isInitialized]);
@@ -106,8 +111,13 @@ export function useRenderUpdates(params: UseRenderUpdatesParams): void {
         expressId: cp.entityId,  // DrawingPolygon uses entityId
       }));
 
-      // No hatching lines for 3D overlay (too dense)
-      const lines: DrawingLine2D[] = [];
+      // Include linework from the generated drawing on the section plane overlay.
+      const lines: DrawingLine2D[] = drawing2D.lines
+        .filter((line) => showHiddenLines || line.visibility !== 'hidden')
+        .map((line) => ({
+          line: line.line,
+          category: line.category,
+        }));
 
       // Upload to renderer - will be drawn on the section plane
       // Pass sectionRange to match exactly what render() uses for section plane position
@@ -132,13 +142,14 @@ export function useRenderUpdates(params: UseRenderUpdatesParams): void {
       selectedIds: selectedEntityIdsRef.current,
       selectedModelIndex: selectedModelIndexRef.current,
       clearColor: clearColorRef.current,
+      visualEnhancement: visualEnhancementRef.current,
       sectionPlane: activeTool === 'section' ? {
         ...sectionPlane,
         min: sectionRangeRef.current?.min,
         max: sectionRangeRef.current?.max,
       } : undefined,
     });
-  }, [drawing2D, activeTool, sectionPlane, isInitialized, coordinateInfo, show3DOverlay]);
+  }, [drawing2D, activeTool, sectionPlane, isInitialized, coordinateInfo, show3DOverlay, showHiddenLines]);
 
   // Re-render when visibility, selection, or section plane changes
   useEffect(() => {
@@ -152,6 +163,7 @@ export function useRenderUpdates(params: UseRenderUpdatesParams): void {
       selectedIds: selectedEntityIds,
       selectedModelIndex,
       clearColor: clearColorRef.current,
+      visualEnhancement: visualEnhancementRef.current,
       sectionPlane: activeTool === 'section' ? {
         ...sectionPlane,
         min: sectionRange?.min,

package/src/hooks/useKeyboardShortcuts.ts

@@ -7,21 +7,20 @@
  */
 
 import { useEffect, useCallback } from 'react';
-import { useViewerStore, stringToEntityRef } from '@/store';
-import type { EntityRef } from '@/store';
+import { useViewerStore } from '@/store';
+import { resetVisibilityForHomeFromStore } from '@/store/homeView';
+import {
+  executeBasketIsolate,
+  executeBasketSet,
+  executeBasketAdd,
+  executeBasketRemove,
+  executeBasketSaveView,
+} from '@/store/basket/basketCommands';
 
 interface KeyboardShortcutsOptions {
   enabled?: boolean;
 }
 
-/** Clear multi-select state so subsequent operations use single-entity selectedEntity */
-function clearMultiSelect(): void {
-  const state = useViewerStore.getState();
-  if (state.selectedEntitiesSet.size > 0) {
-    useViewerStore.setState({ selectedEntitiesSet: new Set(), selectedEntityIds: new Set() });
-  }
-}
-
 /** Get all selected global IDs — multi-select if available, else single selectedEntityId */
 function getAllSelectedGlobalIds(): number[] {
   const state = useViewerStore.getState();
@@ -34,22 +33,6 @@ function getAllSelectedGlobalIds(): number[] {
   return [];
 }
 
-/** Get current selection as EntityRef[] — multi-select if available, else single */
-function getSelectionRefsFromStore(): EntityRef[] {
-  const state = useViewerStore.getState();
-  if (state.selectedEntitiesSet.size > 0) {
-    const refs: EntityRef[] = [];
-    for (const str of state.selectedEntitiesSet) {
-      refs.push(stringToEntityRef(str));
-    }
-    return refs;
-  }
-  if (state.selectedEntity) {
-    return [state.selectedEntity];
-  }
-  return [];
-}
-
 export function useKeyboardShortcuts(options: KeyboardShortcutsOptions = {}) {
   const { enabled = true } = options;
 
@@ -58,16 +41,8 @@ export function useKeyboardShortcuts(options: KeyboardShortcutsOptions = {}) {
   const activeTool = useViewerStore((s) => s.activeTool);
   const setActiveTool = useViewerStore((s) => s.setActiveTool);
   const hideEntities = useViewerStore((s) => s.hideEntities);
-  const showAll = useViewerStore((s) => s.showAll);
-  const clearStoreySelection = useViewerStore((s) => s.clearStoreySelection);
   const toggleTheme = useViewerStore((s) => s.toggleTheme);
-
-  // Basket actions
-  const setBasket = useViewerStore((s) => s.setBasket);
-  const addToBasket = useViewerStore((s) => s.addToBasket);
-  const removeFromBasket = useViewerStore((s) => s.removeFromBasket);
-  const clearBasket = useViewerStore((s) => s.clearBasket);
-  const showPinboard = useViewerStore((s) => s.showPinboard);
+  const toggleBasketPresentationVisible = useViewerStore((s) => s.toggleBasketPresentationVisible);
 
   // Measure tool specific actions
   const activeMeasurement = useViewerStore((s) => s.activeMeasurement);
@@ -117,45 +92,45 @@ export function useKeyboardShortcuts(options: KeyboardShortcutsOptions = {}) {
       setActiveTool('section');
     }
 
-    // Basket / Visibility controls
-    // I = Set basket (isolate selection as basket), or re-apply basket if no selection
+    // Basket controls (automatic context source)
+    // I = Isolate from current context
     if (key === 'i' && !ctrl && !shift) {
-      const state = useViewerStore.getState();
-      // If basket already exists and user hasn't explicitly multi-selected,
-      // re-apply the basket instead of replacing it with a stale single selection.
-      if (state.pinboardEntities.size > 0 && state.selectedEntitiesSet.size === 0) {
-        e.preventDefault();
-        showPinboard();
-      } else {
-        const refs = getSelectionRefsFromStore();
-        if (refs.length > 0) {
-          e.preventDefault();
-          setBasket(refs);
-          // Consume multi-select so subsequent − removes a single entity
-          clearMultiSelect();
-        }
-      }
+      e.preventDefault();
+      executeBasketIsolate();
     }
 
-    // + or = (with shift) = Add to basket
+    // = Set basket from active context
+    if (e.key === '=' && !ctrl && !shift) {
+      e.preventDefault();
+      executeBasketSet();
+    }
+
+    // + Add active context to basket
     if ((e.key === '+' || (e.key === '=' && shift)) && !ctrl) {
       e.preventDefault();
-      const refs = getSelectionRefsFromStore();
-      if (refs.length > 0) {
-        addToBasket(refs);
-        // Consume multi-select so subsequent − removes a single entity
-        clearMultiSelect();
-      }
+      executeBasketAdd();
     }
 
-    // - or _ = Remove from basket
+    // - Remove active context from basket
     if ((e.key === '-' || e.key === '_') && !ctrl) {
       e.preventDefault();
-      const refs = getSelectionRefsFromStore();
-      if (refs.length > 0) {
-        removeFromBasket(refs);
-        // Consume multi-select after removal
-        clearMultiSelect();
+      executeBasketRemove();
+    }
+
+    // D Toggle basket presentation dock
+    if (key === 'd' && !ctrl && !shift) {
+      e.preventDefault();
+      toggleBasketPresentationVisible();
+    }
+
+    // B Save current basket as presentation view with thumbnail
+    if (key === 'b' && !ctrl && !shift) {
+      const state = useViewerStore.getState();
+      if (state.pinboardEntities.size > 0) {
+        e.preventDefault();
+        executeBasketSaveView().catch((err) => {
+          console.error('[useKeyboardShortcuts] Failed to save basket view:', err);
+        });
       }
     }
 
@@ -163,7 +138,6 @@ export function useKeyboardShortcuts(options: KeyboardShortcutsOptions = {}) {
       e.preventDefault();
       const ids = getAllSelectedGlobalIds();
       hideEntities(ids);
-      clearMultiSelect();
     }
     // Space to hide — skip when focused on buttons/selects/links where Space has native behavior
     if (key === ' ' && !ctrl && !shift && selectedEntityId) {
@@ -172,13 +146,11 @@ export function useKeyboardShortcuts(options: KeyboardShortcutsOptions = {}) {
         e.preventDefault();
         const ids = getAllSelectedGlobalIds();
         hideEntities(ids);
-        clearMultiSelect();
       }
     }
     if (key === 'a' && !ctrl && !shift) {
       e.preventDefault();
-      showAll();             // Clear hiddenEntities + isolatedEntities (basket preserved)
-      clearStoreySelection(); // Also clear storey filtering
+      resetVisibilityForHomeFromStore();
     }
 
     // Measure tool shortcuts
@@ -213,9 +185,7 @@ export function useKeyboardShortcuts(options: KeyboardShortcutsOptions = {}) {
     if (key === 'escape') {
       e.preventDefault();
       setSelectedEntityId(null);
-      clearBasket();
-      showAll();
-      clearStoreySelection(); // Also clear storey filtering
+      resetVisibilityForHomeFromStore();
       setActiveTool('select');
     }
 
@@ -232,15 +202,9 @@ export function useKeyboardShortcuts(options: KeyboardShortcutsOptions = {}) {
     setSelectedEntityId,
     activeTool,
     setActiveTool,
-    setBasket,
-    addToBasket,
-    removeFromBasket,
-    clearBasket,
-    showPinboard,
     hideEntities,
-    showAll,
-    clearStoreySelection,
     toggleTheme,
+    toggleBasketPresentationVisible,
     activeMeasurement,
     cancelMeasurement,
     clearMeasurements,
@@ -268,12 +232,15 @@ export const KEYBOARD_SHORTCUTS = [
   { key: 'S', description: 'Toggle snapping (Measure tool)', category: 'Tools' },
   { key: 'Esc', description: 'Cancel measurement (Measure tool)', category: 'Tools' },
   { key: 'Ctrl+C', description: 'Clear measurements (Measure tool)', category: 'Tools' },
-  { key: 'I', description: 'Set basket (isolate selection)', category: 'Visibility' },
-  { key: '+', description: 'Add selection to basket', category: 'Visibility' },
-  { key: '−', description: 'Remove selection from basket', category: 'Visibility' },
+  { key: 'I', description: 'Isolate (set basket from current context)', category: 'Visibility' },
+  { key: '=', description: 'Set basket from current context', category: 'Visibility' },
+  { key: '+', description: 'Add current context to basket', category: 'Visibility' },
+  { key: '−', description: 'Remove current context from basket', category: 'Visibility' },
+  { key: 'D', description: 'Toggle basket presentation dock', category: 'Visibility' },
+  { key: 'B', description: 'Save basket as presentation view', category: 'Visibility' },
   { key: 'Del / Space', description: 'Hide selection', category: 'Visibility' },
-  { key: 'A', description: 'Show all (clear filters, keep basket)', category: 'Visibility' },
-  { key: 'H', description: 'Home (Isometric view)', category: 'Camera' },
+  { key: 'A', description: 'Show all (clear filters and basket)', category: 'Visibility' },
+  { key: 'H', description: 'Home (isometric + reset visibility)', category: 'Camera' },
   { key: 'Z', description: 'Fit all (zoom extents)', category: 'Camera' },
   { key: 'F', description: 'Frame selection', category: 'Camera' },
   { key: '1-6', description: 'Preset views', category: 'Camera' },

package/src/hooks/useViewerSelectors.ts

@@ -157,9 +157,31 @@ export function useHoverState() {
  */
 export function useThemeState() {
   const theme = useViewerStore((state) => state.theme);
+  const isMobile = useViewerStore((state) => state.isMobile);
+  const visualEnhancementsEnabled = useViewerStore((state) => state.visualEnhancementsEnabled);
+  const edgeContrastEnabled = useViewerStore((state) => state.edgeContrastEnabled);
+  const edgeContrastIntensity = useViewerStore((state) => state.edgeContrastIntensity);
+  const contactShadingQuality = useViewerStore((state) => state.contactShadingQuality);
+  const contactShadingIntensity = useViewerStore((state) => state.contactShadingIntensity);
+  const contactShadingRadius = useViewerStore((state) => state.contactShadingRadius);
+  const separationLinesEnabled = useViewerStore((state) => state.separationLinesEnabled);
+  const separationLinesQuality = useViewerStore((state) => state.separationLinesQuality);
+  const separationLinesIntensity = useViewerStore((state) => state.separationLinesIntensity);
+  const separationLinesRadius = useViewerStore((state) => state.separationLinesRadius);
 
   return {
     theme,
+    isMobile,
+    visualEnhancementsEnabled,
+    edgeContrastEnabled,
+    edgeContrastIntensity,
+    contactShadingQuality,
+    contactShadingIntensity,
+    contactShadingRadius,
+    separationLinesEnabled,
+    separationLinesQuality,
+    separationLinesIntensity,
+    separationLinesRadius,
   };
 }
 

package/src/index.css

@@ -4,6 +4,12 @@
 
 @import "tailwindcss";
 
+/* Override Tailwind v4's default media-query dark variant so all dark: utilities
+   respond to the .dark class on <html> instead of prefers-color-scheme.
+   Without this, toggling light mode while the OS is in dark mode leaves all
+   dark: Tailwind utilities active, creating a mixed dark/light UI. */
+@custom-variant dark (&:where(.dark, .dark *));
+
 /* ═══════════════════════════════════════════════════════════════════════════
    TOKYO NIGHT THEME - Dark Stormy Cyberpunk Vibes
    ═══════════════════════════════════════════════════════════════════════════ */

package/src/store/basket/basketCommands.ts

@@ -0,0 +1,81 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+
+import type { EntityRef } from '../types.js';
+import { useViewerStore } from '../index.js';
+import { saveBasketViewWithThumbnailFromStore } from '../basketSave.js';
+import {
+  getSmartBasketInputFromStore,
+  isBasketIsolationActiveFromStore,
+} from '../basketVisibleSet.js';
+
+type BasketViewSource = 'selection' | 'visible' | 'hierarchy' | 'manual';
+
+/**
+ * Resolve basket refs: smart input first, optional context entity as fallback.
+ */
+function getBasketRefs(contextEntityRef?: EntityRef | null): EntityRef[] {
+  const { refs } = getSmartBasketInputFromStore();
+  if (refs.length > 0) return refs;
+  if (contextEntityRef) return [contextEntityRef];
+  return [];
+}
+
+export function executeBasketSet(contextEntityRef?: EntityRef | null): void {
+  const refs = getBasketRefs(contextEntityRef);
+  if (refs.length > 0) {
+    useViewerStore.getState().setBasket(refs);
+  }
+}
+
+/**
+ * Isolate: set basket from context if refs available, else re-show existing basket.
+ */
+export function executeBasketIsolate(contextEntityRef?: EntityRef | null): void {
+  const refs = getBasketRefs(contextEntityRef);
+  if (refs.length > 0) {
+    useViewerStore.getState().setBasket(refs);
+    return;
+  }
+  const state = useViewerStore.getState();
+  if (state.pinboardEntities.size > 0) {
+    state.showPinboard();
+  }
+}
+
+export function executeBasketAdd(contextEntityRef?: EntityRef | null): void {
+  const refs = getBasketRefs(contextEntityRef);
+  if (refs.length > 0) {
+    useViewerStore.getState().addToBasket(refs);
+  }
+}
+
+export function executeBasketRemove(contextEntityRef?: EntityRef | null): void {
+  const refs = getBasketRefs(contextEntityRef);
+  if (refs.length > 0) {
+    useViewerStore.getState().removeFromBasket(refs);
+  }
+}
+
+export function executeBasketToggleVisibility(): void {
+  const state = useViewerStore.getState();
+  if (state.pinboardEntities.size === 0) return;
+  if (isBasketIsolationActiveFromStore()) {
+    state.clearIsolation();
+  } else {
+    state.showPinboard();
+  }
+}
+
+export async function executeBasketSaveView(source: BasketViewSource = 'manual'): Promise<string | null> {
+  const state = useViewerStore.getState();
+  if (state.pinboardEntities.size === 0) return null;
+  const id = await saveBasketViewWithThumbnailFromStore(source);
+  state.setBasketPresentationVisible(true);
+  return id;
+}
+
+export function executeBasketClear(): void {
+  useViewerStore.getState().clearBasket();
+}

package/src/store/basket/basketViewActivator.ts

@@ -0,0 +1,54 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+
+import { useViewerStore } from '../index.js';
+
+const DEFAULT_TRANSITION_MS = 700;
+
+/**
+ * Coordinator for activating a saved basket view.
+ * Owns camera + section + drawing side effects; delegates entity/isolation to pinboard.
+ */
+export function activateBasketViewFromStore(viewId: string): void {
+  const state = useViewerStore.getState();
+  const view = state.basketViews.find((v) => v.id === viewId);
+  if (!view) return;
+
+  // Basket activation must never restore or keep 2D profile overlays.
+  // Basket views should only affect 3D model geometry visibility/sectioning.
+  state.setDrawing2D(null);
+  state.setDrawing2DPanelVisible(false);
+  state.updateDrawing2DDisplayOptions({ show3DOverlay: false });
+
+  state.clearEntitySelection();
+  state.restoreBasketEntities(view.entityRefs, viewId);
+
+  if (view.viewpoint) {
+    const transitionMs = view.transitionMs ?? DEFAULT_TRANSITION_MS;
+    state.cameraCallbacks.applyViewpoint?.(view.viewpoint, true, transitionMs);
+  }
+
+  if (view.section) {
+    const sectionSnapshot = view.section;
+    useViewerStore.setState({
+      sectionPlane: { ...sectionSnapshot.plane },
+      drawing2DPanelVisible: false,
+    });
+    if (sectionSnapshot.plane.enabled) {
+      if (state.activeTool !== 'section') {
+        state.setSuppressNextSection2DPanelAutoOpen(true);
+      }
+      state.setActiveTool('section');
+    } else if (state.activeTool === 'section') {
+      state.setActiveTool('select');
+    }
+  } else {
+    // This view has no section snapshot: ensure previously active cutting is cleared.
+    const current = useViewerStore.getState().sectionPlane;
+    useViewerStore.setState({ sectionPlane: { ...current, enabled: false } });
+    if (state.activeTool === 'section') {
+      state.setActiveTool('select');
+    }
+  }
+}

package/src/store/basketSave.ts

@@ -0,0 +1,122 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+
+import { useViewerStore } from './index.js';
+import { getGlobalRenderer } from '../hooks/useBCF.js';
+
+type BasketViewSource = 'selection' | 'visible' | 'hierarchy' | 'manual';
+
+interface SelectionSnapshot {
+  selectedEntityId: number | null;
+  selectedEntityIds: Set<number>;
+  selectedEntity: ReturnType<typeof useViewerStore.getState>['selectedEntity'];
+  selectedEntitiesSet: Set<string>;
+  selectedEntities: ReturnType<typeof useViewerStore.getState>['selectedEntities'];
+  selectedModelId: string | null;
+}
+
+function hasSelection(snapshot: SelectionSnapshot): boolean {
+  return (
+    snapshot.selectedEntityId !== null ||
+    snapshot.selectedEntityIds.size > 0 ||
+    snapshot.selectedEntity !== null ||
+    snapshot.selectedEntitiesSet.size > 0 ||
+    snapshot.selectedEntities.length > 0
+  );
+}
+
+function snapshotSelectionState(): SelectionSnapshot {
+  const state = useViewerStore.getState();
+  return {
+    selectedEntityId: state.selectedEntityId,
+    selectedEntityIds: new Set(state.selectedEntityIds),
+    selectedEntity: state.selectedEntity ? { ...state.selectedEntity } : null,
+    selectedEntitiesSet: new Set(state.selectedEntitiesSet),
+    selectedEntities: state.selectedEntities.map((ref) => ({ ...ref })),
+    selectedModelId: state.selectedModelId,
+  };
+}
+
+function restoreSelectionState(snapshot: SelectionSnapshot): void {
+  useViewerStore.setState({
+    selectedEntityId: snapshot.selectedEntityId,
+    selectedEntityIds: new Set(snapshot.selectedEntityIds),
+    selectedEntity: snapshot.selectedEntity ? { ...snapshot.selectedEntity } : null,
+    selectedEntitiesSet: new Set(snapshot.selectedEntitiesSet),
+    selectedEntities: snapshot.selectedEntities.map((ref) => ({ ...ref })),
+    selectedModelId: snapshot.selectedModelId,
+  });
+}
+
+async function captureCanvasThumbnail(): Promise<string | null> {
+  const src = document.querySelector('canvas[data-viewport="main"]') as HTMLCanvasElement | null;
+  if (!src) return null;
+
+  // Ensure submitted GPU work is complete before sampling the canvas.
+  const renderer = getGlobalRenderer();
+  const device = renderer?.getGPUDevice();
+  if (device) {
+    await device.queue.onSubmittedWorkDone();
+  }
+
+  await new Promise<void>((resolve) =>
+    requestAnimationFrame(() => requestAnimationFrame(() => resolve())),
+  );
+
+  try {
+    // Capture from the WebGPU canvas first (reliable), then downscale.
+    const fullFrameDataUrl = src.toDataURL('image/png');
+
+    const thumb = document.createElement('canvas');
+    thumb.width = 320;
+    thumb.height = 180;
+    const ctx = thumb.getContext('2d');
+    if (!ctx) return fullFrameDataUrl;
+
+    // Preserve viewport aspect ratio while filling thumbnail bounds (crop, no stretch).
+    ctx.fillStyle = '#0f0f12';
+    ctx.fillRect(0, 0, thumb.width, thumb.height);
+
+    const img = new Image();
+    await new Promise<void>((resolve, reject) => {
+      img.onload = () => resolve();
+      img.onerror = () => reject(new Error('Failed to decode snapshot image'));
+      img.src = fullFrameDataUrl;
+    });
+
+    const srcW = img.naturalWidth || src.width || src.clientWidth;
+    const srcH = img.naturalHeight || src.height || src.clientHeight;
+    if (srcW <= 0 || srcH <= 0) return null;
+
+    const scale = Math.max(thumb.width / srcW, thumb.height / srcH);
+    const drawW = Math.round(srcW * scale);
+    const drawH = Math.round(srcH * scale);
+    const offsetX = Math.floor((thumb.width - drawW) / 2);
+    const offsetY = Math.floor((thumb.height - drawH) / 2);
+    ctx.drawImage(img, offsetX, offsetY, drawW, drawH);
+    return thumb.toDataURL('image/jpeg', 0.75);
+  } catch {
+    return null;
+  }
+}
+
+export async function saveBasketViewWithThumbnailFromStore(
+  source: BasketViewSource = 'manual',
+): Promise<string | null> {
+  const before = snapshotSelectionState();
+  const hadSelection = hasSelection(before);
+
+  if (hadSelection) {
+    useViewerStore.getState().clearEntitySelection();
+  }
+
+  try {
+    const thumbnailDataUrl = await captureCanvasThumbnail();
+    return useViewerStore.getState().saveCurrentBasketView({ source, thumbnailDataUrl });
+  } finally {
+    if (hadSelection) {
+      restoreSelectionState(before);
+    }
+  }
+}