feat: adaptive progressive image loading for photo viewer (#26636)

* feat(web): adaptive progressive image loading for photo viewer

Replace ImageManager with a new AdaptiveImageLoader that progressively
loads images through quality tiers (thumbnail → preview → original).

New components and utilities:
- AdaptiveImage: layered image renderer with thumbhash, thumbnail,
  preview, and original layers with visibility managed by load state
- AdaptiveImageLoader: state machine driving the quality progression
  with per-quality callbacks and error handling
- ImageLayer/Image: low-level image elements with load/error lifecycle
- PreloadManager: preloads adjacent assets for instant navigation
- AlphaBackground/DelayedLoadingSpinner: loading state UI

Zoom is handled via a derived CSS transform applied to the content
wrapper in AdaptiveImage, with the zoom library (zoomTarget: null)
only tracking state without manipulating the DOM directly.

Also adds scaleToCover to container-utils and getAssetUrls to utils.

* fix: don't partially render images in firefox

* add passive loading indicator to asset-viewer

---------

Co-authored-by: Alex <alex.tran1502@gmail.com>

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

@@ -1,99 +0,0 @@
-import { imageManager } from '$lib/managers/ImageManager.svelte';
-import { getAssetMediaUrl } from '$lib/utils';
-import { cancelImageUrl } from '$lib/utils/sw-messaging';
-import { AssetMediaSize } from '@immich/sdk';
-import { assetFactory } from '@test-data/factories/asset-factory';
-
-vi.mock('$lib/utils/sw-messaging', () => ({
-  cancelImageUrl: vi.fn(),
-}));
-
-vi.mock('$lib/utils', () => ({
-  getAssetMediaUrl: vi.fn(),
-}));
-
-describe('ImageManager', () => {
-  beforeEach(() => {
-    vi.clearAllMocks();
-  });
-
-  describe('preload', () => {
-    it('creates an Image with the correct URL', () => {
-      vi.mocked(getAssetMediaUrl).mockReturnValue('/api/assets/123/media');
-      const asset = assetFactory.build();
-
-      imageManager.preload(asset);
-
-      expect(getAssetMediaUrl).toHaveBeenCalledWith({
-        id: asset.id,
-        size: AssetMediaSize.Preview,
-        cacheKey: asset.thumbhash,
-      });
-    });
-
-    it('does nothing for undefined asset', () => {
-      imageManager.preload(undefined);
-      expect(getAssetMediaUrl).not.toHaveBeenCalled();
-    });
-
-    it('does nothing when getAssetMediaUrl returns falsy', () => {
-      vi.mocked(getAssetMediaUrl).mockReturnValue('');
-      const asset = assetFactory.build();
-
-      imageManager.preload(asset);
-
-      expect(getAssetMediaUrl).toHaveBeenCalled();
-    });
-
-    it('uses the specified size', () => {
-      vi.mocked(getAssetMediaUrl).mockReturnValue('/api/assets/123/media');
-      const asset = assetFactory.build();
-
-      imageManager.preload(asset, AssetMediaSize.Thumbnail);
-
-      expect(getAssetMediaUrl).toHaveBeenCalledWith({
-        id: asset.id,
-        size: AssetMediaSize.Thumbnail,
-        cacheKey: asset.thumbhash,
-      });
-    });
-  });
-
-  describe('cancel', () => {
-    it('calls cancelImageUrl with the correct URL', () => {
-      vi.mocked(getAssetMediaUrl).mockReturnValue('/api/assets/123/media');
-      const asset = assetFactory.build();
-
-      imageManager.cancel(asset, AssetMediaSize.Preview);
-
-      expect(cancelImageUrl).toHaveBeenCalledWith('/api/assets/123/media');
-    });
-
-    it('does nothing for undefined asset', () => {
-      imageManager.cancel(undefined);
-      expect(getAssetMediaUrl).not.toHaveBeenCalled();
-      expect(cancelImageUrl).not.toHaveBeenCalled();
-    });
-
-    it('cancels all sizes when size is "all"', () => {
-      vi.mocked(getAssetMediaUrl).mockImplementation(({ size }) => `/api/assets/123/${size}`);
-      const asset = assetFactory.build();
-
-      imageManager.cancel(asset, 'all');
-
-      expect(getAssetMediaUrl).toHaveBeenCalledTimes(Object.values(AssetMediaSize).length);
-      for (const size of Object.values(AssetMediaSize)) {
-        expect(cancelImageUrl).toHaveBeenCalledWith(`/api/assets/123/${size}`);
-      }
-    });
-
-    it('does not call cancelImageUrl when URL is falsy', () => {
-      vi.mocked(getAssetMediaUrl).mockReturnValue('');
-      const asset = assetFactory.build();
-
-      imageManager.cancel(asset, AssetMediaSize.Preview);
-
-      expect(cancelImageUrl).not.toHaveBeenCalled();
-    });
-  });
-});

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

@@ -1,37 +0,0 @@
-import { getAssetMediaUrl } from '$lib/utils';
-import { cancelImageUrl } from '$lib/utils/sw-messaging';
-import { AssetMediaSize, type AssetResponseDto } from '@immich/sdk';
-
-type AllAssetMediaSize = AssetMediaSize | 'all';
-
-class ImageManager {
-  preload(asset: AssetResponseDto | undefined, size: AssetMediaSize = AssetMediaSize.Preview) {
-    if (!asset) {
-      return;
-    }
-
-    const url = getAssetMediaUrl({ id: asset.id, size, cacheKey: asset.thumbhash });
-    if (!url) {
-      return;
-    }
-
-    const img = new Image();
-    img.src = url;
-  }
-
-  cancel(asset: AssetResponseDto | undefined, size: AllAssetMediaSize = AssetMediaSize.Preview) {
-    if (!asset) {
-      return;
-    }
-
-    const sizes = size === 'all' ? Object.values(AssetMediaSize) : [size];
-    for (const size of sizes) {
-      const url = getAssetMediaUrl({ id: asset.id, size, cacheKey: asset.thumbhash });
-      if (url) {
-        cancelImageUrl(url);
-      }
-    }
-  }
-}
-
-export const imageManager = new ImageManager();

web/src/lib/managers/asset-viewer-manager.svelte.ts

@@ -1,3 +1,4 @@
+import type { ImageLoaderStatus } from '$lib/utils/adaptive-image-loader.svelte';
 import { canCopyImageToClipboard } from '$lib/utils/asset-utils';
 import { BaseEventManager } from '$lib/utils/base-event-manager.svelte';
 import { PersistedLocalStorage } from '$lib/utils/persisted';
@@ -25,10 +26,24 @@ export class AssetViewerManager extends BaseEventManager<Events> {
   #animationFrameId: number | null = null;
 
   imgRef = $state<HTMLImageElement | undefined>();
+  imageLoaderStatus = $state<ImageLoaderStatus | undefined>();
+  #isImageLoading = $derived.by(() => {
+    const quality = this.imageLoaderStatus?.quality;
+    if (!quality) {
+      return false;
+    }
+    const previewOrOriginalReady = quality.preview === 'success' || quality.original === 'success';
+    const loadingOriginal = this.zoom > 1 && quality.original !== 'success';
+    return !previewOrOriginalReady || loadingOriginal;
+  });
   isShowActivityPanel = $state(false);
   isPlayingMotionPhoto = $state(false);
   isShowEditor = $state(false);
 
+  get isImageLoading() {
+    return this.#isImageLoading;
+  }
+
   get isShowDetailPanel() {
     return isShowDetailPanel.current;
   }