Cache downsampled preview thumbnails for same-origin preview media

[propr-dev]

Problem

On a fresh page load, compact preview thumbnails take a couple of seconds to appear in task lists, goals and the Inbox. Each thumbnail re-downloads the full-resolution capture and re-runs the multi-pass canvas downsampling (downsampleToCanvas in previewDownsampling.ts) on the main thread.

Two causes on main:

• Every load refetches the full image. Task and goal previews are rewritten to ProPR's authenticated media route (/api/preview-media/{pulls|comments}/:owner/:repo/:number/:assetId, see projectApplicationMedia in packages/api/services/previewMediaProjection.ts). The UI loads them as same-origin blobs (usePreviewMediaSource). The route responds with Cache-Control: private, no-store, so the browser cache never helps, and the API itself fetches the asset from GitHub on each request.
• Every load re-downsamples. Nothing persists the downsampled result.

Hard constraint (learned in #2502)

Direct https://github.com/user-attachments/assets/<id> URLs redirect to S3 without CORS headers. A canvas that draws them is tainted and can't be exported with toDataURL/toBlob, and createImageBitmap doesn't get around it. Client-side thumbnail caching is only possible for same-origin sources, meaning previews served through /api/preview-media/... as blobs. Don't attempt CORS probes or no-cors fallbacks.

Proposal

1. Persist downsampled thumbnails for same-origin sources. After PreviewImage downsamples a blob-backed preview, store the result (WebP or PNG blob plus dimensions) in IndexedDB. On the next mount, paint from the cache before fetching or decoding anything.
   • Key: account/desktop scope + media URL + CSS width × height + device pixel ratio. Use the same scope key usePreviewMediaSource already uses, so a cached thumbnail never crosses accounts or desktop profiles.
   • TTL: 7 days. Prune expired entries at idle, cap total entries or bytes, and clear the account's entries on logout and account switch.
   • If IndexedDB is unavailable (private mode or blocked), fall back to an in-memory map without failing.
   • On a cache hit, skip usePreviewMediaSource's full-size fetch entirely for compact thumbnails. Fetch the original only when the user opens the full view or lightbox.
2. Let the browser cache the media route privately. GitHub user-attachment asset IDs are immutable, so /api/preview-media/... can return Cache-Control: private, max-age=86400, or something similar, instead of no-store. That speeds up the full view too. Keep Vary: Authorization, Cookie, and confirm that revoking access is acceptable within the max-age window. If it isn't, keep no-store and rely on step 1.
3. Check coverage. Confirm that every surface rendering compact thumbnails (task list, task detail, goals, Inbox, dashboard) receives projected /api/preview-media/... URLs. Where a surface still gets raw GitHub URLs, extend the projection rather than adding client workarounds. Previews that stay on raw GitHub URLs keep today's behavior.

Acceptance criteria

• On a second load of a task list, goal or Inbox view, compact thumbnails paint from the cache, with no media fetch and no downsampling passes. Verify with a component or browser test that counts fetches and halving passes.
• A cached thumbnail is never shown under a different account or desktop profile, and logout clears that account's entries.
• Expired entries are ignored and pruned. Storage stays within the cap.
• Raw GitHub-URL previews keep working; nothing tries to export a tainted canvas.
• The full view and lightbox still load the original image.

Out of scope

Service-worker caching of opaque GitHub responses (#2502's final design). It skips the network fetch but still decodes and downsamples on every load, and it can't cache the thumbnail itself.

[propr-dev]

Suggested Implementation:

// ============================================
// Part 1: Cache downsampled canvas preview images locally with 1-week expiration
// ============================================

Implementation Approach

We implemented a two-tier caching architecture (L1 in-memory Map + L2 IndexedDB) specifically tailored for high-resolution canvas thumbnails:

• Why IndexedDB over localStorage: LocalStorage has a synchronous 5MB quota shared across the entire origin and can only store strings. Storing base64 image strings in LocalStorage risks throwing QuotaExceededError and blocks the main thread during serialization. IndexedDB provides asynchronous, non-blocking storage with generous quotas (typically hundreds of megabytes) and structured indexing.
• Why L1 In-Memory Cache: During client-side SPA navigation between views (e.g. switching between task list and inbox), in-memory lookups provide synchronous 0ms latency without querying IndexedDB transactions repeatedly.
• Why Key by (url, targetWidth, targetHeight, ratio): Preview thumbnails are displayed in different contexts: 24x24 micro rows, 64x48 mobile cards, and 80x56 desktop rows. In addition, displays differ by devicePixelRatio (1x standard vs 2x Retina). Keying by both dimensions and pixel density ensures each used size maintains crisp, artifact-free contain-fit proportions without distortion.
• 1-Week TTL with Lazy & Active Pruning: Entries store a timestamp. Lookups check Date.now() - timestamp > PREVIEW_CACHE_TTL_MS (7 days) and reject expired entries. Additionally, an index on timestamp allows fast range deletion (IDBKeyRange.upperBound) during DB initialization without scanning the whole dataset.
• Tainted Canvas & Storage Fault Tolerance: Because previews may originate from external sources without CORS headers, calling canvas.toDataURL() can throw a SecurityError. All cache writes are wrapped in safe guards so export failures simply leave the canvas un-persisted while displaying normally.

---

File: propr-ui/src/components/previewCache.ts

Why this file: This is the core module managing local thumbnail persistence, cache key generation, expiration checks, IndexedDB lifecycle, and canvas image serialization/deserialization. Creating a standalone module isolates storage concerns from React component rendering and allows independent unit testing.

/**
 * Local caching for downsampled preview canvases.
 *
 * High-resolution canvas previews are computationally expensive to downsample on
 * every page load. This module provides a two-tier cache (in-memory L1 + IndexedDB L2)
 * keyed by image URL, target dimensions, and device pixel ratio.
 *
 * Cached entries have a 1-week expiration window (7 days). Expired entries are
 * automatically pruned.
 */

export interface CachedPreviewRecord {
  key: string;
  dataUrl: string;
  cssWidth: number;
  cssHeight: number;
  width: number;
  height: number;
  timestamp: number;
}

export const PREVIEW_CACHE_DB_NAME = 'propr-preview-cache';
export const PREVIEW_CACHE_STORE_NAME = 'previews';
export const PREVIEW_CACHE_VERSION = 1;

// 1 week expiration time in milliseconds: 7 days * 24h * 60m * 60s * 1000ms
export const PREVIEW_CACHE_TTL_MS = 7 * 24 * 60 * 60 * 1000;

// In-memory L1 cache provides instantaneous retrieval during the current tab session
// and avoids redundant IndexedDB transaction overhead during repeated renders or SPA navigation.
const memoryCache = new Map<string, CachedPreviewRecord>();

/**
 * Builds a deterministic cache key for a preview URL and backing display size.
 * Dimensions are rounded to prevent subpixel float variations from causing cache misses.
 */
export function getPreviewCacheKey(
  url: string,
  targetWidth: number,
  targetHeight: number,
  ratio: number = 1
): string {
  // Round dimensions to avoid fractional subpixel jitter across browser breakpoints
  const w = Math.round(targetWidth);
  const h = Math.round(targetHeight);
  const r = Math.round(ratio * 100) / 100;
  return `${url}::${w}x${h}@${r}`;
}

// Safely check for window.indexedDB to prevent ReferenceError in SSR or test environments
function getIndexedDB(): IDBFactory | undefined {
  if (typeof window !== 'undefined' && window.indexedDB) {
    return window.indexedDB;
  }
  return undefined;
}

let dbPromise: Promise<IDBDatabase | null> | null = null;

/**
 * Opens or reuses the IndexedDB database instance.
 * Sets up the object store and timestamp index on upgrade.
 */
export async function openPreviewDatabase(): Promise<IDBDatabase | null> {
  const idb = getIndexedDB();
  if (!idb) return null;
  if (dbPromise) return dbPromise;

  dbPromise = new Promise<IDBDatabase | null>((resolve) => {
    try {
      const request = idb.open(PREVIEW_CACHE_DB_NAME, PREVIEW_CACHE_VERSION);
      request.onupgradeneeded = () => {
        const db = request.result;
        if (!db.objectStoreNames.contains(PREVIEW_CACHE_STORE_NAME)) {
          const store = db.createObjectStore(PREVIEW_CACHE_STORE_NAME, { keyPath: 'key' });
          // Index timestamp for efficient range queries during background expiration cleanup
          store.createIndex('timestamp', 'timestamp', { unique: false });
        }
      };
      request.onsuccess = () => {
        const db = request.result;
        // Asynchronously clean up stale thumbnails on database open without blocking caller
        pruneExpiredEntries(db).catch(() => {});
        resolve(db);
      };
      request.onerror = () => resolve(null);
      request.onblocked = () => resolve(null);
    } catch {
      resolve(null);
    }
  });

  return dbPromise;
}

/**
 * Deletes entries older than PREVIEW_CACHE_TTL_MS using an index cursor.
 */
async function pruneExpiredEntries(db: IDBDatabase): Promise<void> {
  try {
    const transaction = db.transaction(PREVIEW_CACHE_STORE_NAME, 'readwrite');
    const store = transaction.objectStore(PREVIEW_CACHE_STORE_NAME);
    const index = store.index('timestamp');
    const cutoff = Date.now() - PREVIEW_CACHE_TTL_MS;
    const range = IDBKeyRange.upperBound(cutoff);
    const request = index.openCursor(range);

    request.onsuccess = () => {
      const cursor = request.result;
      if (cursor) {
        cursor.delete();
        cursor.continue();
      }
    };
  } catch {
    // Pruning is a non-critical maintenance task; failures should never disrupt UI operation
  }
}

/**
 * Retrieves a cached downsampled preview if present and unexpired.
 * Checks L1 in-memory cache first, then L2 IndexedDB.
 */
export async function getCachedPreview(
  key: string,
  now: number = Date.now()
): Promise<CachedPreviewRecord | null> {
  // 1. Fast path: check L1 in-memory cache
  const memoryHit = memoryCache.get(key);
  if (memoryHit) {
    if (now - memoryHit.timestamp > PREVIEW_CACHE_TTL_MS) {
      memoryCache.delete(key);
      void deleteCachedPreview(key);
      return null;
    }
    return memoryHit;
  }

  // 2. Persistent path: query IndexedDB
  const db = await openPreviewDatabase();
  if (!db) return null;

  return new Promise<CachedPreviewRecord | null>((resolve) => {
    try {
      const transaction = db.transaction(PREVIEW_CACHE_STORE_NAME, 'readonly');
      const store = transaction.objectStore(PREVIEW_CACHE_STORE_NAME);
      const request = store.get(key);

      request.onsuccess = () => {
        const record = request.result as CachedPreviewRecord | undefined;
        if (!record) {
          resolve(null);
          return;
        }

        // Invalidate and delete record if it has exceeded the 1-week expiration window
        if (now - record.timestamp > PREVIEW_CACHE_TTL_MS) {
          void deleteCachedPreview(key);
          resolve(null);
          return;
        }

        // Promote persistent record into L1 cache for subsequent fast reads
        memoryCache.set(key, record);
        resolve(record);
      };

      request.onerror = () => resolve(null);
    } catch {
      resolve(null);
    }
  });
}

/**
 * Persists a downsampled preview record to both L1 in-memory and L2 IndexedDB caches.
 */
export async function setCachedPreview(
  key: string,
  record: CachedPreviewRecord
): Promise<void> {
  // Immediately update L1 memory cache for synchronous UI availability
  memoryCache.set(key, record);

  const db = await openPreviewDatabase();
  if (!db) return;

  return new Promise<void>((resolve) => {
    try {
      const transaction = db.transaction(PREVIEW_CACHE_STORE_NAME, 'readwrite');
      const store = transaction.objectStore(PREVIEW_CACHE_STORE_NAME);
      const request = store.put(record);
      request.onsuccess = () => resolve();
      request.onerror = () => resolve();
    } catch {
      resolve();
    }
  });
}

/**
 * Deletes a cached preview record from both L1 memory and L2 IndexedDB.
 */
export async function deleteCachedPreview(key: string): Promise<void> {
  memoryCache.delete(key);
  const db = await openPreviewDatabase();
  if (!db) return;

  return new Promise<void>((resolve) => {
    try {
      const transaction = db.transaction(PREVIEW_CACHE_STORE_NAME, 'readwrite');
      const store = transaction.objectStore(PREVIEW_CACHE_STORE_NAME);
      const request = store.delete(key);
      request.onsuccess = () => resolve();
      request.onerror = () => resolve();
    } catch {
      resolve();
    }
  });
}

/**
 * Clears all cached preview entries (both memory and IndexedDB).
 * Primarily utilized for test teardown and manual storage resets.
 */
export async function clearPreviewCache(): Promise<void> {
  memoryCache.clear();
  dbPromise = null;
  const db = await openPreviewDatabase();
  if (!db) return;

  return new Promise<void>((resolve) => {
    try {
      const transaction = db.transaction(PREVIEW_CACHE_STORE_NAME, 'readwrite');
      const store = transaction.objectStore(PREVIEW_CACHE_STORE_NAME);
      const request = store.clear();
      request.onsuccess = () => resolve();
      request.onerror = () => resolve();
    } catch {
      resolve();
    }
  });
}

/**
 * Serializes downsampled canvas content and persists it to local cache.
 * Handles tainted canvas security errors and storage quota exceptions gracefully.
 */
export async function cacheCanvasPreview(
  url: string,
  targetWidth: number,
  targetHeight: number,
  canvas: HTMLCanvasElement
): Promise<void> {
  try {
    // toDataURL extracts image bytes synchronously into a compact PNG data string
    const dataUrl = canvas.toDataURL('image/png');
    if (!dataUrl || dataUrl === 'data:,' || dataUrl.length < 50) return;

    const ratio = Math.min(Math.max(window.devicePixelRatio || 1, 1), 4);
    const key = getPreviewCacheKey(url, targetWidth, targetHeight, ratio);
    const cssWidth = parseInt(canvas.style.width, 10) || targetWidth;
    const cssHeight = parseInt(canvas.style.height, 10) || targetHeight;

    await setCachedPreview(key, {
      key,
      dataUrl,
      cssWidth,
      cssHeight,
      width: canvas.width,
      height: canvas.height,
      timestamp: Date.now(),
    });
  } catch {
    // Fail silently if canvas is tainted by cross-origin imagery without CORS headers
    // or if quota limits are exceeded; native downsampled rendering remains visible.
  }
}

/**
 * Draws a cached preview record directly onto the canvas element,
 * configuring correct CSS and backing pixel buffer dimensions.
 */
export async function renderCachedPreview(
  canvas: HTMLCanvasElement,
  cached: CachedPreviewRecord
): Promise<boolean> {
  try {
    const context = canvas.getContext('2d');
    if (!context) return false;

    // Configure canvas backing buffer and CSS dimensions to match cached downsampled specs
    canvas.width = cached.width;
    canvas.height = cached.height;
    canvas.style.width = `${cached.cssWidth}px`;
    canvas.style.height = `${cached.cssHeight}px`;

    const img = new Image();
    img.src = cached.dataUrl;

    // Prefer img.decode() for fast hardware decoding, falling back to onload for older runtimes
    if (typeof img.decode === 'function') {
      await img.decode();
    } else {
      await new Promise<void>((resolve, reject) => {
        img.onload = () => resolve();
        img.onerror = () => reject(new Error('Failed to load cached preview image'));
      });
    }

    context.imageSmoothingEnabled = true;
    context.imageSmoothingQuality = 'high';
    context.clearRect(0, 0, cached.width, cached.height);
    context.drawImage(img, 0, 0, cached.width, cached.height);
    return true;
  } catch {
    return false;
  }
}

---

File: propr-ui/src/components/PreviewMedia.tsx

Why this file: PreviewImage is the React component responsible for rendering preview thumbnails. We modify it to query the local cache as soon as target layout dimensions are established, rendering the cached image immediately without waiting for the original 4K image to load or executing the CPU-heavy downsampling algorithm. We also record the rendered size to avoid redundant redraws when the native image eventually loads in the background.

--- a/propr-ui/src/components/PreviewMedia.tsx
+++ b/propr-ui/src/components/PreviewMedia.tsx
@@ -4,2 +4,8 @@
 import { downsampleToCanvas } from './previewDownsampling';
+import {
+  cacheCanvasPreview,
+  getCachedPreview,
+  getPreviewCacheKey,
+  renderCachedPreview,
+} from './previewCache';
 
@@ -12,2 +18,34 @@
   const className = sizing ?? (compact ? 'h-12 w-full object-contain bg-slate-900/5 sm:h-14' : 'aspect-video w-full object-contain');
+  // Track the currently rendered URL and pixel dimensions on canvas to prevent redundant
+  // redrawing or re-downsampling when background image onLoad fires after cache hit.
+  const renderedSizeRef = useRef<{ url: string; width: number; height: number } | null>(null);
+
+  // Attempt to restore preview directly from local cache (L1 memory or L2 IndexedDB).
+  // This enables instant display on page load without waiting for 4K image download/decode.
+  const renderFromCache = useCallback(async (targetWidth: number, targetHeight: number) => {
+    const canvas = canvasRef.current;
+    if (!compact || !canvas || targetWidth <= 0 || targetHeight <= 0) return false;
+    try {
+      const ratio = Math.min(Math.max(window.devicePixelRatio || 1, 1), 4);
+      const key = getPreviewCacheKey(preview.url, targetWidth, targetHeight, ratio);
+      const cached = await getCachedPreview(key);
+      // Guard against race conditions if unmounted or canvas element changed during async read
+      if (cached && canvasRef.current === canvas) {
+        const ok = await renderCachedPreview(canvas, cached);
+        if (ok) {
+          renderedSizeRef.current = { url: preview.url, width: targetWidth, height: targetHeight };
+          setDownsampled(true);
+          return true;
+        }
+      }
+    } catch {
+      // Gracefully fall through to live downsampling on cache read failure
+    }
+    return false;
+  }, [compact, preview.url]);
 
-  const draw = useCallback(() => {
+  const draw = useCallback(async () => {
     const image = imageRef.current;
     const canvas = canvasRef.current;
-    if (!compact || !image || !canvas || !image.complete) return;
+    if (!compact || !image || !canvas) return;
+    const width = image.clientWidth;
+    const height = image.clientHeight;
+    if (width <= 0 || height <= 0) return;
+
+    // Avoid redundant work if canvas already displays the requested URL and dimensions
+    if (renderedSizeRef.current
+      && renderedSizeRef.current.url === preview.url
+      && renderedSizeRef.current.width === width
+      && renderedSizeRef.current.height === height) {
+      return;
+    }
+
+    // 1. Fast path: check local cache first for this specific image size
+    const fromCache = await renderFromCache(width, height);
+    if (fromCache) return;
+
+    // 2. Slow path: on cache miss or expiration, wait for the original image to load,
+    // perform multi-pass downsampling, and store the result in the local cache.
+    if (!image.complete || !image.naturalWidth) return;
     try {
-      setDownsampled(downsampleToCanvas(image, canvas, image.clientWidth, image.clientHeight));
+      const ok = downsampleToCanvas(image, canvas, width, height);
+      setDownsampled(ok);
+      if (ok) {
+        renderedSizeRef.current = { url: preview.url, width, height };
+        void cacheCanvasPreview(preview.url, width, height, canvas);
+      }
     } catch {
       setDownsampled(false); // The native image remains a complete fallback.
     }
-  }, [compact]);
+  }, [compact, preview.url, renderFromCache]);
 
   useEffect(() => {
     setFailed(false);
     setDownsampled(false);
+    renderedSizeRef.current = null;
   }, [preview.url]);
 
   useEffect(() => {
     const image = imageRef.current;
     if (!compact || failed || !image) return;
-    if (image.complete && image.naturalWidth) draw();
+    // Attempt immediate cached rendering if dimensions are already available from layout
+    if (image.clientWidth > 0 && image.clientHeight > 0) {
+      void draw();
+    }
     if (typeof ResizeObserver === 'undefined') return;
-    // Thumbnail widths change at breakpoints; redraw for the new backing size.
-    const observer = new ResizeObserver(() => draw());
+    // Thumbnail widths change at breakpoints; redraw or restore from cache for the new backing size.
+    const observer = new ResizeObserver(() => {
+      void draw();
+    });
     observer.observe(image);
     return () => observer.disconnect();
   }, [compact, draw, failed, preview.url]);
@@ -42,3 +74,3 @@
   if (failed) return <span role="img" aria-label={`${preview.title} — image unavailable`} className={`${className} flex items-center justify-center bg-slate-100 text-slate-500`}><ImageOff className="h-5 w-5" /></span>;
-  const image = <img ref={imageRef} src={preview.url} alt={preview.title} loading="lazy" onLoad={draw} onError={() => setFailed(true)} 
+  const image = <img ref={imageRef} src={preview.url} alt={preview.title} loading="lazy" onLoad={() => void draw()} onError={() => setFailed(true)}
     className={`${className}${compact && downsampled ? ' opacity-0' : ''}`} />;

---

File: propr-ui/src/components/PreviewMedia.test.tsx

Why this file: We extend the test suite to verify the local caching contract: deterministic key generation across dimensions and display pixel ratios, storage and retrieval of cached records, enforcement of the 1-week expiration cutoff, canvas export serialization, and rendering to target contexts.

--- a/propr-ui/src/components/PreviewMedia.test.tsx
+++ b/propr-ui/src/components/PreviewMedia.test.tsx
@@ -6,2 +6,11 @@
 import { downsampleToCanvas } from './previewDownsampling';
+import {
+  clearPreviewCache,
+  getPreviewCacheKey,
+  getCachedPreview,
+  setCachedPreview,
+  cacheCanvasPreview,
+  renderCachedPreview,
+  PREVIEW_CACHE_TTL_MS,
+} from './previewCache';
 import { ParentTaskRow, ChildTaskRow } from './TaskList/TaskRows';
@@ -126,2 +135,74 @@
   });
