feat(web): image-relative overlays with zoom support for faces and OCR

Split out from #26636 (adaptive image loading). Leverages the
ContentMetrics extraction from #26310.

Moves face bounding boxes and OCR overlays from viewport-relative
to image-relative coordinates.

New features: zoom with face editor open, zoom with OCR boxes
visible, accurate face hover hit-testing at any zoom level.

Bug fixes: face tagging on stacked assets, faces loading when browsing
stacks, face editor auto-close on last face deletion, zoomTarget was
null, disablePointer option name mismatch.

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

@@ -1,14 +1,13 @@
 import { AssetMediaResponseDto, LoginResponseDto } from '@immich/sdk';
-import { Page, expect, test } from '@playwright/test';
+import { expect, test } from '@playwright/test';
+import type { Socket } from 'socket.io-client';
 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;
   let rawAsset: AssetMediaResponseDto;
+  let websocket: Socket;
 
   test.beforeAll(async () => {
     utils.initSdk();
@@ -16,6 +15,11 @@ test.describe('Photo Viewer', () => {
     admin = await utils.adminSetup();
     asset = await utils.createAsset(admin.accessToken);
     rawAsset = await utils.createAsset(admin.accessToken, { assetData: { filename: 'test.arw' } });
+    websocket = await utils.connectWebsocket(admin.accessToken);
+  });
+
+  test.afterAll(() => {
+    utils.disconnectWebsocket(websocket);
   });
 
   test.beforeEach(async ({ context, page }) => {
@@ -26,31 +30,51 @@ 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();
+    const preview = page.getByTestId('preview').filter({ visible: true });
-    expect(box).toBeTruthy();
+    await expect(preview).toHaveAttribute('src', /.+/);
-    const { x, y, width, height } = box!;
+
-    await page.mouse.move(x + width / 2, y + height / 2);
+    const originalResponse = page.waitForResponse((response) => response.url().includes('/original'));
+
+    const { width, height } = page.viewportSize()!;
+    await page.mouse.move(width / 2, height / 2);
     await page.mouse.wheel(0, -1);
-    await expect.poll(async () => await imageLocator(page).getAttribute('src')).toContain('original');
+
+    await originalResponse;
+
+    const original = page.getByTestId('original').filter({ visible: true });
+    await expect(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();
+    const preview = page.getByTestId('preview').filter({ visible: true });
-    expect(box).toBeTruthy();
+    await expect(preview).toHaveAttribute('src', /.+/);
-    const { x, y, width, height } = box!;
+
-    await page.mouse.move(x + width / 2, y + height / 2);
+    const fullsizeResponse = page.waitForResponse((response) => response.url().includes('fullsize'));
+
+    const { width, height } = page.viewportSize()!;
+    await page.mouse.move(width / 2, height / 2);
     await page.mouse.wheel(0, -1);
-    await expect.poll(async () => await imageLocator(page).getAttribute('src')).toContain('fullsize');
+
+    await fullsizeResponse;
+
+    const original = page.getByTestId('original').filter({ visible: true });
+    await expect(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');
+    const preview = page.getByTestId('preview').filter({ visible: true });
+    await expect(preview).toHaveAttribute('src', /.+/);
+    const initialSrc = await preview.getAttribute('src');
+
+    const websocketEvent = utils.waitForWebsocketEvent({ event: 'assetUpdate', id: asset.id });
     await utils.replaceAsset(admin.accessToken, asset.id);
-    await expect.poll(async () => await imageLocator(page).getAttribute('src')).not.toBe(initialSrc);
+    await websocketEvent;
+
+    await expect(preview).not.toHaveAttribute('src', initialSrc!);
   });
 });

e2e/src/ui/generators/timeline/rest-response.ts

@@ -284,7 +284,11 @@ const createDefaultOwner = (ownerId: string) => {
  * Convert a TimelineAssetConfig to a full AssetResponseDto
  * This matches the response from GET /api/assets/:id
  */
-export function toAssetResponseDto(asset: MockTimelineAsset, owner?: UserResponseDto): AssetResponseDto {
+export function toAssetResponseDto(
+  asset: MockTimelineAsset,
+  owner?: UserResponseDto,
+  overrides?: Partial<Pick<AssetResponseDto, 'people' | 'unassignedFaces'>>,
+): AssetResponseDto {
   const now = new Date().toISOString();
 
   // Default owner if not provided
@@ -338,8 +342,8 @@ export function toAssetResponseDto(asset: MockTimelineAsset, owner?: UserRespons
     exifInfo,
     livePhotoVideoId: asset.livePhotoVideoId,
     tags: [],
-    people: [],
+    people: overrides?.people ?? [],
-    unassignedFaces: [],
+    unassignedFaces: overrides?.unassignedFaces ?? [],
     stack: asset.stack,
     isOffline: false,
     hasMetadata: true,

e2e/src/ui/mock-network/face-editor-network.ts

@@ -1,3 +1,9 @@
+import {
+  type AssetFaceResponseDto,
+  type AssetFaceWithoutPersonResponseDto,
+  type AssetResponseDto,
+  type PersonWithFacesResponseDto,
+} from '@immich/sdk';
 import { BrowserContext } from '@playwright/test';
 import { randomThumbnail } from 'src/ui/generators/timeline';
 
@@ -125,3 +131,117 @@ export const setupFaceEditorMockApiRoutes = async (
     });
   });
 };
+
+export type MockFaceSpec = {
+  personId: string;
+  personName: string;
+  faceId: string;
+  boundingBoxX1: number;
+  boundingBoxY1: number;
+  boundingBoxX2: number;
+  boundingBoxY2: number;
+};
+
+export const createMockFaceData = (
+  faceSpecs: MockFaceSpec[],
+  imageWidth: number,
+  imageHeight: number,
+): { people: PersonWithFacesResponseDto[]; unassignedFaces: AssetFaceWithoutPersonResponseDto[] } => {
+  const people: PersonWithFacesResponseDto[] = faceSpecs.map((spec) => ({
+    id: spec.personId,
+    name: spec.personName,
+    birthDate: null,
+    isHidden: false,
+    thumbnailPath: `/upload/thumbs/${spec.personId}.jpeg`,
+    updatedAt: new Date().toISOString(),
+    faces: [
+      {
+        id: spec.faceId,
+        imageWidth,
+        imageHeight,
+        boundingBoxX1: spec.boundingBoxX1,
+        boundingBoxY1: spec.boundingBoxY1,
+        boundingBoxX2: spec.boundingBoxX2,
+        boundingBoxY2: spec.boundingBoxY2,
+      },
+    ],
+  }));
+
+  return { people, unassignedFaces: [] };
+};
+
+export const setupFaceOverlayMockApiRoutes = async (
+  context: BrowserContext,
+  assetDto: AssetResponseDto,
+  faceSpecs: MockFaceSpec[],
+) => {
+  const faceResponseMap = new Map<string, AssetFaceResponseDto>();
+  for (const spec of faceSpecs) {
+    faceResponseMap.set(spec.faceId, {
+      id: spec.faceId,
+      imageWidth: assetDto.width ?? 3000,
+      imageHeight: assetDto.height ?? 4000,
+      boundingBoxX1: spec.boundingBoxX1,
+      boundingBoxY1: spec.boundingBoxY1,
+      boundingBoxX2: spec.boundingBoxX2,
+      boundingBoxY2: spec.boundingBoxY2,
+      person: {
+        id: spec.personId,
+        name: spec.personName,
+        birthDate: null,
+        isHidden: false,
+        thumbnailPath: `/upload/thumbs/${spec.personId}.jpeg`,
+        updatedAt: new Date().toISOString(),
+      },
+    });
+  }
+
+  await context.route(`**/api/assets/${assetDto.id}`, async (route, request) => {
+    if (request.method() !== 'GET') {
+      return route.fallback();
+    }
+    return route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      json: assetDto,
+    });
+  });
+
+  await context.route(`**/api/faces?id=${assetDto.id}`, async (route, request) => {
+    if (request.method() !== 'GET') {
+      return route.fallback();
+    }
+    return route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      json: [...faceResponseMap.values()],
+    });
+  });
+
+  await context.route('**/api/faces/*', async (route, request) => {
+    if (request.method() !== 'DELETE') {
+      return route.fallback();
+    }
+    const url = new URL(request.url());
+    const faceId = url.pathname.split('/').at(-1);
+    if (faceId) {
+      faceResponseMap.delete(faceId);
+    }
+    return route.fulfill({
+      status: 200,
+      contentType: 'text/plain',
+      body: 'OK',
+    });
+  });
+
+  await context.route('**/api/people/*/thumbnail', async (route) => {
+    if (!route.request().serviceWorker()) {
+      return route.continue();
+    }
+    return route.fulfill({
+      status: 200,
+      headers: { 'content-type': 'image/jpeg' },
+      body: await randomThumbnail('person-thumb', 1),
+    });
+  });
+};

e2e/src/ui/mock-network/ocr-network.ts

@@ -0,0 +1,55 @@
+import { faker } from '@faker-js/faker';
+import type { AssetOcrResponseDto } from '@immich/sdk';
+import { BrowserContext } from '@playwright/test';
+
+export type MockOcrBox = {
+  text: string;
+  x1: number;
+  y1: number;
+  x2: number;
+  y2: number;
+  x3: number;
+  y3: number;
+  x4: number;
+  y4: number;
+};
+
+export const createMockOcrData = (assetId: string, boxes: MockOcrBox[]): AssetOcrResponseDto[] => {
+  return boxes.map((box) => ({
+    id: faker.string.uuid(),
+    assetId,
+    x1: box.x1,
+    y1: box.y1,
+    x2: box.x2,
+    y2: box.y2,
+    x3: box.x3,
+    y3: box.y3,
+    x4: box.x4,
+    y4: box.y4,
+    boxScore: 0.95,
+    textScore: 0.9,
+    text: box.text,
+  }));
+};
+
+export const setupOcrMockApiRoutes = async (
+  context: BrowserContext,
+  ocrDataByAssetId: Map<string, AssetOcrResponseDto[]>,
+) => {
+  await context.route('**/assets/*/ocr', async (route, request) => {
+    if (request.method() !== 'GET') {
+      return route.fallback();
+    }
+    const url = new URL(request.url());
+    const segments = url.pathname.split('/');
+    const assetIdIndex = segments.indexOf('assets') + 1;
+    const assetId = segments[assetIdIndex];
+
+    const ocrData = ocrDataByAssetId.get(assetId) ?? [];
+    return route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      json: ocrData,
+    });
+  });
+};

e2e/src/ui/specs/asset-viewer/broken-asset.e2e-spec.ts

