feat: Add thumbnail canvas cache with LRU eviction

src/lib/catalog/thumbnail-cache.ts

@@ -0,0 +1,194 @@
+/**
+ * LRU cache for thumbnail ImageBitmaps
+ * Provides GPU-ready bitmaps for canvas rendering with 50MB memory limit
+ * Throttled loading to prevent overwhelming the browser
+ */
+
+export interface CacheEntry {
+  bitmap: ImageBitmap;
+  width: number;
+  height: number;
+  size: number; // decoded bytes (w * h * 4)
+}
+
+interface QueuedLoad {
+  volumeUuid: string;
+  file: File;
+  resolve: (entry: CacheEntry) => void;
+  reject: (error: Error) => void;
+}
+
+class ThumbnailCache {
+  private cache = new Map<string, CacheEntry>(); // volume_uuid -> entry
+  private pending = new Map<string, Promise<CacheEntry>>(); // coalesce concurrent requests
+  private totalBytes = 0;
+  private readonly maxBytes = 50 * 1024 * 1024; // 50MB
+
+  // Throttling
+  private queue: QueuedLoad[] = [];
+  private activeLoads = 0;
+  private readonly maxConcurrent = 6; // Limit concurrent createImageBitmap calls
+
+  /**
+   * Get or load a thumbnail bitmap
+   * Coalesces concurrent requests for the same thumbnail
+   */
+  async get(volumeUuid: string, file: File): Promise<CacheEntry> {
+    // Check cache first
+    const existing = this.cache.get(volumeUuid);
+    if (existing) {
+      this.touch(volumeUuid);
+      return existing;
+    }
+
+    // Join existing load if in progress
+    const pendingLoad = this.pending.get(volumeUuid);
+    if (pendingLoad) {
+      return pendingLoad;
+    }
+
+    // Create promise and queue the load
+    const loadPromise = new Promise<CacheEntry>((resolve, reject) => {
+      this.queue.push({ volumeUuid, file, resolve, reject });
+    });
+
+    this.pending.set(volumeUuid, loadPromise);
+    this.processQueue();
+
+    try {
+      return await loadPromise;
+    } finally {
+      this.pending.delete(volumeUuid);
+    }
+  }
+
+  /**
+   * Process queued loads with concurrency limit
+   * Uses FILO (stack) ordering - most recent requests processed first
+   * This prioritizes currently visible items over items that scrolled past
+   */
+  private processQueue(): void {
+    while (this.queue.length > 0 && this.activeLoads < this.maxConcurrent) {
+      const item = this.queue.pop()!; // FILO: pop from end (most recent)
+      this.activeLoads++;
+
+      this.load(item.volumeUuid, item.file)
+        .then(item.resolve)
+        .catch(item.reject)
+        .finally(() => {
+          this.activeLoads--;
+          this.processQueue();
+        });
+    }
+  }
+
+  /**
+   * Check if a thumbnail is cached (without loading)
+   */
+  has(volumeUuid: string): boolean {
+    return this.cache.has(volumeUuid);
+  }
+
+  /**
+   * Get cached entry synchronously (returns undefined if not cached)
+   */
+  getSync(volumeUuid: string): CacheEntry | undefined {
+    const entry = this.cache.get(volumeUuid);
+    if (entry) {
+      this.touch(volumeUuid);
+    }
+    return entry;
+  }
+
+  /**
+   * Invalidate a specific cache entry (e.g., when cover is edited)
+   */
+  invalidate(volumeUuid: string): void {
+    const entry = this.cache.get(volumeUuid);
+    if (entry) {
+      entry.bitmap.close();
+      this.totalBytes -= entry.size;
+      this.cache.delete(volumeUuid);
+    }
+    // Also remove from pending if in progress
+    this.pending.delete(volumeUuid);
+    // Remove from queue if waiting
+    this.queue = this.queue.filter((item) => item.volumeUuid !== volumeUuid);
+  }
+
+  /**
+   * Clear entire cache
+   */
+  clear(): void {
+    for (const entry of this.cache.values()) {
+      entry.bitmap.close();
+    }
+    this.cache.clear();
+    this.totalBytes = 0;
+  }
+
+  /**
+   * Get cache statistics
+   */
+  getStats(): { count: number; totalBytes: number; maxBytes: number; utilization: string } {
+    return {
+      count: this.cache.size,
+      totalBytes: this.totalBytes,
+      maxBytes: this.maxBytes,
+      utilization: ((this.totalBytes / this.maxBytes) * 100).toFixed(1) + '%'
+    };
+  }
+
+  /**
+   * Load and decode a thumbnail
+   */
+  private async load(volumeUuid: string, file: File): Promise<CacheEntry> {
+    const bitmap = await createImageBitmap(file);
+    const size = bitmap.width * bitmap.height * 4; // RGBA
+
+    // Evict if needed before adding
+    while (this.totalBytes + size > this.maxBytes && this.cache.size > 0) {
+      this.evictLRU();
+    }
+
+    const entry: CacheEntry = {
+      bitmap,
+      width: bitmap.width,
+      height: bitmap.height,
+      size
+    };
+
+    this.cache.set(volumeUuid, entry);
+    this.totalBytes += size;
+
+    return entry;
+  }
+
+  /**
+   * Move entry to end of Map (most recently used)
+   */
+  private touch(volumeUuid: string): void {
+    const entry = this.cache.get(volumeUuid);
+    if (entry) {
+      this.cache.delete(volumeUuid);
+      this.cache.set(volumeUuid, entry);
+    }
+  }
+
+  /**
+   * Evict least recently used entry (first in Map)
+   */
+  private evictLRU(): void {
+    const firstKey = this.cache.keys().next().value;
+    if (firstKey) {
+      const entry = this.cache.get(firstKey);
+      if (entry) {
+        entry.bitmap.close(); // Release GPU memory
+        this.totalBytes -= entry.size;
+        this.cache.delete(firstKey);
+      }
+    }
+  }
+}
+
+export const thumbnailCache = new ThumbnailCache();