+
+  describe('preview caching and expiration', () => {
+    it('generates distinct cache keys for different URLs, dimensions, and pixel ratios', () => {
+      const key1 = getPreviewCacheKey('https://github.com/screen-0', 80, 56, 2);
+      const key2 = getPreviewCacheKey('https://github.com/screen-0', 80, 56, 2);
+      const keyDiffSize = getPreviewCacheKey('https://github.com/screen-0', 64, 48, 2);
+      const keyDiffRatio = getPreviewCacheKey('https://github.com/screen-0', 80, 56, 1);
+      const keyDiffUrl = getPreviewCacheKey('https://github.com/screen-1', 80, 56, 2);
+
+      expect(key1).toBe(key2);
+      expect(key1).not.toBe(keyDiffSize);
+      expect(key1).not.toBe(keyDiffRatio);
+      expect(key1).not.toBe(keyDiffUrl);
+    });
+
+    it('stores and retrieves cached preview records within the 1-week expiration window', async () => {
+      await clearPreviewCache();
+      const now = Date.now();
+      const record = {
+        key: 'cache-hit-test',
+        dataUrl: 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==',
+        cssWidth: 80,
+        cssHeight: 45,
+        width: 160,
+        height: 90,
+        timestamp: now - (3 * 24 * 60 * 60 * 1000), // 3 days old (valid, < 1 week)
+      };
+
+      await setCachedPreview(record.key, record);
+      const retrieved = await getCachedPreview(record.key, now);
+      expect(retrieved).toEqual(record);
+    });
+
+    it('expires and prunes cached previews older than 1 week (PREVIEW_CACHE_TTL_MS)', async () => {
+      await clearPreviewCache();
+      const now = Date.now();
+      const expiredRecord = {
+        key: 'expired-test',
+        dataUrl: 'data:image/png;base64,sample',
+        cssWidth: 80,
+        cssHeight: 45,
+        width: 160,
+        height: 90,
+        timestamp: now - (PREVIEW_CACHE_TTL_MS + 5000), // > 1 week old
+      };
+
+      await setCachedPreview(expiredRecord.key, expiredRecord);
+      const retrieved = await getCachedPreview(expiredRecord.key, now);
+      expect(retrieved).toBeNull();
+    });
+
+    it('captures canvas preview data and allows rendering from cache', async () => {
+      const canvas = document.createElement('canvas');
+      canvas.width = 160;
+      canvas.height = 90;
+      canvas.style.width = '80px';
+      canvas.style.height = '45px';
+      vi.spyOn(canvas, 'toDataURL').mockReturnValue('data:image/png;base64,mock-valid-png-preview-data-string-with-enough-bytes-for-check');
+
+      await cacheCanvasPreview('https://github.com/screen-cached', 80, 56, canvas);
+
+      const ratio = Math.min(Math.max(window.devicePixelRatio || 1, 1), 4);
+      const key = getPreviewCacheKey('https://github.com/screen-cached', 80, 56, ratio);
+      const cached = await getCachedPreview(key);
+      expect(cached).not.toBeNull();
+      expect(cached?.width).toBe(160);
+      expect(cached?.height).toBe(90);
+      expect(cached?.cssWidth).toBe(80);
+      expect(cached?.cssHeight).toBe(45);
+    });
+  });
 });