@@ -64,7 +64,9 @@ test.describe('broken-asset responsiveness', () => {
 
   test('broken asset in main viewer shows icon and uses text-base', async ({ context, page }) => {
     await context.route(
-      (url) => url.pathname.includes(`/api/assets/${fixture.primaryAsset.id}/thumbnail`),
+      (url) =>
+        url.pathname.includes(`/api/assets/${fixture.primaryAsset.id}/thumbnail`) ||
+        url.pathname.includes(`/api/assets/${fixture.primaryAsset.id}/original`),
       async (route) => {
         return route.fulfill({ status: 404 });
       },
@@ -73,7 +75,7 @@ test.describe('broken-asset responsiveness', () => {
     await page.goto(`/photos/${fixture.primaryAsset.id}`);
     await page.waitForSelector('#immich-asset-viewer');
 
-    const viewerBrokenAsset = page.locator('#immich-asset-viewer #broken-asset [data-broken-asset]');
+    const viewerBrokenAsset = page.locator('[data-viewer-content] [data-broken-asset]').first();
     await expect(viewerBrokenAsset).toBeVisible();
 
     await expect(viewerBrokenAsset.locator('svg')).toBeVisible();

e2e/src/ui/specs/asset-viewer/face-overlay.e2e-spec.ts

@@ -0,0 +1,196 @@
+import { expect, test } from '@playwright/test';
+import { toAssetResponseDto } from 'src/ui/generators/timeline';
+import {
+  createMockFaceData,
+  createMockPeople,
+  type MockFaceSpec,
+  setupFaceEditorMockApiRoutes,
+  setupFaceOverlayMockApiRoutes,
+} from 'src/ui/mock-network/face-editor-network';
+import { assetViewerUtils } from '../timeline/utils';
+import { ensureDetailPanelVisible, setupAssetViewerFixture } from './utils';
+
+test.describe.configure({ mode: 'parallel' });
+
+const FACE_SPECS: MockFaceSpec[] = [
+  {
+    personId: 'person-alice',
+    personName: 'Alice Johnson',
+    faceId: 'face-alice',
+    boundingBoxX1: 1000,
+    boundingBoxY1: 500,
+    boundingBoxX2: 1500,
+    boundingBoxY2: 1200,
+  },
+  {
+    personId: 'person-bob',
+    personName: 'Bob Smith',
+    faceId: 'face-bob',
+    boundingBoxX1: 2000,
+    boundingBoxY1: 800,
+    boundingBoxX2: 2400,
+    boundingBoxY2: 1600,
+  },
+];
+
+test.describe('face overlay bounding boxes', () => {
+  const fixture = setupAssetViewerFixture(901);
+  const mockPeople = createMockPeople(4);
+
+  test.beforeEach(async ({ context }) => {
+    const faceData = createMockFaceData(
+      FACE_SPECS,
+      fixture.primaryAssetDto.width ?? 3000,
+      fixture.primaryAssetDto.height ?? 4000,
+    );
+    const assetDtoWithFaces = toAssetResponseDto(fixture.primaryAsset, undefined, faceData);
+    await setupFaceOverlayMockApiRoutes(context, assetDtoWithFaces, FACE_SPECS);
+    await setupFaceEditorMockApiRoutes(context, mockPeople, { requests: [] });
+  });
+
+  test('face overlay divs render with correct aria labels', async ({ page }) => {
+    await page.goto(`/photos/${fixture.primaryAsset.id}`);
+    await assetViewerUtils.waitForViewerLoad(page, fixture.primaryAsset);
+
+    const aliceOverlay = page.getByLabel('Person: Alice Johnson');
+    const bobOverlay = page.getByLabel('Person: Bob Smith');
+
+    await expect(aliceOverlay).toBeVisible();
+    await expect(bobOverlay).toBeVisible();
+  });
+
+  test('face overlay shows border on hover', async ({ page }) => {
+    await page.goto(`/photos/${fixture.primaryAsset.id}`);
+    await assetViewerUtils.waitForViewerLoad(page, fixture.primaryAsset);
+
+    const aliceOverlay = page.getByLabel('Person: Alice Johnson');
+    await expect(aliceOverlay).toBeVisible();
+
+    await expect(aliceOverlay).not.toHaveClass(/border-solid/);
+
+    await aliceOverlay.hover();
+    await expect(aliceOverlay).toHaveClass(/border-solid/);
+    await expect(aliceOverlay).toHaveClass(/border-white/);
+    await expect(aliceOverlay).toHaveClass(/border-3/);
+  });
+
+  test('face name tooltip appears on hover', async ({ page }) => {
+    await page.goto(`/photos/${fixture.primaryAsset.id}`);
+    await assetViewerUtils.waitForViewerLoad(page, fixture.primaryAsset);
+
+    const aliceOverlay = page.getByLabel('Person: Alice Johnson');
+    await expect(aliceOverlay).toBeVisible();
+
+    await aliceOverlay.hover();
+
+    const nameTooltip = aliceOverlay.locator('div', { hasText: 'Alice Johnson' });
+    await expect(nameTooltip).toBeVisible();
+  });
+
+  test('face overlays hidden in face edit mode', async ({ page }) => {
+    await page.goto(`/photos/${fixture.primaryAsset.id}`);
+    await assetViewerUtils.waitForViewerLoad(page, fixture.primaryAsset);
+
+    const aliceOverlay = page.getByLabel('Person: Alice Johnson');
+    await expect(aliceOverlay).toBeVisible();
+
+    await ensureDetailPanelVisible(page);
+    await page.getByLabel('Tag people').click();
+    await page.locator('#face-selector').waitFor({ state: 'visible' });
+
+    await expect(aliceOverlay).toBeHidden();
+  });
+});
+
+test.describe('zoom and face editor interaction', () => {
+  const fixture = setupAssetViewerFixture(902);
+  const mockPeople = createMockPeople(4);
+
+  test.beforeEach(async ({ context }) => {
+    const faceData = createMockFaceData(
+      FACE_SPECS,
+      fixture.primaryAssetDto.width ?? 3000,
+      fixture.primaryAssetDto.height ?? 4000,
+    );
+    const assetDtoWithFaces = toAssetResponseDto(fixture.primaryAsset, undefined, faceData);
+    await setupFaceOverlayMockApiRoutes(context, assetDtoWithFaces, FACE_SPECS);
+    await setupFaceEditorMockApiRoutes(context, mockPeople, { requests: [] });
+  });
+
+  test('zoom is preserved when entering face edit mode', async ({ page }) => {
+    await page.goto(`/photos/${fixture.primaryAsset.id}`);
+    await assetViewerUtils.waitForViewerLoad(page, fixture.primaryAsset);
+
+    const { width, height } = page.viewportSize()!;
+    await page.mouse.move(width / 2, height / 2);
+    await page.mouse.wheel(0, -1);
+    await page.waitForTimeout(300);
+
+    const zoomedTransform = await page.locator('[data-viewer-content] img[draggable="false"]').evaluate((element) => {
+      return getComputedStyle(element.closest('[style*="transform"]') ?? element).transform;
+    });
+    const isZoomed = zoomedTransform !== 'none' && zoomedTransform !== '';
+
+    await ensureDetailPanelVisible(page);
+    await page.getByLabel('Tag people').click();
+    await page.locator('#face-selector').waitFor({ state: 'visible' });
+
+    await expect(page.locator('#face-editor')).toBeVisible();
+
+    if (isZoomed) {
+      const afterTransform = await page.locator('[data-viewer-content] img[draggable="false"]').evaluate((element) => {
+        return getComputedStyle(element.closest('[style*="transform"]') ?? element).transform;
+      });
+      expect(afterTransform).not.toBe('none');
+    }
+  });
+});
+
+test.describe('face removal auto-close', () => {
+  const fixture = setupAssetViewerFixture(903);
+  const singleFaceSpec: MockFaceSpec[] = [
+    {
+      personId: 'person-solo',
+      personName: 'Solo Person',
+      faceId: 'face-solo',
+      boundingBoxX1: 1000,
+      boundingBoxY1: 500,
+      boundingBoxX2: 1500,
+      boundingBoxY2: 1200,
+    },
+  ];
+
+  test.beforeEach(async ({ context }) => {
+    const faceData = createMockFaceData(
+      singleFaceSpec,
+      fixture.primaryAssetDto.width ?? 3000,
+      fixture.primaryAssetDto.height ?? 4000,
+    );
+    const assetDtoWithFaces = toAssetResponseDto(fixture.primaryAsset, undefined, faceData);
+    await setupFaceOverlayMockApiRoutes(context, assetDtoWithFaces, singleFaceSpec);
+  });
+
+  test('person side panel closes when last face is removed', async ({ page }) => {
+    await page.goto(`/photos/${fixture.primaryAsset.id}`);
+    await assetViewerUtils.waitForViewerLoad(page, fixture.primaryAsset);
+
+    await ensureDetailPanelVisible(page);
+
+    const editPeopleButton = page.locator('#detail-panel').getByLabel('Edit people');
+    await expect(editPeopleButton).toBeVisible();
+    await editPeopleButton.click();
+
+    const personName = page.locator('text=Solo Person');
+    await expect(personName.first()).toBeVisible({ timeout: 5000 });
+
+    const deleteButton = page.getByLabel('Delete face');
+    await expect(deleteButton).toBeVisible();
+    await deleteButton.click();
+
+    const confirmButton = page.getByRole('button', { name: /confirm/i });
+    await expect(confirmButton).toBeVisible();
+    await confirmButton.click();
+
+    await expect(page.locator('text=Edit faces')).toBeHidden({ timeout: 5000 });
+  });
+});

e2e/src/ui/specs/asset-viewer/ocr.e2e-spec.ts

@@ -0,0 +1,152 @@
+import type { AssetOcrResponseDto, AssetResponseDto } from '@immich/sdk';
+import { expect, test } from '@playwright/test';
+import { toAssetResponseDto } from 'src/ui/generators/timeline';
+import {
+  createMockStack,
+  createMockStackAsset,
+  MockStack,
+  setupBrokenAssetMockApiRoutes,
+} from 'src/ui/mock-network/broken-asset-network';
+import { createMockOcrData, setupOcrMockApiRoutes } from 'src/ui/mock-network/ocr-network';
+import { assetViewerUtils } from '../timeline/utils';
+import { setupAssetViewerFixture } from './utils';
+
+test.describe.configure({ mode: 'parallel' });
+
+const PRIMARY_OCR_BOXES = [
+  { text: 'Hello World', x1: 0.1, y1: 0.1, x2: 0.4, y2: 0.1, x3: 0.4, y3: 0.15, x4: 0.1, y4: 0.15 },
+  { text: 'Immich Photo', x1: 0.2, y1: 0.3, x2: 0.6, y2: 0.3, x3: 0.6, y3: 0.36, x4: 0.2, y4: 0.36 },
+];
+
+const SECONDARY_OCR_BOXES = [
+  { text: 'Second Asset Text', x1: 0.15, y1: 0.2, x2: 0.55, y2: 0.2, x3: 0.55, y3: 0.26, x4: 0.15, y4: 0.26 },
+];
+
+test.describe('OCR bounding boxes', () => {
+  const fixture = setupAssetViewerFixture(920);
+
+  test.beforeEach(async ({ context }) => {
+    const primaryAssetDto = toAssetResponseDto(fixture.primaryAsset);
+    const ocrDataByAssetId = new Map<string, AssetOcrResponseDto[]>([
+      [primaryAssetDto.id, createMockOcrData(primaryAssetDto.id, PRIMARY_OCR_BOXES)],
+    ]);
+
+    await setupOcrMockApiRoutes(context, ocrDataByAssetId);
+  });
+
+  test('OCR bounding boxes appear when clicking OCR button', async ({ page }) => {
+    await page.goto(`/photos/${fixture.primaryAsset.id}`);
+    await assetViewerUtils.waitForViewerLoad(page, fixture.primaryAsset);
+
+    const ocrButton = page.getByLabel('Text recognition');
+    await expect(ocrButton).toBeVisible();
+    await ocrButton.click();
+
+    const ocrBoxes = page.locator('[data-viewer-content] .border-blue-500');
+    await expect(ocrBoxes).toHaveCount(2);
+
+    await expect(ocrBoxes.nth(0)).toContainText('Hello World');
+    await expect(ocrBoxes.nth(1)).toContainText('Immich Photo');
+  });
+
+  test('OCR bounding boxes toggle off on second click', async ({ page }) => {
+    await page.goto(`/photos/${fixture.primaryAsset.id}`);
+    await assetViewerUtils.waitForViewerLoad(page, fixture.primaryAsset);
+
+    const ocrButton = page.getByLabel('Text recognition');
+    await ocrButton.click();
+    await expect(page.locator('[data-viewer-content] .border-blue-500').first()).toBeVisible();
+
+    await ocrButton.click();
+    await expect(page.locator('[data-viewer-content] .border-blue-500')).toHaveCount(0);
+  });
+});
+
+test.describe('OCR with stacked assets', () => {
+  const fixture = setupAssetViewerFixture(921);
+  let mockStack: MockStack;
+  let primaryAssetDto: AssetResponseDto;
+  let secondAssetDto: AssetResponseDto;
+
+  test.beforeAll(async () => {
+    primaryAssetDto = toAssetResponseDto(fixture.primaryAsset);
+    secondAssetDto = createMockStackAsset(fixture.adminUserId);
+    secondAssetDto.originalFileName = 'second-ocr-asset.jpg';
+    mockStack = createMockStack(primaryAssetDto, [secondAssetDto], new Set());
+  });
+
+  test.beforeEach(async ({ context }) => {
+    await setupBrokenAssetMockApiRoutes(context, mockStack);
+
+    const ocrDataByAssetId = new Map<string, AssetOcrResponseDto[]>([
+      [primaryAssetDto.id, createMockOcrData(primaryAssetDto.id, PRIMARY_OCR_BOXES)],
+      [secondAssetDto.id, createMockOcrData(secondAssetDto.id, SECONDARY_OCR_BOXES)],
+    ]);
+
+    await setupOcrMockApiRoutes(context, ocrDataByAssetId);
+  });
+
+  test('different OCR boxes shown for different stacked assets', async ({ page }) => {
+    await page.goto(`/photos/${fixture.primaryAsset.id}`);
+    await assetViewerUtils.waitForViewerLoad(page, fixture.primaryAsset);
+
+    const ocrButton = page.getByLabel('Text recognition');
+    await expect(ocrButton).toBeVisible();
+    await ocrButton.click();
+
+    const ocrBoxes = page.locator('[data-viewer-content] .border-blue-500');
+    await expect(ocrBoxes).toHaveCount(2);
+    await expect(ocrBoxes.nth(0)).toContainText('Hello World');
+
+    const stackThumbnails = page.locator('#stack-slideshow [data-asset]');
+    await expect(stackThumbnails).toHaveCount(2);
+    await stackThumbnails.nth(1).click();
+
+    // refreshOcr() clears showOverlay when switching assets, so re-enable it
+    await expect(ocrBoxes).toHaveCount(0);
+    await expect(ocrButton).toBeVisible();
+    await ocrButton.click();
+
+    await expect(ocrBoxes).toHaveCount(1);
+    await expect(ocrBoxes.first()).toContainText('Second Asset Text');
+  });
+});
+
+test.describe('OCR boxes and zoom', () => {
+  const fixture = setupAssetViewerFixture(922);
+
+  test.beforeEach(async ({ context }) => {
+    const primaryAssetDto = toAssetResponseDto(fixture.primaryAsset);
+    const ocrDataByAssetId = new Map<string, AssetOcrResponseDto[]>([
+      [primaryAssetDto.id, createMockOcrData(primaryAssetDto.id, PRIMARY_OCR_BOXES)],
+    ]);
+
+    await setupOcrMockApiRoutes(context, ocrDataByAssetId);
+  });
+
+  test('OCR boxes scale with zoom', async ({ page }) => {
+    await page.goto(`/photos/${fixture.primaryAsset.id}`);
+    await assetViewerUtils.waitForViewerLoad(page, fixture.primaryAsset);
+
+    const ocrButton = page.getByLabel('Text recognition');
+    await expect(ocrButton).toBeVisible();
+    await ocrButton.click();
+
+    const ocrBox = page.locator('[data-viewer-content] .border-blue-500').first();
+    await expect(ocrBox).toBeVisible();
+
+    const initialBox = await ocrBox.boundingBox();
+    expect(initialBox).toBeTruthy();
+
+    const { width, height } = page.viewportSize()!;
+    await page.mouse.move(width / 2, height / 2);
+    await page.mouse.wheel(0, -3);
+    await page.waitForTimeout(500);
+
+    const zoomedBox = await ocrBox.boundingBox();
+    expect(zoomedBox).toBeTruthy();
+
+    expect(zoomedBox!.width).toBeGreaterThan(initialBox!.width);
+    expect(zoomedBox!.height).toBeGreaterThan(initialBox!.height);
+  });
+});

e2e/src/ui/specs/asset-viewer/stack-face-tag.e2e-spec.ts

@@ -0,0 +1,100 @@
+import { type AssetResponseDto } from '@immich/sdk';
+import { expect, test } from '@playwright/test';
+import { toAssetResponseDto } from 'src/ui/generators/timeline';
+import {
+  createMockStack,
+  createMockStackAsset,
+  MockStack,
+  setupBrokenAssetMockApiRoutes,
+} from 'src/ui/mock-network/broken-asset-network';
+import {
+  createMockPeople,
+  FaceCreateCapture,
+  MockPerson,
+  setupFaceEditorMockApiRoutes,
+} from 'src/ui/mock-network/face-editor-network';
+import { assetViewerUtils } from '../timeline/utils';
+import { ensureDetailPanelVisible, setupAssetViewerFixture } from './utils';
+
+test.describe.configure({ mode: 'parallel' });
+test.describe('stack face-tag selection preservation', () => {
+  const fixture = setupAssetViewerFixture(910);
+  let mockStack: MockStack;
+  let primaryAssetDto: AssetResponseDto;
+  let secondAssetDto: AssetResponseDto;
+  let mockPeople: MockPerson[];
+  let faceCreateCapture: FaceCreateCapture;
+
+  test.beforeAll(async () => {
+    primaryAssetDto = toAssetResponseDto(fixture.primaryAsset);
+    secondAssetDto = createMockStackAsset(fixture.adminUserId);
+    secondAssetDto.originalFileName = 'second-stacked-asset.jpg';
+    mockStack = createMockStack(primaryAssetDto, [secondAssetDto], new Set());
+    mockPeople = createMockPeople(3);
+  });
+
+  test.beforeEach(async ({ context }) => {
+    faceCreateCapture = { requests: [] };
+    await setupBrokenAssetMockApiRoutes(context, mockStack);
+    await setupFaceEditorMockApiRoutes(context, mockPeople, faceCreateCapture);
+  });
+
+  test('selected stacked asset is preserved after tagging a face', async ({ page }) => {
+    await page.goto(`/photos/${fixture.primaryAsset.id}`);
+    await assetViewerUtils.waitForViewerLoad(page, fixture.primaryAsset);
+
+    const stackSlideshow = page.locator('#stack-slideshow');
+    await expect(stackSlideshow).toBeVisible();
+
+    const stackThumbnails = stackSlideshow.locator('[data-asset]');
+    await expect(stackThumbnails).toHaveCount(2);
+
+    await stackThumbnails.nth(1).click();
+
+    await ensureDetailPanelVisible(page);
+    await expect(page.locator('#detail-panel')).toContainText('second-stacked-asset.jpg');
+
+    await page.getByLabel('Tag people').click();
+    await page.locator('#face-selector').waitFor({ state: 'visible' });
+
+    await page.locator('#face-selector').getByText(mockPeople[0].name).click();
+
+    const confirmButton = page.getByRole('button', { name: /confirm/i });
+    await expect(confirmButton).toBeVisible();
+    await confirmButton.click();
+
+    await expect(page.locator('#face-selector')).toBeHidden();
+
+    expect(faceCreateCapture.requests).toHaveLength(1);
+    expect(faceCreateCapture.requests[0].assetId).toBe(secondAssetDto.id);
+
+    await expect(page.locator('#detail-panel')).toContainText('second-stacked-asset.jpg');
+
+    const selectedThumbnail = stackSlideshow.locator(`[data-asset="${secondAssetDto.id}"]`);
+    await expect(selectedThumbnail).toBeVisible();
+  });
+
+  test('primary asset stays selected after tagging a face without switching', async ({ page }) => {
+    await page.goto(`/photos/${fixture.primaryAsset.id}`);
+    await assetViewerUtils.waitForViewerLoad(page, fixture.primaryAsset);
+
+    await ensureDetailPanelVisible(page);
+    await expect(page.locator('#detail-panel')).toContainText(primaryAssetDto.originalFileName);
+
+    await page.getByLabel('Tag people').click();
+    await page.locator('#face-selector').waitFor({ state: 'visible' });
+
+    await page.locator('#face-selector').getByText(mockPeople[0].name).click();
+
+    const confirmButton = page.getByRole('button', { name: /confirm/i });
+    await expect(confirmButton).toBeVisible();
+    await confirmButton.click();
+
+    await expect(page.locator('#face-selector')).toBeHidden();
+
+    expect(faceCreateCapture.requests).toHaveLength(1);
+    expect(faceCreateCapture.requests[0].assetId).toBe(primaryAssetDto.id);
+
+    await expect(page.locator('#detail-panel')).toContainText(primaryAssetDto.originalFileName);
+  });
+});

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

@@ -0,0 +1,25 @@
+import { cancelImageUrl } from '$lib/utils/sw-messaging';
+
+export function loadImage(src: string, onLoad: () => void, onError: () => void, onStart?: () => void) {
+  let destroyed = false;
+
+  const handleLoad = () => !destroyed && onLoad();
+  const handleError = () => !destroyed && onError();
+
+  const img = document.createElement('img');
+  img.addEventListener('load', handleLoad);
+  img.addEventListener('error', handleError);
+
+  onStart?.();
+  img.src = src;
+
+  return () => {
+    destroyed = true;
+    img.removeEventListener('load', handleLoad);
+    img.removeEventListener('error', handleError);
+    cancelImageUrl(src);
+    img.remove();
+  };
+}
+
+export type LoadImageFunction = typeof loadImage;

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

@@ -1,34 +1,42 @@
 import { assetViewerManager } from '$lib/managers/asset-viewer-manager.svelte';
 import { createZoomImageWheel } from '@zoom-image/core';
 
-export const zoomImageAction = (node: HTMLElement, options?: { disabled?: boolean }) => {
+export const zoomImageAction = (
-  const zoomInstance = createZoomImageWheel(node, { maxZoom: 10, initialState: assetViewerManager.zoomState });
+  node: HTMLElement,
+  options?: { disablePointer?: boolean; zoomTarget?: HTMLElement },
+) => {
+  const zoomInstance = createZoomImageWheel(node, {
+    maxZoom: 10,
+    initialState: assetViewerManager.zoomState,
+    zoomTarget: options?.zoomTarget,
+  });
 
   const unsubscribes = [
     assetViewerManager.on({ ZoomChange: (state) => zoomInstance.setState(state) }),
     zoomInstance.subscribe(({ state }) => assetViewerManager.onZoomChange(state)),
   ];
 
-  const stopIfDisabled = (event: Event) => {
+  const stopPointerIfDisabled = (event: Event) => {
-    if (options?.disabled) {
+    if (options?.disablePointer) {
       event.stopImmediatePropagation();
     }
   };
 
-  node.addEventListener('wheel', stopIfDisabled, { capture: true });
+  node.addEventListener('pointerdown', stopPointerIfDisabled, { capture: true });
-  node.addEventListener('pointerdown', stopIfDisabled, { capture: true });
 
   node.style.overflow = 'visible';
   return {
-    update(newOptions?: { disabled?: boolean }) {
+    update(newOptions?: { disablePointer?: boolean; zoomTarget?: HTMLElement }) {
       options = newOptions;
+      if (newOptions?.zoomTarget !== undefined) {
+        zoomInstance.setState({ zoomTarget: newOptions.zoomTarget });
+      }
     },
     destroy() {
       for (const unsubscribe of unsubscribes) {
         unsubscribe();
       }
-      node.removeEventListener('wheel', stopIfDisabled, { capture: true });
+      node.removeEventListener('pointerdown', stopPointerIfDisabled, { capture: true });
-      node.removeEventListener('pointerdown', stopIfDisabled, { capture: true });
       zoomInstance.cleanup();
     },
   };

web/src/lib/components/AdaptiveImage.svelte

@@ -0,0 +1,214 @@
+<script lang="ts">
+  import { thumbhash } from '$lib/actions/thumbhash';
+  import AlphaBackground from '$lib/components/AlphaBackground.svelte';
+  import BrokenAsset from '$lib/components/assets/broken-asset.svelte';
+  import DelayedLoadingSpinner from '$lib/components/DelayedLoadingSpinner.svelte';
+  import ImageLayer from '$lib/components/ImageLayer.svelte';
+  import { assetViewerManager } from '$lib/managers/asset-viewer-manager.svelte';
+  import { getAssetUrls } from '$lib/utils';
+  import { AdaptiveImageLoader, type QualityList } from '$lib/utils/adaptive-image-loader.svelte';
+  import { scaleToCover, scaleToFit } from '$lib/utils/container-utils';
+  import { getAltText } from '$lib/utils/thumbnail-util';
+  import { toTimelineAsset } from '$lib/utils/timeline-util';
+  import type { AssetResponseDto, SharedLinkResponseDto } from '@immich/sdk';
+  import { untrack, type Snippet } from 'svelte';
+
+  type Props = {
+    asset: AssetResponseDto;
+    sharedLink?: SharedLinkResponseDto;
+    objectFit?: 'contain' | 'cover';
+    container: {
+      width: number;
+      height: number;
+    };
+    onUrlChange?: (url: string) => void;
+    onImageReady?: () => void;
+    onError?: () => void;
+    ref?: HTMLDivElement;
+    imgRef?: HTMLImageElement;
+    backdrop?: Snippet;
+    overlays?: Snippet;
+  };
+
+  let {
+    ref = $bindable(),
+    // eslint-disable-next-line no-useless-assignment
+    imgRef = $bindable(),
+    asset,
+    sharedLink,
+    objectFit = 'contain',
+    container,
+    onUrlChange,
+    onImageReady,
+    onError,
+    backdrop,
+    overlays,
+  }: Props = $props();
+
+  const afterThumbnail = (loader: AdaptiveImageLoader) => {
+    if (assetViewerManager.zoom > 1) {
+      loader.trigger('original');
+    } else {
+      loader.trigger('preview');
+    }
+  };
+
+  const buildQualityList = () => {
+    const assetUrls = getAssetUrls(asset, sharedLink);
+    const qualityList: QualityList = [
+      {
+        quality: 'thumbnail',
+        url: assetUrls.thumbnail,
+        onAfterLoad: afterThumbnail,
+        onAfterError: afterThumbnail,
+      },
+      {
+        quality: 'preview',
+        url: assetUrls.preview,
+        onAfterError: (loader) => loader.trigger('original'),
+      },
+      { quality: 'original', url: assetUrls.original },
+    ];
+    return qualityList;
+  };
+
+  const loaderKey = $derived(`${asset.id}:${asset.thumbhash}:${sharedLink?.id}`);
+
+  const adaptiveImageLoader = $derived.by(() => {
+    void loaderKey;
+
+    return untrack(
+      () =>
+        new AdaptiveImageLoader(buildQualityList(), {
+          onImageReady,
+          onError,
+          onUrlChange,
+        }),
+    );
+  });
+
+  $effect.pre(() => {
+    const loader = adaptiveImageLoader;
+    untrack(() => assetViewerManager.resetZoomState());
+    return () => loader.destroy();
+  });
+
+  const imageDimensions = $derived.by(() => {
+    const { width, height } = asset;
+    if (width && width > 0 && height && height > 0) {
+      return { width, height };
+    }
+    return { width: 1, height: 1 };
+  });
+
+  const { width, height, left, top } = $derived.by(() => {
+    const scaleFn = objectFit === 'cover' ? scaleToCover : scaleToFit;
+    const { width, height } = scaleFn(imageDimensions, container);
+    return {
+      width: width + 'px',
+      height: height + 'px',
+      left: (container.width - width) / 2 + 'px',
+      top: (container.height - height) / 2 + 'px',
+    };
+  });
+
+  const { status } = $derived(adaptiveImageLoader);
+  const alt = $derived(status.urls.preview ? $getAltText(toTimelineAsset(asset)) : '');
+
+  const show = $derived.by(() => {
+    const { quality, started, hasError, urls } = status;
+    return {
+      alphaBackground: !hasError && started,
+      spinner: !asset.thumbhash && !started,
+      brokenAsset: hasError,
+      thumbhash: quality.thumbnail !== 'success' && quality.preview !== 'success' && quality.original !== 'success',
+      thumbnail: quality.thumbnail !== 'error' && quality.preview !== 'success' && quality.original !== 'success',
+      preview: quality.preview !== 'error' && quality.original !== 'success',
+      original: quality.original !== 'error' && urls.original !== undefined,
+    };
+  });
+
+  $effect(() => {
+    assetViewerManager.imageLoaderStatus = status;
+  });
+
+  $effect(() => {
+    if (assetViewerManager.zoom > 1 && status.quality.original !== 'success') {
+      untrack(() => void adaptiveImageLoader.trigger('original'));
+    }
+  });
+
+  let thumbnailElement = $state<HTMLImageElement>();
+  let previewElement = $state<HTMLImageElement>();
+  let originalElement = $state<HTMLImageElement>();
+
+  $effect(() => {
+    const quality = status.quality;
+    imgRef =
+      (quality.original === 'success' ? originalElement : undefined) ??
+      (quality.preview === 'success' ? previewElement : undefined) ??
+      (quality.thumbnail === 'success' ? thumbnailElement : undefined);
+  });
+</script>
+
+<div class="relative h-full w-full overflow-hidden will-change-transform" bind:this={ref}>
+  {@render backdrop?.()}
+
+  <div class="absolute inset-0" style:left style:top style:width style:height>
+    {#if show.alphaBackground}
+      <AlphaBackground />
+    {/if}
+
+    {#if show.thumbhash}
+      {#if asset.thumbhash}
+        <!-- Thumbhash / spinner layer  -->
+        <canvas use:thumbhash={{ base64ThumbHash: asset.thumbhash }} class="h-full w-full absolute"></canvas>
+      {:else if show.spinner}
+        <DelayedLoadingSpinner />
+      {/if}
+    {/if}
+
+    {#if show.thumbnail}
+      <ImageLayer
+        {adaptiveImageLoader}
+        {width}
+        {height}
+        quality="thumbnail"
+        src={status.urls.thumbnail}
+        alt=""
+        role="presentation"
+        bind:ref={thumbnailElement}
+      />
+    {/if}
+
+    {#if show.brokenAsset}
+      <BrokenAsset class="text-xl h-full w-full absolute" />
+    {/if}
+
+    {#if show.preview}
+      <ImageLayer
+        {adaptiveImageLoader}
+        {alt}
+        {width}
+        {height}
+        {overlays}
+        quality="preview"
+        src={status.urls.preview}
+        bind:ref={previewElement}
+      />
+    {/if}
+
+    {#if show.original}
+      <ImageLayer
+        {adaptiveImageLoader}
+        {alt}
+        {width}
+        {height}
+        {overlays}
+        quality="original"
+        src={status.urls.original}
+        bind:ref={originalElement}
+      />
+    {/if}
+  </div>
+</div>

web/src/lib/components/AlphaBackground.svelte

@@ -0,0 +1,11 @@
+<script lang="ts">
+  import type { ClassValue } from 'svelte/elements';
+
+  interface Props {
+    class?: ClassValue;
+  }
+
+  let { class: className = '' }: Props = $props();
+</script>
+
+<div class="absolute h-full w-full bg-gray-300 dark:bg-gray-700 {className}"></div>

web/src/lib/components/DelayedLoadingSpinner.svelte

@@ -0,0 +1,20 @@
+<script lang="ts">
+  import { LoadingSpinner } from '@immich/ui';
+</script>
+
+<div class="delayed-spinner absolute flex h-full items-center justify-center">
+  <LoadingSpinner />
+</div>
+
+<style>
+  @keyframes delayedVisibility {
+    to {
+      visibility: visible;
+    }
+  }
+
+  .delayed-spinner {
+    visibility: hidden;
+    animation: 0s linear 0.4s forwards delayedVisibility;
+  }
+</style>

web/src/lib/components/Image.svelte

@@ -1,4 +1,5 @@
 <script lang="ts">
+  import { isFirefox } from '$lib/utils/asset-utils';
   import { cancelImageUrl } from '$lib/utils/sw-messaging';
   import { onDestroy, untrack } from 'svelte';
   import type { HTMLImgAttributes } from 'svelte/elements';
@@ -14,6 +15,7 @@
   let { src, onStart, onLoad, onError, ref = $bindable(), ...rest }: Props = $props();
 
   let capturedSource: string | undefined = $state();
+  let loaded = $state(false);
   let destroyed = false;
 
   $effect(() => {
@@ -32,11 +34,25 @@
     }
   });
 
+  const completeLoad = () => {
+    if (destroyed) {
+      return;
+    }
+    loaded = true;
+    onLoad?.();
+  };
+
   const handleLoad = () => {
     if (destroyed || !src) {
       return;
     }
-    onLoad?.();
+
+    if (isFirefox && ref) {
+      ref.decode().then(completeLoad, completeLoad);
+      return;
+    }
+
+    completeLoad();
   };
 
   const handleError = () => {
@@ -49,6 +65,13 @@
 
 {#if capturedSource}
   {#key capturedSource}
-    <img bind:this={ref} src={capturedSource} {...rest} onload={handleLoad} onerror={handleError} />
+    <img
+      bind:this={ref}
+      src={capturedSource}
+      {...rest}
+      style:visibility={isFirefox && !loaded ? 'hidden' : undefined}
+      onload={handleLoad}
+      onerror={handleError}
+    />
   {/key}
 {/if}

web/src/lib/components/ImageLayer.svelte

@@ -0,0 +1,47 @@
+<script lang="ts">
+  import Image from '$lib/components/Image.svelte';
+  import type { AdaptiveImageLoader, ImageQuality } from '$lib/utils/adaptive-image-loader.svelte';
+  import type { Snippet } from 'svelte';
+
+  type Props = {
+    adaptiveImageLoader: AdaptiveImageLoader;
+    quality: ImageQuality;
+    src: string | undefined;
+    alt?: string;
+    role?: string;
+    ref?: HTMLImageElement;
+    width: string;
+    height: string;
+    overlays?: Snippet;
+  };
+
+  let {
+    adaptiveImageLoader,
+    quality,
+    src,
+    alt = '',
+    role,
+    ref = $bindable(),
+    width,
+    height,
+    overlays,
+  }: Props = $props();
+</script>
+
+{#key adaptiveImageLoader}
+  <div class="absolute top-0" style:width style:height>
+    <Image
+      {src}
+      onStart={() => adaptiveImageLoader.onStart(quality)}
+      onLoad={() => adaptiveImageLoader.onLoad(quality)}
+      onError={() => adaptiveImageLoader.onError(quality)}
+      bind:ref
+      class="h-full w-full bg-transparent"
+      {alt}
+      {role}
+      draggable={false}
+      data-testid={quality}
+    />
+    {@render overlays?.()}
+  </div>
+{/key}

web/src/lib/components/LoadingDots.svelte

@@ -0,0 +1,46 @@
+<script lang="ts">
+  import type { ClassValue } from 'svelte/elements';
+
+  interface Props {
+    class?: ClassValue;
+  }
+
+  let { class: className }: Props = $props();
+</script>
+
+<div class="delayed inline-flex items-center gap-1 {className}">
+  {#each [0, 1, 2] as i (i)}
+    <span class="dot block size-1.5 rounded-full bg-white shadow-[0_0_3px_rgba(0,0,0,0.6)]" style:--delay="{i * 0.25}s"
+    ></span>
+  {/each}
+</div>
+
+<style>
+  .delayed {
+    visibility: hidden;
+    animation: delayed-visibility 0s linear 0.4s forwards;
+  }
+
+  @keyframes delayed-visibility {
+    to {
+      visibility: visible;
+    }
+  }
+
+  .dot {
+    animation: dot-stream 1.6s var(--delay, 0s) ease-in-out infinite;
+  }
+
+  @keyframes dot-stream {
+    0%,
+    80%,
+    100% {
+      opacity: 0.3;
+      transform: scale(0.8);
+    }
+    40% {
+      opacity: 1;
+      transform: scale(1.15);
+    }
+  }
+</style>

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

@@ -0,0 +1,104 @@
+import { loadImage } from '$lib/actions/image-loader.svelte';
+import { getAssetUrls } from '$lib/utils';
+import { AdaptiveImageLoader, type QualityList } from '$lib/utils/adaptive-image-loader.svelte';
+import type { AssetResponseDto, SharedLinkResponseDto } from '@immich/sdk';
+
+type AssetCursor = {
+  current: AssetResponseDto;
+  nextAsset?: AssetResponseDto;
+  previousAsset?: AssetResponseDto;
+};
+
+export class PreloadManager {
+  private nextPreloader: AdaptiveImageLoader | undefined;
+  private previousPreloader: AdaptiveImageLoader | undefined;
+
+  private startPreloader(
+    asset: AssetResponseDto | undefined,
+    sharedlink: SharedLinkResponseDto | undefined,
+  ): AdaptiveImageLoader | undefined {
+    if (!asset) {
+      return;
+    }
+    const urls = getAssetUrls(asset, sharedlink);
+    const afterThumbnail = (loader: AdaptiveImageLoader) => loader.trigger('preview');
+    const qualityList: QualityList = [
+      {
+        quality: 'thumbnail',
+        url: urls.thumbnail,
+        onAfterLoad: afterThumbnail,
+        onAfterError: afterThumbnail,
+      },
+      {
+        quality: 'preview',
+        url: urls.preview,
+        onAfterError: (loader) => loader.trigger('original'),
+      },
+      { quality: 'original', url: urls.original },
+    ];
+    const loader = new AdaptiveImageLoader(qualityList, undefined, loadImage);
+    loader.start();
+    return loader;
+  }
+
+  private destroyPreviousPreloader() {
+    this.previousPreloader?.destroy();
+    this.previousPreloader = undefined;
+  }
+
+  private destroyNextPreloader() {
+    this.nextPreloader?.destroy();
+    this.nextPreloader = undefined;
+  }
+
+  cancelBeforeNavigation(direction: 'previous' | 'next') {
+    switch (direction) {
+      case 'next': {
+        this.destroyPreviousPreloader();
+        break;
+      }
+      case 'previous': {
+        this.destroyNextPreloader();
+        break;
+      }
+    }
+  }
+
+  updateAfterNavigation(oldCursor: AssetCursor, newCursor: AssetCursor, sharedlink: SharedLinkResponseDto | undefined) {
+    const movedForward = newCursor.current.id === oldCursor.nextAsset?.id;
+    const movedBackward = newCursor.current.id === oldCursor.previousAsset?.id;
+
+    if (!movedBackward) {
+      this.destroyPreviousPreloader();
+    }
+
+    if (!movedForward) {
+      this.destroyNextPreloader();
+    }
+
+    if (movedForward) {
+      this.nextPreloader = this.startPreloader(newCursor.nextAsset, sharedlink);
+    } else if (movedBackward) {
+      this.previousPreloader = this.startPreloader(newCursor.previousAsset, sharedlink);
+    } else {
+      this.previousPreloader = this.startPreloader(newCursor.previousAsset, sharedlink);
+      this.nextPreloader = this.startPreloader(newCursor.nextAsset, sharedlink);
+    }
+  }
+
+  initializePreloads(cursor: AssetCursor, sharedlink: SharedLinkResponseDto | undefined) {
+    if (cursor.nextAsset) {
+      this.nextPreloader = this.startPreloader(cursor.nextAsset, sharedlink);
+    }
+    if (cursor.previousAsset) {
+      this.previousPreloader = this.startPreloader(cursor.previousAsset, sharedlink);
+    }
+  }
+
+  destroy() {
+    this.destroyNextPreloader();
+    this.destroyPreviousPreloader();
+  }
+}
+
+export const preloadManager = new PreloadManager();

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

@@ -34,7 +34,9 @@
     type PersonResponseDto,
     type StackResponseDto,
   } from '@immich/sdk';
-  import { ActionButton, CommandPaletteDefaultProvider, type ActionItem } from '@immich/ui';
+  import { ActionButton, CommandPaletteDefaultProvider, Tooltip, type ActionItem } from '@immich/ui';
+  import LoadingDots from '$lib/components/LoadingDots.svelte';
+  import { assetViewerManager } from '$lib/managers/asset-viewer-manager.svelte';
   import {
     mdiArrowLeft,
     mdiArrowRight,
@@ -104,7 +106,16 @@
     <ActionButton action={Close} />
   </div>
 
-  <div class="flex gap-2 overflow-x-auto dark" data-testid="asset-viewer-navbar-actions">
+  <div class="flex items-center gap-2 overflow-x-auto dark" data-testid="asset-viewer-navbar-actions">
+    {#if assetViewerManager.isImageLoading}
+      <Tooltip text={$t('loading')}>
+        {#snippet child({ props })}
+          <div {...props} role="status" aria-label={$t('loading')}>
+            <LoadingDots class="me-1" />
+          </div>
+        {/snippet}
+      </Tooltip>
+    {/if}
     <ActionButton action={Cast} />
     <ActionButton action={Actions.Share} />
     <ActionButton action={Actions.Offline} />

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

@@ -5,15 +5,17 @@
   import NextAssetAction from '$lib/components/asset-viewer/actions/next-asset-action.svelte';
   import PreviousAssetAction from '$lib/components/asset-viewer/actions/previous-asset-action.svelte';
   import AssetViewerNavBar from '$lib/components/asset-viewer/asset-viewer-nav-bar.svelte';
+  import { preloadManager } from '$lib/components/asset-viewer/PreloadManager.svelte';
   import { AssetAction, ProjectionType } from '$lib/constants';
   import { activityManager } from '$lib/managers/activity-manager.svelte';
   import { assetViewerManager } from '$lib/managers/asset-viewer-manager.svelte';
+  import { assetCacheManager } from '$lib/managers/AssetCacheManager.svelte';
   import { authManager } from '$lib/managers/auth-manager.svelte';
   import { editManager, EditToolType } from '$lib/managers/edit/edit-manager.svelte';
   import { eventManager } from '$lib/managers/event-manager.svelte';
-  import { imageManager } from '$lib/managers/ImageManager.svelte';
   import { getAssetActions } from '$lib/services/asset.service';
   import { assetViewingStore } from '$lib/stores/asset-viewing.store';
+  import { isFaceEditMode } from '$lib/stores/face-edit.svelte';
   import { ocrManager } from '$lib/stores/ocr.svelte';
   import { alwaysLoadOriginalVideo } from '$lib/stores/preferences.store';
   import { SlideshowNavigation, SlideshowState, slideshowStore } from '$lib/stores/slideshow.store';
@@ -36,6 +38,7 @@
   } from '@immich/sdk';
   import { CommandPaletteDefaultProvider } from '@immich/ui';
   import { onDestroy, onMount, untrack } from 'svelte';
+  import type { SwipeCustomEvent } from 'svelte-gestures';
   import { t } from 'svelte-i18n';
   import { fly } from 'svelte/transition';
   import Thumbnail from '../assets/thumbnail/thumbnail.svelte';
@@ -92,20 +95,20 @@
     stopProgress: stopSlideshowProgress,
     slideshowNavigation,
     slideshowState,
-    slideshowTransition,
     slideshowRepeat,
   } = slideshowStore;
   const stackThumbnailSize = 60;
   const stackSelectedThumbnailSize = 65;
 
-  const asset = $derived(cursor.current);
+  let stack: StackResponseDto | undefined = $state();
+  let selectedStackAsset: AssetResponseDto | undefined = $state();
+  let previewStackedAsset: AssetResponseDto | undefined = $state();
+
+  const asset = $derived(previewStackedAsset ?? selectedStackAsset ?? cursor.current);
   const nextAsset = $derived(cursor.nextAsset);
   const previousAsset = $derived(cursor.previousAsset);
   let sharedLink = getSharedLink();
-  let previewStackedAsset: AssetResponseDto | undefined = $state();
   let fullscreenElement = $state<Element>();
-  let unsubscribes: (() => void)[] = [];
-  let stack: StackResponseDto | null = $state(null);
 
   let playOriginalVideo = $state($alwaysLoadOriginalVideo);
   let slideshowStartAssetId = $state<string>();
@@ -114,81 +117,97 @@
     playOriginalVideo = value;
   };
 
+  const selectStackedAsset = async (id: string) => {
+    selectedStackAsset = await assetCacheManager.getAsset({ id });
+  };
+
   const refreshStack = async () => {
-    if (authManager.isSharedLink) {
+    if (authManager.isSharedLink || !withStacked) {
       return;
     }
 
-    if (asset.stack) {
+    if (!cursor.current.stack) {
-      stack = await getStack({ id: asset.stack.id });
+      stack = undefined;
+      selectedStackAsset = undefined;
+      return;
     }
 
-    if (!stack?.assets.some(({ id }) => id === asset.id)) {
+    stack = await getStack({ id: cursor.current.stack.id });
-      stack = null;
+    const primaryAsset = stack?.assets.find(({ id }) => id === stack?.primaryAssetId);
+    if (primaryAsset) {
+      await selectStackedAsset(primaryAsset.id);
     }
-
-    untrack(() => {
-      imageManager.preload(stack?.assets[1]);
-    });
   };
 
   const handleFavorite = async () => {
-    if (album && album.isActivityEnabled) {
+    if (!album || !album.isActivityEnabled) {
-      try {
+      return;
-        await activityManager.toggleLike();
+    }
-      } catch (error) {
+
-        handleError(error, $t('errors.unable_to_change_favorite'));
+    try {
-      }
+      await activityManager.toggleLike();
+    } catch (error) {
+      handleError(error, $t('errors.unable_to_change_favorite'));
     }
   };
 
   onMount(() => {
     syncAssetViewerOpenClass(true);
-    unsubscribes.push(
+    const slideshowStateUnsubscribe = slideshowState.subscribe((value) => {
-      slideshowState.subscribe((value) => {
+      if (value === SlideshowState.PlaySlideshow) {
-        if (value === SlideshowState.PlaySlideshow) {
+        slideshowHistory.reset();
-          slideshowHistory.reset();
+        slideshowHistory.queue(toTimelineAsset(asset));
-          slideshowHistory.queue(toTimelineAsset(asset));
+        handlePromiseError(handlePlaySlideshow());
-          handlePromiseError(handlePlaySlideshow());
+      } else if (value === SlideshowState.StopSlideshow) {
-        } else if (value === SlideshowState.StopSlideshow) {
+        handlePromiseError(handleStopSlideshow());
-          handlePromiseError(handleStopSlideshow());
+      }
-        }
+    });
-      }),
+
-      slideshowNavigation.subscribe((value) => {
+    const slideshowNavigationUnsubscribe = slideshowNavigation.subscribe((value) => {
-        if (value === SlideshowNavigation.Shuffle) {
+      if (value === SlideshowNavigation.Shuffle) {
-          slideshowHistory.reset();
+        slideshowHistory.reset();
-          slideshowHistory.queue(toTimelineAsset(asset));
+        slideshowHistory.queue(toTimelineAsset(asset));
-        }
+      }
-      }),
+    });
-    );
+
+    return () => {
+      slideshowStateUnsubscribe();
+      slideshowNavigationUnsubscribe();
+    };
   });
 
   onDestroy(() => {
-    for (const unsubscribe of unsubscribes) {
-      unsubscribe();
-    }
-
     activityManager.reset();
     assetViewerManager.closeEditor();
     syncAssetViewerOpenClass(false);
+    preloadManager.destroy();
   });
 
   const closeViewer = () => {
     onClose?.(asset);
   };
 
+  const refreshPreservingSelection = async () => {
+    const id = asset.id;
+    assetCacheManager.invalidateAsset(id);
+    if (selectedStackAsset) {
+      await selectStackedAsset(id);
+    } else {
+      const asset = await assetCacheManager.getAsset({ id });
+      assetViewingStore.setAsset(asset);
+    }
+    onAssetChange?.(asset);
+  };
+
   const closeEditor = async () => {
     if (editManager.hasAppliedEdits) {
-      const refreshedAsset = await getAssetInfo({ id: asset.id });
+      await refreshPreservingSelection();
-      onAssetChange?.(refreshedAsset);
-      assetViewingStore.setAsset(refreshedAsset);
     }
     assetViewerManager.closeEditor();
   };
 
   const tracker = new InvocationTracker();
-
+  const navigateAsset = (order?: 'previous' | 'next') => {
-  const navigateAsset = (order?: 'previous' | 'next', e?: Event) => {
     if (!order) {
       if ($slideshowState === SlideshowState.PlaySlideshow) {
         order = $slideshowNavigation === SlideshowNavigation.AscendingOrder ? 'previous' : 'next';
@@ -197,16 +216,19 @@
       }
     }
 
-    e?.stopPropagation();
+    preloadManager.cancelBeforeNavigation(order);
-    imageManager.cancel(asset);
+
     if (tracker.isActive()) {
       return;
     }
 
     void tracker.invoke(async () => {
+      const isShuffle =
+        $slideshowState === SlideshowState.PlaySlideshow && $slideshowNavigation === SlideshowNavigation.Shuffle;
+
       let hasNext: boolean;
 
-      if ($slideshowState === SlideshowState.PlaySlideshow && $slideshowNavigation === SlideshowNavigation.Shuffle) {
+      if (isShuffle) {
         hasNext = order === 'previous' ? slideshowHistory.previous() : slideshowHistory.next();
         if (!hasNext) {
           const asset = await onRandom?.();
@@ -220,17 +242,22 @@
           order === 'previous' ? await navigateToAsset(cursor.previousAsset) : await navigateToAsset(cursor.nextAsset);
       }
 
-      if ($slideshowState === SlideshowState.PlaySlideshow) {
+      if ($slideshowState !== SlideshowState.PlaySlideshow) {
-        if (hasNext) {
+        return;
-          $restartSlideshowProgress = true;
-        } else if ($slideshowRepeat && slideshowStartAssetId) {
-          // Loop back to starting asset
-          await setAssetId(slideshowStartAssetId);
-          $restartSlideshowProgress = true;
-        } else {
-          await handleStopSlideshow();
-        }
       }
+
+      if (hasNext) {
+        $restartSlideshowProgress = true;
+        return;
+      }
+
+      if ($slideshowRepeat && slideshowStartAssetId) {
+        await setAssetId(slideshowStartAssetId);
+        $restartSlideshowProgress = true;
+        return;
+      }
+
+      await handleStopSlideshow();
     }, $t('error_while_navigating'));
   };
 
@@ -274,12 +301,10 @@
     }
   };
 
-  const handleStackedAssetMouseEvent = (isMouseOver: boolean, asset: AssetResponseDto) => {
-    previewStackedAsset = isMouseOver ? asset : undefined;
-  };
   const handlePreAction = (action: Action) => {
     preAction?.(action);
   };
+
   const handleAction = async (action: Action) => {
     switch (action.type) {
       case AssetAction.DELETE:
@@ -288,7 +313,7 @@
         break;
       }
       case AssetAction.REMOVE_ASSET_FROM_STACK: {
-        stack = action.stack;
+        stack = action.stack ?? undefined;
         if (stack) {
           cursor.current = stack.assets[0];
         }
@@ -342,27 +367,50 @@
     }
   };
 
+  const refreshOcr = async () => {
+    ocrManager.clear();
+    if (sharedLink) {
+      return;
+    }
+
+    await ocrManager.getAssetOcr(asset.id);
+  };
+
   const refresh = async () => {
     await refreshStack();
-    ocrManager.clear();
+    await refreshOcr();
-    if (!sharedLink) {
-      if (previewStackedAsset) {
-        await ocrManager.getAssetOcr(previewStackedAsset.id);
-      }
-      await ocrManager.getAssetOcr(asset.id);
-    }
   };
+
   $effect(() => {
     // eslint-disable-next-line @typescript-eslint/no-unused-expressions
-    asset;
+    cursor.current;
     untrack(() => handlePromiseError(refresh()));
-    imageManager.preload(cursor.nextAsset);
+  });
-    imageManager.preload(cursor.previousAsset);
+
+  $effect(() => {
+    // eslint-disable-next-line @typescript-eslint/no-unused-expressions
+    previewStackedAsset;
+    untrack(() => handlePromiseError(refreshOcr()));
+  });
+
+  let lastCursor = $state<AssetCursor>();
+
+  $effect(() => {
+    if (cursor.current.id === lastCursor?.current.id) {
+      return;
+    }
+    if (lastCursor) {
+      preloadManager.updateAfterNavigation(lastCursor, cursor, sharedLink);
+    }
+    if (!lastCursor) {
+      preloadManager.initializePreloads(cursor, sharedLink);
+    }
+    lastCursor = cursor;
   });
 
   const viewerKind = $derived.by(() => {
     if (previewStackedAsset) {
-      return previewStackedAsset.type === AssetTypeEnum.Image ? 'StackPhotoViewer' : 'StackVideoViewer';
+      return previewStackedAsset.type === AssetTypeEnum.Image ? 'PhotoViewer' : 'StackVideoViewer';
     }
     if (asset.type === AssetTypeEnum.Video) {
       return 'VideoViewer';
@@ -403,6 +451,27 @@
       assetViewerManager.isShowDetailPanel &&
       !assetViewerManager.isShowEditor,
   );
+
+  const onSwipe = (event: SwipeCustomEvent) => {
+    if (assetViewerManager.zoom > 1) {
+      return;
+    }
+
+    if (ocrManager.showOverlay) {
+      return;
+    }
+
+    if (event.detail.direction === 'left') {
+      navigateAsset('next');
+    }
+
+    if (event.detail.direction === 'right') {
+      navigateAsset('previous');
+    }
+  };
+
+  let containerWidth = $state(0);
+  let containerHeight = $state(0);
 </script>
 
 <CommandPaletteDefaultProvider name={$t('assets')} actions={[Tag]} />
@@ -414,6 +483,8 @@
   class="fixed start-0 top-0 grid size-full grid-cols-4 grid-rows-[64px_1fr] overflow-hidden bg-black"
   use:focusTrap
   bind:this={assetViewerHtmlElement}
+  bind:clientWidth={containerWidth}
+  bind:clientHeight={containerHeight}
 >
   <!-- Top navigation bar -->
   {#if $slideshowState === SlideshowState.None && !assetViewerManager.isShowEditor}
@@ -448,23 +519,15 @@
     </div>
   {/if}
 
-  {#if $slideshowState === SlideshowState.None && showNavigation && !assetViewerManager.isShowEditor && previousAsset}
+  {#if $slideshowState === SlideshowState.None && showNavigation && !assetViewerManager.isShowEditor && !isFaceEditMode.value && previousAsset}
     <div class="my-auto col-span-1 col-start-1 row-span-full row-start-1 justify-self-start">
       <PreviousAssetAction onPreviousAsset={() => navigateAsset('previous')} />
     </div>
   {/if}
 
   <!-- Asset Viewer -->
-  <div class="z-[-1] relative col-start-1 col-span-4 row-start-1 row-span-full">
+  <div data-viewer-content class="z-[-1] relative col-start-1 col-span-4 row-start-1 row-span-full">
-    {#if viewerKind === 'StackPhotoViewer'}
+    {#if viewerKind === 'StackVideoViewer'}
-      <PhotoViewer
-        cursor={{ ...cursor, current: previewStackedAsset! }}
-        onPreviousAsset={() => navigateAsset('previous')}
-        onNextAsset={() => navigateAsset('next')}
-        haveFadeTransition={false}
-        {sharedLink}
-      />
-    {:else if viewerKind === 'StackVideoViewer'}
       <VideoViewer
         asset={previewStackedAsset!}
         cacheKey={previewStackedAsset!.thumbhash}
@@ -495,11 +558,10 @@
       <CropArea {asset} />
     {:else if viewerKind === 'PhotoViewer'}
       <PhotoViewer
-        {cursor}
+        cursor={{ ...cursor, current: asset }}
-        onPreviousAsset={() => navigateAsset('previous')}
-        onNextAsset={() => navigateAsset('next')}
         {sharedLink}
-        haveFadeTransition={$slideshowState !== SlideshowState.None && $slideshowTransition}
+        {onSwipe}
+        onTagFace={refreshPreservingSelection}
       />
     {:else if viewerKind === 'VideoViewer'}
       <VideoViewer
@@ -533,9 +595,55 @@
         <OcrButton />
       </div>
     {/if}
+
+    {#if stack && withStacked && !assetViewerManager.isShowEditor}
+      {@const stackedAssets = stack.assets}
+      <div
+        id="stack-slideshow"
+        class="absolute bottom-0 max-w-[calc(100%-5rem)] col-span-4 col-start-1 pointer-events-none"
+      >
+        <div
+          role="presentation"
+          class="relative inline-flex flex-row flex-nowrap max-w-full overflow-x-auto overflow-y-hidden horizontal-scrollbar pointer-events-auto"
+          onmouseleave={() => (previewStackedAsset = undefined)}
+        >
+          {#each stackedAssets as stackedAsset (stackedAsset.id)}
+            <div
+              class={['inline-block px-1 relative transition-all pb-2']}
+              style:bottom={stackedAsset.id === asset.id ? '0' : '-10px'}
+            >
+              <Thumbnail
+                imageClass={{ 'border-2 border-white': stackedAsset.id === asset.id }}
+                brokenAssetClass="text-xs"
+                dimmed={stackedAsset.id !== asset.id}
+                asset={toTimelineAsset(stackedAsset)}
+                onClick={async () => {
+                  await selectStackedAsset(stackedAsset.id);
+                  previewStackedAsset = undefined;
+                }}
+                onMouseEvent={async ({ isMouseOver }) => {
+                  if (isMouseOver) {
+                    previewStackedAsset = stackedAsset;
+                    previewStackedAsset = await assetCacheManager.getAsset({ id: stackedAsset.id });
+                  }
+                }}
+                readonly
+                thumbnailSize={stackedAsset.id === asset.id ? stackSelectedThumbnailSize : stackThumbnailSize}
+                showStackedIcon={false}
+                disableLinkMouseOver
+              />
+
+              <div class="w-full flex place-items-center place-content-center">
+                <div class={['w-2 h-2 rounded-full flex mt-0.5', { 'bg-white': stackedAsset.id === asset.id }]}></div>
+              </div>
+            </div>
+          {/each}
+        </div>
+      </div>
+    {/if}
   </div>
 
-  {#if $slideshowState === SlideshowState.None && showNavigation && !assetViewerManager.isShowEditor && nextAsset}
+  {#if $slideshowState === SlideshowState.None && showNavigation && !assetViewerManager.isShowEditor && !isFaceEditMode.value && nextAsset}
     <div class="my-auto col-span-1 col-start-4 row-span-full row-start-1 justify-self-end">
       <NextAssetAction onNextAsset={() => navigateAsset('next')} />
     </div>
@@ -550,7 +658,7 @@
     >
       {#if showDetailPanel}
         <div class="w-90 h-full">
-          <DetailPanel {asset} currentAlbum={album} />
+          <DetailPanel {asset} currentAlbum={album} onRefreshPeople={refreshPreservingSelection} />
         </div>
       {:else if assetViewerManager.isShowEditor}
         <div class="w-100 h-full">
@@ -560,42 +668,6 @@
     </div>
   {/if}
 
-  {#if stack && withStacked && !assetViewerManager.isShowEditor}
-    {@const stackedAssets = stack.assets}
-    <div id="stack-slideshow" class="absolute bottom-0 w-full col-span-4 col-start-1 pointer-events-none">
-      <div class="relative flex flex-row no-wrap overflow-x-auto overflow-y-hidden horizontal-scrollbar">
-        {#each stackedAssets as stackedAsset (stackedAsset.id)}
-          <div
-            class={['inline-block px-1 relative transition-all pb-2 pointer-events-auto']}
-            style:bottom={stackedAsset.id === asset.id ? '0' : '-10px'}
-          >
-            <Thumbnail
-              imageClass={{ 'border-2 border-white': stackedAsset.id === asset.id }}
-              brokenAssetClass="text-xs"
-              dimmed={stackedAsset.id !== asset.id}
-              asset={toTimelineAsset(stackedAsset)}
-              onClick={() => {
-                cursor.current = stackedAsset;
-                previewStackedAsset = undefined;
-              }}
-              onMouseEvent={({ isMouseOver }) => handleStackedAssetMouseEvent(isMouseOver, stackedAsset)}
-              readonly
-              thumbnailSize={stackedAsset.id === asset.id ? stackSelectedThumbnailSize : stackThumbnailSize}
-              showStackedIcon={false}
-              disableLinkMouseOver
-            />
-
-            {#if stackedAsset.id === asset.id}
-              <div class="w-full flex place-items-center place-content-center">
-                <div class="w-2 h-2 bg-white rounded-full flex mt-0.5"></div>
-              </div>
-            {/if}
-          </div>
-        {/each}
-      </div>
-    </div>
-  {/if}
-
   {#if isShared && album && assetViewerManager.isShowActivityPanel && $user}
     <div
       transition:fly={{ duration: 150 }}

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

@@ -20,13 +20,7 @@
   import { handleError } from '$lib/utils/handle-error';
   import { fromISODateTime, fromISODateTimeUTC, toTimelineAsset } from '$lib/utils/timeline-util';
   import { getParentPath } from '$lib/utils/tree-utils';
-  import {
+  import { AssetMediaSize, getAllAlbums, type AlbumResponseDto, type AssetResponseDto } from '@immich/sdk';
-    AssetMediaSize,
-    getAllAlbums,
-    getAssetInfo,
-    type AlbumResponseDto,
-    type AssetResponseDto,
-  } from '@immich/sdk';
   import { Icon, IconButton, LoadingSpinner, modalManager, Text } from '@immich/ui';
   import {
     mdiCalendar,
@@ -52,9 +46,10 @@
   interface Props {
     asset: AssetResponseDto;
     currentAlbum?: AlbumResponseDto | null;
+    onRefreshPeople?: () => Promise<void>;
   }
 
-  let { asset, currentAlbum = null }: Props = $props();
+  let { asset, currentAlbum = null, onRefreshPeople }: Props = $props();
 
   let showAssetPath = $state(false);
   let showEditFaces = $state(false);
@@ -120,11 +115,6 @@
     return undefined;
   };
 
-  const handleRefreshPeople = async () => {
-    asset = await getAssetInfo({ id: asset.id });
-    showEditFaces = false;
-  };
-
   const getAssetFolderHref = (asset: AssetResponseDto) => {
     // Remove the last part of the path to get the parent path
     return Route.folders({ path: getParentPath(asset.originalPath) });
@@ -575,6 +565,6 @@
     assetId={asset.id}
     assetType={asset.type}
     onClose={() => (showEditFaces = false)}
-    onRefresh={handleRefreshPeople}
+    onRefresh={() => void onRefreshPeople?.()}
   />
 {/if}

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

@@ -1,9 +1,8 @@
 <script lang="ts">
   import ImageThumbnail from '$lib/components/assets/thumbnail/image-thumbnail.svelte';
-  import { assetViewingStore } from '$lib/stores/asset-viewing.store';
   import { isFaceEditMode } from '$lib/stores/face-edit.svelte';
   import { getPeopleThumbnailUrl } from '$lib/utils';
-  import { getContentMetrics, getNaturalSize } from '$lib/utils/container-utils';
+  import { getNaturalSize, scaleToFit } from '$lib/utils/container-utils';
   import { handleError } from '$lib/utils/handle-error';
   import { createFace, getAllPeople, type PersonResponseDto } from '@immich/sdk';
   import { Button, Input, modalManager, toastManager } from '@immich/ui';
@@ -17,9 +16,10 @@
     containerWidth: number;
     containerHeight: number;
     assetId: string;
+    onTagFace?: () => Promise<void>;
   }
 
-  let { htmlElement, containerWidth, containerHeight, assetId }: Props = $props();
+  let { htmlElement, containerWidth, containerHeight, assetId, onTagFace }: Props = $props();
 
   let canvasEl: HTMLCanvasElement | undefined = $state();
   let canvas: Canvas | undefined = $state();
@@ -81,15 +81,20 @@
     await getPeople();
   });
 
-  $effect(() => {
+  const imageContentMetrics = $derived.by(() => {
-    const metrics = getContentMetrics(htmlElement);
+    const natural = getNaturalSize(htmlElement);
-
+    const container = { width: containerWidth, height: containerHeight };
-    const imageBoundingBox = {
+    const { width: contentWidth, height: contentHeight } = scaleToFit(natural, container);
-      top: metrics.offsetY,
+    return {
-      left: metrics.offsetX,
+      contentWidth,
-      width: metrics.contentWidth,
+      contentHeight,
-      height: metrics.contentHeight,
+      offsetX: (containerWidth - contentWidth) / 2,
+      offsetY: (containerHeight - contentHeight) / 2,
     };
+  });
+
+  $effect(() => {
+    const { offsetX, offsetY } = imageContentMetrics;
 
     if (!canvas) {
       return;
@@ -105,8 +110,8 @@
     }
 
     faceRect.set({
-      top: imageBoundingBox.top + 200,
+      top: offsetY + 200,
-      left: imageBoundingBox.left + 200,
+      left: offsetX + 200,
     });
 
     faceRect.setCoords();
@@ -214,13 +219,13 @@
     }
 
     const { left, top, width, height } = faceRect.getBoundingRect();
-    const metrics = getContentMetrics(htmlElement);
+    const { offsetX, offsetY, contentWidth, contentHeight } = imageContentMetrics;
     const natural = getNaturalSize(htmlElement);
 
-    const scaleX = natural.width / metrics.contentWidth;
+    const scaleX = natural.width / contentWidth;
-    const scaleY = natural.height / metrics.contentHeight;
+    const scaleY = natural.height / contentHeight;
-    const imageX = (left - metrics.offsetX) * scaleX;
+    const imageX = (left - offsetX) * scaleX;
-    const imageY = (top - metrics.offsetY) * scaleY;
+    const imageY = (top - offsetY) * scaleY;
 
     return {
       imageWidth: natural.width,
@@ -258,7 +263,7 @@
         },
       });
 
-      await assetViewingStore.setAssetId(assetId);
+      await onTagFace?.();
     } catch (error) {
       handleError(error, 'Error tagging face');
     } finally {

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

@@ -1,66 +1,57 @@
 <script lang="ts">
   import { shortcuts } from '$lib/actions/shortcut';
+  import { thumbhash } from '$lib/actions/thumbhash';
   import { zoomImageAction } from '$lib/actions/zoom-image';
+  import AdaptiveImage from '$lib/components/AdaptiveImage.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 AssetViewerEvents from '$lib/components/AssetViewerEvents.svelte';
-  import { assetViewerFadeDuration } from '$lib/constants';
   import { assetViewerManager } from '$lib/managers/asset-viewer-manager.svelte';
   import { castManager } from '$lib/managers/cast-manager.svelte';
-  import { imageManager } from '$lib/managers/ImageManager.svelte';
   import { isFaceEditMode } from '$lib/stores/face-edit.svelte';
   import { ocrManager } from '$lib/stores/ocr.svelte';
   import { boundingBoxesArray, type Faces } from '$lib/stores/people.store';
-  import { SlideshowLook, SlideshowState, slideshowLookCssMapping, slideshowStore } from '$lib/stores/slideshow.store';
+  import { SlideshowLook, SlideshowState, slideshowStore } from '$lib/stores/slideshow.store';
-  import { getAssetUrl, targetImageSize as getTargetImageSize, handlePromiseError } from '$lib/utils';
+  import { handlePromiseError } from '$lib/utils';
   import { canCopyImageToClipboard, copyImageToClipboard } from '$lib/utils/asset-utils';
-  import { type ContentMetrics, getContentMetrics } from '$lib/utils/container-utils';
+  import { getNaturalSize, scaleToFit, type ContentMetrics } from '$lib/utils/container-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 { type SharedLinkResponseDto } from '@immich/sdk';
-  import { toTimelineAsset } from '$lib/utils/timeline-util';
+  import { toastManager } from '@immich/ui';
-  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 { t } from 'svelte-i18n';
-  import { fade } from 'svelte/transition';
   import type { AssetCursor } from './asset-viewer.svelte';
 
   interface Props {
     cursor: AssetCursor;
-    element?: HTMLDivElement | undefined;
+    element?: HTMLDivElement;
-    haveFadeTransition?: boolean;
+    sharedLink?: SharedLinkResponseDto;
-    sharedLink?: SharedLinkResponseDto | undefined;
+    onReady?: () => void;
-    onPreviousAsset?: (() => void) | null;
+    onError?: () => void;
-    onNextAsset?: (() => void) | null;
+    onSwipe?: (event: SwipeCustomEvent) => void;
+    onTagFace?: () => Promise<void>;
   }
 
-  let {
+  let { cursor, element = $bindable(), sharedLink, onReady, onError, onSwipe, onTagFace }: Props = $props();
-    cursor,
-    element = $bindable(),
-    haveFadeTransition = true,
-    sharedLink = undefined,
-    onPreviousAsset = null,
-    onNextAsset = null,
-  }: Props = $props();
 
   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 visibleImageReady: boolean = $state(false);
 
-  let loader = $state<HTMLImageElement>();
+  let previousAssetId: string | undefined;
-
   $effect.pre(() => {
-    void asset.id;
+    const id = asset.id;
+    if (id === previousAssetId) {
+      return;
+    }
+    previousAssetId = id;
     untrack(() => {
       assetViewerManager.resetZoomState();
+      visibleImageReady = false;
       $boundingBoxesArray = [];
     });
   });
@@ -69,25 +60,30 @@
     $boundingBoxesArray = [];
   });
 
+  let containerWidth = $state(0);
+  let containerHeight = $state(0);
+
+  const container = $derived({
+    width: containerWidth,
+    height: containerHeight,
+  });
+
   const overlayMetrics = $derived.by((): ContentMetrics => {
     if (!assetViewerManager.imgRef || !visibleImageReady) {
       return { contentWidth: 0, contentHeight: 0, offsetX: 0, offsetY: 0 };
     }
 
-    const { contentWidth, contentHeight, offsetX, offsetY } = getContentMetrics(assetViewerManager.imgRef);
+    const natural = getNaturalSize(assetViewerManager.imgRef);
-    const { currentZoom, currentPositionX, currentPositionY } = assetViewerManager.zoomState;
+    const scaled = scaleToFit(natural, container);
-
     return {
-      contentWidth: contentWidth * currentZoom,
+      contentWidth: scaled.width,
-      contentHeight: contentHeight * currentZoom,
+      contentHeight: scaled.height,
-      offsetX: offsetX * currentZoom + currentPositionX,
+      offsetX: 0,
-      offsetY: offsetY * currentZoom + currentPositionY,
+      offsetY: 0,
     };
   });
 
-  let ocrBoxes = $derived(ocrManager.showOverlay ? getOcrBoundingBoxes(ocrManager.data, overlayMetrics) : []);
+  const ocrBoxes = $derived(ocrManager.showOverlay ? getOcrBoundingBoxes(ocrManager.data, overlayMetrics) : []);
-
-  let isOcrActive = $derived(ocrManager.showOverlay);
 
   const onCopy = async () => {
     if (!canCopyImageToClipboard() || !assetViewerManager.imgRef) {
@@ -108,12 +104,6 @@
 
   const onPlaySlideshow = () => ($slideshowState = SlideshowState.PlaySlideshow);
 
-  $effect(() => {
-    if (isFaceEditMode.value && assetViewerManager.zoom > 1) {
-      onZoom();
-    }
-  });
-
   // TODO move to action + command palette
   const onCopyShortcut = (event: KeyboardEvent) => {
     if (globalThis.getSelection()?.type === 'Range') {
@@ -124,29 +114,15 @@
     handlePromiseError(onCopy());
   };
 
-  const onSwipe = (event: SwipeCustomEvent) => {
+  let currentPreviewUrl = $state<string>();
-    if (assetViewerManager.zoom > 1) {
-      return;
-    }
 
-    if (ocrManager.showOverlay) {
+  const onUrlChange = (url: string) => {
-      return;
+    currentPreviewUrl = url;
-    }
-
-    if (onNextAsset && event.detail.direction === 'left') {
-      onNextAsset();
-    }
-
-    if (onPreviousAsset && event.detail.direction === 'right') {
-      onPreviousAsset();
-    }
   };
 
-  const targetImageSize = $derived(getTargetImageSize(asset, originalImageLoaded || assetViewerManager.zoom > 1));
-
   $effect(() => {
-    if (imageLoaderUrl) {
+    if (currentPreviewUrl) {
-      void cast(imageLoaderUrl);
+      void cast(currentPreviewUrl);
     }
   });
 
@@ -164,37 +140,11 @@
     }
   };
 
-  const onload = () => {
+  const blurredSlideshow = $derived(
-    imageLoaded = true;
+    $slideshowState !== SlideshowState.None && $slideshowLook === SlideshowLook.BlurredBackground && !!asset.thumbhash,
-    originalImageLoaded = targetImageSize === AssetMediaSize.Fullsize || targetImageSize === 'original';
-  };
-
-  const onerror = () => {
-    imageError = imageLoaded = true;
-  };
-
-  onDestroy(() => imageManager.cancel(asset, targetImageSize));
-
-  let imageLoaderUrl = $derived(
-    getAssetUrl({ asset, sharedLink, forceOriginal: originalImageLoaded || assetViewerManager.zoom > 1 }),
   );
 
-  let containerWidth = $state(0);
+  let adaptiveImage = $state<HTMLDivElement | undefined>();
-  let containerHeight = $state(0);
-
-  let lastUrl: string | undefined;
-
-  $effect(() => {
-    if (lastUrl && lastUrl !== imageLoaderUrl) {
-      untrack(() => {
-        imageLoaded = false;
-        originalImageLoaded = false;
-        imageError = false;
-        visibleImageReady = false;
-      });
-    }
-    lastUrl = imageLoaderUrl;
-  });
 
   const faceToNameMap = $derived.by(() => {
     // eslint-disable-next-line svelte/prefer-svelte-reactivity
@@ -208,29 +158,6 @@
   });
 
   const faces = $derived(Array.from(faceToNameMap.keys()));
-
-  const handleImageMouseMove = (event: MouseEvent) => {
-    $boundingBoxesArray = [];
-    if (!assetViewerManager.imgRef || !element || isFaceEditMode.value || ocrManager.showOverlay) {
-      return;
-    }
-
-    const containerRect = element.getBoundingClientRect();
-    const mouseX = event.clientX - containerRect.left;
-    const mouseY = event.clientY - containerRect.top;
-
-    const faceBoxes = getBoundingBox(faces, overlayMetrics);
-
-    for (const [index, box] of faceBoxes.entries()) {
-      if (mouseX >= box.left && mouseX <= box.left + box.width && mouseY >= box.top && mouseY <= box.top + box.height) {
-        $boundingBoxesArray.push(faces[index]);
-      }
-    }
-  };
-
-  const handleImageMouseLeave = () => {
-    $boundingBoxesArray = [];
-  };
 </script>
 
 <AssetViewerEvents {onCopy} {onZoom} />
@@ -243,12 +170,7 @@
     { shortcut: { key: 'c', meta: true }, onShortcut: onCopyShortcut, 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"
@@ -256,74 +178,77 @@
   bind:clientHeight={containerHeight}
   role="presentation"
   ondblclick={onZoom}
-  onmousemove={handleImageMouseMove}
+  use:zoomImageAction={{ disablePointer: isFaceEditMode.value, zoomTarget: adaptiveImage }}
-  onmouseleave={handleImageMouseLeave}
+  {...useSwipe((event) => onSwipe?.(event))}
 >
-  {#if !imageLoaded}
+  <AdaptiveImage
-    <div id="spinner" class="flex h-full items-center justify-center">
+    {asset}
-      <LoadingSpinner />
+    {sharedLink}
-    </div>
+    {container}
-  {:else if !imageError}
+    objectFit={$slideshowState !== SlideshowState.None && $slideshowLook === SlideshowLook.Cover ? 'cover' : 'contain'}
-    <div
+    {onUrlChange}
-      use:zoomImageAction={{ disabled: isOcrActive }}
+    onImageReady={() => {
-      {...useSwipe(onSwipe)}
+      visibleImageReady = true;
-      class="h-full w-full"
+      onReady?.();
-      transition:fade={{ duration: haveFadeTransition ? assetViewerFadeDuration : 0 }}
+    }}
-    >
+    onError={() => {
-      {#if $slideshowState !== SlideshowState.None && $slideshowLook === SlideshowLook.BlurredBackground}
+      onError?.();
-        <img
+      onReady?.();
-          src={imageLoaderUrl}
+    }}
-          alt=""
+    bind:imgRef={assetViewerManager.imgRef}
-          class="-z-1 absolute top-0 start-0 object-cover h-full w-full blur-lg"
+    bind:ref={adaptiveImage}
-          draggable="false"
+  >
-        />
+    {#snippet backdrop()}
+      {#if blurredSlideshow}
+        <canvas
+          use:thumbhash={{ base64ThumbHash: asset.thumbhash! }}
+          class="absolute top-0 left-0 inset-s-0 h-dvh w-dvw"
+        ></canvas>
       {/if}
-      <img
+    {/snippet}
-        bind:this={assetViewerManager.imgRef}
+    {#snippet overlays()}
-        src={imageLoaderUrl}
+      {#if !isFaceEditMode.value && !ocrManager.showOverlay}
-        onload={() => (visibleImageReady = true)}
+        {#each getBoundingBox(faces, overlayMetrics) as boundingbox, index (boundingbox.id)}
-        alt={$getAltText(toTimelineAsset(asset))}
+          {@const face = faces[index]}
-        class="h-full w-full {$slideshowState === SlideshowState.None
+          {@const name = faceToNameMap.get(face)}
-          ? 'object-contain'
+          {@const isActive = $boundingBoxesArray.includes(face)}
-          : slideshowLookCssMapping[$slideshowLook]}"
+          <!-- svelte-ignore a11y_no_static_element_interactions -->
-        draggable="false"
-      />
-      {#each getBoundingBox($boundingBoxesArray, overlayMetrics) as boundingbox, index (boundingbox.id)}
-        <div
-          class="absolute border-solid border-white border-3 rounded-lg"
-          style="top: {boundingbox.top}px; left: {boundingbox.left}px; height: {boundingbox.height}px; width: {boundingbox.width}px;"
-        ></div>
-        {#if faceToNameMap.get($boundingBoxesArray[index])}
           <div
-            class="absolute bg-white/90 text-black px-2 py-1 rounded text-sm font-medium whitespace-nowrap pointer-events-none shadow-lg"
+            class={[
-            style="top: {boundingbox.top + boundingbox.height + 4}px; left: {boundingbox.left +
+              'absolute pointer-events-auto outline-none rounded-lg',
-              boundingbox.width}px; transform: translateX(-100%);"
+              isActive && 'border-solid border-white border-3',
+            ]}
+            style="top: {boundingbox.top}px; left: {boundingbox.left}px; height: {boundingbox.height}px; width: {boundingbox.width}px;"
+            aria-label="{$t('person')}: {name || $t('unknown')}"
+            onmouseenter={() => ($boundingBoxesArray = [face])}
+            onmouseleave={() => ($boundingBoxesArray = [])}
           >
-            {faceToNameMap.get($boundingBoxesArray[index])}
+            {#if isActive && name}
+              <div
+                aria-hidden="true"
+                class="absolute bg-white/90 text-black px-2 py-1 rounded text-sm font-medium whitespace-nowrap pointer-events-none shadow-lg"
+                style="top: {boundingbox.height + 4}px; right: 0;"
+              >
+                {name}
+              </div>
+            {/if}
           </div>
-        {/if}
+        {/each}
-      {/each}
+      {/if}
 
       {#each ocrBoxes as ocrBox (ocrBox.id)}
         <OcrBoundingBox {ocrBox} />
       {/each}
-    </div>
+    {/snippet}
+  </AdaptiveImage>
 
-    {#if isFaceEditMode.value}
+  {#if isFaceEditMode.value && assetViewerManager.imgRef}
-      <FaceEditor htmlElement={assetViewerManager.imgRef} {containerWidth} {containerHeight} assetId={asset.id} />
+    <FaceEditor
-    {/if}
+      htmlElement={assetViewerManager.imgRef}
+      {containerWidth}
+      {containerHeight}
+      assetId={asset.id}
+      {onTagFace}
+    />
   {/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/faces-page/person-side-panel.svelte

@@ -1,8 +1,8 @@
 <script lang="ts">
   import OnEvents from '$lib/components/OnEvents.svelte';
   import { timeBeforeShowLoadingSpinner } from '$lib/constants';
+  import { assetViewerManager } from '$lib/managers/asset-viewer-manager.svelte';
   import { eventManager } from '$lib/managers/event-manager.svelte';
-  import { assetViewingStore } from '$lib/stores/asset-viewing.store';
   import { boundingBoxesArray } from '$lib/stores/people.store';
   import { getPeopleThumbnailUrl, handlePromiseError } from '$lib/utils';
   import { handleError } from '$lib/utils/handle-error';
@@ -25,7 +25,6 @@
   import { fly } from 'svelte/transition';
   import ImageThumbnail from '../assets/thumbnail/image-thumbnail.svelte';
   import AssignFaceSidePanel from './assign-face-side-panel.svelte';
-  import { assetViewerManager } from '$lib/managers/asset-viewer-manager.svelte';
 
   interface Props {
     assetId: string;
@@ -179,7 +178,10 @@
 
       peopleWithFaces = peopleWithFaces.filter((f) => f.id !== face.id);
 
-      await assetViewingStore.setAssetId(assetId);
+      onRefresh();
+      if (peopleWithFaces.length === 0) {
+        onClose();
+      }
     } catch (error) {
       handleError(error, $t('error_delete_face'));
     }

web/src/lib/components/memory-page/memory-photo-viewer.svelte

@@ -4,7 +4,7 @@
   import { getAssetMediaUrl } from '$lib/utils';
   import { getAltText } from '$lib/utils/thumbnail-util';
   import { AssetMediaSize } from '@immich/sdk';
-  import { LoadingSpinner } from '@immich/ui';
+  import DelayedLoadingSpinner from '$lib/components/DelayedLoadingSpinner.svelte';
   import { onMount } from 'svelte';
   import { fade } from 'svelte/transition';
 
@@ -44,9 +44,7 @@
 {/if}
 
 {#if !imageLoaded}
-  <div id="spinner" class="flex h-full items-center justify-center">
+  <DelayedLoadingSpinner />
-    <LoadingSpinner />
-  </div>
 {:else if imageLoaded}
   <div transition:fade={{ duration: assetViewerFadeDuration }} class="h-full w-full">
     <img
@@ -57,15 +55,3 @@
     />
   </div>
 {/if}
-
-<style>
-  @keyframes delayedVisibility {
-    to {
-      visibility: visible;
-    }
-  }
-  #spinner {
-    visibility: hidden;
-    animation: 0s linear 0.4s forwards delayedVisibility;
-  }
-</style>

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';
@@ -23,10 +24,24 @@ export class AssetViewerManager extends BaseEventManager<Events> {
   #zoomState = $state(createDefaultZoomState());
 
   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;
   }

web/src/lib/utils.ts

@@ -186,6 +186,14 @@ export const getAssetUrl = ({
   return getAssetMediaUrl({ id, size, cacheKey });
 };
 
+export function getAssetUrls(asset: AssetResponseDto, sharedLink?: SharedLinkResponseDto) {
+  return {
+    thumbnail: getAssetMediaUrl({ id: asset.id, cacheKey: asset.thumbhash, size: AssetMediaSize.Thumbnail }),
+    preview: getAssetUrl({ asset, sharedLink })!,
+    original: getAssetUrl({ asset, sharedLink, forceOriginal: true })!,
+  };
+}
+
 const forceUseOriginal = (asset: AssetResponseDto) => {
   return asset.type === AssetTypeEnum.Image && asset.duration && !asset.duration.includes('0:00:00.000');
 };

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

@@ -0,0 +1,304 @@
+import { AdaptiveImageLoader, type QualityList } from '$lib/utils/adaptive-image-loader.svelte';
+import { cancelImageUrl } from '$lib/utils/sw-messaging';
+
+vi.mock('$lib/utils/sw-messaging', () => ({
+  cancelImageUrl: vi.fn(),
+}));
+
+function createQualityList(overrides?: {
+  onAfterLoad?: Record<string, (loader: AdaptiveImageLoader) => void>;
+  onAfterError?: Record<string, (loader: AdaptiveImageLoader) => void>;
+}): QualityList {
+  return [
+    {
+      quality: 'thumbnail',
+      url: '/thumbnail.jpg',
+      onAfterLoad: overrides?.onAfterLoad?.thumbnail,
+      onAfterError: overrides?.onAfterError?.thumbnail,
+    },
+    {
+      quality: 'preview',
+      url: '/preview.jpg',
+      onAfterLoad: overrides?.onAfterLoad?.preview,
+      onAfterError: overrides?.onAfterError?.preview,
+    },
+    {
+      quality: 'original',
+      url: '/original.jpg',
+      onAfterLoad: overrides?.onAfterLoad?.original,
+      onAfterError: overrides?.onAfterError?.original,
+    },
+  ];
+}
+
+describe('AdaptiveImageLoader', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('constructor', () => {
+    it('initializes with thumbnail URL set', () => {
+      const loader = new AdaptiveImageLoader(createQualityList());
+      expect(loader.status.urls.thumbnail).toBe('/thumbnail.jpg');
+      expect(loader.status.urls.preview).toBeUndefined();
+      expect(loader.status.urls.original).toBeUndefined();
+    });
+
+    it('initializes all qualities as unloaded', () => {
+      const loader = new AdaptiveImageLoader(createQualityList());
+      expect(loader.status.quality.thumbnail).toBe('unloaded');
+      expect(loader.status.quality.preview).toBe('unloaded');
+      expect(loader.status.quality.original).toBe('unloaded');
+    });
+  });
+
+  describe('onStart', () => {
+    it('sets started to true', () => {
+      const loader = new AdaptiveImageLoader(createQualityList());
+      expect(loader.status.started).toBe(false);
+      loader.onStart('thumbnail');
+      expect(loader.status.started).toBe(true);
+    });
+
+    it('is a no-op after destroy', () => {
+      const loader = new AdaptiveImageLoader(createQualityList());
+      loader.destroy();
+      loader.onStart('thumbnail');
+      expect(loader.status.started).toBe(false);
+    });
+  });
+
+  describe('onLoad', () => {
+    it('sets quality to success and calls callbacks', () => {
+      const onUrlChange = vi.fn();
+      const onImageReady = vi.fn();
+      const loader = new AdaptiveImageLoader(createQualityList(), { onUrlChange, onImageReady });
+
+      loader.onLoad('thumbnail');
+
+      expect(loader.status.quality.thumbnail).toBe('success');
+      expect(onUrlChange).toHaveBeenCalledWith('/thumbnail.jpg');
+      expect(onImageReady).toHaveBeenCalledOnce();
+    });
+
+    it('calls onAfterLoad callback', () => {
+      const onAfterLoad = vi.fn();
+      const qualityList = createQualityList({ onAfterLoad: { thumbnail: onAfterLoad } });
+      const loader = new AdaptiveImageLoader(qualityList);
+
+      loader.onLoad('thumbnail');
+
+      expect(onAfterLoad).toHaveBeenCalledWith(loader);
+    });
+
+    it('ignores load if URL is not set', () => {
+      const onImageReady = vi.fn();
+      const loader = new AdaptiveImageLoader(createQualityList(), { onImageReady });
+
+      loader.onLoad('preview');
+
+      expect(loader.status.quality.preview).toBe('unloaded');
+      expect(onImageReady).not.toHaveBeenCalled();
+    });
+
+    it('ignores load if a higher quality is already loaded', () => {
+      const onUrlChange = vi.fn();
+      const loader = new AdaptiveImageLoader(createQualityList(), { onUrlChange });
+
+      loader.onLoad('thumbnail');
+      loader.trigger('preview');
+      loader.onLoad('preview');
+
+      onUrlChange.mockClear();
+      loader.onLoad('thumbnail');
+
+      expect(onUrlChange).not.toHaveBeenCalled();
+    });
+
+    it('is a no-op after destroy', () => {
+      const onImageReady = vi.fn();
+      const loader = new AdaptiveImageLoader(createQualityList(), { onImageReady });
+
+      loader.destroy();
+      loader.onLoad('thumbnail');
+
+      expect(onImageReady).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('onError', () => {
+    it('sets quality to error and clears URL', () => {
+      const onError = vi.fn();
+      const loader = new AdaptiveImageLoader(createQualityList(), { onError });
+
+      loader.onError('thumbnail');
+
+      expect(loader.status.quality.thumbnail).toBe('error');
+      expect(loader.status.urls.thumbnail).toBeUndefined();
+      expect(loader.status.hasError).toBe(true);
+      expect(onError).toHaveBeenCalledOnce();
+    });
+
+    it('calls onAfterError callback', () => {
+      const onAfterError = vi.fn();
+      const qualityList = createQualityList({ onAfterError: { thumbnail: onAfterError } });
+      const loader = new AdaptiveImageLoader(qualityList);
+
+      loader.onError('thumbnail');
+
+      expect(onAfterError).toHaveBeenCalledWith(loader);
+    });
+
+    it('is a no-op after destroy', () => {
+      const onError = vi.fn();
+      const loader = new AdaptiveImageLoader(createQualityList(), { onError });
+
+      loader.destroy();
+      loader.onError('thumbnail');
+
+      expect(onError).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('trigger', () => {
+    it('sets the URL for the quality', () => {
+      const loader = new AdaptiveImageLoader(createQualityList());
+
+      loader.trigger('preview');
+
+      expect(loader.status.urls.preview).toBe('/preview.jpg');
+    });
+
+    it('returns true if URL is already set', () => {
+      const loader = new AdaptiveImageLoader(createQualityList());
+
+      expect(loader.trigger('thumbnail')).toBe(true);
+    });
+
+    it('returns false when triggering a new quality', () => {
+      const loader = new AdaptiveImageLoader(createQualityList());
+
+      expect(loader.trigger('preview')).toBe(false);
+    });
+
+    it('clears hasError when triggering', () => {
+      const loader = new AdaptiveImageLoader(createQualityList());
+
+      loader.onError('thumbnail');
+      expect(loader.status.hasError).toBe(true);
+
+      loader.trigger('preview');
+      expect(loader.status.hasError).toBe(false);
+    });
+
+    it('calls imageLoader when provided', () => {
+      const imageLoader = vi.fn(() => vi.fn());
+      const loader = new AdaptiveImageLoader(createQualityList(), undefined, imageLoader);
+
+      loader.trigger('preview');
+
+      expect(imageLoader).toHaveBeenCalledWith(
+        '/preview.jpg',
+        expect.any(Function),
+        expect.any(Function),
+        expect.any(Function),
+      );
+    });
+
+    it('returns false after destroy', () => {
+      const loader = new AdaptiveImageLoader(createQualityList());
+
+      loader.destroy();
+
+      expect(loader.trigger('preview')).toBe(false);
+    });
+
+    it('calls onAfterError if URL is empty', () => {
+      const onAfterError = vi.fn();
+      const qualityList = createQualityList({ onAfterError: { preview: onAfterError } });
+      (qualityList[1] as { url: string }).url = '';
+      const loader = new AdaptiveImageLoader(qualityList);
+
+      expect(loader.trigger('preview')).toBe(false);
+      expect(onAfterError).toHaveBeenCalledWith(loader);
+    });
+  });
+
+  describe('start', () => {
+    it('throws if no imageLoader is provided', () => {
+      const loader = new AdaptiveImageLoader(createQualityList());
+      expect(() => loader.start()).toThrow('Start requires imageLoader to be specified');
+    });
+
+    it('calls imageLoader with thumbnail URL', () => {
+      const imageLoader = vi.fn(() => vi.fn());
+      const loader = new AdaptiveImageLoader(createQualityList(), undefined, imageLoader);
+
+      loader.start();
+
+      expect(imageLoader).toHaveBeenCalledWith(
+        '/thumbnail.jpg',
+        expect.any(Function),
+        expect.any(Function),
+        expect.any(Function),
+      );
+    });
+  });
+
+  describe('destroy', () => {
+    it('cancels all image URLs when no imageLoader', () => {
+      const loader = new AdaptiveImageLoader(createQualityList());
+
+      loader.destroy();
+
+      expect(cancelImageUrl).toHaveBeenCalledWith('/thumbnail.jpg');
+      expect(cancelImageUrl).toHaveBeenCalledWith('/preview.jpg');
+      expect(cancelImageUrl).toHaveBeenCalledWith('/original.jpg');
+    });
+
+    it('calls destroy functions when imageLoader is provided', () => {
+      const destroyFn = vi.fn();
+      const imageLoader = vi.fn(() => destroyFn);
+      const loader = new AdaptiveImageLoader(createQualityList(), undefined, imageLoader);
+
+      loader.start();
+      loader.destroy();
+
+      expect(destroyFn).toHaveBeenCalledOnce();
+      expect(cancelImageUrl).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('progressive loading flow', () => {
+    it('thumbnail load triggers preview via onAfterLoad', () => {
+      const triggerSpy = vi.fn();
+      const qualityList = createQualityList({
+        onAfterLoad: {
+          thumbnail: (loader) => {
+            triggerSpy();
+            loader.trigger('preview');
+          },
+        },
+      });
+      const loader = new AdaptiveImageLoader(qualityList);
+
+      loader.onLoad('thumbnail');
+
+      expect(triggerSpy).toHaveBeenCalledOnce();
+      expect(loader.status.urls.preview).toBe('/preview.jpg');
+    });
+
+    it('thumbnail error triggers preview via onAfterError', () => {
+      const qualityList = createQualityList({
+        onAfterError: {
+          thumbnail: (loader) => loader.trigger('preview'),
+        },
+      });
+      const loader = new AdaptiveImageLoader(qualityList);
+
+      loader.onError('thumbnail');
+
+      expect(loader.status.urls.preview).toBe('/preview.jpg');
+    });
+  });
+});

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

@@ -0,0 +1,164 @@
+import type { LoadImageFunction } from '$lib/actions/image-loader.svelte';
+import { cancelImageUrl } from '$lib/utils/sw-messaging';
+
+export type ImageQuality = 'thumbnail' | 'preview' | 'original';
+
+export type ImageStatus = 'unloaded' | 'success' | 'error';
+
+export type ImageLoaderStatus = {
+  urls: Record<ImageQuality, string | undefined>;
+  quality: Record<ImageQuality, ImageStatus>;
+  started: boolean;
+  hasError: boolean;
+};
+
+type ImageLoaderCallbacks = {
+  onUrlChange?: (url: string) => void;
+  onImageReady?: () => void;
+  onError?: () => void;
+};
+
+export type QualityConfig = {
+  url: string;
+  quality: ImageQuality;
+  onAfterLoad?: (loader: AdaptiveImageLoader) => void;
+  onAfterError?: (loader: AdaptiveImageLoader) => void;
+};
+
+export type QualityList = [
+  QualityConfig & { quality: 'thumbnail' },
+  QualityConfig & { quality: 'preview' },
+  QualityConfig & { quality: 'original' },
+];
+
+export class AdaptiveImageLoader {
+  private destroyFunctions: (() => void)[] = [];
+  private qualityConfigs: Record<ImageQuality, QualityConfig>;
+  private highestLoadedQualityIndex = -1;
+  private destroyed = false;
+
+  status = $state<ImageLoaderStatus>({
+    started: false,
+    hasError: false,
+    urls: { thumbnail: undefined, preview: undefined, original: undefined },
+    quality: { thumbnail: 'unloaded', preview: 'unloaded', original: 'unloaded' },
+  });
+
+  constructor(
+    private readonly qualityList: QualityList,
+    private readonly callbacks?: ImageLoaderCallbacks,
+    private readonly imageLoader?: LoadImageFunction,
+  ) {
+    this.qualityConfigs = {
+      thumbnail: qualityList[0],
+      preview: qualityList[1],
+      original: qualityList[2],
+    };
+    this.status.urls.thumbnail = qualityList[0].url;
+  }
+
+  start() {
+    if (!this.imageLoader) {
+      throw new Error('Start requires imageLoader to be specified');
+    }
+
+    this.destroyFunctions.push(
+      this.imageLoader(
+        this.qualityList[0].url,
+        () => this.onLoad('thumbnail'),
+        () => this.onError('thumbnail'),
+        () => this.onStart('thumbnail'),
+      ),
+    );
+  }
+
+  onStart(_: ImageQuality) {
+    if (this.destroyed) {
+      return;
+    }
+    this.status.started = true;
+  }
+
+  onLoad(quality: ImageQuality) {
+    if (this.destroyed) {
+      return;
+    }
+
+    const config = this.qualityConfigs[quality];
+
+    if (!this.status.urls[quality]) {
+      return;
+    }
+
+    const index = this.qualityList.indexOf(config);
+    if (index <= this.highestLoadedQualityIndex) {
+      return;
+    }
+
+    this.highestLoadedQualityIndex = index;
+    this.status.quality[quality] = 'success';
+    this.callbacks?.onUrlChange?.(this.qualityConfigs[quality].url);
+    this.callbacks?.onImageReady?.();
+
+    config.onAfterLoad?.(this);
+  }
+
+  onError(quality: ImageQuality) {
+    if (this.destroyed) {
+      return;
+    }
+
+    const config = this.qualityConfigs[quality];
+
+    this.status.hasError = true;
+    this.status.quality[quality] = 'error';
+    this.status.urls[quality] = undefined;
+    this.callbacks?.onError?.();
+
+    config.onAfterError?.(this);
+  }
+
+  trigger(quality: ImageQuality) {
+    if (this.destroyed) {
+      return false;
+    }
+
+    const url = this.qualityConfigs[quality].url;
+    if (!url) {
+      this.qualityConfigs[quality].onAfterError?.(this);
+      return false;
+    }
+
+    if (this.status.urls[quality]) {
+      return true;
+    }
+
+    this.status.hasError = false;
+    this.status.urls[quality] = url;
+    if (this.imageLoader) {
+      this.destroyFunctions.push(
+        this.imageLoader(
+          url,
+          () => this.onLoad(quality),
+          () => this.onError(quality),
+          () => this.onStart(quality),
+        ),
+      );
+    }
+    return false;
+  }
+
+  destroy() {
+    this.destroyed = true;
+    if (this.imageLoader) {
+      for (const destroy of this.destroyFunctions) {
+        destroy();
+      }
+      return;
+    }
+
+    for (const config of Object.values(this.qualityConfigs)) {
+      cancelImageUrl(config.url);
+    }
+  }
+}

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

@@ -224,6 +224,8 @@ const supportedImageMimeTypes = new Set([
   'image/webp',
 ]);
 
+export const isFirefox = typeof navigator !== 'undefined' && navigator.userAgent.includes('Firefox');
+
 async function addSupportedMimeTypes(): Promise<void> {
   const isSafari = /^((?!chrome|android).)*safari/i.test(navigator.userAgent); // https://stackoverflow.com/a/23522755
   if (isSafari) {

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

@@ -5,6 +5,19 @@ export interface ContentMetrics {
   offsetY: number;
 }
 
+export const scaleToCover = (
+  dimensions: { width: number; height: number },
+  container: { width: number; height: number },
+): { width: number; height: number } => {
+  const scaleX = container.width / dimensions.width;
+  const scaleY = container.height / dimensions.height;
+  const scale = Math.max(scaleX, scaleY);
+  return {
+    width: dimensions.width * scale,
+    height: dimensions.height * scale,
+  };
+};
+
 export const scaleToFit = (
   dimensions: { width: number; height: number },
   container: { width: number; height: number },

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

@@ -0,0 +1,54 @@
+import { scaleToFit } from '$lib/utils/container-utils';
+
+describe('scaleToFit', () => {
+  const tests = [
+    {
+      name: 'landscape image in square container',
+      dimensions: { width: 2000, height: 1000 },
+      container: { width: 500, height: 500 },
+      expected: { width: 500, height: 250 },
+    },
+    {
+      name: 'portrait image in square container',
+      dimensions: { width: 1000, height: 2000 },
+      container: { width: 500, height: 500 },
+      expected: { width: 250, height: 500 },
+    },
+    {
+      name: 'square image in square container',
+      dimensions: { width: 1000, height: 1000 },
+      container: { width: 500, height: 500 },
+      expected: { width: 500, height: 500 },
+    },
+    {
+      name: 'landscape image in landscape container',
+      dimensions: { width: 1600, height: 900 },
+      container: { width: 800, height: 600 },
+      expected: { width: 800, height: 450 },
+    },
+    {
+      name: 'portrait image in portrait container',
+      dimensions: { width: 900, height: 1600 },
+      container: { width: 600, height: 800 },
+      expected: { width: 450, height: 800 },
+    },
+    {
+      name: 'image matches container exactly',
+      dimensions: { width: 500, height: 300 },
+      container: { width: 500, height: 300 },
+      expected: { width: 500, height: 300 },
+    },
+    {
+      name: 'image smaller than container scales up',
+      dimensions: { width: 100, height: 50 },
+      container: { width: 400, height: 400 },
+      expected: { width: 400, height: 200 },
+    },
+  ];
+
+  for (const { name, dimensions, container, expected } of tests) {
+    it(`should handle ${name}`, () => {
+      expect(scaleToFit(dimensions, container)).toEqual(expected);
+    });
+  }
+});