@ifc-lite/viewer 1.8.0 → 1.10.0

package/src/components/viewer/Viewport.tsx

@@ -7,7 +7,7 @@
  */
 
 import { useCallback, useEffect, useRef, useState, useMemo } from 'react';
-import { Renderer } from '@ifc-lite/renderer';
+import { Renderer, type VisualEnhancementOptions } from '@ifc-lite/renderer';
 import type { MeshData, CoordinateInfo } from '@ifc-lite/geometry';
 import { useViewerStore, resolveEntityRef, type MeasurePoint, type SnapVisualization } from '@/store';
 import {
@@ -158,7 +158,20 @@ export function Viewport({ geometry, coordinateInfo, computedIsolatedIds, modelI
   const { updateCameraRotationRealtime, updateScaleRealtime, setCameraCallbacks } = useCameraState();
 
   // Theme state
-  const { theme } = useThemeState();
+  const {
+    theme,
+    isMobile,
+    visualEnhancementsEnabled,
+    edgeContrastEnabled,
+    edgeContrastIntensity,
+    contactShadingQuality,
+    contactShadingIntensity,
+    contactShadingRadius,
+    separationLinesEnabled,
+    separationLinesQuality,
+    separationLinesIntensity,
+    separationLinesRadius,
+  } = useThemeState();
 
   // Hover state
   const { hoverTooltipsEnabled, setHoverState, clearHover } = useHoverState();
@@ -215,6 +228,37 @@ export function Viewport({ geometry, coordinateInfo, computedIsolatedIds, modelI
   // Theme-aware clear color ref (updated when theme changes)
   // Tokyo Night storm: #1a1b26 = rgb(26, 27, 38)
   const clearColorRef = useRef<[number, number, number, number]>([0.102, 0.106, 0.149, 1]);
+  const visualEnhancement = useMemo<VisualEnhancementOptions>(() => ({
+    enabled: visualEnhancementsEnabled,
+    edgeContrast: {
+      enabled: edgeContrastEnabled,
+      intensity: edgeContrastIntensity,
+    },
+    contactShading: {
+      quality: isMobile ? 'off' : contactShadingQuality,
+      intensity: contactShadingIntensity,
+      radius: contactShadingRadius,
+    },
+    separationLines: {
+      enabled: separationLinesEnabled,
+      quality: isMobile ? 'low' : separationLinesQuality,
+      intensity: isMobile ? Math.min(0.4, separationLinesIntensity) : separationLinesIntensity,
+      radius: isMobile ? 1.0 : separationLinesRadius,
+    },
+  }), [
+    visualEnhancementsEnabled,
+    edgeContrastEnabled,
+    edgeContrastIntensity,
+    isMobile,
+    contactShadingQuality,
+    contactShadingIntensity,
+    contactShadingRadius,
+    separationLinesEnabled,
+    separationLinesQuality,
+    separationLinesIntensity,
+    separationLinesRadius,
+  ]);
+  const visualEnhancementRef = useRef<VisualEnhancementOptions>(visualEnhancement);
 
   // Animation frame ref
   const animationFrameRef = useRef<number | null>(null);
@@ -330,6 +374,7 @@ export function Viewport({ geometry, coordinateInfo, computedIsolatedIds, modelI
   useEffect(() => { measurementConstraintEdgeRef.current = measurementConstraintEdge; }, [measurementConstraintEdge]);
   useEffect(() => { sectionPlaneRef.current = sectionPlane; }, [sectionPlane]);
   useEffect(() => { sectionRangeRef.current = sectionRange; }, [sectionRange]);
+  useEffect(() => { visualEnhancementRef.current = visualEnhancement; }, [visualEnhancement]);
   useEffect(() => {
     geometryRef.current = geometry;
   }, [geometry]);
@@ -459,6 +504,7 @@ export function Viewport({ geometry, coordinateInfo, computedIsolatedIds, modelI
             selectedId: selectedEntityIdRef.current,
             selectedModelIndex: selectedModelIndexRef.current,
             clearColor: clearColorRef.current,
+            visualEnhancement: visualEnhancementRef.current,
             sectionPlane: activeToolRef.current === 'section' ? {
               ...sectionPlaneRef.current,
               min: sectionRangeRef.current?.min,
@@ -485,6 +531,7 @@ export function Viewport({ geometry, coordinateInfo, computedIsolatedIds, modelI
             selectedId: selectedEntityIdRef.current,
             selectedModelIndex: selectedModelIndexRef.current,
             clearColor: clearColorRef.current,
+            visualEnhancement: visualEnhancementRef.current,
             sectionPlane: activeToolRef.current === 'section' ? {
               ...sectionPlaneRef.current,
               min: sectionRangeRef.current?.min,
@@ -501,6 +548,7 @@ export function Viewport({ geometry, coordinateInfo, computedIsolatedIds, modelI
             selectedId: selectedEntityIdRef.current,
             selectedModelIndex: selectedModelIndexRef.current,
             clearColor: clearColorRef.current,
+            visualEnhancement: visualEnhancementRef.current,
             sectionPlane: activeToolRef.current === 'section' ? {
               ...sectionPlaneRef.current,
               min: sectionRangeRef.current?.min,
@@ -534,6 +582,7 @@ export function Viewport({ geometry, coordinateInfo, computedIsolatedIds, modelI
             selectedId: selectedEntityIdRef.current,
             selectedModelIndex: selectedModelIndexRef.current,
             clearColor: clearColorRef.current,
+            visualEnhancement: visualEnhancementRef.current,
             sectionPlane: activeToolRef.current === 'section' ? {
               ...sectionPlaneRef.current,
               min: sectionRangeRef.current?.min,
@@ -557,6 +606,7 @@ export function Viewport({ geometry, coordinateInfo, computedIsolatedIds, modelI
             selectedId: selectedEntityIdRef.current,
             selectedModelIndex: selectedModelIndexRef.current,
             clearColor: clearColorRef.current,
+            visualEnhancement: visualEnhancementRef.current,
             sectionPlane: activeToolRef.current === 'section' ? {
               ...sectionPlaneRef.current,
               min: sectionRangeRef.current?.min,
@@ -573,6 +623,7 @@ export function Viewport({ geometry, coordinateInfo, computedIsolatedIds, modelI
             selectedId: selectedEntityIdRef.current,
             selectedModelIndex: selectedModelIndexRef.current,
             clearColor: clearColorRef.current,
+            visualEnhancement: visualEnhancementRef.current,
             sectionPlane: activeToolRef.current === 'section' ? {
               ...sectionPlaneRef.current,
               min: sectionRangeRef.current?.min,
@@ -598,6 +649,7 @@ export function Viewport({ geometry, coordinateInfo, computedIsolatedIds, modelI
           selectedId: selectedEntityIdRef.current,
           selectedModelIndex: selectedModelIndexRef.current,
           clearColor: clearColorRef.current,
+          visualEnhancement: visualEnhancementRef.current,
           sectionPlane: activeToolRef.current === 'section' ? {
             ...sectionPlaneRef.current,
             min: sectionRangeRef.current?.min,
@@ -614,6 +666,7 @@ export function Viewport({ geometry, coordinateInfo, computedIsolatedIds, modelI
         selectedId: selectedEntityIdRef.current,
         selectedModelIndex: selectedModelIndexRef.current,
         clearColor: clearColorRef.current,
+        visualEnhancement: visualEnhancementRef.current,
         sectionPlane: activeToolRef.current === 'section' ? {
           ...sectionPlaneRef.current,
           min: sectionRangeRef.current?.min,
@@ -767,6 +820,7 @@ export function Viewport({ geometry, coordinateInfo, computedIsolatedIds, modelI
     clearColorRef,
     sectionPlaneRef,
     sectionRangeRef,
+    visualEnhancementRef,
     lastCameraStateRef,
     updateCameraRotationRealtime,
     calculateScale,
@@ -783,6 +837,7 @@ export function Viewport({ geometry, coordinateInfo, computedIsolatedIds, modelI
     geometryBoundsRef,
     pendingColorUpdates,
     clearPendingColorUpdates,
+    clearColorRef,
   });
 
   useRenderUpdates({
@@ -790,6 +845,7 @@ export function Viewport({ geometry, coordinateInfo, computedIsolatedIds, modelI
     isInitialized,
     theme,
     clearColorRef,
+    visualEnhancementRef,
     hiddenEntities,
     isolatedEntities,
     selectedEntityId,

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/useGeometryStreaming.ts

@@ -20,6 +20,8 @@ export interface UseGeometryStreamingParams {
   geometryBoundsRef: MutableRefObject<{ min: { x: number; y: number; z: number }; max: { x: number; y: number; z: number } }>;
   pendingColorUpdates: Map<number, [number, number, number, number]> | null;
   clearPendingColorUpdates: () => void;
+  // Clear color ref — color update renders must preserve theme background
+  clearColorRef: MutableRefObject<[number, number, number, number]>;
 }
 
 export function useGeometryStreaming(params: UseGeometryStreamingParams): void {
@@ -32,6 +34,7 @@ export function useGeometryStreaming(params: UseGeometryStreamingParams): void {
     geometryBoundsRef,
     pendingColorUpdates,
     clearPendingColorUpdates,
+    clearColorRef,
   } = params;
 
   // Track processed meshes for incremental updates
@@ -397,7 +400,16 @@ export function useGeometryStreaming(params: UseGeometryStreamingParams): void {
         // Non-empty map = set color overrides
         scene.setColorOverrides(pendingColorUpdates, device, pipeline);
       }
-      renderer.render();
+      // Re-render with current theme background — render() without options
+      // defaults to black background.  Do NOT pass hiddenIds/isolatedIds here:
+      // visibility filtering causes partial batches which write depth only for
+      // visible elements, but overlay batches cover all geometry.  Without
+      // filtering, all original batches write depth for every entity, ensuring
+      // depthCompare 'equal' matches exactly for the overlay pass.
+      // The next render from useRenderUpdates will apply the correct visibility.
+      renderer.render({
+        clearColor: clearColorRef.current,
+      });
       clearPendingColorUpdates();
     }
   }, [pendingColorUpdates, isInitialized, clearPendingColorUpdates]);

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>;
@@ -54,6 +55,7 @@ export function useRenderUpdates(params: UseRenderUpdatesParams): void {
     isInitialized,
     theme,
     clearColorRef,
+    visualEnhancementRef,
     hiddenEntities,
     isolatedEntities,
     selectedEntityId,
@@ -88,6 +90,7 @@ export function useRenderUpdates(params: UseRenderUpdatesParams): void {
         selectedId: selectedEntityIdRef.current,
         selectedModelIndex: selectedModelIndexRef.current,
         clearColor: clearColorRef.current,
+        visualEnhancement: visualEnhancementRef.current,
       });
     }
   }, [theme, isInitialized]);
@@ -132,6 +135,7 @@ 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,
@@ -152,6 +156,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

@@ -279,5 +279,6 @@ export const KEYBOARD_SHORTCUTS = [
   { key: '1-6', description: 'Preset views', category: 'Camera' },
   { key: 'T', description: 'Toggle theme', category: 'UI' },
   { key: 'Esc', description: 'Reset all (clear selection, basket, isolation)', category: 'Selection' },
+  { key: 'Ctrl+K', description: 'Command palette', category: 'UI' },
   { key: '?', description: 'Show info panel', category: 'Help' },
 ] as const;

package/src/hooks/useLens.ts

@@ -24,6 +24,7 @@
 
 import { useEffect, useRef, useMemo } from 'react';
 import { evaluateLens, evaluateAutoColorLens, rgbaToHex, isGhostColor } from '@ifc-lite/lens';
+import type { AutoColorEvaluationResult } from '@ifc-lite/lens';
 import { useViewerStore } from '@/store';
 import { createLensDataProvider } from '@/lib/lens';
 import { useLensDiscovery } from './useLensDiscovery';
@@ -95,7 +96,7 @@ export function useLens() {
 
     // Store auto-color legend entries for UI display
     if (isAutoColor && 'legend' in result) {
-      useViewerStore.getState().setLensAutoColorLegend(result.legend);
+      useViewerStore.getState().setLensAutoColorLegend((result as AutoColorEvaluationResult).legend);
     } else {
       useViewerStore.getState().setLensAutoColorLegend([]);
     }

package/src/hooks/useSandbox.ts

@@ -0,0 +1,113 @@
+/* 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/. */
+
+/**
+ * useSandbox — React hook for executing scripts in a QuickJS sandbox.
+ *
+ * Creates a fresh sandbox context per execution for full isolation.
+ * The WASM module is cached across the session (cheap to reuse),
+ * but each script runs in a clean context with no leaked state.
+ */
+
+import { useCallback, useEffect, useRef } from 'react';
+import { useBim } from '../sdk/BimProvider.js';
+import { useViewerStore } from '../store/index.js';
+import type { Sandbox, ScriptResult, SandboxConfig } from '@ifc-lite/sandbox';
+
+/** Type guard for ScriptError shape (has logs + durationMs) */
+function isScriptError(err: unknown): err is { message: string; logs: Array<{ level: string; args: unknown[]; timestamp: number }>; durationMs: number } {
+  return (
+    err !== null &&
+    typeof err === 'object' &&
+    'logs' in err &&
+    Array.isArray((err as Record<string, unknown>).logs) &&
+    'durationMs' in err &&
+    typeof (err as Record<string, unknown>).durationMs === 'number'
+  );
+}
+
+/**
+ * Hook that provides a sandbox execution interface.
+ *
+ * Each execute() call creates a fresh QuickJS context for full isolation —
+ * scripts cannot leak global state between runs. The WASM module itself
+ * is cached (loaded once per app lifetime, ~1ms context creation overhead).
+ */
+export function useSandbox(config?: SandboxConfig) {
+  const bim = useBim();
+  const activeSandboxRef = useRef<Sandbox | null>(null);
+
+  const setExecutionState = useViewerStore((s) => s.setScriptExecutionState);
+  const setResult = useViewerStore((s) => s.setScriptResult);
+  const setError = useViewerStore((s) => s.setScriptError);
+
+  /** Execute a script in an isolated sandbox context */
+  const execute = useCallback(async (code: string): Promise<ScriptResult | null> => {
+    setExecutionState('running');
+    setError(null);
+
+    let sandbox: Sandbox | null = null;
+    try {
+      // Create a fresh sandbox for every execution — full isolation
+      const { createSandbox } = await import('@ifc-lite/sandbox');
+      sandbox = await createSandbox(bim, {
+        permissions: { model: true, query: true, viewer: true, mutate: true, lens: true, export: true, ...config?.permissions },
+        limits: { timeoutMs: 30_000, ...config?.limits },
+      });
+      activeSandboxRef.current = sandbox;
+
+      const result = await sandbox.eval(code);
+      setResult({
+        value: result.value,
+        logs: result.logs,
+        durationMs: result.durationMs,
+      });
+      return result;
+    } catch (err: unknown) {
+      const message = err instanceof Error ? err.message : String(err);
+      setError(message);
+
+      // If the error is a ScriptError with captured logs, preserve them
+      if (isScriptError(err)) {
+        setResult({
+          value: undefined,
+          logs: err.logs as ScriptResult['logs'],
+          durationMs: err.durationMs,
+        });
+      }
+      return null;
+    } finally {
+      // Always dispose the sandbox after execution
+      if (sandbox) {
+        sandbox.dispose();
+      }
+      if (activeSandboxRef.current === sandbox) {
+        activeSandboxRef.current = null;
+      }
+    }
+  }, [bim, config?.permissions, config?.limits, setExecutionState, setResult, setError]);
+
+  /** Reset clears any active sandbox (no-op if none running) */
+  const reset = useCallback(() => {
+    if (activeSandboxRef.current) {
+      activeSandboxRef.current.dispose();
+      activeSandboxRef.current = null;
+    }
+    setExecutionState('idle');
+    setResult(null);
+    setError(null);
+  }, [setExecutionState, setResult, setError]);
+
+  // Cleanup on unmount
+  useEffect(() => {
+    return () => {
+      if (activeSandboxRef.current) {
+        activeSandboxRef.current.dispose();
+        activeSandboxRef.current = null;
+      }
+    };
+  }, []);
+
+  return { execute, reset };
+}

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/lib/recent-files.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/. */
+
+/**
+ * Track recently opened model files via localStorage + IndexedDB.
+ *
+ * localStorage: metadata (name, size, timestamp) — for palette display.
+ * IndexedDB:    actual file blobs — so recent files can be loaded instantly
+ *               without the user re-selecting them from the file picker.
+ *
+ * Shared between MainToolbar (writes) and CommandPalette (reads).
+ */
+
+const KEY = 'ifc-lite:recent-files';
+const DB_NAME = 'ifc-lite-file-cache';
+const DB_VERSION = 1;
+const STORE_NAME = 'files';
+const MAX_CACHED_FILES = 5;
+/** Max file size to cache (150 MB) — avoids filling IndexedDB quota */
+const MAX_CACHE_SIZE = 150 * 1024 * 1024;
+
+export interface RecentFileEntry {
+  name: string;
+  size: number;
+  timestamp: number;
+}
+
+// ── localStorage (metadata) ─────────────────────────────────────────────
+
+export function getRecentFiles(): RecentFileEntry[] {
+  try { return JSON.parse(localStorage.getItem(KEY) ?? '[]'); }
+  catch { return []; }
+}
+
+export function recordRecentFiles(files: { name: string; size: number }[]) {
+  try {
+    const names = new Set(files.map(f => f.name));
+    const existing = getRecentFiles().filter(f => !names.has(f.name));
+    const entries: RecentFileEntry[] = files.map(f => ({
+      name: f.name,
+      size: f.size,
+      timestamp: Date.now(),
+    }));
+    localStorage.setItem(KEY, JSON.stringify([...entries, ...existing].slice(0, 10)));
+  } catch { /* noop */ }
+}
+
+/** Format bytes into human-readable size */
+export function formatFileSize(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(0)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+// ── IndexedDB (file blob cache) ─────────────────────────────────────────
+
+function openDB(): Promise<IDBDatabase> {
+  return new Promise((resolve, reject) => {
+    const req = indexedDB.open(DB_NAME, DB_VERSION);
+    req.onupgradeneeded = () => {
+      const db = req.result;
+      if (!db.objectStoreNames.contains(STORE_NAME)) {
+        db.createObjectStore(STORE_NAME, { keyPath: 'name' });
+      }
+    };
+    req.onsuccess = () => resolve(req.result);
+    req.onerror = () => reject(req.error);
+  });
+}
+
+/** Cache file blobs in IndexedDB for instant reload from palette. */
+export async function cacheFileBlobs(files: File[]): Promise<void> {
+  try {
+    const db = await openDB();
+    const tx = db.transaction(STORE_NAME, 'readwrite');
+    const store = tx.objectStore(STORE_NAME);
+
+    for (const file of files) {
+      if (file.size > MAX_CACHE_SIZE) continue; // skip oversized files
+      const blob = await file.arrayBuffer();
+      store.put({ name: file.name, blob, size: file.size, type: file.type, timestamp: Date.now() });
+    }
+
+    // Evict old entries beyond MAX_CACHED_FILES
+    const allReq = store.getAll();
+    allReq.onsuccess = () => {
+      const all = allReq.result as { name: string; timestamp: number }[];
+      if (all.length > MAX_CACHED_FILES) {
+        all.sort((a, b) => b.timestamp - a.timestamp);
+        for (let i = MAX_CACHED_FILES; i < all.length; i++) {
+          store.delete(all[i].name);
+        }
+      }
+    };
+
+    await new Promise<void>((resolve, reject) => {
+      tx.oncomplete = () => resolve();
+      tx.onerror = () => reject(tx.error);
+    });
+    db.close();
+  } catch { /* IndexedDB unavailable — degrade gracefully */ }
+}
+
+/** Retrieve a cached file blob and reconstruct a File object. */
+export async function getCachedFile(name: string): Promise<File | null> {
+  try {
+    const db = await openDB();
+    const tx = db.transaction(STORE_NAME, 'readonly');
+    const store = tx.objectStore(STORE_NAME);
+    const req = store.get(name);
+    const result = await new Promise<{ name: string; blob: ArrayBuffer; size: number; type: string } | undefined>((resolve, reject) => {
+      req.onsuccess = () => resolve(req.result);
+      req.onerror = () => reject(req.error);
+    });
+    db.close();
+    if (!result) return null;
+    return new File([result.blob], result.name, { type: result.type || 'application/octet-stream' });
+  } catch {
+    return null;
+  }
+}