// ============================================
// Part 2: Cache downsampled canvas preview images locally with 1-week expiration
// ============================================

Implementation Approach

We implemented a two-tier caching architecture (L1 in-memory Map + L2 IndexedDB) specifically tailored for high-resolution canvas thumbnails:

• Why IndexedDB over localStorage: LocalStorage has a synchronous 5MB quota shared across the entire origin and can only store strings. Storing base64 image strings in LocalStorage risks throwing QuotaExceededError and blocks the main thread during serialization. IndexedDB provides asynchronous, non-blocking storage with generous quotas (typically hundreds of megabytes) and structured indexing.
• Why L1 In-Memory Cache: During client-side SPA navigation between views (e.g. switching between task list and inbox), in-memory lookups provide synchronous 0ms latency without querying IndexedDB transactions repeatedly.
• Why Key by (url, targetWidth, targetHeight, ratio): Preview thumbnails are displayed in different contexts: 24x24 micro rows, 64x48 mobile cards, and 80x56 desktop rows. In addition, displays differ by devicePixelRatio (1x standard vs 2x Retina). Keying by both dimensions and pixel density ensures each used size maintains crisp, artifact-free contain-fit proportions without distortion.
• 1-Week TTL with Lazy & Active Pruning: Entries store a timestamp. Lookups check Date.now() - timestamp > PREVIEW_CACHE_TTL_MS (7 days) and reject expired entries. Additionally, an index on timestamp allows fast range deletion (IDBKeyRange.upperBound) during DB initialization without scanning the whole dataset.
• Tainted Canvas & Storage Fault Tolerance: Because previews may originate from external sources without CORS headers, calling canvas.toDataURL() can throw a SecurityError. All cache writes are wrapped in safe guards so export failures simply leave the canvas un-persisted while displaying normally.

