feat(cache): persistent Cache API for media storage

[Just-Insane]

Description

Add a service-worker-backed Cache API layer for media (images, videos, files). Media is served from cache on subsequent loads, reducing bandwidth usage and improving perceived load times. Failed or errored media requests are not cached to prevent poisoning the cache with error responses.

Fixes #

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

Checklist:

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings

AI disclosure:

• Fully AI generated (explain what all the generated code does in moderate detail).
• Partially AI assisted (clarify which code was AI assisted and briefly explain what it does).

A fetch-event handler in the service worker intercepts requests matching the Matrix media path pattern. On a cache hit it returns the cached response directly. On a miss it fetches from the network, clones the response, stores the clone in a named Cache API store only when the status is 2xx (avoiding caching 404s or auth errors), then returns the original response to the page. A separate message handler lets the main thread send a CLEAR_MEDIA_CACHE command to purge the store on logout.

[Copilot]

Pull request overview

This PR introduces new client-side caching behavior for media and avatar rendering to reduce repeated downloads and processing, while also adjusting fetch cache semantics for authenticated requests.

Changes:

• Added a persistent Cache API–backed layer to useBlobCache with expiry/eviction, plus a public cache-clear helper.
• Updated media/config fetches to use cache: 'no-cache', and made downloadMedia throw on non-2xx responses.
• Added an in-memory SVG avatar processing cache shared between room avatars and user avatars, with a developer-tools UI action to clear it.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
src/sw.ts	Adjusts request cache mode used by authenticated SW fetches.
src/app/utils/matrix.ts	Changes media download fetch cache mode and adds error throwing on non-OK responses.
src/app/hooks/useBlobCache.ts	Implements persistent Cache API storage, metadata tracking, eviction, and cache stats.
src/app/features/settings/developer-tools/DevelopTools.tsx	Adds a “Caches” section with SVG avatar cache size + clear action.
src/app/components/user-avatar/UserAvatar.tsx	Reuses shared SVG-processing hook for user avatars.
src/app/components/room-avatar/AvatarImage.tsx	Adds module-level SVG blob URL cache and exports cache utilities + hook.
.changeset/media-cache.md	Declares a minor release note for persistent media caching.

Comments suppressed due to low confidence (6)

src/app/hooks/useBlobCache.ts:90

• cacheMedia always pushes new metadata entries even if the URL is already cached. If the same URL is cached more than once in a session, cacheMetadata will contain duplicates and size/count stats (and eviction) will be wrong. Update existing metadata entries for the same URL (or de-dup before pushing).

    await cache.put(url, response);

    // Update metadata
    cacheMetadata.push({
      url,
      size: blob.size,
      cachedAt: Date.now(),
    });

    // Check size and evict if needed
    await evictIfNeeded();

src/app/hooks/useBlobCache.ts:144

• evictIfNeeded evicts a fixed 10% of entries once, but it may still leave the cache above MAX_CACHE_SIZE_MB (e.g. a few very large blobs). Consider evicting in a loop until under the limit, or evicting at least one item and recomputing size after deletions.

async function evictIfNeeded(): Promise<void> {
  const totalSizeBytes = cacheMetadata.reduce((sum, m) => sum + m.size, 0);
  const totalSizeMB = totalSizeBytes / (1024 * 1024);

  if (totalSizeMB <= MAX_CACHE_SIZE_MB) return;

  try {
    const cache = await openMediaCache();
    const toEvict = Math.ceil(cacheMetadata.length * 0.1); // Evict 10% of entries

    const toDelete: CacheMetadata[] = [];
    for (let i = 0; i < toEvict && cacheMetadata.length > 0; i++) {
      const oldest = cacheMetadata.shift();
      if (oldest) {
        toDelete.push(oldest);
      }
    }

    // Delete all in parallel
    await Promise.all(toDelete.map((m) => cache.delete(m.url)));
  } catch {

src/app/hooks/useBlobCache.ts:159

• clearMediaCache clears imageBlobCache without revoking the existing blob: object URLs. That leaves the underlying memory allocated for the lifetime of the page. Revoke each object URL before clearing the map (and consider clearing inflightRequests too).

export async function clearMediaCache(): Promise<void> {
  try {
    await caches.delete(CACHE_NAME);
    cacheMetadata = [];
    metadataLoaded = false;
    imageBlobCache.clear();
  } catch {

src/app/hooks/useBlobCache.ts:197

• This hook updates state during render when url !== cacheState.sourceUrl. Setting state while rendering can cause React warnings and extra renders, and can become an infinite loop in edge cases. Move this synchronization into a useEffect that runs when url changes, or derive blobUrl directly from url/cache without using state for sourceUrl.

  if (url !== cacheState.sourceUrl) {
    setCacheState({
      sourceUrl: url,
      blobUrl: url ? imageBlobCache.get(url) : undefined,
    });
  }

src/app/components/room-avatar/AvatarImage.tsx:86

• useProcessedAvatarSrc doesn't deduplicate in-flight processing. If multiple components mount with the same src simultaneously, they can fetch/process concurrently and overwrite the cache entry; the overwritten blob URL is never revoked, leaking memory. Consider storing an in-flight Promise per src (or checking the cache again before set) and revoking any replaced blob URL.

    const cachedBlobUrl = svgBlobCache.get(src);
    if (cachedBlobUrl) {
      setProcessedSrc(cachedBlobUrl);
      return () => {
        isMounted = false;
      };
    }

    const processImage = async () => {
      try {
        const res = await fetch(src, { mode: 'cors' });
        const contentType = res.headers.get('content-type');

        if (contentType && contentType.includes('image/svg+xml')) {
          const text = await res.text();
          const parser = new DOMParser();
          const doc = parser.parseFromString(text, 'image/svg+xml');

          const animations = doc.querySelectorAll('animate, animateTransform, animateMotion');
          animations.forEach((anim) => anim.setAttribute('repeatCount', 'indefinite'));

          const style = doc.createElementNS('http://www.w3.org/2000/svg', 'style');
          style.textContent = '* { animation-iteration-count: infinite !important; }';
          doc.documentElement.appendChild(style);

          const serializer = new XMLSerializer();
          const newSvgString = serializer.serializeToString(doc);
          const blob = new Blob([newSvgString], { type: 'image/svg+xml' });

          const blobUrl = URL.createObjectURL(blob);
          // Store in module cache so future remounts skip processing.
          svgBlobCache.set(src, blobUrl);
          if (isMounted) setProcessedSrc(blobUrl);
        } else if (isMounted) setProcessedSrc(src);
      } catch {

src/app/hooks/useBlobCache.ts:161

• The persistent Cache API store in useBlobCache will survive reloads and (without an explicit integration point) also survive logout/account switching. Since clearMediaCache isn’t referenced anywhere in the codebase, cached authenticated media can remain available to subsequent sessions in the same browser profile. Hook this into the logout flow (and/or a SW message) so media is purged when credentials are cleared.

/**
 * Clear all media from persistent cache.
 * Useful for "Clear Cache" settings option.
 */
export async function clearMediaCache(): Promise<void> {
  try {
    await caches.delete(CACHE_NAME);
    cacheMetadata = [];
    metadataLoaded = false;
    imageBlobCache.clear();
  } catch {
    // Cache clear failed — silent ignore
  }

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.