Merge with dependent PRs

e2e/src/web/specs/photo-viewer.e2e-spec.ts

@@ -1,10 +1,7 @@
 import { AssetMediaResponseDto, LoginResponseDto } from '@immich/sdk';
-import { Page, expect, test } from '@playwright/test';
+import { expect, test } from '@playwright/test';
 import { utils } from 'src/utils';
 
-function imageLocator(page: Page) {
-  return page.getByAltText('Image taken').locator('visible=true');
-}
 test.describe('Photo Viewer', () => {
   let admin: LoginResponseDto;
   let asset: AssetMediaResponseDto;
@@ -26,31 +23,32 @@ test.describe('Photo Viewer', () => {
 
   test('loads original photo when zoomed', async ({ page }) => {
     await page.goto(`/photos/${asset.id}`);
-    await expect.poll(async () => await imageLocator(page).getAttribute('src')).toContain('thumbnail');
-    const box = await imageLocator(page).boundingBox();
+    await expect(page.getByTestId('thumbnail')).toHaveAttribute('src', /thumbnail/);
+    const box = await page.getByTestId('thumbnail').boundingBox();
     expect(box).toBeTruthy();
     const { x, y, width, height } = box!;
     await page.mouse.move(x + width / 2, y + height / 2);
     await page.mouse.wheel(0, -1);
-    await expect.poll(async () => await imageLocator(page).getAttribute('src')).toContain('original');
+    await expect(page.getByTestId('original')).toBeInViewport();
+    await expect(page.getByTestId('original')).toHaveAttribute('src', /original/);
   });
 
   test('loads fullsize image when zoomed and original is web-incompatible', async ({ page }) => {
     await page.goto(`/photos/${rawAsset.id}`);
-    await expect.poll(async () => await imageLocator(page).getAttribute('src')).toContain('thumbnail');
-    const box = await imageLocator(page).boundingBox();
+    await expect(page.getByTestId('thumbnail')).toHaveAttribute('src', /thumbnail/);
+    const box = await page.getByTestId('thumbnail').boundingBox();
     expect(box).toBeTruthy();
     const { x, y, width, height } = box!;
     await page.mouse.move(x + width / 2, y + height / 2);
     await page.mouse.wheel(0, -1);
-    await expect.poll(async () => await imageLocator(page).getAttribute('src')).toContain('fullsize');
+    await expect(page.getByTestId('original')).toHaveAttribute('src', /fullsize/);
   });
 
   test('reloads photo when checksum changes', async ({ page }) => {
     await page.goto(`/photos/${asset.id}`);
-    await expect.poll(async () => await imageLocator(page).getAttribute('src')).toContain('thumbnail');
-    const initialSrc = await imageLocator(page).getAttribute('src');
+    await expect(page.getByTestId('thumbnail')).toHaveAttribute('src', /thumbnail/);
+    const initialSrc = await page.getByTestId('thumbnail').getAttribute('src');
     await utils.replaceAsset(admin.accessToken, asset.id);
-    await expect.poll(async () => await imageLocator(page).getAttribute('src')).not.toBe(initialSrc);
+    await expect(page.getByTestId('preview')).not.toHaveAttribute('src', initialSrc!);
   });
 });

web/src/lib/actions/image-loader.svelte.ts

@@ -0,0 +1,159 @@
+import { cancelImageUrl } from '$lib/utils/sw-messaging';
+import type { ClassValue } from 'svelte/elements';
+
+import { imageManager } from '$lib/managers/ImageManager.svelte';
+/**
+ * Converts a ClassValue to a string suitable for className assignment.
+ * Handles strings, arrays, and objects similar to how clsx works.
+ */
+function classValueToString(value: ClassValue | undefined): string {
+  if (!value) {
+    return '';
+  }
+  if (typeof value === 'string') {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value
+      .map((v) => classValueToString(v))
+      .filter(Boolean)
+      .join(' ');
+  }
+  // Object/dictionary case
+  return Object.entries(value)
+    .filter(([, v]) => v)
+    .map(([k]) => k)
+    .join(' ');
+}
+
+export interface ImageLoaderParams {
+  src: string | undefined;
+  onStart?: () => void;
+  onLoad?: () => void;
+  onError?: (error: Error) => void;
+  onElementCreated?: (element: HTMLImageElement) => void;
+  imgClass?: ClassValue;
+  alt?: string;
+  draggable?: boolean;
+  role?: string;
+  style?: string;
+  title?: string | null;
+  loading?: 'lazy' | 'eager';
+  dataAttributes?: Record<string, string>;
+}
+
+/**
+ * 1. Creates and appends an <img> element to the parent
+ * 2. Coordinates with service worker before src triggers fetch
+ * 3. Adds load/error listeners
+ * 4. Cancels SW request when element is removed from DOM
+ */
+export function imageLoader(node: HTMLElement, params: ImageLoaderParams) {
+  let currentSrc = params.src;
+  let currentCallbacks = params;
+  let imgElement: HTMLImageElement | null = null;
+
+  const handleLoad = () => {
+    currentCallbacks.onLoad?.();
+  };
+
+  const handleError = () => {
+    currentCallbacks.onError?.(new Error(`Failed to load image: ${currentSrc}`));
+  };
+
+  const updateImageAttributes = (img: HTMLImageElement, params: ImageLoaderParams) => {
+    if (params.alt !== undefined) {
+      img.alt = params.alt;
+    }
+    if (params.draggable !== undefined) {
+      img.draggable = params.draggable;
+    }
+    if (params.imgClass) {
+      img.className = classValueToString(params.imgClass);
+    }
+    if (params.role) {
+      img.role = params.role;
+    }
+    if (params.style !== undefined) {
+      img.setAttribute('style', params.style);
+    }
+    if (params.title !== undefined && params.title !== null) {
+      img.title = params.title;
+    }
+    if (params.loading !== undefined) {
+      img.loading = params.loading;
+    }
+    if (params.dataAttributes) {
+      for (const [key, value] of Object.entries(params.dataAttributes)) {
+        img.setAttribute(key, value);
+      }
+    }
+  };
+
+  const createImageElement = (src: string | undefined, elementParams: ImageLoaderParams) => {
+    const img = document.createElement('img');
+    updateImageAttributes(img, elementParams);
+
+    img.addEventListener('load', handleLoad);
+    img.addEventListener('error', handleError);
+
+    elementParams.onElementCreated?.(img);
+    elementParams.onStart?.();
+
+    // Set src once during construction
+    if (src) {
+      imageManager.prepareImageUrl(src).then(
+        () => {
+          img.src = src;
+          node.append(img);
+        },
+        (error) => {
+          currentCallbacks.onError?.(error);
+        },
+      );
+    } else {
+      img.classList.add('hidden');
+      node.append(img);
+    }
+
+    return img;
+  };
+
+  imgElement = createImageElement(currentSrc, params);
+
+  const cleanupImageElement = () => {
+    cancelImageUrl(currentSrc);
+    if (imgElement) {
+      imgElement.removeEventListener('load', handleLoad);
+      imgElement.removeEventListener('error', handleError);
+      imgElement.remove();
+    }
+  };
+
+  return {
+    update(newParams: ImageLoaderParams) {
+      // If src changed, recreate the image element
+      if (newParams.src !== currentSrc) {
+        cleanupImageElement();
+
+        currentSrc = newParams.src;
+        currentCallbacks = newParams;
+
+        imgElement = createImageElement(currentSrc, newParams);
+        return;
+      }
+
+      currentCallbacks = newParams;
+
+      if (!imgElement) {
+        return;
+      }
+
+      updateImageAttributes(imgElement, newParams);
+    },
+
+    destroy() {
+      cleanupImageElement();
+    },
+  };
+}

web/src/lib/actions/thumbhash.ts

@@ -3,17 +3,27 @@ import { thumbHashToRGBA } from 'thumbhash';
 
 /**
  * Renders a thumbnail onto a canvas from a base64 encoded hash.
- * @param canvas
- * @param param1 object containing the base64 encoded hash (base64Thumbhash: yourString)
  */
-export function thumbhash(canvas: HTMLCanvasElement, { base64ThumbHash }: { base64ThumbHash: string }) {
-  const ctx = canvas.getContext('2d');
-  if (ctx) {
-    const { w, h, rgba } = thumbHashToRGBA(decodeBase64(base64ThumbHash));
-    const pixels = ctx.createImageData(w, h);
-    canvas.width = w;
-    canvas.height = h;
-    pixels.data.set(rgba);
-    ctx.putImageData(pixels, 0, 0);
-  }
+export function thumbhash(canvas: HTMLCanvasElement, options: { base64ThumbHash: string }) {
+  render(canvas, options);
+
+  return {
+    update(newOptions: { base64ThumbHash: string }) {
+      render(canvas, newOptions);
+    },
+  };
 }
+
+const render = (canvas: HTMLCanvasElement, options: { base64ThumbHash: string }) => {
+  const ctx = canvas.getContext('2d');
+  if (!ctx) {
+    return;
+  }
+
+  const { w, h, rgba } = thumbHashToRGBA(decodeBase64(options.base64ThumbHash));
+  const pixels = ctx.createImageData(w, h);
+  canvas.width = w;
+  canvas.height = h;
+  pixels.data.set(rgba);
+  ctx.putImageData(pixels, 0, 0);
+};

web/src/lib/actions/zoom-image.ts

@@ -1,48 +1,42 @@
 import { photoZoomState } from '$lib/stores/zoom-image.store';
-import { useZoomImageWheel } from '@zoom-image/svelte';
+import { createZoomImageWheel } from '@zoom-image/core';
 import { get } from 'svelte/store';
 
 export const zoomImageAction = (node: HTMLElement, options?: { disabled?: boolean }) => {
-  const { createZoomImage, zoomImageState, setZoomImageState } = useZoomImageWheel();
-
-  createZoomImage(node, {
+  const state = get(photoZoomState);
+  const zoomInstance = createZoomImageWheel(node, {
     maxZoom: 10,
+    initialState: state,
   });
 
-  const state = get(photoZoomState);
-  if (state) {
-    setZoomImageState(state);
-  }
+  const unsubscribes = [
+    photoZoomState.subscribe((state) => zoomInstance.setState(state)),
+    zoomInstance.subscribe(({ state }) => {
+      photoZoomState.set(state);
+    }),
+  ];
 
-  // Store original event handlers so we can prevent them when disabled
-  const wheelHandler = (event: WheelEvent) => {
+  const stopIfDisabled = (event: Event) => {
     if (options?.disabled) {
       event.stopImmediatePropagation();
     }
   };
 
-  const pointerDownHandler = (event: PointerEvent) => {
-    if (options?.disabled) {
-      event.stopImmediatePropagation();
-    }
-  };
-
-  // Add handlers at capture phase with higher priority
-  node.addEventListener('wheel', wheelHandler, { capture: true });
-  node.addEventListener('pointerdown', pointerDownHandler, { capture: true });
-
-  const unsubscribes = [photoZoomState.subscribe(setZoomImageState), zoomImageState.subscribe(photoZoomState.set)];
+  node.addEventListener('wheel', stopIfDisabled, { capture: true });
+  node.addEventListener('pointerdown', stopIfDisabled, { capture: true });
 
+  node.style.overflow = 'visible';
   return {
     update(newOptions?: { disabled?: boolean }) {
       options = newOptions;
     },
     destroy() {
-      node.removeEventListener('wheel', wheelHandler, { capture: true });
-      node.removeEventListener('pointerdown', pointerDownHandler, { capture: true });
       for (const unsubscribe of unsubscribes) {
         unsubscribe();
       }
+      node.removeEventListener('wheel', stopIfDisabled, { capture: true });
+      node.removeEventListener('pointerdown', stopIfDisabled, { capture: true });
+      zoomInstance.cleanup();
     },
   };
 };

web/src/lib/components/asset-viewer/adaptive-image.svelte

@@ -0,0 +1,246 @@
+<script lang="ts">
+  import { imageLoader } from '$lib/actions/image-loader.svelte';
+  import { thumbhash } from '$lib/actions/thumbhash';
+  import { zoomImageAction } from '$lib/actions/zoom-image';
+  import BrokenAsset from '$lib/components/assets/broken-asset.svelte';
+  import { SlideshowLook, SlideshowState } from '$lib/stores/slideshow.store';
+  import { photoZoomState, photoZoomTransform, resetZoomState } from '$lib/stores/zoom-image.store';
+  import { AdaptiveImageLoader } from '$lib/utils/adaptive-image-loader.svelte';
+  import { getDimensions } from '$lib/utils/asset-utils';
+  import { scaleToFit } from '$lib/utils/layout-utils';
+  import { getAltText } from '$lib/utils/thumbnail-util';
+  import { toTimelineAsset } from '$lib/utils/timeline-util';
+  import type { AssetResponseDto, SharedLinkResponseDto } from '@immich/sdk';
+  import { LoadingSpinner } from '@immich/ui';
+  import { onDestroy, untrack, type Snippet } from 'svelte';
+
+  interface Props {
+    asset: AssetResponseDto;
+    sharedLink?: SharedLinkResponseDto;
+    zoomDisabled?: boolean;
+    imageClass?: string;
+    container: {
+      width: number;
+      height: number;
+    };
+    slideshowState: SlideshowState;
+    slideshowLook: SlideshowLook;
+    onImageReady?: () => void;
+    onError?: () => void;
+    imgElement?: HTMLImageElement;
+    overlays?: Snippet;
+  }
+
+  let {
+    imgElement = $bindable<HTMLImageElement | undefined>(),
+    asset,
+    sharedLink,
+    zoomDisabled = false,
+    imageClass = '',
+    container,
+    slideshowState,
+    slideshowLook,
+    onImageReady,
+    onError,
+    overlays,
+  }: Props = $props();
+
+  let previousLoader = $state<AdaptiveImageLoader>();
+  let previousAssetId: string | undefined;
+  let previousSharedLinkId: string | undefined;
+
+  const adaptiveImageLoader = $derived.by(() => {
+    if (previousAssetId === asset.id && previousSharedLinkId === sharedLink?.id) {
+      return previousLoader!;
+    }
+
+    return untrack(() => {
+      previousAssetId = asset.id;
+      previousSharedLinkId = sharedLink?.id;
+
+      previousLoader?.destroy();
+      resetZoomState();
+      const loader = new AdaptiveImageLoader(asset, sharedLink, {
+        currentZoomFn: () => $photoZoomState.currentZoom,
+        onImageReady,
+        onError,
+      });
+      previousLoader = loader;
+      return loader;
+    });
+  });
+  onDestroy(() => adaptiveImageLoader.destroy());
+
+  const imageDimensions = $derived.by(() => {
+    if ((asset.width ?? 0) > 0 && (asset.height ?? 0) > 0) {
+      return { width: asset.width!, height: asset.height! };
+    }
+
+    if (asset.exifInfo?.exifImageHeight && asset.exifInfo.exifImageWidth) {
+      return getDimensions(asset.exifInfo) as { width: number; height: number };
+    }
+
+    return { width: 1, height: 1 };
+  });
+
+  const scaledDimensions = $derived(scaleToFit(imageDimensions, container));
+
+  const renderDimensions = $derived.by(() => {
+    const { width, height } = scaledDimensions;
+    return {
+      width: width + 'px',
+      height: height + 'px',
+      left: (container.width - width) / 2 + 'px',
+      top: (container.height - height) / 2 + 'px',
+    };
+  });
+
+  const loadState = $derived(adaptiveImageLoader.adaptiveLoaderState);
+  const imageAltText = $derived(loadState.previewUrl ? $getAltText(toTimelineAsset(asset)) : '');
+  const thumbnailUrl = $derived(loadState.thumbnailUrl);
+  const previewUrl = $derived(loadState.previewUrl);
+  const originalUrl = $derived(loadState.originalUrl);
+  const showSpinner = $derived(!asset.thumbhash && loadState.quality === 'basic');
+  const showBrokenAsset = $derived(loadState.hasError && loadState.quality !== 'loading-original');
+
+  // Effect: Upgrade to original when user zooms in
+  $effect(() => {
+    if ($photoZoomState.currentZoom > 1 && loadState.quality === 'preview') {
+      void adaptiveImageLoader.triggerOriginal();
+    }
+  });
+  let thumbnailElement = $state<HTMLImageElement>();
+  let previewElement = $state<HTMLImageElement>();
+  let originalElement = $state<HTMLImageElement>();
+
+  // Effect: Synchronize highest quality element as main imgElement
+  $effect(() => {
+    imgElement = originalElement ?? previewElement ?? thumbnailElement;
+  });
+</script>
+
+<div
+  class="relative h-full w-full"
+  style:left={renderDimensions.left}
+  style:top={renderDimensions.top}
+  style:width={renderDimensions.width}
+  style:height={renderDimensions.height}
+>
+  {#if asset.thumbhash}
+    <!-- Thumbhash / spinner layer  -->
+    <div style:transform-origin="0px 0px" style:transform={$photoZoomTransform} class="h-full w-full absolute">
+      <canvas use:thumbhash={{ base64ThumbHash: asset.thumbhash }} class="h-full w-full absolute -z-2"></canvas>
+    </div>
+  {:else if showSpinner}
+    <div id="spinner" class="absolute flex h-full items-center justify-center">
+      <LoadingSpinner />
+    </div>
+  {/if}
+
+  <div
+    use:imageLoader={{
+      src: thumbnailUrl,
+      onStart: () => adaptiveImageLoader.onThumbnailStart(),
+      onLoad: () => adaptiveImageLoader.onThumbnailLoad(),
+      onError: () => adaptiveImageLoader.onThumbnailError(),
+      onElementCreated: (el) => (thumbnailElement = el),
+      imgClass: ['absolute h-full', 'w-full', !thumbnailUrl && 'hidden'],
+      alt: '',
+      role: 'presentation',
+      dataAttributes: {
+        'data-testid': 'thumbnail',
+      },
+    }}
+  ></div>
+
+  {#if showBrokenAsset}
+    <div class="h-full w-full absolute">
+      <BrokenAsset class="text-xl h-full w-full" />
+    </div>
+  {:else}
+    <!-- Slideshow blurred background -->
+    {#if thumbnailUrl && slideshowState !== SlideshowState.None && slideshowLook === SlideshowLook.BlurredBackground}
+      <img
+        src={thumbnailUrl}
+        alt=""
+        role="presentation"
+        class="-z-1 absolute top-0 start-0 object-cover h-full w-full blur-lg"
+        draggable="false"
+      />
+    {/if}
+
+    <div
+      class="absolute top-0"
+      style:transform-origin="0px 0px"
+      style:transform={$photoZoomTransform}
+      style:width={renderDimensions.width}
+      style:height={renderDimensions.height}
+    >
+      <div
+        use:imageLoader={{
+          src: previewUrl,
+          onStart: () => adaptiveImageLoader.onPreviewStart(),
+          onLoad: () => adaptiveImageLoader.onPreviewLoad(),
+          onError: () => adaptiveImageLoader.onPreviewError(),
+          onElementCreated: (el) => (previewElement = el),
+          imgClass: ['h-full', 'w-full', { imageClass }, !previewUrl && 'hidden'],
+          alt: imageAltText,
+          draggable: false,
+          dataAttributes: {
+            'data-testid': 'preview',
+          },
+        }}
+      ></div>
+
+      {@render overlays?.()}
+    </div>
+
+    <div
+      class="absolute top-0"
+      style:transform-origin="0px 0px"
+      style:transform={$photoZoomTransform}
+      style:width={renderDimensions.width}
+      style:height={renderDimensions.height}
+    >
+      <div
+        use:imageLoader={{
+          src: originalUrl,
+          onStart: () => adaptiveImageLoader.onOriginalStart(),
+          onLoad: () => adaptiveImageLoader.onOriginalLoad(),
+          onError: () => adaptiveImageLoader.onOriginalError(),
+          onElementCreated: (el) => (originalElement = el),
+          imgClass: ['h-full', 'w-full', { imageClass }, !originalUrl && 'hidden'],
+          alt: imageAltText,
+          draggable: false,
+          dataAttributes: {
+            'data-testid': 'original',
+          },
+        }}
+      ></div>
+
+      {@render overlays?.()}
+    </div>
+
+    <!-- Use placeholder empty image to zoomImage so it can monitor mouse-wheel events and update zoom state -->
+    <div
+      class="absolute top-0"
+      use:zoomImageAction={{ disabled: zoomDisabled }}
+      style:width={renderDimensions.width}
+      style:height={renderDimensions.height}
+    >
+      <img alt="" class="absolute h-full w-full hidden" draggable="false" />
+    </div>
+  {/if}
+</div>
+
+<style>
+  @keyframes delayedVisibility {
+    to {
+      visibility: visible;
+    }
+  }
+  #spinner {
+    visibility: hidden;
+    animation: 0s linear 0.4s forwards delayedVisibility;
+  }
+</style>

web/src/lib/components/asset-viewer/asset-viewer.svelte

@@ -11,24 +11,24 @@
   import { assetViewerManager } from '$lib/managers/asset-viewer-manager.svelte';
   import { authManager } from '$lib/managers/auth-manager.svelte';
   import { editManager, EditToolType } from '$lib/managers/edit/edit-manager.svelte';
-  import { preloadManager } from '$lib/managers/PreloadManager.svelte';
+  import { eventManager } from '$lib/managers/event-manager.svelte';
+  import { imageManager } from '$lib/managers/ImageManager.svelte';
   import { assetViewingStore } from '$lib/stores/asset-viewing.store';
   import { ocrManager } from '$lib/stores/ocr.svelte';
   import { alwaysLoadOriginalVideo } from '$lib/stores/preferences.store';
   import { SlideshowNavigation, SlideshowState, slideshowStore } from '$lib/stores/slideshow.store';
   import { user } from '$lib/stores/user.store';
-  import { getAssetJobMessage, getAssetUrl, getSharedLink, handlePromiseError } from '$lib/utils';
+  import { getAssetJobMessage, getSharedLink, handlePromiseError } from '$lib/utils';
   import type { OnUndoDelete } from '$lib/utils/actions';
   import { navigateToAsset } from '$lib/utils/asset-utils';
   import { handleError } from '$lib/utils/handle-error';
   import { InvocationTracker } from '$lib/utils/invocationTracker';
   import { SlideshowHistory } from '$lib/utils/slideshow-history';
-  import { preloadImageUrl } from '$lib/utils/sw-messaging';
+
   import { toTimelineAsset } from '$lib/utils/timeline-util';
   import {
     AssetJobName,
     AssetTypeEnum,
-    getAllAlbums,
     getAssetInfo,
     getStack,
     runAssetJobs,
@@ -97,7 +97,6 @@
     stopProgress: stopSlideshowProgress,
     slideshowNavigation,
     slideshowState,
-    slideshowTransition,
   } = slideshowStore;
   const stackThumbnailSize = 60;
   const stackSelectedThumbnailSize = 65;
@@ -105,12 +104,11 @@
   const asset = $derived(cursor.current);
   const nextAsset = $derived(cursor.nextAsset);
   const previousAsset = $derived(cursor.previousAsset);
-  let appearsInAlbums: AlbumResponseDto[] = $state([]);
+
   let sharedLink = getSharedLink();
   let previewStackedAsset: AssetResponseDto | undefined = $state();
   let isShowEditor = $state(false);
   let fullscreenElement = $state<Element>();
-  let unsubscribes: (() => void)[] = [];
   let stack: StackResponseDto | null = $state(null);
 
   let zoomToggle = $state(() => void 0);
@@ -125,93 +123,114 @@
       return;
     }
 
-    if (asset.stack) {
-      stack = await getStack({ id: asset.stack.id });
+    if (!asset.stack) {
+      return;
     }
 
+    stack = await getStack({ id: asset.stack.id });
+
     if (!stack?.assets.some(({ id }) => id === asset.id)) {
       stack = null;
     }
 
     untrack(() => {
-      if (stack && stack?.assets.length > 1) {
-        preloadImageUrl(getAssetUrl({ asset: stack.assets[1] }));
-      }
+      void imageManager.preload(stack?.assets[1], 'thumbnail');
     });
   };
 
   const handleFavorite = async () => {
-    if (album && album.isActivityEnabled) {
-      try {
-        await activityManager.toggleLike();
-      } catch (error) {
-        handleError(error, $t('errors.unable_to_change_favorite'));
-      }
-    }
-  };
-
-  onMount(async () => {
-    unsubscribes.push(
-      slideshowState.subscribe((value) => {
-        if (value === SlideshowState.PlaySlideshow) {
-          slideshowHistory.reset();
-          slideshowHistory.queue(toTimelineAsset(asset));
-          handlePromiseError(handlePlaySlideshow());
-        } else if (value === SlideshowState.StopSlideshow) {
-          handlePromiseError(handleStopSlideshow());
-        }
-      }),
-      slideshowNavigation.subscribe((value) => {
-        if (value === SlideshowNavigation.Shuffle) {
-          slideshowHistory.reset();
-          slideshowHistory.queue(toTimelineAsset(asset));
-        }
-      }),
-    );
-
-    if (!sharedLink) {
-      await handleGetAllAlbums();
-    }
-  });
-
-  onDestroy(() => {
-    for (const unsubscribe of unsubscribes) {
-      unsubscribe();
-    }
-
-    activityManager.reset();
-  });
-
-  const handleGetAllAlbums = async () => {
-    if (authManager.isSharedLink) {
+    if (!album || !album.isActivityEnabled) {
       return;
     }
 
     try {
-      appearsInAlbums = await getAllAlbums({ assetId: asset.id });
+      await activityManager.toggleLike();
     } catch (error) {
-      console.error('Error getting album that asset belong to', error);
+      handleError(error, $t('errors.unable_to_change_favorite'));
     }
   };
 
+  onMount(() => {
+    const slideshowStateUnsubscribe = slideshowState.subscribe((value) => {
+      if (value === SlideshowState.PlaySlideshow) {
+        slideshowHistory.reset();
+        slideshowHistory.queue(toTimelineAsset(asset));
+        handlePromiseError(handlePlaySlideshow());
+      } else if (value === SlideshowState.StopSlideshow) {
+        handlePromiseError(handleStopSlideshow());
+      }
+    });
+
+    const slideshowNavigationUnsubscribe = slideshowNavigation.subscribe((value) => {
+      if (value === SlideshowNavigation.Shuffle) {
+        slideshowHistory.reset();
+        slideshowHistory.queue(toTimelineAsset(asset));
+      }
+    });
+
+    return () => {
+      slideshowStateUnsubscribe();
+      slideshowNavigationUnsubscribe();
+    };
+  });
+
+  onDestroy(() => {
+    activityManager.reset();
+    if (cursor.nextAsset) {
+      imageManager.cancel(cursor.nextAsset, 'all');
+    }
+    if (cursor.previousAsset) {
+      imageManager.cancel(cursor.previousAsset, 'all');
+    }
+  });
+
   const closeViewer = () => {
     onClose?.(asset);
   };
 
   const closeEditor = async () => {
     if (editManager.hasAppliedEdits) {
-      console.log(asset);
       const refreshedAsset = await getAssetInfo({ id: asset.id });
-      console.log(refreshedAsset);
       onAssetChange?.(refreshedAsset);
       assetViewingStore.setAsset(refreshedAsset);
     }
     isShowEditor = false;
   };
 
-  const tracker = new InvocationTracker();
+  const cancelPreloadsBeforeNavigation = (direction: 'previous' | 'next') => {
+    const assetToCancel = direction === 'next' ? cursor.previousAsset : cursor.nextAsset;
+    if (!assetToCancel) {
+      return;
+    }
 
-  const navigateAsset = (order?: 'previous' | 'next', e?: Event) => {
+    imageManager.cancel(assetToCancel, 'all');
+  };
+
+  const updatePreloadsAfterNavigation = (oldCursor: AssetCursor, newCursor: AssetCursor) => {
+    const movedForward = newCursor.current.id === oldCursor.nextAsset?.id;
+    const movedBackward = newCursor.current.id === oldCursor.previousAsset?.id;
+
+    if (movedForward) {
+      imageManager.cancel(oldCursor.previousAsset, 'all');
+      void imageManager.preload(newCursor.nextAsset, 'thumbnail');
+      return;
+    }
+
+    if (movedBackward) {
+      imageManager.cancel(oldCursor.nextAsset, 'all');
+      void imageManager.preload(newCursor.previousAsset, 'thumbnail');
+      return;
+    }
+
+    // For thoroughness: navigated to non-adjacent asset (e.g., slideshow random)
+    imageManager.cancel(oldCursor.nextAsset, 'all');
+    imageManager.cancel(oldCursor.previousAsset, 'all');
+    void imageManager.preload(newCursor.nextAsset, 'thumbnail');
+    void imageManager.preload(newCursor.previousAsset, 'thumbnail');
+  };
+
+  const tracker = new InvocationTracker();
+  const navigateAsset = (order?: 'previous' | 'next') => {
     if (!order) {
       if ($slideshowState === SlideshowState.PlaySlideshow) {
         order = $slideshowNavigation === SlideshowNavigation.AscendingOrder ? 'previous' : 'next';
@@ -220,12 +239,12 @@
       }
     }
 
-    e?.stopPropagation();
-    preloadManager.cancel(asset);
     if (tracker.isActive()) {
       return;
     }
 
+    cancelPreloadsBeforeNavigation(order);
+
     void tracker.invoke(
       async () => {
         let hasNext = false;
@@ -246,12 +265,14 @@
               : await navigateToAsset(cursor.nextAsset);
         }
 
-        if ($slideshowState === SlideshowState.PlaySlideshow) {
-          if (hasNext) {
-            $restartSlideshowProgress = true;
-          } else {
-            await handleStopSlideshow();
-          }
+        if ($slideshowState !== SlideshowState.PlaySlideshow) {
+          return;
+        }
+
+        if (hasNext) {
+          $restartSlideshowProgress = true;
+        } else {
+          await handleStopSlideshow();
         }
       },
       (error: Error) => $t('error_while_navigating', { values: { message: error.message } }),
@@ -322,7 +343,7 @@
   const handleAction = async (action: Action) => {
     switch (action.type) {
       case AssetAction.ADD_TO_ALBUM: {
-        await handleGetAllAlbums();
+        eventManager.emit('AlbumAddAssets');
         break;
       }
       case AssetAction.REMOVE_ASSET_FROM_STACK: {
@@ -377,21 +398,34 @@
 
   const refresh = async () => {
     await refreshStack();
-    await handleGetAllAlbums();
     ocrManager.clear();
-    if (!sharedLink) {
-      if (previewStackedAsset) {
-        await ocrManager.getAssetOcr(previewStackedAsset.id);
-      }
-      await ocrManager.getAssetOcr(asset.id);
+    if (sharedLink) {
+      return;
     }
+
+    if (previewStackedAsset) {
+      await ocrManager.getAssetOcr(previewStackedAsset.id);
+    }
+    await ocrManager.getAssetOcr(asset.id);
   };
   $effect(() => {
     // eslint-disable-next-line @typescript-eslint/no-unused-expressions
     asset;
     untrack(() => handlePromiseError(refresh()));
-    preloadManager.preload(cursor.nextAsset);
-    preloadManager.preload(cursor.previousAsset);
+  });
+
+  let lastCursor = $state<AssetCursor>();
+
+  $effect(() => {
+    if (cursor.current.id === lastCursor?.current.id) {
+      return;
+    }
+
+    if (lastCursor) {
+      // After navigation completes, reconcile preloads with full state information
+      updatePreloadsAfterNavigation(lastCursor, cursor);
+    }
+    lastCursor = cursor;
   });
 
   const onAssetReplace = async ({ oldAssetId, newAssetId }: { oldAssetId: string; newAssetId: string }) => {
@@ -501,15 +535,7 @@
   <!-- Asset Viewer -->
   <div class="z-[-1] relative col-start-1 col-span-4 row-start-1 row-span-full">
     {#if viewerKind === 'StackPhotoViewer'}
-      <PhotoViewer
-        bind:zoomToggle
-        bind:copyImage
-        cursor={{ ...cursor, current: previewStackedAsset! }}
-        onPreviousAsset={() => navigateAsset('previous')}
-        onNextAsset={() => navigateAsset('next')}
-        haveFadeTransition={false}
-        {sharedLink}
-      />
+      <PhotoViewer bind:zoomToggle bind:copyImage cursor={{ ...cursor, current: previewStackedAsset! }} {sharedLink} />
     {:else if viewerKind === 'StackVideoViewer'}
       <VideoViewer
         assetId={previewStackedAsset!.id}
@@ -539,15 +565,7 @@
     {:else if viewerKind === 'CropArea'}
       <CropArea {asset} />
     {:else if viewerKind === 'PhotoViewer'}
-      <PhotoViewer
-        bind:zoomToggle
-        bind:copyImage
-        {cursor}
-        onPreviousAsset={() => navigateAsset('previous')}
-        onNextAsset={() => navigateAsset('next')}
-        {sharedLink}
-        haveFadeTransition={$slideshowState !== SlideshowState.None && $slideshowTransition}
-      />
+      <PhotoViewer bind:zoomToggle bind:copyImage {cursor} {sharedLink} />
     {:else if viewerKind === 'VideoViewer'}
       <VideoViewer
         assetId={asset.id}
@@ -595,7 +613,7 @@
       class="row-start-1 row-span-4 w-90 overflow-y-auto transition-all dark:border-l dark:border-s-immich-dark-gray bg-light"
       translate="yes"
     >
-      <DetailPanel {asset} currentAlbum={album} albums={appearsInAlbums} />
+      <DetailPanel {asset} currentAlbum={album} />
     </div>
   {/if}
 

web/src/lib/components/asset-viewer/detail-panel.svelte

@@ -8,6 +8,7 @@
   import { AppRoute, QueryParameter, timeToLoadTheMap } from '$lib/constants';
   import { assetViewerManager } from '$lib/managers/asset-viewer-manager.svelte';
   import { authManager } from '$lib/managers/auth-manager.svelte';
+  import { eventManager } from '$lib/managers/event-manager.svelte';
   import { featureFlagsManager } from '$lib/managers/feature-flags-manager.svelte';
   import AssetChangeDateModal from '$lib/modals/AssetChangeDateModal.svelte';
   import { isFaceEditMode } from '$lib/stores/face-edit.svelte';
@@ -17,10 +18,17 @@
   import { getAssetThumbnailUrl, getPeopleThumbnailUrl } from '$lib/utils';
   import { delay, getDimensions } from '$lib/utils/asset-utils';
   import { getByteUnitString } from '$lib/utils/byte-units';
+  import { handleError } from '$lib/utils/handle-error';
   import { getMetadataSearchQuery } from '$lib/utils/metadata-search';
   import { fromISODateTime, fromISODateTimeUTC, toTimelineAsset } from '$lib/utils/timeline-util';
   import { getParentPath } from '$lib/utils/tree-utils';
-  import { AssetMediaSize, getAssetInfo, type AlbumResponseDto, type AssetResponseDto } from '@immich/sdk';
+  import {
+    AssetMediaSize,
+    getAllAlbums,
+    getAssetInfo,
+    type AlbumResponseDto,
+    type AssetResponseDto,
+  } from '@immich/sdk';
   import { Icon, IconButton, LoadingSpinner, modalManager } from '@immich/ui';
   import {
     mdiCalendar,
@@ -35,6 +43,7 @@
     mdiPlus,
   } from '@mdi/js';
   import { DateTime } from 'luxon';
+  import { onDestroy, untrack } from 'svelte';
   import { t } from 'svelte-i18n';
   import { slide } from 'svelte/transition';
   import ImageThumbnail from '../assets/thumbnail/image-thumbnail.svelte';
@@ -44,11 +53,10 @@
 
   interface Props {
     asset: AssetResponseDto;
-    albums?: AlbumResponseDto[];
     currentAlbum?: AlbumResponseDto | null;
   }
 
-  let { asset, albums = [], currentAlbum = null }: Props = $props();
+  let { asset, currentAlbum = null }: Props = $props();
 
   let showAssetPath = $state(false);
   let showEditFaces = $state(false);
@@ -74,14 +82,43 @@
   );
   let previousId: string | undefined = $state();
 
+  let albums = $state<AlbumResponseDto[]>([]);
+
+  const refreshAlbums = async () => {
+    if (authManager.isSharedLink) {
+      return;
+    }
+
+    try {
+      albums = await getAllAlbums({ assetId: asset.id });
+    } catch (error) {
+      handleError(error, 'Error getting asset album membership');
+    }
+  };
+
+  eventManager.on('AlbumAddAssets', () => void refreshAlbums());
+  onDestroy(() => {
+    eventManager.off('AlbumAddAssets', () => void refreshAlbums());
+  });
+
+  $effect(() => {
+    // eslint-disable-next-line @typescript-eslint/no-unused-expressions
+    asset;
+    untrack(() => void refreshAlbums());
+  });
+
   $effect(() => {
     if (!previousId) {
       previousId = asset.id;
+      return;
     }
-    if (asset.id !== previousId) {
-      showEditFaces = false;
-      previousId = asset.id;
+
+    if (asset.id === previousId) {
+      return;
     }
+
+    showEditFaces = false;
+    previousId = asset.id;
   });
 
   const getMegapixel = (width: number, height: number): number | undefined => {

web/src/lib/components/asset-viewer/photo-viewer.svelte

@@ -1,51 +1,40 @@
 <script lang="ts">
   import { shortcuts } from '$lib/actions/shortcut';
-  import { zoomImageAction } from '$lib/actions/zoom-image';
+  import AdaptiveImage from '$lib/components/asset-viewer/adaptive-image.svelte';
   import FaceEditor from '$lib/components/asset-viewer/face-editor/face-editor.svelte';
   import OcrBoundingBox from '$lib/components/asset-viewer/ocr-bounding-box.svelte';
-  import BrokenAsset from '$lib/components/assets/broken-asset.svelte';
-  import { assetViewerFadeDuration } from '$lib/constants';
   import { castManager } from '$lib/managers/cast-manager.svelte';
-  import { preloadManager } from '$lib/managers/PreloadManager.svelte';
   import { photoViewerImgElement } from '$lib/stores/assets-store.svelte';
   import { isFaceEditMode } from '$lib/stores/face-edit.svelte';
   import { ocrManager } from '$lib/stores/ocr.svelte';
   import { boundingBoxesArray } from '$lib/stores/people.store';
-  import { SlideshowLook, SlideshowState, slideshowLookCssMapping, slideshowStore } from '$lib/stores/slideshow.store';
+  import { SlideshowState, slideshowLookCssMapping, slideshowStore } from '$lib/stores/slideshow.store';
   import { photoZoomState } from '$lib/stores/zoom-image.store';
-  import { getAssetUrl, targetImageSize as getTargetImageSize, handlePromiseError } from '$lib/utils';
+  import { handlePromiseError } from '$lib/utils';
   import { canCopyImageToClipboard, copyImageToClipboard } from '$lib/utils/asset-utils';
   import { handleError } from '$lib/utils/handle-error';
   import { getOcrBoundingBoxes } from '$lib/utils/ocr-utils';
   import { getBoundingBox } from '$lib/utils/people-utils';
-  import { getAltText } from '$lib/utils/thumbnail-util';
-  import { toTimelineAsset } from '$lib/utils/timeline-util';
-  import { AssetMediaSize, type SharedLinkResponseDto } from '@immich/sdk';
-  import { LoadingSpinner, toastManager } from '@immich/ui';
-  import { onDestroy, untrack } from 'svelte';
-  import { useSwipe, type SwipeCustomEvent } from 'svelte-gestures';
+  import { type SharedLinkResponseDto } from '@immich/sdk';
+  import { toastManager } from '@immich/ui';
+  import { onDestroy } from 'svelte';
   import { t } from 'svelte-i18n';
-  import { fade } from 'svelte/transition';
   import type { AssetCursor } from './asset-viewer.svelte';
 
   interface Props {
     cursor: AssetCursor;
-    element?: HTMLDivElement | undefined;
-    haveFadeTransition?: boolean;
-    sharedLink?: SharedLinkResponseDto | undefined;
-    onPreviousAsset?: (() => void) | null;
-    onNextAsset?: (() => void) | null;
+    element?: HTMLDivElement;
+    sharedLink?: SharedLinkResponseDto;
+    onReady?: () => void;
     copyImage?: () => Promise<void>;
-    zoomToggle?: (() => void) | null;
+    zoomToggle?: () => void;
   }
 
   let {
     cursor,
     element = $bindable(),
-    haveFadeTransition = true,
-    sharedLink = undefined,
-    onPreviousAsset = null,
-    onNextAsset = null,
+    sharedLink,
+    onReady,
     copyImage = $bindable(),
     zoomToggle = $bindable(),
   }: Props = $props();
@@ -53,20 +42,6 @@
   const { slideshowState, slideshowLook } = slideshowStore;
   const asset = $derived(cursor.current);
 
-  let imageLoaded: boolean = $state(false);
-  let originalImageLoaded: boolean = $state(false);
-  let imageError: boolean = $state(false);
-
-  let loader = $state<HTMLImageElement>();
-
-  photoZoomState.set({
-    currentRotation: 0,
-    currentZoom: 1,
-    enable: true,
-    currentPositionX: 0,
-    currentPositionY: 0,
-  });
-
   onDestroy(() => {
     $boundingBoxesArray = [];
   });
@@ -115,29 +90,11 @@
     handlePromiseError(copyImage());
   };
 
-  const onSwipe = (event: SwipeCustomEvent) => {
-    if ($photoZoomState.currentZoom > 1) {
-      return;
-    }
-
-    if (ocrManager.showOverlay) {
-      return;
-    }
-
-    if (onNextAsset && event.detail.direction === 'left') {
-      onNextAsset();
-    }
-
-    if (onPreviousAsset && event.detail.direction === 'right') {
-      onPreviousAsset();
-    }
-  };
-
-  const targetImageSize = $derived(getTargetImageSize(asset, originalImageLoaded || $photoZoomState.currentZoom > 1));
+  let currentPreviewUrl = $state<string>();
 
   $effect(() => {
-    if (imageLoaderUrl) {
-      void cast(imageLoaderUrl);
+    if (currentPreviewUrl) {
+      void cast(currentPreviewUrl);
     }
   });
 
@@ -155,35 +112,11 @@
     }
   };
 
-  const onload = () => {
-    imageLoaded = true;
-    originalImageLoaded = targetImageSize === AssetMediaSize.Fullsize || targetImageSize === 'original';
-  };
-
-  const onerror = () => {
-    imageError = imageLoaded = true;
-  };
-
-  onDestroy(() => preloadManager.cancelPreloadUrl(imageLoaderUrl));
-
-  let imageLoaderUrl = $derived(
-    getAssetUrl({ asset, sharedLink, forceOriginal: originalImageLoaded || $photoZoomState.currentZoom > 1 }),
-  );
-
   let containerWidth = $state(0);
   let containerHeight = $state(0);
-
-  let lastUrl: string | undefined;
-
-  $effect(() => {
-    if (lastUrl && lastUrl !== imageLoaderUrl) {
-      untrack(() => {
-        imageLoaded = false;
-        originalImageLoaded = false;
-        imageError = false;
-      });
-    }
-    lastUrl = imageLoaderUrl;
+  const container = $derived({
+    width: containerWidth,
+    height: containerHeight,
   });
 </script>
 
@@ -193,49 +126,28 @@
     { shortcut: { key: 's' }, onShortcut: onPlaySlideshow, preventDefault: true },
     { shortcut: { key: 'c', ctrl: true }, onShortcut: onCopyShortcut, preventDefault: false },
     { shortcut: { key: 'c', meta: true }, onShortcut: onCopyShortcut, preventDefault: false },
-    { shortcut: { key: 'z' }, onShortcut: zoomToggle, preventDefault: false },
   ]}
 />
-{#if imageError}
-  <div id="broken-asset" class="h-full w-full">
-    <BrokenAsset class="text-xl h-full w-full" />
-  </div>
-{/if}
-<img bind:this={loader} style="display:none" src={imageLoaderUrl} alt="" aria-hidden="true" {onload} {onerror} />
+
 <div
   bind:this={element}
   class="relative h-full w-full select-none"
   bind:clientWidth={containerWidth}
   bind:clientHeight={containerHeight}
 >
-  {#if !imageLoaded}
-    <div id="spinner" class="flex h-full items-center justify-center">
-      <LoadingSpinner />
-    </div>
-  {:else if !imageError}
-    <div
-      use:zoomImageAction={{ disabled: isOcrActive }}
-      {...useSwipe(onSwipe)}
-      class="h-full w-full"
-      transition:fade={{ duration: haveFadeTransition ? assetViewerFadeDuration : 0 }}
-    >
-      {#if $slideshowState !== SlideshowState.None && $slideshowLook === SlideshowLook.BlurredBackground}
-        <img
-          src={imageLoaderUrl}
-          alt=""
-          class="-z-1 absolute top-0 start-0 object-cover h-full w-full blur-lg"
-          draggable="false"
-        />
-      {/if}
-      <img
-        bind:this={$photoViewerImgElement}
-        src={imageLoaderUrl}
-        alt={$getAltText(toTimelineAsset(asset))}
-        class="h-full w-full {$slideshowState === SlideshowState.None
-          ? 'object-contain'
-          : slideshowLookCssMapping[$slideshowLook]}"
-        draggable="false"
-      />
+  <AdaptiveImage
+    {asset}
+    {sharedLink}
+    {container}
+    zoomDisabled={isOcrActive}
+    imageClass={$slideshowState === SlideshowState.None ? 'object-contain' : slideshowLookCssMapping[$slideshowLook]}
+    slideshowState={$slideshowState}
+    slideshowLook={$slideshowLook}
+    onImageReady={() => onReady?.()}
+    onError={() => onReady?.()}
+    bind:imgElement={$photoViewerImgElement}
+  >
+    {#snippet overlays()}
       <!-- eslint-disable-next-line svelte/require-each-key -->
       {#each getBoundingBox($boundingBoxesArray, $photoZoomState, $photoViewerImgElement) as boundingbox}
         <div
@@ -247,23 +159,10 @@
       {#each ocrBoxes as ocrBox (ocrBox.id)}
         <OcrBoundingBox {ocrBox} />
       {/each}
-    </div>
+    {/snippet}
+  </AdaptiveImage>
 
-    {#if isFaceEditMode.value}
-      <FaceEditor htmlElement={$photoViewerImgElement} {containerWidth} {containerHeight} assetId={asset.id} />
-    {/if}
+  {#if isFaceEditMode.value}
+    <FaceEditor htmlElement={$photoViewerImgElement} {containerWidth} {containerHeight} assetId={asset.id} />
   {/if}
 </div>
-
-<style>
-  @keyframes delayedVisibility {
-    to {
-      visibility: visible;
-    }
-  }
-  #broken-asset,
-  #spinner {
-    visibility: hidden;
-    animation: 0s linear 0.4s forwards delayedVisibility;
-  }
-</style>

web/src/lib/components/assets/thumbnail/image-thumbnail.svelte

@@ -1,9 +1,8 @@
 <script lang="ts">
+  import { imageLoader } from '$lib/actions/image-loader.svelte';
   import BrokenAsset from '$lib/components/assets/broken-asset.svelte';
-  import { preloadManager } from '$lib/managers/PreloadManager.svelte';
   import { Icon } from '@immich/ui';
   import { mdiEyeOffOutline } from '@mdi/js';
-  import type { ActionReturn } from 'svelte/action';
   import type { ClassValue } from 'svelte/elements';
 
   interface Props {
@@ -54,16 +53,6 @@
     onComplete?.(true);
   };
 
-  function mount(elem: HTMLImageElement): ActionReturn {
-    if (elem.complete) {
-      loaded = true;
-      onComplete?.(false);
-    }
-    return {
-      destroy: () => preloadManager.cancelPreloadUrl(url),
-    };
-  }
-
   let optionalClasses = $derived(
     [
       curve && 'rounded-xl',
@@ -76,26 +65,28 @@
       .filter(Boolean)
       .join(' '),
   );
+
+  let style = $derived(
+    `width: ${widthStyle}; height: ${heightStyle ?? ''}; filter: ${hidden ? 'grayscale(50%)' : 'none'}; opacity: ${hidden ? '0.5' : '1'};`,
+  );
 </script>
 
 {#if errored}
   <BrokenAsset class={optionalClasses} width={widthStyle} height={heightStyle} />
 {:else}
-  <img
-    use:mount
-    onload={setLoaded}
-    onerror={setErrored}
-    style:width={widthStyle}
-    style:height={heightStyle}
-    style:filter={hidden ? 'grayscale(50%)' : 'none'}
-    style:opacity={hidden ? '0.5' : '1'}
-    src={url}
-    alt={loaded || errored ? altText : ''}
-    {title}
-    class={['object-cover', optionalClasses, imageClass]}
-    draggable="false"
-    loading={preload ? 'eager' : 'lazy'}
-  />
+  <div
+    use:imageLoader={{
+      src: url,
+      onLoad: setLoaded,
+      onError: setErrored,
+      imgClass: ['object-cover', optionalClasses, imageClass],
+      style,
+      alt: loaded || errored ? altText : '',
+      draggable: false,
+      title,
+      loading: preload ? 'eager' : 'lazy',
+    }}
+  ></div>
 {/if}
 
 {#if hidden}

web/src/lib/managers/ImageManager.svelte.ts

@@ -0,0 +1,66 @@
+import { getAssetUrlForKind, ImageKinds, type ImageKind } from '$lib/utils';
+import { cancelImageUrl, prepareImageUrl } from '$lib/utils/sw-messaging';
+import { type AssetResponseDto } from '@immich/sdk';
+
+class ImageManager {
+  async preload(asset: AssetResponseDto | undefined, kind: ImageKind = 'preview', suppressError = 'true') {
+    if (!asset) {
+      return;
+    }
+
+    const url = getAssetUrlForKind(asset, kind);
+    if (!url) {
+      return;
+    }
+
+    const promise = this.#executePreloadAndWait(url);
+    if (suppressError) {
+      return promise.catch(() => void 0);
+    }
+    return promise;
+  }
+
+  async prepareImageUrl(url: string | undefined) {
+    if (!url) {
+      return;
+    }
+
+    return this.#prepareImageUrl(url);
+  }
+
+  // Prepare a url for cancelation - call this before requesting an image in order to be able to cancel it
+  async #prepareImageUrl(url: string) {
+    await prepareImageUrl(url);
+  }
+
+  async #executePreloadAndWait(url: string): Promise<void> {
+    return new Promise<void>((resolve, reject) => {
+      const img = new Image();
+      img.addEventListener('load', () => resolve());
+      img.addEventListener('error', () => reject(new Error(`Failed to preload image: ${url}`)));
+      img.src = url;
+    });
+  }
+
+  cancel(asset: AssetResponseDto | undefined, kind: ImageKind | 'all' = 'preview') {
+    if (!asset) {
+      return;
+    }
+
+    const kinds = kind === 'all' ? (Object.keys(ImageKinds) as ImageKind[]) : [kind];
+    for (const k of kinds) {
+      const url = getAssetUrlForKind(asset, k);
+      if (url) {
+        cancelImageUrl(url);
+      }
+    }
+  }
+
+  cancelPreloadUrl(url: string | undefined) {
+    if (url) {
+      cancelImageUrl(url);
+    }
+  }
+}
+
+export const imageManager = new ImageManager();

web/src/lib/managers/PreloadManager.svelte.ts

@@ -1,38 +0,0 @@
-import { getAssetUrl } from '$lib/utils';
-import { cancelImageUrl, preloadImageUrl } from '$lib/utils/sw-messaging';
-import { AssetTypeEnum, type AssetResponseDto } from '@immich/sdk';
-
-class PreloadManager {
-  preload(asset: AssetResponseDto | undefined) {
-    if (globalThis.isSecureContext) {
-      preloadImageUrl(getAssetUrl({ asset }));
-      return;
-    }
-    if (!asset || asset.type !== AssetTypeEnum.Image) {
-      return;
-    }
-    const img = new Image();
-    const url = getAssetUrl({ asset });
-    if (!url) {
-      return;
-    }
-    img.src = url;
-  }
-
-  cancel(asset: AssetResponseDto | undefined) {
-    if (!globalThis.isSecureContext || !asset) {
-      return;
-    }
-    const url = getAssetUrl({ asset });
-    cancelImageUrl(url);
-  }
-
-  cancelPreloadUrl(url: string | undefined) {
-    if (!globalThis.isSecureContext) {
-      return;
-    }
-    cancelImageUrl(url);
-  }
-}
-
-export const preloadManager = new PreloadManager();

web/src/lib/stores/assets-store.svelte.ts

@@ -1,4 +1,4 @@
 import { writable } from 'svelte/store';
 
-export const photoViewerImgElement = writable<HTMLImageElement | null>(null);
+export const photoViewerImgElement = writable<HTMLImageElement>();
 export const isSelectingAllAssets = writable(false);

web/src/lib/stores/zoom-image.store.ts

@@ -1,4 +1,25 @@
 import type { ZoomImageWheelState } from '@zoom-image/core';
-import { writable } from 'svelte/store';
+import { derived, writable } from 'svelte/store';
 
-export const photoZoomState = writable<ZoomImageWheelState>();
+export const photoZoomState = writable<ZoomImageWheelState>({
+  currentRotation: 0,
+  currentZoom: 1,
+  enable: true,
+  currentPositionX: 0,
+  currentPositionY: 0,
+});
+
+export const photoZoomTransform = derived(
+  photoZoomState,
+  ($state) => `translate(${$state.currentPositionX}px,${$state.currentPositionY}px) scale(${$state.currentZoom})`,
+);
+
+export const resetZoomState = () => {
+  photoZoomState.set({
+    currentRotation: 0,
+    currentZoom: 1,
+    enable: true,
+    currentPositionX: 0,
+    currentPositionY: 0,
+  });
+};

web/src/lib/utils.ts

@@ -31,6 +31,15 @@ import { mdiCogRefreshOutline, mdiDatabaseRefreshOutline, mdiHeadSyncOutline, md
 import { init, register, t } from 'svelte-i18n';
 import { derived, get } from 'svelte/store';
 
+export const ImageKinds = {
+  thumbnail: true,
+  preview: true,
+  fullsize: true,
+  original: true,
+} as const;
+
+export type ImageKind = keyof typeof ImageKinds;
+
 interface DownloadRequestOptions<T = unknown> {
   method?: 'GET' | 'POST' | 'PUT' | 'DELETE';
   url: string;
@@ -195,6 +204,23 @@ const createUrl = (path: string, parameters?: Record<string, unknown>) => {
 
 type AssetUrlOptions = { id: string; cacheKey?: string | null; edited?: boolean };
 
+export const getAssetUrlForKind = (asset: AssetResponseDto, kind: ImageKind) => {
+  switch (kind) {
+    case 'preview': {
+      return getAssetThumbnailUrl({ id: asset.id, size: AssetMediaSize.Preview, cacheKey: asset.thumbhash });
+    }
+    case 'thumbnail': {
+      return getAssetThumbnailUrl({ id: asset.id, size: AssetMediaSize.Thumbnail, cacheKey: asset.thumbhash });
+    }
+    case 'fullsize': {
+      return getAssetThumbnailUrl({ id: asset.id, size: AssetMediaSize.Fullsize, cacheKey: asset.thumbhash });
+    }
+    case 'original': {
+      return getAssetOriginalUrl({ id: asset.id, cacheKey: asset.thumbhash });
+    }
+  }
+};
+
 export const getAssetUrl = ({
   asset,
   sharedLink,

web/src/lib/utils/adaptive-image-loader.svelte.ts

@@ -0,0 +1,150 @@
+import { imageManager } from '$lib/managers/ImageManager.svelte';
+import { getAssetUrl, getAssetUrlForKind } from '$lib/utils';
+import { type AssetResponseDto, type SharedLinkResponseDto } from '@immich/sdk';
+
+/**
+ * Quality levels for progressive image loading
+ */
+type ImageQuality =
+  | 'basic'
+  | 'loading-thumbnail'
+  | 'thumbnail'
+  | 'loading-preview'
+  | 'preview'
+  | 'loading-original'
+  | 'original';
+
+export interface ImageLoaderState {
+  previewUrl?: string;
+  thumbnailUrl?: string;
+  originalUrl?: string;
+  quality: ImageQuality;
+  hasError: boolean;
+}
+enum ImageStatus {
+  Unloaded = 'Unloaded',
+  Success = 'Success',
+  Error = 'Error',
+}
+
+/**
+ * Coordinates adaptive loading of a single asset image:
+ * thumbhash → thumbnail → preview → original (on zoom)
+ *
+ */
+export class AdaptiveImageLoader {
+  private state = $state<ImageLoaderState>({
+    quality: 'basic',
+    hasError: false,
+    thumbnailUrl: undefined,
+  });
+
+  private readonly currentZoomFn: () => number;
+  private readonly onImageReady?: () => void;
+  private readonly onError?: () => void;
+  private readonly thumbnailUrl: string;
+  private readonly previewUrl: string | undefined;
+  private readonly originalUrl: string | undefined;
+  private thumbnailImage = ImageStatus.Unloaded;
+  private previewImage = ImageStatus.Unloaded;
+  private originalImage = ImageStatus.Unloaded;
+
+  constructor(
+    asset: AssetResponseDto,
+    sharedLink: SharedLinkResponseDto | undefined,
+    callbacks: {
+      currentZoomFn: () => number;
+      onImageReady?: () => void;
+      onError?: () => void;
+    },
+  ) {
+    this.currentZoomFn = callbacks.currentZoomFn;
+    this.onImageReady = callbacks.onImageReady;
+    this.onError = callbacks.onError;
+
+    this.thumbnailUrl = getAssetUrlForKind(asset, 'thumbnail');
+    this.previewUrl = getAssetUrl({ asset, sharedLink });
+    this.originalUrl = getAssetUrl({ asset, sharedLink, forceOriginal: true });
+    this.state.thumbnailUrl = this.thumbnailUrl;
+  }
+
+  get adaptiveLoaderState(): ImageLoaderState {
+    return this.state;
+  }
+
+  onThumbnailStart() {
+    this.state.quality = 'loading-thumbnail';
+  }
+
+  onThumbnailLoad() {
+    this.state.quality = 'thumbnail';
+    this.thumbnailImage = ImageStatus.Success;
+    this.onImageReady?.();
+    this.triggerMainImage();
+  }
+
+  onThumbnailError() {
+    this.state.thumbnailUrl = undefined;
+    this.thumbnailImage = ImageStatus.Error;
+    this.triggerMainImage();
+  }
+
+  triggerMainImage() {
+    const wantsOriginal = this.currentZoomFn?.() > 1;
+    return wantsOriginal ? this.triggerOriginal() : this.triggerPreview();
+  }
+
+  triggerPreview() {
+    if (!this.previewUrl) {
+      // no preview, try original?
+      this.triggerOriginal();
+      return false;
+    }
+    this.state.previewUrl = this.previewUrl;
+  }
+
+  onPreviewStart() {
+    this.state.quality = 'loading-preview';
+  }
+
+  onPreviewLoad() {
+    this.state.quality = 'preview';
+    this.previewImage = ImageStatus.Success;
+    this.onImageReady?.();
+  }
+
+  onPreviewError() {
+    this.previewImage = ImageStatus.Error;
+    this.state.previewUrl = undefined;
+    // TODO: maybe try original, but only if preview's error isnt due to cancelation
+  }
+
+  triggerOriginal() {
+    if (!this.originalUrl) {
+      this.onError?.();
+      return false;
+    }
+    this.state.originalUrl = this.originalUrl;
+  }
+
+  onOriginalStart() {
+    this.state.quality = 'loading-original';
+  }
+
+  onOriginalLoad() {
+    this.state.quality = 'original';
+    this.originalImage = ImageStatus.Success;
+    this.onImageReady?.();
+  }
+
+  onOriginalError() {
+    this.originalImage = ImageStatus.Error;
+    this.state.originalUrl = undefined;
+  }
+
+  destroy(): void {
+    imageManager.cancelPreloadUrl(this.thumbnailUrl);
+    imageManager.cancelPreloadUrl(this.previewUrl);
+    imageManager.cancelPreloadUrl(this.originalUrl);
+  }
+}

web/src/lib/utils/layout-utils.ts

@@ -129,3 +129,19 @@ export type CommonPosition = {
   width: number;
   height: number;
 };
+
+// Scales dimensions to fit within a container (like object-fit: contain)
+export const scaleToFit = (
+  dimensions: { width: number; height: number },
+  container: { width: number; height: number },
+) => {
+  const scaleX = container.width / dimensions.width;
+  const scaleY = container.height / dimensions.height;
+
+  const scale = Math.min(scaleX, scaleY);
+
+  return {
+    width: dimensions.width * scale,
+    height: dimensions.height * scale,
+  };
+};

web/src/lib/utils/sw-messaging.ts

@@ -1,14 +1,31 @@
-const broadcast = new BroadcastChannel('immich');
+import { ServiceWorkerMessenger } from './sw-messenger';
+
+const messenger = new ServiceWorkerMessenger('immich');
+
+let isServiceWorkerEnabled = true;
+
+messenger.onAckTimeout(() => {
+  if (!isServiceWorkerEnabled) {
+    return;
+  }
+  console.error('[ServiceWorker] No communication detected. Auto-disabled service worker.');
+  isServiceWorkerEnabled = false;
+});
+
+const isValidSwContext = (url: string | undefined | null): url is string => {
+  return globalThis.isSecureContext && isServiceWorkerEnabled && !!url;
+};
 
 export function cancelImageUrl(url: string | undefined | null) {
-  if (!url) {
+  if (!isValidSwContext(url)) {
     return;
   }
-  broadcast.postMessage({ type: 'cancel', url });
+  void messenger.send('cancel', { url });
 }
-export function preloadImageUrl(url: string | undefined | null) {
-  if (!url) {
+
+export async function prepareImageUrl(url: string | undefined | null) {
+  if (!isValidSwContext(url)) {
     return;
   }
-  broadcast.postMessage({ type: 'preload', url });
+  await messenger.send('prepare', { url });
 }

web/src/lib/utils/sw-messenger.ts

@@ -0,0 +1,150 @@
+/**
+ * Low-level protocol for communicating with the service worker via postMessage.
+ *
+ * Protocol:
+ * 1. Main thread sends request: { type: string, requestId: string, ...data }
+ * 2. SW sends ack: { type: 'ack', requestId: string }
+ * 3. SW sends response (optional): { type: 'response', requestId: string, result?: any, error?: string }
+ */
+
+interface PendingRequest {
+  resolveAck: () => void;
+  resolveResponse?: (result: unknown) => void;
+  rejectResponse?: (error: Error) => void;
+  ackTimeout: ReturnType<typeof setTimeout>;
+  ackReceived: boolean;
+}
+
+export class ServiceWorkerMessenger {
+  readonly #pendingRequests = new Map<string, PendingRequest>();
+  readonly #ackTimeoutMs: number;
+  #requestCounter = 0;
+  #onTimeout?: (type: string, data: Record<string, unknown>) => void;
+
+  constructor(_channelName: string, ackTimeoutMs = 5000) {
+    this.#ackTimeoutMs = ackTimeoutMs;
+
+    // Listen for messages from the service worker
+    if ('serviceWorker' in navigator) {
+      navigator.serviceWorker.addEventListener('message', (event) => {
+        this.#handleMessage(event.data);
+      });
+    }
+  }
+
+  #handleMessage(data: unknown) {
+    if (typeof data !== 'object' || data === null) {
+      return;
+    }
+
+    const message = data as { requestId?: string; type?: string; error?: string; result?: unknown };
+    const requestId = message.requestId;
+    if (!requestId) {
+      return;
+    }
+
+    const pending = this.#pendingRequests.get(requestId);
+    if (!pending) {
+      return;
+    }
+
+    if (message.type === 'ack') {
+      pending.ackReceived = true;
+      clearTimeout(pending.ackTimeout);
+      pending.resolveAck();
+      return;
+    }
+
+    if (message.type === 'response') {
+      clearTimeout(pending.ackTimeout);
+      this.#pendingRequests.delete(requestId);
+
+      if (message.error) {
+        pending.rejectResponse?.(new Error(message.error));
+        return;
+      }
+
+      pending.resolveResponse?.(message.result);
+    }
+  }
+
+  /**
+   * Set a callback to be invoked when an ack timeout occurs.
+   * This can be used to detect and disable faulty service workers.
+   */
+  onAckTimeout(callback: (type: string, data: Record<string, unknown>) => void): void {
+    this.#onTimeout = callback;
+  }
+
+  /**
+   * Send a message to the service worker.
+   * - send(): waits for ack, resolves when acknowledged
+   * - request(): waits for response, throws on error/timeout
+   */
+  #sendInternal<T>(type: string, data: Record<string, unknown>, waitForResponse: boolean): Promise<T> {
+    const requestId = `${type}-${++this.#requestCounter}-${Date.now()}`;
+
+    const promise = new Promise<T>((resolve, reject) => {
+      const ackTimeout = setTimeout(() => {
+        const pending = this.#pendingRequests.get(requestId);
+        if (pending && !pending.ackReceived) {
+          this.#pendingRequests.delete(requestId);
+          console.warn(`[ServiceWorker] ${type} request not acknowledged:`, data);
+          this.#onTimeout?.(type, data);
+          // Only reject if we're waiting for a response
+          if (waitForResponse) {
+            reject(new Error(`Service worker did not acknowledge ${type} request`));
+          } else {
+            pending.resolveAck();
+          }
+        }
+      }, this.#ackTimeoutMs);
+
+      this.#pendingRequests.set(requestId, {
+        resolveAck: waitForResponse ? () => {} : () => resolve(undefined as T),
+        resolveResponse: waitForResponse ? (result: unknown) => resolve(result as T) : undefined,
+        rejectResponse: waitForResponse ? reject : undefined,
+        ackTimeout,
+        ackReceived: false,
+      });
+
+      // Send message to the active service worker
+      // Feature detection is done in constructor and at call sites (sw-messaging.ts:isValidSwContext)
+      // eslint-disable-next-line compat/compat
+      navigator.serviceWorker.controller?.postMessage({
+        type,
+        requestId,
+        ...data,
+      });
+    });
+
+    return promise;
+  }
+
+  /**
+   * Send a one-way message to the service worker.
+   * Returns a promise that resolves after the service worker acknowledges receipt.
+   * Rejects if no ack is received within the timeout period.
+   */
+  send(type: string, data: Record<string, unknown>): Promise<void> {
+    return this.#sendInternal<void>(type, data, false);
+  }
+
+  /**
+   * Send a request and wait for ack + response.
+   * Returns a promise that resolves with the response data or rejects on error/timeout.
+   */
+  request<T = void>(type: string, data: Record<string, unknown>): Promise<T> {
+    return this.#sendInternal<T>(type, data, true);
+  }
+
+  /**
+   * Clean up pending requests
+   */
+  close(): void {
+    for (const pending of this.#pendingRequests.values()) {
+      clearTimeout(pending.ackTimeout);
+    }
+    this.#pendingRequests.clear();
+  }
+}

web/src/service-worker/broadcast-channel.ts

@@ -1,25 +0,0 @@
-import { handleCancel, handlePreload } from './request';
-
-export const installBroadcastChannelListener = () => {
-  const broadcast = new BroadcastChannel('immich');
-  // eslint-disable-next-line  unicorn/prefer-add-event-listener
-  broadcast.onmessage = (event) => {
-    if (!event.data) {
-      return;
-    }
-
-    const url = new URL(event.data.url, event.origin);
-
-    switch (event.data.type) {
-      case 'preload': {
-        handlePreload(url);
-        break;
-      }
-
-      case 'cancel': {
-        handleCancel(url);
-        break;
-      }
-    }
-  };
-};

web/src/service-worker/cache.ts

@@ -1,42 +0,0 @@
-import { version } from '$service-worker';
-
-const CACHE = `cache-${version}`;
-
-let _cache: Cache | undefined;
-const getCache = async () => {
-  if (_cache) {
-    return _cache;
-  }
-  _cache = await caches.open(CACHE);
-  return _cache;
-};
-
-export const get = async (key: string) => {
-  const cache = await getCache();
-  if (!cache) {
-    return;
-  }
-
-  return cache.match(key);
-};
-
-export const put = async (key: string, response: Response) => {
-  if (response.status !== 200) {
-    return;
-  }
-
-  const cache = await getCache();
-  if (!cache) {
-    return;
-  }
-
-  cache.put(key, response.clone());
-};
-
-export const prune = async () => {
-  for (const key of await caches.keys()) {
-    if (key !== CACHE) {
-      await caches.delete(key);
-    }
-  }
-};

web/src/service-worker/index.ts

@@ -2,9 +2,8 @@
 /// <reference no-default-lib="true"/>
 /// <reference lib="esnext" />
 /// <reference lib="webworker" />
-import { installBroadcastChannelListener } from './broadcast-channel';
-import { prune } from './cache';
-import { handleRequest } from './request';
+import { installMessageListener } from './messaging';
+import { handleFetch as handleAssetFetch } from './request';
 
 const ASSET_REQUEST_REGEX = /^\/api\/assets\/[a-f0-9-]+\/(original|thumbnail)/;
 
@@ -12,7 +11,6 @@ const sw = globalThis as unknown as ServiceWorkerGlobalScope;
 
 const handleActivate = (event: ExtendableEvent) => {
   event.waitUntil(sw.clients.claim());
-  event.waitUntil(prune());
 };
 
 const handleInstall = (event: ExtendableEvent) => {
@@ -28,7 +26,7 @@ const handleFetch = (event: FetchEvent): void => {
   // Cache requests for thumbnails
   const url = new URL(event.request.url);
   if (url.origin === self.location.origin && ASSET_REQUEST_REGEX.test(url.pathname)) {
-    event.respondWith(handleRequest(event.request));
+    event.respondWith(handleAssetFetch(event.request));
     return;
   }
 };
@@ -36,4 +34,4 @@ const handleFetch = (event: FetchEvent): void => {
 sw.addEventListener('install', handleInstall, { passive: true });
 sw.addEventListener('activate', handleActivate, { passive: true });
 sw.addEventListener('fetch', handleFetch, { passive: true });
-installBroadcastChannelListener();
+installMessageListener();

web/src/service-worker/messaging.ts

@@ -0,0 +1,60 @@
+import { handleCancel, handlePrepare } from './request';
+
+const sw = globalThis as unknown as ServiceWorkerGlobalScope;
+
+/**
+ * Send acknowledgment for a request
+ */
+function sendAck(client: Client, requestId: string) {
+  client.postMessage({
+    type: 'ack',
+    requestId,
+  });
+}
+
+/**
+ * Handle 'prepare' request: prepare SW to track this request for cancelation
+ */
+const handlePrepareRequest = (client: Client, url: URL, requestId: string) => {
+  sendAck(client, requestId);
+  handlePrepare(url);
+};
+
+/**
+ * Handle 'cancel' request: cancel a pending request
+ */
+const handleCancelRequest = (client: Client, url: URL, requestId: string) => {
+  sendAck(client, requestId);
+  handleCancel(url);
+};
+
+export const installMessageListener = () => {
+  sw.addEventListener('message', (event) => {
+    if (!event.data?.requestId) {
+      return;
+    }
+
+    const requestId = event.data.requestId;
+    const url = event.data.url ? new URL(event.data.url, self.location.origin) : undefined;
+    if (!url) {
+      return;
+    }
+
+    const client = event.source as Client;
+    if (!client) {
+      return;
+    }
+
+    switch (event.data.type) {
+      case 'prepare': {
+        handlePrepareRequest(client, url, requestId);
+        break;
+      }
+
+      case 'cancel': {
+        handleCancelRequest(client, url, requestId);
+        break;
+      }
+    }
+  });
+};

web/src/service-worker/request.ts

@@ -1,73 +1,124 @@
-import { get, put } from './cache';
+type PendingRequest = {
+  controller: AbortController;
+  promise: Promise<Response>;
+  canceled: boolean;
+  canceledAt?: number; // Timestamp when cancellation occurred
+  fetchStartedAt?: number; // Timestamp when fetch body)
+};
 
-const pendingRequests = new Map<string, AbortController>();
+const pendingRequests = new Map<string, PendingRequest>();
 
-const isURL = (request: URL | RequestInfo): request is URL => (request as URL).href !== undefined;
-const isRequest = (request: RequestInfo): request is Request => (request as Request).url !== undefined;
+const getRequestKey = (request: URL | Request): string => (request instanceof URL ? request.href : request.url);
 
-const assertResponse = (response: Response) => {
-  if (!(response instanceof Response)) {
-    throw new TypeError('Fetch did not return a valid Response object');
+const CANCELED_MESSAGE = 'Canceled - this is normal';
+
+/**
+ * Clean up old requests after a timeout
+ */
+const CANCELATION_EXPIRED_TIMEOUT_MS = 60_000;
+const FETCH_EXPIRED_TIMEOUT_MS = 60_000;
+
+const cleanupOldRequests = () => {
+  const now = Date.now();
+  const keysToDelete: string[] = [];
+
+  for (const [key, request] of pendingRequests.entries()) {
+    if (request.canceled && request.canceledAt) {
+      const age = now - request.canceledAt;
+      if (age > CANCELATION_EXPIRED_TIMEOUT_MS) {
+        keysToDelete.push(key);
+      }
+      continue;
+    }
+
+    // Clean up completed requests after 5s (allows time for potential cancellations)
+    if (request.fetchStartedAt) {
+      const age = now - request.fetchStartedAt;
+      if (age > FETCH_EXPIRED_TIMEOUT_MS) {
+        keysToDelete.push(key);
+      }
+    }
+  }
+
+  for (const key of keysToDelete) {
+    pendingRequests.delete(key);
   }
 };
 
-const getCacheKey = (request: URL | Request) => {
-  if (isURL(request)) {
-    return request.toString();
-  }
-
-  if (isRequest(request)) {
-    return request.url;
-  }
-
-  throw new Error(`Invalid request: ${request}`);
+/**
+ * Get existing request and cleanup old requests
+ */
+const getExisting = (requestKey: string): PendingRequest | undefined => {
+  cleanupOldRequests();
+  return pendingRequests.get(requestKey);
 };
 
-export const handlePreload = async (request: URL | Request) => {
-  try {
-    return await handleRequest(request);
-  } catch (error) {
-    console.error(`Preload failed: ${error}`);
+// Mark this URL as prepared - actual fetch will happen when handleFetch is called
+export const handlePrepare = async (request: URL | Request) => {
+  const requestKey = getRequestKey(request);
+  const existing = getExisting(requestKey);
+
+  if (existing?.canceled) {
+    // Prepare overrides cancel - reset the canceled request
+    pendingRequests.delete(requestKey);
   }
 };
 
-export const handleRequest = async (request: URL | Request) => {
-  const cacheKey = getCacheKey(request);
-  const cachedResponse = await get(cacheKey);
-  if (cachedResponse) {
-    return cachedResponse;
+export const handleFetch = (request: URL | Request): Promise<Response> => {
+  const requestKey = getRequestKey(request);
+  const existing = getExisting(requestKey);
+
+  if (existing) {
+    if (existing.canceled) {
+      return Promise.resolve(new Response(undefined, { status: 204 }));
+    }
+    // Clone the response from the shared promise to avoid "Response is disturbed or locked" errors
+    return existing.promise.then((response) => response.clone());
   }
 
-  try {
-    const cancelToken = new AbortController();
-    pendingRequests.set(cacheKey, cancelToken);
-    const response = await fetch(request, { signal: cancelToken.signal });
-
-    assertResponse(response);
-    put(cacheKey, response);
-
-    return response;
-  } catch (error) {
-    if (error.name === 'AbortError') {
+  // No existing request, create a new one
+  const controller = new AbortController();
+  const promise = fetch(request, { signal: controller.signal }).catch((error: unknown) => {
+    const standardError = error instanceof Error ? error : new Error(String(error));
+    if (standardError.name === 'AbortError' || standardError.message === CANCELED_MESSAGE) {
       // dummy response avoids network errors in the console for these requests
       return new Response(undefined, { status: 204 });
     }
+    throw standardError;
+  });
 
-    console.log('Not an abort error', error);
+  pendingRequests.set(requestKey, {
+    controller,
+    promise,
+    canceled: false,
+    fetchStartedAt: Date.now(),
+  });
 
-    throw error;
-  } finally {
-    pendingRequests.delete(cacheKey);
-  }
+  // Clone for the first caller, so the promise retains the unconsumed original response for future callers
+  return promise.then((response) => response.clone());
 };
 
 export const handleCancel = (url: URL) => {
-  const cacheKey = getCacheKey(url);
-  const pendingRequest = pendingRequests.get(cacheKey);
-  if (!pendingRequest) {
-    return;
-  }
+  const requestKey = getRequestKey(url);
 
-  pendingRequest.abort();
-  pendingRequests.delete(cacheKey);
+  const pendingRequest = pendingRequests.get(requestKey);
+  if (pendingRequest) {
+    // Mark existing request as canceled with timestamp
+    pendingRequest.canceled = true;
+    pendingRequest.canceledAt = Date.now();
+    pendingRequest.controller.abort(CANCELED_MESSAGE);
+  } else {
+    // No pending request - create a pre-canceled placeholder
+    const controller = new AbortController();
+    controller.abort(CANCELED_MESSAGE);
+
+    const preCanceledRequest: PendingRequest = {
+      controller,
+      promise: Promise.resolve(new Response(undefined, { status: 204 })),
+      canceled: true,
+      canceledAt: Date.now(),
+    };
+
+    pendingRequests.set(requestKey, preCanceledRequest);
+  }
 };