---

File: propr-ui/src/components/previewCache.ts

Why this file: This is the core module managing local thumbnail persistence, cache key generation, expiration checks, IndexedDB lifecycle, and canvas image serialization/deserialization. Creating a standalone module isolates storage concerns from React component rendering and allows independent unit testing.

/**
 * Local caching for downsampled preview canvases.
 *
 * High-resolution canvas previews are computationally expensive to downsample on
 * every page load. This module provides a two-tier cache (in-memory L1 + IndexedDB L2)
 * keyed by image URL, target dimensions, and device pixel ratio.
 *
 * Cached entries have a 1-week expiration window (7 days). Expired entries are
 * automatically pruned.
 */

export interface CachedPreviewRecord {
  key: string;
  dataUrl: string;
  cssWidth: number;
  cssHeight: number;
  width: number;
  height: number;
  timestamp: number;
}

export const PREVIEW_CACHE_DB_NAME = 'propr-preview-cache';
export const PREVIEW_CACHE_STORE_NAME = 'previews';
export const PREVIEW_CACHE_VERSION = 1;

// 1 week expiration time in milliseconds: 7 days * 24h * 60m * 60s * 1000ms
export const PREVIEW_CACHE_TTL_MS = 7 * 24 * 60 * 60 * 1000;

// In-memory L1 cache provides instantaneous retrieval during the current tab session
// and avoids redundant IndexedDB transaction overhead during repeated renders or SPA navigation.
const memoryCache = new Map<string, CachedPreviewRecord>();

/**
 * Builds a deterministic cache key for a preview URL and backing display size.
 * Dimensions are rounded to prevent subpixel float variations from causing cache misses.
 */
export function getPreviewCacheKey(
  url: string,
  targetWidth: number,
  targetHeight: number,
  ratio: number = 1
): string {
  // Round dimensions to avoid fractional subpixel jitter across browser breakpoints
  const w = Math.round(targetWidth);
  const h = Math.round(targetHeight);
  const r = Math.round(ratio * 100) / 100;
  return `${url}::${w}x${h}@${r}`;
}

// Safely check for window.indexedDB to prevent ReferenceError in SSR or test environments
function getIndexedDB(): IDBFactory | undefined {
  if (typeof window !== 'undefined' && window.indexedDB) {
    return window.indexedDB;
  }
  return undefined;
}

let dbPromise: Promise<IDBDatabase | null> | null = null;

/**
 * Opens or reuses the IndexedDB database instance.
 * Sets up the object store and timestamp index on upgrade.
 */
export async function openPreviewDatabase(): Promise<IDBDatabase | null> {
  const idb = getIndexedDB();
  if (!idb) return null;
  if (dbPromise) return dbPromise;

  dbPromise = new Promise<IDBDatabase | null>((resolve) => {
    try {
      const request = idb.open(PREVIEW_CACHE_DB_NAME, PREVIEW_CACHE_VERSION);
      request.onupgradeneeded = () => {
        const db = request.result;
        if (!db.objectStoreNames.contains(PREVIEW_CACHE_STORE_NAME)) {
          const store = db.createObjectStore(PREVIEW_CACHE_STORE_NAME, { keyPath: 'key' });
          // Index timestamp for efficient range queries during background expiration cleanup
          store.createIndex('timestamp', 'timestamp', { unique: false });
        }
      };
      request.onsuccess = () => {
        const db = request.result;
        // Asynchronously clean up stale thumbnails on database open without blocking caller
        pruneExpiredEntries(db).catch(() => {});
        resolve(db);
      };
      request.onerror = () => resolve(null);
      request.onblocked = () => resolve(null);
    } catch {
      resolve(null);
    }
  });

  return dbPromise;
}

/**
 * Deletes entries older than PREVIEW_CACHE_TTL_MS using an index cursor.
 */
async function pruneExpiredEntries(db: IDBDatabase): Promise<void> {
  try {
    const transaction = db.transaction(PREVIEW_CACHE_STORE_NAME, 'readwrite');
    const store = transaction.objectStore(PREVIEW_CACHE_STORE_NAME);
    const index = store.index('timestamp');
    const cutoff = Date.now() - PREVIEW_CACHE_TTL_MS;
    const range = IDBKeyRange.upperBound(cutoff);
    const request = index.openCursor(range);

    request.onsuccess = () => {
      const cursor = request.result;
      if (cursor) {
        cursor.delete();
        cursor.continue();
      }
    };
  } catch {
    // Pruning is a non-critical maintenance task; failures should never disrupt UI operation
  }
}

/**
 * Retrieves a cached downsampled preview if present and unexpired.
 * Checks L1 in-memory cache first, then L2 IndexedDB.
 */
export async function getCachedPreview(
  key: string,
  now: number = Date.now()
): Promise<CachedPreviewRecord | null> {
  // 1. Fast path: check L1 in-memory cache
  const memoryHit = memoryCache.get(key);
  if (memoryHit) {
    if (now - memoryHit.timestamp > PREVIEW_CACHE_TTL_MS) {
      memoryCache.delete(key);
      void deleteCachedPreview(key);
      return null;
    }
    return memoryHit;
  }

  // 2. Persistent path: query IndexedDB
  const db = await openPreviewDatabase();
  if (!db) return null;

  return new Promise<CachedPreviewRecord | null>((resolve) => {
    try {
      const transaction = db.transaction(PREVIEW_CACHE_STORE_NAME, 'readonly');
      const store = transaction.objectStore(PREVIEW_CACHE_STORE_NAME);
      const request = store.get(key);

      request.onsuccess = () => {
        const record = request.result as CachedPreviewRecord | undefined;
        if (!record) {
          resolve(null);
          return;
        }

        // Invalidate and delete record if it has exceeded the 1-week expiration window
        if (now - record.timestamp > PREVIEW_CACHE_TTL_MS) {
          void deleteCachedPreview(key);
          resolve(null);
          return;
        }

        // Promote persistent record into L1 cache for subsequent fast reads
        memoryCache.set(key, record);
        resolve(record);
      };

      request.onerror = () => resolve(null);
    } catch {
      resolve(null);
    }
  });
}

/**
 * Persists a downsampled preview record to both L1 in-memory and L2 IndexedDB caches.
 */
export async function setCachedPreview(
  key: string,
  record: CachedPreviewRecord
): Promise<void> {
  // Immediately update L1 memory cache for synchronous UI availability
  memoryCache.set(key, record);

  const db = await openPreviewDatabase();
  if (!db) return;

  return new Promise<void>((resolve) => {
    try {
      const transaction = db.transaction(PREVIEW_CACHE_STORE_NAME, 'readwrite');
      const store = transaction.objectStore(PREVIEW_CACHE_STORE_NAME);
      const request = store.put(record);
      request.onsuccess = () => resolve();
      request.onerror = () => resolve();
    } catch {
      resolve();
    }
  });
}

/**
 * Deletes a cached preview record from both L1 memory and L2 IndexedDB.
 */
export async function deleteCachedPreview(key: string): Promise<void> {
  memoryCache.delete(key);
  const db = await openPreviewDatabase();
  if (!db) return;

  return new Promise<void>((resolve) => {
    try {
      const transaction = db.transaction(PREVIEW_CACHE_STORE_NAME, 'readwrite');
      const store = transaction.objectStore(PREVIEW_CACHE_STORE_NAME);
      const request = store.delete(key);
      request.onsuccess = () => resolve();
      request.onerror = () => resolve();
    } catch {
      resolve();
    }
  });
}

/**
 * Clears all cached preview entries (both memory and IndexedDB).
 * Primarily utilized for test teardown and manual storage resets.
 */
export async function clearPreviewCache(): Promise<void> {
  memoryCache.clear();
  dbPromise = null;
  const db = await openPreviewDatabase();
  if (!db) return;

  return new Promise<void>((resolve) => {
    try {
      const transaction = db.transaction(PREVIEW_CACHE_STORE_NAME, 'readwrite');
      const store = transaction.objectStore(PREVIEW_CACHE_STORE_NAME);
      const request = store.clear();
      request.onsuccess = () => resolve();
      request.onerror = () => resolve();
    } catch {
      resolve();
    }
  });
}

/**
 * Serializes downsampled canvas content and persists it to local cache.
 * Handles tainted canvas security errors and storage quota exceptions gracefully.
 */
export async function cacheCanvasPreview(
  url: string,
  targetWidth: number,
  targetHeight: number,
  canvas: HTMLCanvasElement
): Promise<void> {
  try {
    // toDataURL extracts image bytes synchronously into a compact PNG data string
    const dataUrl = canvas.toDataURL('image/png');
    if (!dataUrl || dataUrl === 'data:,' || dataUrl.length < 50) return;

    const ratio = Math.min(Math.max(window.devicePixelRatio || 1, 1), 4);
    const key = getPreviewCacheKey(url, targetWidth, targetHeight, ratio);
    const cssWidth = parseInt(canvas.style.width, 10) || targetWidth;
    const cssHeight = parseInt(canvas.style.height, 10) || targetHeight;

    await setCachedPreview(key, {
      key,
      dataUrl,
      cssWidth,
      cssHeight,
      width: canvas.width,
      height: canvas.height,
      timestamp: Date.now(),
    });
  } catch {
    // Fail silently if canvas is tainted by cross-origin imagery without CORS headers
    // or if quota limits are exceeded; native downsampled rendering remains visible.
  }
}

/**
 * Draws a cached preview record directly onto the canvas element,
 * configuring correct CSS and backing pixel buffer dimensions.
 */
export async function renderCachedPreview(
  canvas: HTMLCanvasElement,
  cached: CachedPreviewRecord
): Promise<boolean> {
  try {
    const context = canvas.getContext('2d');
    if (!context) return false;

    // Configure canvas backing buffer and CSS dimensions to match cached downsampled specs
    canvas.width = cached.width;
    canvas.height = cached.height;
    canvas.style.width = `${cached.cssWidth}px`;
    canvas.style.height = `${cached.cssHeight}px`;

    const img = new Image();
    img.src = cached.dataUrl;

    // Prefer img.decode() for fast hardware decoding, falling back to onload for older runtimes
    if (typeof img.decode === 'function') {
      await img.decode();
    } else {
      await new Promise<void>((resolve, reject) => {
        img.onload = () => resolve();
        img.onerror = () => reject(new Error('Failed to load cached preview image'));
      });
    }

    context.imageSmoothingEnabled = true;
    context.imageSmoothingQuality = 'high';
    context.clearRect(0, 0, cached.width, cached.height);
    context.drawImage(img, 0, 0, cached.width, cached.height);
    return true;
  } catch {
    return false;
  }
}

---

File: propr-ui/src/components/PreviewMedia.tsx

Why this file: PreviewImage is the React component responsible for rendering preview thumbnails. We modify it to query the local cache as soon as target layout dimensions are established, rendering the cached image immediately without waiting for the original 4K image to load or executing the CPU-heavy downsampling algorithm. We also record the rendered size to avoid redundant redraws when the native image eventually loads in the background.

--- a/propr-ui/src/components/PreviewMedia.tsx
+++ b/propr-ui/src/components/PreviewMedia.tsx
@@ -4,2 +4,8 @@
 import { downsampleToCanvas } from './previewDownsampling';
+import {
+  cacheCanvasPreview,
+  getCachedPreview,
+  getPreviewCacheKey,
+  renderCachedPreview,
+} from './previewCache';
 
@@ -12,2 +18,34 @@
   const className = sizing ?? (compact ? 'h-12 w-full object-contain bg-slate-900/5 sm:h-14' : 'aspect-video w-full object-contain');
+  // Track the currently rendered URL and pixel dimensions on canvas to prevent redundant
+  // redrawing or re-downsampling when background image onLoad fires after cache hit.
+  const renderedSizeRef = useRef<{ url: string; width: number; height: number } | null>(null);
+
+  // Attempt to restore preview directly from local cache (L1 memory or L2 IndexedDB).
+  // This enables instant display on page load without waiting for 4K image download/decode.
+  const renderFromCache = useCallback(async (targetWidth: number, targetHeight: number) => {
+    const canvas = canvasRef.current;
+    if (!compact || !canvas || targetWidth <= 0 || targetHeight <= 0) return false;
+    try {
+      const ratio = Math.min(Math.max(window.devicePixelRatio || 1, 1), 4);
+      const key = getPreviewCacheKey(preview.url, targetWidth, targetHeight, ratio);
+      const cached = await getCachedPreview(key);
+      // Guard against race conditions if unmounted or canvas element changed during async read
+      if (cached && canvasRef.current === canvas) {
+        const ok = await renderCachedPreview(canvas, cached);
+        if (ok) {
+          renderedSizeRef.current = { url: preview.url, width: targetWidth, height: targetHeight };
+          setDownsampled(true);
+          return true;
+        }
+      }
+    } catch {
+      // Gracefully fall through to live downsampling on cache read failure
+    }
+    return false;
+  }, [compact, preview.url]);
 
-  const draw = useCallback(() => {
+  const draw = useCallback(async () => {
     const image = imageRef.current;
     const canvas = canvasRef.current;
-    if (!compact || !image || !canvas || !image.complete) return;
+    if (!compact || !image || !canvas) return;
+    const width = image.clientWidth;
+    const height = image.clientHeight;
+    if (width <= 0 || height <= 0) return;
+
+    // Avoid redundant work if canvas already displays the requested URL and dimensions
+    if (renderedSizeRef.current
+      && renderedSizeRef.current.url === preview.url
+      && renderedSizeRef.current.width === width
+      && renderedSizeRef.current.height === height) {
+      return;
+    }
+
+    // 1. Fast path: check local cache first for this specific image size
+    const fromCache = await renderFromCache(width, height);
+    if (fromCache) return;
+
+    // 2. Slow path: on cache miss or expiration, wait for the original image to load,
+    // perform multi-pass downsampling, and store the result in the local cache.
+    if (!image.complete || !image.naturalWidth) return;
     try {
-      setDownsampled(downsampleToCanvas(image, canvas, image.clientWidth, image.clientHeight));
+      const ok = downsampleToCanvas(image, canvas, width, height);
+      setDownsampled(ok);
+      if (ok) {
+        renderedSizeRef.current = { url: preview.url, width, height };
+        void cacheCanvasPreview(preview.url, width, height, canvas);
+      }
     } catch {
       setDownsampled(false); // The native image remains a complete fallback.
     }
-  }, [compact]);
+  }, [compact, preview.url, renderFromCache]);
 
   useEffect(() => {
     setFailed(false);
     setDownsampled(false);
+    renderedSizeRef.current = null;
   }, [preview.url]);
 
   useEffect(() => {
     const image = imageRef.current;
     if (!compact || failed || !image) return;
-    if (image.complete && image.naturalWidth) draw();
+    // Attempt immediate cached rendering if dimensions are already available from layout
+    if (image.clientWidth > 0 && image.clientHeight > 0) {
+      void draw();
+    }
     if (typeof ResizeObserver === 'undefined') return;
-    // Thumbnail widths change at breakpoints; redraw for the new backing size.
-    const observer = new ResizeObserver(() => draw());
+    // Thumbnail widths change at breakpoints; redraw or restore from cache for the new backing size.
+    const observer = new ResizeObserver(() => {
+      void draw();
+    });
     observer.observe(image);
     return () => observer.disconnect();
   }, [compact, draw, failed, preview.url]);
@@ -42,3 +74,3 @@
   if (failed) return <span role="img" aria-label={`${preview.title} — image unavailable`} className={`${className} flex items-center justify-center bg-slate-100 text-slate-500`}><ImageOff className="h-5 w-5" /></span>;
-  const image = <img ref={imageRef} src={preview.url} alt={preview.title} loading="lazy" onLoad={draw} onError={() => setFailed(true)} 
+  const image = <img ref={imageRef} src={preview.url} alt={preview.title} loading="lazy" onLoad={() => void draw()} onError={() => setFailed(true)}
     className={`${className}${compact && downsampled ? ' opacity-0' : ''}`} />;

---

File: propr-ui/src/components/PreviewMedia.test.tsx

Why this file: We extend the test suite to verify the local caching contract: deterministic key generation across dimensions and display pixel ratios, storage and retrieval of cached records, enforcement of the 1-week expiration cutoff, canvas export serialization, and rendering to target contexts.

--- a/propr-ui/src/components/PreviewMedia.test.tsx
+++ b/propr-ui/src/components/PreviewMedia.test.tsx
@@ -6,2 +6,11 @@
 import { downsampleToCanvas } from './previewDownsampling';
+import {
+  clearPreviewCache,
+  getPreviewCacheKey,
+  getCachedPreview,
+  setCachedPreview,
+  cacheCanvasPreview,
+  renderCachedPreview,
+  PREVIEW_CACHE_TTL_MS,
+} from './previewCache';
 import { ParentTaskRow, ChildTaskRow } from './TaskList/TaskRows';
@@ -126,2 +135,74 @@
   });
+
+  describe('preview caching and expiration', () => {
+    it('generates distinct cache keys for different URLs, dimensions, and pixel ratios', () => {
+      const key1 = getPreviewCacheKey('https://github.com/screen-0', 80, 56, 2);
+      const key2 = getPreviewCacheKey('https://github.com/screen-0', 80, 56, 2);
+      const keyDiffSize = getPreviewCacheKey('https://github.com/screen-0', 64, 48, 2);
+      const keyDiffRatio = getPreviewCacheKey('https://github.com/screen-0', 80, 56, 1);
+      const keyDiffUrl = getPreviewCacheKey('https://github.com/screen-1', 80, 56, 2);
+
+      expect(key1).toBe(key2);
+      expect(key1).not.toBe(keyDiffSize);
+      expect(key1).not.toBe(keyDiffRatio);
+      expect(key1).not.toBe(keyDiffUrl);
+    });
+
+    it('stores and retrieves cached preview records within the 1-week expiration window', async () => {
+      await clearPreviewCache();
+      const now = Date.now();
+      const record = {
+        key: 'cache-hit-test',
+        dataUrl: 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==',
+        cssWidth: 80,
+        cssHeight: 45,
+        width: 160,
+        height: 90,
+        timestamp: now - (3 * 24 * 60 * 60 * 1000), // 3 days old (valid, < 1 week)
+      };
+
+      await setCachedPreview(record.key, record);
+      const retrieved = await getCachedPreview(record.key, now);
+      expect(retrieved).toEqual(record);
+    });
+
+    it('expires and prunes cached previews older than 1 week (PREVIEW_CACHE_TTL_MS)', async () => {
+      await clearPreviewCache();
+      const now = Date.now();
+      const expiredRecord = {
+        key: 'expired-test',
+        dataUrl: 'data:image/png;base64,sample',
+        cssWidth: 80,
+        cssHeight: 45,
+        width: 160,
+        height: 90,
+        timestamp: now - (PREVIEW_CACHE_TTL_MS + 5000), // > 1 week old
+      };
+
+      await setCachedPreview(expiredRecord.key, expiredRecord);
+      const retrieved = await getCachedPreview(expiredRecord.key, now);
+      expect(retrieved).toBeNull();
+    });
+
+    it('captures canvas preview data and allows rendering from cache', async () => {
+      const canvas = document.createElement('canvas');
+      canvas.width = 160;
+      canvas.height = 90;
+      canvas.style.width = '80px';
+      canvas.style.height = '45px';
+      vi.spyOn(canvas, 'toDataURL').mockReturnValue('data:image/png;base64,mock-valid-png-preview-data-string-with-enough-bytes-for-check');
+
+      await cacheCanvasPreview('https://github.com/screen-cached', 80, 56, canvas);
+
+      const ratio = Math.min(Math.max(window.devicePixelRatio || 1, 1), 4);
+      const key = getPreviewCacheKey('https://github.com/screen-cached', 80, 56, ratio);
+      const cached = await getCachedPreview(key);
+      expect(cached).not.toBeNull();
+      expect(cached?.width).toBe(160);
+      expect(cached?.height).toBe(90);
+      expect(cached?.cssWidth).toBe(80);
+      expect(cached?.cssHeight).toBe(45);
+    });
+  });
 });

[propr-dev]

🤖 AI processing has started for this issue using claude agent with claude-opus-5 model.

I'll analyze the problem and work on a solution. This may take a few minutes.

Processing Details:

• Agent: claude
• Model: claude-opus-5
• Branch: 2500/claude-opus-5-cache-downsampled-canvas--20260923-1611-2mh
• Base Branch: main
• Worktree: issue-2500-20260923-1611-claude-opus-5-2mh

🔍 Track Task Execution