feat(web): face overlay hover UX and face editor zoom preservation

Change-Id: I7164305d7764bec54fa06b8738cd97fd6a6a6964 refactor(web): use asset metadata for face editor image dimensions instead of DOM The face editor previously read naturalWidth/naturalHeight from the DOM element via a $effect + load event listener. This was fragile on slow hardware (ARM CI) because imgRef changes as AdaptiveImage progresses through quality levels, and the DOM element's natural dimensions could be 0 during transitions. Now the face editor receives imageSize as a prop from the parent, derived from the asset's metadata dimensions which are always available immediately. Change-Id: Id4c3a59110feff4c50f429bbd744eac46a6a6964 Change-Id: I7164305d7764bec54fa06b8738cd97fd6a6a6964
2026-03-26 11:50:53 +03:00 · 2026-03-19 13:02:46 +00:00
parent ed04d87273
commit 590a9df7ec
21 changed files with 1147 additions and 208 deletions
--- a/web/src/lib/components/AdaptiveImage.svelte
+++ b/web/src/lib/components/AdaptiveImage.svelte
@@ -23,6 +23,8 @@
    onError?: () => void;
    ref?: HTMLDivElement;
    imgRef?: HTMLImageElement;
+    imgNaturalSize?: Size;
+    imgScaledSize?: Size;
    backdrop?: Snippet;
    overlays?: Snippet;
  };
@@ -31,6 +33,10 @@
    ref = $bindable(),
    // eslint-disable-next-line no-useless-assignment
    imgRef = $bindable(),
+    // eslint-disable-next-line no-useless-assignment
+    imgNaturalSize = $bindable(),
+    // eslint-disable-next-line no-useless-assignment
+    imgScaledSize = $bindable(),
    asset,
    sharedLink,
    objectFit = 'contain',
@@ -98,9 +104,21 @@
    return { width: 1, height: 1 };
  });

-  const { width, height, left, top } = $derived.by(() => {
+  $effect(() => {
+    imgNaturalSize = imageDimensions;
+  });
+
+  const scaledDimensions = $derived.by(() => {
    const scaleFn = objectFit === 'cover' ? scaleToCover : scaleToFit;
-    const { width, height } = scaleFn(imageDimensions, container);
+    return scaleFn(imageDimensions, container);
+  });
+
+  $effect(() => {
+    imgScaledSize = scaledDimensions;
+  });
+
+  const { width, height, left, top } = $derived.by(() => {
+    const { width, height } = scaledDimensions;
    return {
      width: width + 'px',
      height: height + 'px',
--- a/web/src/lib/components/asset-viewer/asset-viewer.svelte
+++ b/web/src/lib/components/asset-viewer/asset-viewer.svelte
@@ -59,7 +59,7 @@
    previousAsset?: AssetResponseDto;
  };

-  interface Props {
+  type Props = {
    cursor: AssetCursor;
    showNavigation?: boolean;
    withStacked?: boolean;
@@ -72,7 +72,7 @@
    onUndoDelete?: OnUndoDelete;
    onClose?: (asset: AssetResponseDto) => void;
    onRandom?: () => Promise<{ id: string } | undefined>;
-  }
+  };

  let {
    cursor,
@@ -176,6 +176,7 @@
  onDestroy(() => {
    activityManager.reset();
    assetViewerManager.closeEditor();
+    isFaceEditMode.value = false;
    syncAssetViewerOpenClass(false);
    preloadManager.destroy();
  });
@@ -290,6 +291,9 @@

  const handleStackedAssetMouseEvent = (isMouseOver: boolean, stackedAsset: AssetResponseDto) => {
    previewStackedAsset = isMouseOver ? stackedAsset : undefined;
+    if (isMouseOver) {
+      isFaceEditMode.value = false;
+    }
  };

  const handlePreAction = (action: Action) => {
@@ -358,15 +362,18 @@
    }
  };

+  const refreshOcr = async () => {
+    ocrManager.clear();
+    if (sharedLink) {
+      return;
+    }
+
+    await ocrManager.getAssetOcr(asset.id);
+  };
+
  const refresh = async () => {
    await refreshStack();
-    ocrManager.clear();
-    if (!sharedLink) {
-      if (previewStackedAsset) {
-        await ocrManager.getAssetOcr(previewStackedAsset.id);
-      }
-      await ocrManager.getAssetOcr(asset.id);
-    }
+    await refreshOcr();
  };

  $effect(() => {
@@ -375,6 +382,12 @@
    untrack(() => handlePromiseError(refresh()));
  });

+  $effect(() => {
+    // eslint-disable-next-line @typescript-eslint/no-unused-expressions
+    previewStackedAsset;
+    untrack(() => ocrManager.clear());
+  });
+
  let lastCursor = $state<AssetCursor>();

  $effect(() => {
@@ -460,7 +473,7 @@

 <section
  id="immich-asset-viewer"
-  class="fixed start-0 top-0 grid size-full grid-cols-4 grid-rows-[64px_1fr] overflow-hidden bg-black"
+  class="fixed start-0 top-0 grid size-full grid-cols-4 grid-rows-[64px_1fr] overflow-hidden bg-black touch-none"
  use:focusTrap
  bind:this={assetViewerHtmlElement}
 >
@@ -612,6 +625,7 @@
              onClick={() => {
                cursor.current = stackedAsset;
                previewStackedAsset = undefined;
+                isFaceEditMode.value = false;
              }}
              onMouseEvent={({ isMouseOver }) => handleStackedAssetMouseEvent(isMouseOver, stackedAsset)}
              readonly
--- a/web/src/lib/components/asset-viewer/detail-panel.svelte
+++ b/web/src/lib/components/asset-viewer/detail-panel.svelte
@@ -7,10 +7,11 @@
  import { timeToLoadTheMap } from '$lib/constants';
  import { assetViewerManager } from '$lib/managers/asset-viewer-manager.svelte';
  import { authManager } from '$lib/managers/auth-manager.svelte';
+  import { eventManager } from '$lib/managers/event-manager.svelte';
  import { featureFlagsManager } from '$lib/managers/feature-flags-manager.svelte';
  import AssetChangeDateModal from '$lib/modals/AssetChangeDateModal.svelte';
  import { Route } from '$lib/route';
-  import { isFaceEditMode } from '$lib/stores/face-edit.svelte';
+  import { isEditFacesPanelOpen, isFaceEditMode } from '$lib/stores/face-edit.svelte';
  import { boundingBoxesArray } from '$lib/stores/people.store';
  import { locale } from '$lib/stores/preferences.store';
  import { preferences, user } from '$lib/stores/user.store';
@@ -49,15 +50,15 @@
  import UserAvatar from '../shared-components/user-avatar.svelte';
  import AlbumListItemDetails from './album-list-item-details.svelte';

-  interface Props {
+  type Props = {
    asset: AssetResponseDto;
    currentAlbum?: AlbumResponseDto | null;
-  }
+  };

  let { asset, currentAlbum = null }: Props = $props();

  let showAssetPath = $state(false);
-  let showEditFaces = $state(false);
+  let showEditFaces = $derived(isEditFacesPanelOpen.value);
  let isOwner = $derived($user?.id === asset.ownerId);
  let people = $derived(asset.people || []);
  let unassignedFaces = $derived(asset.unassignedFaces || []);
@@ -106,7 +107,7 @@
      return;
    }

-    showEditFaces = false;
+    isEditFacesPanelOpen.value = false;
    previousId = asset.id;
  });

@@ -122,7 +123,8 @@

  const handleRefreshPeople = async () => {
    asset = await getAssetInfo({ id: asset.id });
-    showEditFaces = false;
+    eventManager.emit('AssetUpdate', asset);
+    isEditFacesPanelOpen.value = false;
  };

  const getAssetFolderHref = (asset: AssetResponseDto) => {
@@ -219,7 +221,7 @@
              shape="round"
              color="secondary"
              variant="ghost"
-              onclick={() => (showEditFaces = true)}
+              onclick={() => (isEditFacesPanelOpen.value = true)}
            />
          {/if}
        </div>
@@ -228,13 +230,14 @@
      <div class="mt-2 flex flex-wrap gap-2">
        {#each people as person, index (person.id)}
          {#if showingHiddenPeople || !person.isHidden}
+            {@const isHighlighted = people[index].faces.some((f) => $boundingBoxesArray.some((b) => b.id === f.id))}
            <a
-              class="w-22"
+              class="group w-22 outline-none"
              href={Route.viewPerson(person, { previousRoute })}
              onfocus={() => ($boundingBoxesArray = people[index].faces)}
              onblur={() => ($boundingBoxesArray = [])}
-              onmouseover={() => ($boundingBoxesArray = people[index].faces)}
-              onmouseleave={() => ($boundingBoxesArray = [])}
+              onpointerover={() => ($boundingBoxesArray = people[index].faces)}
+              onpointerleave={() => ($boundingBoxesArray = [])}
            >
              <div class="relative">
                <ImageThumbnail
@@ -246,6 +249,8 @@
                  widthStyle="90px"
                  heightStyle="90px"
                  hidden={person.isHidden}
+                  highlighted={isHighlighted}
+                  class="group-focus-visible:outline-2 group-focus-visible:outline-offset-2 group-focus-visible:outline-immich-primary dark:group-focus-visible:outline-immich-dark-primary"
                />
              </div>
              <p class="mt-1 truncate font-medium" title={person.name}>{person.name}</p>
@@ -574,7 +579,7 @@
  <PersonSidePanel
    assetId={asset.id}
    assetType={asset.type}
-    onClose={() => (showEditFaces = false)}
+    onClose={() => (isEditFacesPanelOpen.value = false)}
    onRefresh={handleRefreshPeople}
  />
 {/if}
--- a/web/src/lib/components/asset-viewer/face-editor/face-editor.svelte
+++ b/web/src/lib/components/asset-viewer/face-editor/face-editor.svelte
@@ -1,10 +1,12 @@
 <script lang="ts">
  import ImageThumbnail from '$lib/components/assets/thumbnail/image-thumbnail.svelte';
+  import { assetViewerManager } from '$lib/managers/asset-viewer-manager.svelte';
  import { assetViewingStore } from '$lib/stores/asset-viewing.store';
  import { isFaceEditMode } from '$lib/stores/face-edit.svelte';
  import { getPeopleThumbnailUrl } from '$lib/utils';
-  import { getNaturalSize, scaleToFit } from '$lib/utils/container-utils';
+  import { computeContentMetrics, mapContentRectToNatural, type Size } from '$lib/utils/container-utils';
  import { handleError } from '$lib/utils/handle-error';
+  import { scaleFaceRectOnResize, type ResizeContext } from '$lib/utils/people-utils';
  import { createFace, getAllPeople, type PersonResponseDto } from '@immich/sdk';
  import { shortcut } from '$lib/actions/shortcut';
  import { Button, Input, modalManager, toastManager } from '@immich/ui';
@@ -12,17 +14,19 @@
  import { clamp } from 'lodash-es';
  import { onMount } from 'svelte';
  import { t } from 'svelte-i18n';
+  import { fade } from 'svelte/transition';

  type Props = {
-    htmlElement: HTMLImageElement | HTMLVideoElement;
+    imageSize: Size;
    containerWidth: number;
    containerHeight: number;
    assetId: string;
  };

-  let { htmlElement, containerWidth, containerHeight, assetId }: Props = $props();
+  let { imageSize, containerWidth, containerHeight, assetId }: Props = $props();

  let canvasEl: HTMLCanvasElement | undefined = $state();
+  let containerEl: HTMLDivElement | undefined = $state();
  let canvas: Canvas | undefined = $state();
  let faceRect: Rect | undefined = $state();
  let faceSelectorEl: HTMLDivElement | undefined = $state();
@@ -32,6 +36,9 @@

  let searchTerm = $state('');
  let faceBoxPosition = $state({ left: 0, top: 0, width: 0, height: 0 });
+  let userMovedRect = false;
+  let previousMetrics: ResizeContext | null = null;
+  let panModifierHeld = $state(false);

  let filteredCandidates = $derived(
    searchTerm
@@ -53,11 +60,12 @@
  };

  const setupCanvas = () => {
-    if (!canvasEl || !htmlElement) {
+    if (!canvasEl) {
      return;
    }

-    canvas = new Canvas(canvasEl);
+    canvas = new Canvas(canvasEl, { width: containerWidth, height: containerHeight });
+    canvas.selection = false;
    configureControlStyle();

    // eslint-disable-next-line tscompat/tscompat
@@ -75,66 +83,103 @@

    canvas.add(faceRect);
    canvas.setActiveObject(faceRect);
-    setDefaultFaceRectanglePosition(faceRect);
  };

-  onMount(async () => {
-    setupCanvas();
-    await getPeople();
+  onMount(() => {
+    void getPeople();
  });

-  const imageContentMetrics = $derived.by(() => {
-    const natural = getNaturalSize(htmlElement);
-    const container = { width: containerWidth, height: containerHeight };
-    const { width: contentWidth, height: contentHeight } = scaleToFit(natural, container);
-    return {
-      contentWidth,
-      contentHeight,
-      offsetX: (containerWidth - contentWidth) / 2,
-      offsetY: (containerHeight - contentHeight) / 2,
-    };
-  });
-
-  const setDefaultFaceRectanglePosition = (faceRect: Rect) => {
-    const { offsetX, offsetY } = imageContentMetrics;
-
-    faceRect.set({
-      top: offsetY + 200,
-      left: offsetX + 200,
-    });
-
-    faceRect.setCoords();
-    positionFaceSelector();
-  };
-
  $effect(() => {
    if (!canvas) {
      return;
    }

-    canvas.setDimensions({
-      width: containerWidth,
-      height: containerHeight,
-    });
+    const upperCanvas = canvas.upperCanvasEl;
+    const controller = new AbortController();
+    const { signal } = controller;

-    if (!faceRect) {
+    const stopIfOnTarget = (event: PointerEvent) => {
+      if (canvas?.findTarget(event).target) {
+        event.stopPropagation();
+      }
+    };
+
+    const handlePointerDown = (event: PointerEvent) => {
+      if (!canvas) {
+        return;
+      }
+      if (canvas.findTarget(event).target) {
+        event.stopPropagation();
+        return;
+      }
+      if (faceRect) {
+        event.stopPropagation();
+        const pointer = canvas.getScenePoint(event);
+        faceRect.set({ left: pointer.x, top: pointer.y });
+        faceRect.setCoords();
+        userMovedRect = true;
+        canvas.renderAll();
+        positionFaceSelector();
+      }
+    };
+
+    upperCanvas.addEventListener('pointerdown', handlePointerDown, { signal });
+    upperCanvas.addEventListener('pointermove', stopIfOnTarget, { signal });
+    upperCanvas.addEventListener('pointerup', stopIfOnTarget, { signal });
+
+    return () => {
+      controller.abort();
+    };
+  });
+
+  const imageContentMetrics = $derived.by(() => {
+    if (imageSize.width === 0 || imageSize.height === 0) {
+      return { contentWidth: 0, contentHeight: 0, offsetX: 0, offsetY: 0 };
+    }
+    return computeContentMetrics(imageSize, { width: containerWidth, height: containerHeight });
+  });
+
+  const setDefaultFaceRectanglePosition = (faceRect: Rect) => {
+    const { offsetX, offsetY, contentWidth, contentHeight } = imageContentMetrics;
+
+    faceRect.set({
+      top: offsetY + contentHeight / 2 - 56,
+      left: offsetX + contentWidth / 2 - 56,
+    });
+  };
+
+  $effect(() => {
+    const { offsetX, offsetY, contentWidth } = imageContentMetrics;
+
+    if (contentWidth === 0) {
      return;
    }

-    if (!isFaceRectIntersectingCanvas(faceRect, canvas)) {
+    const isFirstRun = previousMetrics === null;
+
+    if (isFirstRun && !canvas) {
+      setupCanvas();
+    }
+
+    if (!canvas || !faceRect) {
+      return;
+    }
+
+    if (!isFirstRun) {
+      canvas.setDimensions({ width: containerWidth, height: containerHeight });
+    }
+
+    if (!isFirstRun && userMovedRect && previousMetrics) {
+      faceRect.set(scaleFaceRectOnResize(faceRect, previousMetrics, { contentWidth, offsetX, offsetY }));
+    } else {
      setDefaultFaceRectanglePosition(faceRect);
    }
-  });

-  const isFaceRectIntersectingCanvas = (faceRect: Rect, canvas: Canvas) => {
-    const faceBox = faceRect.getBoundingRect();
-    return !(
-      0 > faceBox.left + faceBox.width ||
-      0 > faceBox.top + faceBox.height ||
-      canvas.width < faceBox.left ||
-      canvas.height < faceBox.top
-    );
-  };
+    faceRect.setCoords();
+    previousMetrics = { contentWidth, offsetX, offsetY };
+    canvas.renderAll();
+    positionFaceSelector();
+  });

  const cancel = () => {
    isFaceEditMode.value = false;
@@ -164,11 +209,15 @@
    const gap = 15;
    const padding = faceRect.padding ?? 0;
    const rawBox = faceRect.getBoundingRect();
+    if (Number.isNaN(rawBox.left) || Number.isNaN(rawBox.width)) {
+      return;
+    }
+    const { currentZoom, currentPositionX, currentPositionY } = assetViewerManager.zoomState;
    const faceBox = {
-      left: rawBox.left - padding,
-      top: rawBox.top - padding,
-      width: rawBox.width + padding * 2,
-      height: rawBox.height + padding * 2,
+      left: (rawBox.left - padding) * currentZoom + currentPositionX,
+      top: (rawBox.top - padding) * currentZoom + currentPositionY,
+      width: (rawBox.width + padding * 2) * currentZoom,
+      height: (rawBox.height + padding * 2) * currentZoom,
    };
    const selectorWidth = faceSelectorEl.offsetWidth;
    const chromeHeight = faceSelectorEl.offsetHeight - scrollableListEl.offsetHeight;
@@ -178,20 +227,21 @@
    const clampTop = (top: number) => clamp(top, gap, containerHeight - selectorHeight - gap);
    const clampLeft = (left: number) => clamp(left, gap, containerWidth - selectorWidth - gap);

-    const overlapArea = (position: { top: number; left: number }) => {
-      const selectorRight = position.left + selectorWidth;
-      const selectorBottom = position.top + selectorHeight;
-      const faceRight = faceBox.left + faceBox.width;
-      const faceBottom = faceBox.top + faceBox.height;
+    const faceRight = faceBox.left + faceBox.width;
+    const faceBottom = faceBox.top + faceBox.height;

-      const overlapX = Math.max(0, Math.min(selectorRight, faceRight) - Math.max(position.left, faceBox.left));
-      const overlapY = Math.max(0, Math.min(selectorBottom, faceBottom) - Math.max(position.top, faceBox.top));
+    const overlapArea = (position: { top: number; left: number }) => {
+      const overlapX = Math.max(
+        0,
+        Math.min(position.left + selectorWidth, faceRight) - Math.max(position.left, faceBox.left),
+      );
+      const overlapY = Math.max(
+        0,
+        Math.min(position.top + selectorHeight, faceBottom) - Math.max(position.top, faceBox.top),
+      );
      return overlapX * overlapY;
    };

-    const faceBottom = faceBox.top + faceBox.height;
-    const faceRight = faceBox.left + faceBox.width;
-
    const positions = [
      { top: clampTop(faceBottom + gap), left: clampLeft(faceBox.left) },
      { top: clampTop(faceBox.top - selectorHeight - gap), left: clampLeft(faceBox.left) },
@@ -213,45 +263,139 @@
      }
    }

-    faceSelectorEl.style.top = `${bestPosition.top}px`;
-    faceSelectorEl.style.left = `${bestPosition.left}px`;
+    const containerRect = containerEl?.getBoundingClientRect();
+    const offsetTop = containerRect?.top ?? 0;
+    const offsetLeft = containerRect?.left ?? 0;
+    faceSelectorEl.style.top = `${bestPosition.top + offsetTop}px`;
+    faceSelectorEl.style.left = `${bestPosition.left + offsetLeft}px`;
    scrollableListEl.style.height = `${listHeight}px`;
-    faceBoxPosition = { left: faceBox.left, top: faceBox.top, width: faceBox.width, height: faceBox.height };
+    faceBoxPosition = faceBox;
  };

+  $effect(() => {
+    if (!canvas) {
+      return;
+    }
+
+    const { currentZoom, currentPositionX, currentPositionY } = assetViewerManager.zoomState;
+    canvas.setViewportTransform([currentZoom, 0, 0, currentZoom, currentPositionX, currentPositionY]);
+    canvas.renderAll();
+    positionFaceSelector();
+  });
+
  $effect(() => {
    const rect = faceRect;
    if (rect) {
-      rect.on('moving', positionFaceSelector);
-      rect.on('scaling', positionFaceSelector);
+      const onUserMove = () => {
+        userMovedRect = true;
+        positionFaceSelector();
+      };
+      rect.on('moving', onUserMove);
+      rect.on('scaling', onUserMove);
      return () => {
-        rect.off('moving', positionFaceSelector);
-        rect.off('scaling', positionFaceSelector);
+        rect.off('moving', onUserMove);
+        rect.off('scaling', onUserMove);
      };
    }
  });

+  const isMac = typeof navigator !== 'undefined' && /Mac|iPhone|iPad|iPod/.test(navigator.userAgent);
+  const panModifierKey = isMac ? 'Meta' : 'Control';
+  const panModifierLabel = isMac ? '⌘' : 'Ctrl';
+  const isZoomed = $derived(assetViewerManager.zoom > 1);
+
+  $effect(() => {
+    if (!containerEl) {
+      return;
+    }
+    const element = containerEl;
+    const parent = element.parentElement;
+
+    const activate = () => {
+      panModifierHeld = true;
+      element.style.pointerEvents = 'none';
+      if (parent) {
+        parent.style.cursor = 'move';
+      }
+    };
+
+    const deactivate = () => {
+      panModifierHeld = false;
+      element.style.pointerEvents = '';
+      if (parent) {
+        parent.style.cursor = '';
+      }
+    };
+
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (event.key === panModifierKey) {
+        activate();
+      }
+    };
+    const onKeyUp = (event: KeyboardEvent) => {
+      if (event.key === panModifierKey) {
+        deactivate();
+      }
+    };
+
+    document.addEventListener('keydown', onKeyDown);
+    document.addEventListener('keyup', onKeyUp);
+    window.addEventListener('blur', deactivate);
+
+    return () => {
+      document.removeEventListener('keydown', onKeyDown);
+      document.removeEventListener('keyup', onKeyUp);
+      window.removeEventListener('blur', deactivate);
+      deactivate();
+    };
+  });
+
+  const trapEvents = (node: HTMLElement) => {
+    const stop = (e: Event) => e.stopPropagation();
+    const eventTypes = ['keydown', 'pointerdown', 'pointermove', 'pointerup'] as const;
+    for (const type of eventTypes) {
+      node.addEventListener(type, stop);
+    }
+
+    // Move to body so the selector isn't affected by the zoom transform on the container
+    document.body.append(node);
+
+    return {
+      destroy() {
+        for (const type of eventTypes) {
+          node.removeEventListener(type, stop);
+        }
+        node.remove();
+      },
+    };
+  };
+
  const getFaceCroppedCoordinates = () => {
-    if (!faceRect || !htmlElement) {
+    if (!faceRect || imageSize.width === 0 || imageSize.height === 0) {
      return;
    }

-    const { left, top, width, height } = faceRect.getBoundingRect();
-    const { offsetX, offsetY, contentWidth, contentHeight } = imageContentMetrics;
-    const natural = getNaturalSize(htmlElement);
+    const scaledWidth = faceRect.getScaledWidth();
+    const scaledHeight = faceRect.getScaledHeight();

-    const scaleX = natural.width / contentWidth;
-    const scaleY = natural.height / contentHeight;
-    const imageX = (left - offsetX) * scaleX;
-    const imageY = (top - offsetY) * scaleY;
+    const imageRect = mapContentRectToNatural(
+      {
+        left: faceRect.left - scaledWidth / 2,
+        top: faceRect.top - scaledHeight / 2,
+        width: scaledWidth,
+        height: scaledHeight,
+      },
+      imageContentMetrics,
+      imageSize,
+    );

    return {
-      imageWidth: natural.width,
-      imageHeight: natural.height,
-      x: Math.floor(imageX),
-      y: Math.floor(imageY),
-      width: Math.floor(width * scaleX),
-      height: Math.floor(height * scaleY),
+      imageWidth: imageSize.width,
+      imageHeight: imageSize.height,
+      x: Math.floor(imageRect.left),
+      y: Math.floor(imageRect.top),
+      width: Math.floor(imageRect.width),
+      height: Math.floor(imageRect.height),
    };
  };

@@ -282,10 +426,9 @@
      });

      await assetViewingStore.setAssetId(assetId);
+      isFaceEditMode.value = false;
    } catch (error) {
      handleError(error, 'Error tagging face');
-    } finally {
-      isFaceEditMode.value = false;
    }
  };
 </script>
@@ -294,8 +437,8 @@

 <div
  id="face-editor-data"
+  bind:this={containerEl}
  class="absolute start-0 top-0 z-5 h-full w-full overflow-hidden"
-  data-overlay-interactive
  data-face-left={faceBoxPosition.left}
  data-face-top={faceBoxPosition.top}
  data-face-width={faceBoxPosition.width}
@@ -306,7 +449,9 @@
  <div
    id="face-selector"
    bind:this={faceSelectorEl}
-    class="absolute top-[calc(50%-250px)] start-[calc(50%-125px)] max-w-[250px] w-[250px] bg-white dark:bg-immich-dark-gray dark:text-immich-dark-fg backdrop-blur-sm px-2 py-4 rounded-xl border border-gray-200 dark:border-gray-800 transition-[top,left] duration-200 ease-out"
+    class="fixed z-20 w-[min(200px,45vw)] min-w-48 bg-white dark:bg-immich-dark-gray dark:text-immich-dark-fg backdrop-blur-sm px-2 py-4 rounded-xl border border-gray-200 dark:border-gray-800 transition-[top,left] duration-200 ease-out"
+    use:trapEvents
+    onwheel={(e) => e.stopPropagation()}
  >
    <p class="text-center text-sm">{$t('select_person_to_tag')}</p>

@@ -347,4 +492,15 @@

    <Button size="small" fullWidth onclick={cancel} color="danger" class="mt-2">{$t('cancel')}</Button>
  </div>
+
+  {#if isZoomed && !panModifierHeld}
+    <div
+      transition:fade={{ duration: 200 }}
+      class="absolute bottom-4 inset-s-1/2 -translate-x-1/2 pointer-events-none z-10"
+    >
+      <p class="bg-black/60 text-white text-xs px-3 py-1.5 rounded-full whitespace-nowrap">
+        {$t('hold_key_to_pan', { values: { key: panModifierLabel } })}
+      </p>
+    </div>
+  {/if}
 </div>
--- a/web/src/lib/components/asset-viewer/photo-viewer.svelte
+++ b/web/src/lib/components/asset-viewer/photo-viewer.svelte
@@ -8,13 +8,13 @@
  import AssetViewerEvents from '$lib/components/AssetViewerEvents.svelte';
  import { assetViewerManager } from '$lib/managers/asset-viewer-manager.svelte';
  import { castManager } from '$lib/managers/cast-manager.svelte';
-  import { isFaceEditMode } from '$lib/stores/face-edit.svelte';
+  import { isEditFacesPanelOpen, 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, slideshowStore } from '$lib/stores/slideshow.store';
  import { handlePromiseError } from '$lib/utils';
  import { canCopyImageToClipboard, copyImageToClipboard } from '$lib/utils/asset-utils';
-  import { getNaturalSize, scaleToFit, type Size } from '$lib/utils/container-utils';
+  import type { Size } 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';
@@ -67,13 +67,10 @@
    height: containerHeight,
  });

-  const overlaySize = $derived.by((): Size => {
-    if (!assetViewerManager.imgRef || !visibleImageReady) {
-      return { width: 0, height: 0 };
-    }
+  let imageDimensions = $state<Size>({ width: 0, height: 0 });
+  let scaledDimensions = $state<Size>({ width: 0, height: 0 });

-    return scaleToFit(getNaturalSize(assetViewerManager.imgRef), { width: containerWidth, height: containerHeight });
-  });
+  const overlaySize = $derived(visibleImageReady ? scaledDimensions : { width: 0, height: 0 });

  const ocrBoxes = $derived(ocrManager.showOverlay ? getOcrBoundingBoxes(ocrManager.data, overlaySize) : []);

@@ -97,12 +94,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') {
@@ -147,46 +138,22 @@

  const faceToNameMap = $derived.by(() => {
    // eslint-disable-next-line svelte/prefer-svelte-reactivity
-    const map = new Map<Faces, string>();
+    const map = new Map<Faces, string | undefined>();
    for (const person of asset.people ?? []) {
      for (const face of person.faces ?? []) {
        map.set(face, person.name);
      }
    }
+    for (const face of asset.unassignedFaces ?? []) {
+      map.set(face, undefined);
+    }
    return map;
  });

+  // Array needed for indexed access in the template (faces[index])
  const faces = $derived(Array.from(faceToNameMap.keys()));
-
-  const handleImageMouseMove = (event: MouseEvent) => {
-    $boundingBoxesArray = [];
-    if (!assetViewerManager.imgRef || !element || isFaceEditMode.value || ocrManager.showOverlay) {
-      return;
-    }
-
-    const natural = getNaturalSize(assetViewerManager.imgRef);
-    const scaled = scaleToFit(natural, container);
-    const { currentZoom, currentPositionX, currentPositionY } = assetViewerManager.zoomState;
-
-    const contentOffsetX = (container.width - scaled.width) / 2;
-    const contentOffsetY = (container.height - scaled.height) / 2;
-
-    const containerRect = element.getBoundingClientRect();
-    const mouseX = (event.clientX - containerRect.left - contentOffsetX * currentZoom - currentPositionX) / currentZoom;
-    const mouseY = (event.clientY - containerRect.top - contentOffsetY * currentZoom - currentPositionY) / currentZoom;
-
-    const faceBoxes = getBoundingBox(faces, overlaySize);
-
-    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 = [];
-  };
+  const boundingBoxes = $derived(getBoundingBox(faces, overlaySize));
+  const activeBoundingBoxes = $derived(boundingBoxes.filter((box) => $boundingBoxesArray.some((f) => f.id === box.id)));
 </script>

 <AssetViewerEvents {onCopy} {onZoom} />
@@ -207,8 +174,6 @@
  bind:clientHeight={containerHeight}
  role="presentation"
  ondblclick={onZoom}
-  onmousemove={handleImageMouseMove}
-  onmouseleave={handleImageMouseLeave}
  use:zoomImageAction={{ zoomTarget: adaptiveImage }}
  {...useSwipe((event) => onSwipe?.(event))}
 >
@@ -227,6 +192,8 @@
      onReady?.();
    }}
    bind:imgRef={assetViewerManager.imgRef}
+    bind:imgNaturalSize={imageDimensions}
+    bind:imgScaledSize={scaledDimensions}
    bind:ref={adaptiveImage}
  >
    {#snippet backdrop()}
@@ -238,20 +205,40 @@
      {/if}
    {/snippet}
    {#snippet overlays()}
-      {#each getBoundingBox($boundingBoxesArray, overlaySize) as boundingbox, index (boundingbox.id)}
+      {#if !isFaceEditMode.value}
+        {#each boundingBoxes as boundingbox, index (boundingbox.id)}
+          {@const face = faces[index]}
+          {@const name = faceToNameMap.get(face)}
+          {#if name !== undefined || isEditFacesPanelOpen.value}
+            <!-- svelte-ignore a11y_no_static_element_interactions -->
+            <div
+              class="absolute pointer-events-auto outline-none rounded-lg"
+              style="top: {boundingbox.top}px; left: {boundingbox.left}px; height: {boundingbox.height}px; width: {boundingbox.width}px;"
+              aria-label="{$t('person')}: {name ?? $t('unknown')}"
+              onpointerenter={() => ($boundingBoxesArray = [face])}
+              onpointerleave={() => ($boundingBoxesArray = [])}
+            ></div>
+          {/if}
+        {/each}
+      {/if}
+
+      {#each activeBoundingBoxes as boundingbox (boundingbox.id)}
+        {@const face = faces.find((f) => f.id === boundingbox.id)}
+        {@const name = face ? faceToNameMap.get(face) : undefined}
        <div
-          class="absolute border-solid border-white border-3 rounded-lg"
+          class="absolute border-solid border-white border-3 rounded-lg pointer-events-none"
          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"
-            style="top: {boundingbox.top + boundingbox.height + 4}px; left: {boundingbox.left +
-              boundingbox.width}px; transform: translateX(-100%);"
-          >
-            {faceToNameMap.get($boundingBoxesArray[index])}
-          </div>
-        {/if}
+        >
+          {#if name}
+            <div
+              aria-hidden="true"
+              class="absolute bg-white/90 text-black px-2 py-1 rounded text-sm font-medium whitespace-nowrap shadow-lg"
+              style="top: {boundingbox.height + 4}px; right: 0;"
+            >
+              {name}
+            </div>
+          {/if}
+        </div>
      {/each}

      {#each ocrBoxes as ocrBox (ocrBox.id)}
@@ -261,6 +248,6 @@
  </AdaptiveImage>

  {#if isFaceEditMode.value && assetViewerManager.imgRef}
-    <FaceEditor htmlElement={assetViewerManager.imgRef} {containerWidth} {containerHeight} assetId={asset.id} />
+    <FaceEditor imageSize={imageDimensions} {containerWidth} {containerHeight} assetId={asset.id} />
  {/if}
 </div>
--- a/web/src/lib/components/asset-viewer/video-native-viewer.svelte
+++ b/web/src/lib/components/asset-viewer/video-native-viewer.svelte
@@ -11,14 +11,16 @@
    videoViewerVolume,
  } from '$lib/stores/preferences.store';
  import { getAssetMediaUrl, getAssetPlaybackUrl } from '$lib/utils';
+  import type { Size } from '$lib/utils/container-utils';
  import { AssetMediaSize } from '@immich/sdk';
  import { LoadingSpinner } from '@immich/ui';
  import { onDestroy, onMount } from 'svelte';
  import { useSwipe, type SwipeCustomEvent } from 'svelte-gestures';
  import { fade } from 'svelte/transition';

-  interface Props {
+  type Props = {
    assetId: string;
+    imageSize: Size;
    loopVideo: boolean;
    cacheKey: string | null;
    playOriginalVideo: boolean;
@@ -27,10 +29,11 @@
    onVideoEnded?: () => void;
    onVideoStarted?: () => void;
    onClose?: () => void;
-  }
+  };

  let {
    assetId,
+    imageSize,
    loopVideo,
    cacheKey,
    playOriginalVideo,
@@ -173,7 +176,7 @@
      {/if}

      {#if isFaceEditMode.value}
-        <FaceEditor htmlElement={videoPlayer} {containerWidth} {containerHeight} {assetId} />
+        <FaceEditor {imageSize} {containerWidth} {containerHeight} {assetId} />
      {/if}
    {/if}
  </div>
--- a/web/src/lib/components/asset-viewer/video-wrapper-viewer.svelte
+++ b/web/src/lib/components/asset-viewer/video-wrapper-viewer.svelte
@@ -4,7 +4,7 @@
  import { ProjectionType } from '$lib/constants';
  import type { AssetResponseDto } from '@immich/sdk';

-  interface Props {
+  type Props = {
    asset: AssetResponseDto;
    assetId?: string;
    projectionType: string | null | undefined;
@@ -16,7 +16,7 @@
    onNextAsset?: () => void;
    onVideoEnded?: () => void;
    onVideoStarted?: () => void;
-  }
+  };

  let {
    asset,
@@ -42,6 +42,7 @@
    {loopVideo}
    {cacheKey}
    assetId={effectiveAssetId}
+    imageSize={{ width: asset.width ?? 1, height: asset.height ?? 1 }}
    {playOriginalVideo}
    {onPreviousAsset}
    {onNextAsset}
--- a/web/src/lib/components/assets/thumbnail/image-thumbnail.svelte
+++ b/web/src/lib/components/assets/thumbnail/image-thumbnail.svelte
@@ -16,6 +16,7 @@
    circle?: boolean;
    hidden?: boolean;
    border?: boolean;
+    highlighted?: boolean;
    hiddenIconClass?: string;
    class?: ClassValue;
    brokenAssetClass?: ClassValue;
@@ -34,6 +35,7 @@
    circle = false,
    hidden = false,
    border = false,
+    highlighted = false,
    hiddenIconClass = 'text-white',
    onComplete = undefined,
    class: imageClass = '',
@@ -83,6 +85,10 @@
  />
 {/if}

+{#if highlighted}
+  <span class={['absolute inset-0 pointer-events-none border-2 border-white', sharedClasses]} {style}></span>
+{/if}
+
 {#if hidden}
  <div class="absolute start-1/2 top-1/2 translate-x-[-50%] translate-y-[-50%] transform">
    <!-- TODO fix `title` type -->
--- a/web/src/lib/components/faces-page/person-side-panel.svelte
+++ b/web/src/lib/components/faces-page/person-side-panel.svelte
@@ -27,12 +27,12 @@
  import ImageThumbnail from '../assets/thumbnail/image-thumbnail.svelte';
  import AssignFaceSidePanel from './assign-face-side-panel.svelte';

-  interface Props {
+  type Props = {
    assetId: string;
    assetType: AssetTypeEnum;
    onClose: () => void;
    onRefresh: () => void;
-  }
+  };

  let { assetId, assetType, onClose, onRefresh }: Props = $props();

@@ -58,6 +58,8 @@
  let automaticRefreshTimeout: ReturnType<typeof setTimeout>;

  const thumbnailWidth = '90px';
+  const focusHighlightClass =
+    'group-focus-visible:outline-2 group-focus-visible:outline-offset-2 group-focus-visible:outline-immich-primary dark:group-focus-visible:outline-immich-dark-primary';

  async function loadPeople() {
    const timeout = setTimeout(() => (isShowLoadingPeople = true), timeBeforeShowLoadingSpinner);
@@ -226,14 +228,16 @@
      {:else}
        {#each peopleWithFaces as face, index (face.id)}
          {@const personName = face.person ? face.person?.name : $t('face_unassigned')}
+          {@const isHighlighted = $boundingBoxesArray.some((f) => f.id === face.id)}
          <div class="relative h-29 w-24">
            <div
              role="button"
              tabindex={index}
-              class="absolute start-0 top-0 h-22.5 w-22.5 cursor-default"
+              data-testid="face-thumbnail"
+              class="group absolute inset-s-0 top-0 h-22.5 w-22.5 cursor-default outline-none"
              onfocus={() => ($boundingBoxesArray = [peopleWithFaces[index]])}
-              onmouseover={() => ($boundingBoxesArray = [peopleWithFaces[index]])}
-              onmouseleave={() => ($boundingBoxesArray = [])}
+              onpointerover={() => ($boundingBoxesArray = [peopleWithFaces[index]])}
+              onpointerleave={() => ($boundingBoxesArray = [])}
            >
              <div class="relative">
                {#if selectedPersonToCreate[face.id]}
@@ -245,6 +249,8 @@
                    title={$t('new_person')}
                    widthStyle={thumbnailWidth}
                    heightStyle={thumbnailWidth}
+                    highlighted={isHighlighted}
+                    class={focusHighlightClass}
                  />
                {:else if selectedPersonToReassign[face.id]}
                  <ImageThumbnail
@@ -259,6 +265,8 @@
                    widthStyle={thumbnailWidth}
                    heightStyle={thumbnailWidth}
                    hidden={selectedPersonToReassign[face.id].isHidden}
+                    highlighted={isHighlighted}
+                    class={focusHighlightClass}
                  />
                {:else if face.person}
                  <ImageThumbnail
@@ -270,6 +278,8 @@
                    widthStyle={thumbnailWidth}
                    heightStyle={thumbnailWidth}
                    hidden={face.person.isHidden}
+                    highlighted={isHighlighted}
+                    class={focusHighlightClass}
                  />
                {:else}
                  {#await zoomImageToBase64(face, assetId, assetType, assetViewerManager.imgRef)}
@@ -281,6 +291,8 @@
                      title={$t('face_unassigned')}
                      widthStyle="90px"
                      heightStyle="90px"
+                      highlighted={isHighlighted}
+                      class={focusHighlightClass}
                    />
                  {:then data}
                    <ImageThumbnail
@@ -291,6 +303,8 @@
                      title={$t('face_unassigned')}
                      widthStyle="90px"
                      heightStyle="90px"
+                      highlighted={isHighlighted}
+                      class={focusHighlightClass}
                    />
                  {/await}
                {/if}
--- a/web/src/lib/stores/face-edit.svelte.ts
+++ b/web/src/lib/stores/face-edit.svelte.ts
@@ -1 +1,2 @@
 export const isFaceEditMode = $state({ value: false });
+export const isEditFacesPanelOpen = $state({ value: false });
--- a/web/src/lib/utils/container-utils.spec.ts
+++ b/web/src/lib/utils/container-utils.spec.ts
@@ -1,6 +1,9 @@
 import {
+  computeContentMetrics,
  getContentMetrics,
  getNaturalSize,
+  mapContentRectToNatural,
+  mapContentToNatural,
  mapNormalizedRectToContent,
  mapNormalizedToContent,
  scaleToCover,
@@ -123,6 +126,53 @@ describe('scaleToCover', () => {
  });
 });

+describe('computeContentMetrics', () => {
+  it('should compute metrics with scaleToFit by default', () => {
+    expect(computeContentMetrics({ width: 2000, height: 1000 }, { width: 800, height: 600 })).toEqual({
+      contentWidth: 800,
+      contentHeight: 400,
+      offsetX: 0,
+      offsetY: 100,
+    });
+  });
+
+  it('should accept scaleToCover as scale function', () => {
+    expect(computeContentMetrics({ width: 2000, height: 1000 }, { width: 800, height: 600 }, scaleToCover)).toEqual({
+      contentWidth: 1200,
+      contentHeight: 600,
+      offsetX: -200,
+      offsetY: 0,
+    });
+  });
+
+  it('should compute zero offsets when aspect ratios match', () => {
+    expect(computeContentMetrics({ width: 1600, height: 900 }, { width: 800, height: 450 })).toEqual({
+      contentWidth: 800,
+      contentHeight: 450,
+      offsetX: 0,
+      offsetY: 0,
+    });
+  });
+});
+
+// Coordinate space glossary:
+//
+// "Normalized" coordinates: values in the 0–1 range, where (0,0) is the top-left
+// of the image and (1,1) is the bottom-right. Resolution-independent.
+//
+// "Content" coordinates: pixel positions within the container, after the image
+// has been scaled (scaleToFit/scaleToCover) and offset (centered). This is what
+// CSS and DOM layout use for positioning overlays like face boxes and OCR text.
+//
+// "Natural" coordinates: pixel positions in the original image file at its full
+// resolution (e.g. 4000×3000). Used when cropping or drawing on the source image.
+//
+// "Metadata pixel space": the coordinate system used by face detection / OCR
+// models, where positions are in pixels relative to the image dimensions stored
+// in metadata (face.imageWidth/imageHeight). These may differ from the natural
+// dimensions if the image was resized. To convert to normalized, divide by
+// the metadata dimensions (e.g. face.boundingBoxX1 / face.imageWidth).
+
 describe('mapNormalizedToContent', () => {
  const metrics = { contentWidth: 800, contentHeight: 400, offsetX: 0, offsetY: 100 };

@@ -152,6 +202,31 @@ describe('mapNormalizedToContent', () => {
  });
 });

+describe('mapContentToNatural', () => {
+  const metrics = { contentWidth: 800, contentHeight: 400, offsetX: 0, offsetY: 100 };
+  const natural = { width: 4000, height: 2000 };
+
+  it('should map content origin to natural origin', () => {
+    expect(mapContentToNatural({ x: 0, y: 100 }, metrics, natural)).toEqual({ x: 0, y: 0 });
+  });
+
+  it('should map content bottom-right to natural bottom-right', () => {
+    expect(mapContentToNatural({ x: 800, y: 500 }, metrics, natural)).toEqual({ x: 4000, y: 2000 });
+  });
+
+  it('should map content center to natural center', () => {
+    expect(mapContentToNatural({ x: 400, y: 300 }, metrics, natural)).toEqual({ x: 2000, y: 1000 });
+  });
+
+  it('should be the inverse of mapNormalizedToContent', () => {
+    const normalized = { x: 0.3, y: 0.7 };
+    const contentPoint = mapNormalizedToContent(normalized, metrics);
+    const naturalPoint = mapContentToNatural(contentPoint, metrics, natural);
+    expect(naturalPoint.x).toBeCloseTo(normalized.x * natural.width);
+    expect(naturalPoint.y).toBeCloseTo(normalized.y * natural.height);
+  });
+});
+
 describe('mapNormalizedRectToContent', () => {
  const metrics = { contentWidth: 800, contentHeight: 400, offsetX: 0, offsetY: 100 };

@@ -177,3 +252,28 @@ describe('mapNormalizedRectToContent', () => {
    expect(rect).toEqual({ left: 200, top: 100, width: 400, height: 200 });
  });
 });
+
+describe('mapContentRectToNatural', () => {
+  const metrics = { contentWidth: 800, contentHeight: 400, offsetX: 0, offsetY: 100 };
+  const natural = { width: 4000, height: 2000 };
+
+  it('should map a content rect to natural image coordinates', () => {
+    const rect = mapContentRectToNatural({ left: 200, top: 200, width: 400, height: 200 }, metrics, natural);
+    expect(rect).toEqual({ left: 1000, top: 500, width: 2000, height: 1000 });
+  });
+
+  it('should map full content rect to full natural dimensions', () => {
+    const rect = mapContentRectToNatural({ left: 0, top: 100, width: 800, height: 400 }, metrics, natural);
+    expect(rect).toEqual({ left: 0, top: 0, width: 4000, height: 2000 });
+  });
+
+  it('should be the inverse of mapNormalizedRectToContent', () => {
+    const normalized = { topLeft: { x: 0.2, y: 0.3 }, bottomRight: { x: 0.8, y: 0.9 } };
+    const contentRect = mapNormalizedRectToContent(normalized.topLeft, normalized.bottomRight, metrics);
+    const naturalRect = mapContentRectToNatural(contentRect, metrics, natural);
+    expect(naturalRect.left).toBeCloseTo(normalized.topLeft.x * natural.width);
+    expect(naturalRect.top).toBeCloseTo(normalized.topLeft.y * natural.height);
+    expect(naturalRect.width).toBeCloseTo((normalized.bottomRight.x - normalized.topLeft.x) * natural.width);
+    expect(naturalRect.height).toBeCloseTo((normalized.bottomRight.y - normalized.topLeft.y) * natural.height);
+  });
+});
--- a/web/src/lib/utils/container-utils.ts
+++ b/web/src/lib/utils/container-utils.ts
@@ -63,16 +63,24 @@ export const getNaturalSize = (element: HTMLImageElement | HTMLVideoElement): Si
  return { width: element.naturalWidth, height: element.naturalHeight };
 };

-export const getContentMetrics = (element: HTMLImageElement | HTMLVideoElement): ContentMetrics => {
-  const natural = getNaturalSize(element);
-  const client = getElementSize(element);
-  const { width: contentWidth, height: contentHeight } = scaleToFit(natural, client);
+export function computeContentMetrics(
+  imageSize: Size,
+  containerSize: Size,
+  scaleFn: (dimensions: Size, container: Size) => Size = scaleToFit,
+) {
+  const { width: contentWidth, height: contentHeight } = scaleFn(imageSize, containerSize);
  return {
    contentWidth,
    contentHeight,
-    offsetX: (client.width - contentWidth) / 2,
-    offsetY: (client.height - contentHeight) / 2,
+    offsetX: (containerSize.width - contentWidth) / 2,
+    offsetY: (containerSize.height - contentHeight) / 2,
  };
+}
+
+export const getContentMetrics = (element: HTMLImageElement | HTMLVideoElement): ContentMetrics => {
+  const natural = getNaturalSize(element);
+  const client = getElementSize(element);
+  return computeContentMetrics(natural, client);
 };

 export function mapNormalizedToContent(point: Point, sizeOrMetrics: Size | ContentMetrics): Point {
@@ -88,6 +96,13 @@ export function mapNormalizedToContent(point: Point, sizeOrMetrics: Size | Conte
  };
 }

+export function mapContentToNatural(point: Point, metrics: ContentMetrics, naturalSize: Size): Point {
+  return {
+    x: ((point.x - metrics.offsetX) / metrics.contentWidth) * naturalSize.width,
+    y: ((point.y - metrics.offsetY) / metrics.contentHeight) * naturalSize.height,
+  };
+}
+
 export type Rect = {
  top: number;
  left: number;
@@ -109,3 +124,18 @@ export function mapNormalizedRectToContent(
    height: br.y - tl.y,
  };
 }
+
+export function mapContentRectToNatural(rect: Rect, metrics: ContentMetrics, naturalSize: Size): Rect {
+  const topLeft = mapContentToNatural({ x: rect.left, y: rect.top }, metrics, naturalSize);
+  const bottomRight = mapContentToNatural(
+    { x: rect.left + rect.width, y: rect.top + rect.height },
+    metrics,
+    naturalSize,
+  );
+  return {
+    top: topLeft.y,
+    left: topLeft.x,
+    width: bottomRight.x - topLeft.x,
+    height: bottomRight.y - topLeft.y,
+  };
+}
--- a/web/src/lib/utils/people-utils.spec.ts
+++ b/web/src/lib/utils/people-utils.spec.ts
@@ -1,6 +1,6 @@
 import type { Faces } from '$lib/stores/people.store';
 import type { Size } from '$lib/utils/container-utils';
-import { getBoundingBox } from '$lib/utils/people-utils';
+import { getBoundingBox, scaleFaceRectOnResize, type FaceRectState, type ResizeContext } from '$lib/utils/people-utils';

 const makeFace = (overrides: Partial<Faces> = {}): Faces => ({
  id: 'face-1',
@@ -68,3 +68,96 @@ describe('getBoundingBox', () => {
    expect(boxes[0].left).toBeLessThan(boxes[1].left);
  });
 });
+
+describe('scaleFaceRectOnResize', () => {
+  const makeRect = (overrides: Partial<FaceRectState> = {}): FaceRectState => ({
+    left: 300,
+    top: 400,
+    scaleX: 1,
+    scaleY: 1,
+    ...overrides,
+  });
+
+  const makePrevious = (overrides: Partial<ResizeContext> = {}): ResizeContext => ({
+    offsetX: 100,
+    offsetY: 50,
+    contentWidth: 800,
+    ...overrides,
+  });
+
+  it('should preserve relative position when container doubles in size', () => {
+    const rect = makeRect({ left: 300, top: 250 });
+    const previous = makePrevious({ offsetX: 100, offsetY: 50, contentWidth: 800 });
+
+    const result = scaleFaceRectOnResize(rect, previous, { offsetX: 200, offsetY: 100, contentWidth: 1600 });
+
+    // imageRelLeft = (300 - 100) * 2 = 400, new left = 200 + 400 = 600
+    // imageRelTop = (250 - 50) * 2 = 400, new top = 100 + 400 = 500
+    expect(result.left).toBe(600);
+    expect(result.top).toBe(500);
+    expect(result.scaleX).toBe(2);
+    expect(result.scaleY).toBe(2);
+  });
+
+  it('should preserve relative position when container halves in size', () => {
+    const rect = makeRect({ left: 300, top: 250 });
+    const previous = makePrevious({ offsetX: 100, offsetY: 50, contentWidth: 800 });
+
+    const result = scaleFaceRectOnResize(rect, previous, { offsetX: 50, offsetY: 25, contentWidth: 400 });
+
+    // imageRelLeft = (300 - 100) * 0.5 = 100, new left = 50 + 100 = 150
+    // imageRelTop = (250 - 50) * 0.5 = 100, new top = 25 + 100 = 125
+    expect(result.left).toBe(150);
+    expect(result.top).toBe(125);
+    expect(result.scaleX).toBe(0.5);
+    expect(result.scaleY).toBe(0.5);
+  });
+
+  it('should handle no change in dimensions', () => {
+    const rect = makeRect({ left: 300, top: 250, scaleX: 1.5, scaleY: 1.5 });
+    const previous = makePrevious({ offsetX: 100, offsetY: 50, contentWidth: 800 });
+
+    const result = scaleFaceRectOnResize(rect, previous, { offsetX: 100, offsetY: 50, contentWidth: 800 });
+
+    expect(result.left).toBe(300);
+    expect(result.top).toBe(250);
+    expect(result.scaleX).toBe(1.5);
+    expect(result.scaleY).toBe(1.5);
+  });
+
+  it('should handle offset changes without content width change', () => {
+    const rect = makeRect({ left: 300, top: 250 });
+    const previous = makePrevious({ offsetX: 100, offsetY: 50, contentWidth: 800 });
+
+    const result = scaleFaceRectOnResize(rect, previous, { offsetX: 150, offsetY: 75, contentWidth: 800 });
+
+    // scale = 1, imageRelLeft = 200, imageRelTop = 200
+    // new left = 150 + 200 = 350, new top = 75 + 200 = 275
+    expect(result.left).toBe(350);
+    expect(result.top).toBe(275);
+    expect(result.scaleX).toBe(1);
+    expect(result.scaleY).toBe(1);
+  });
+
+  it('should compound existing scale factors', () => {
+    const rect = makeRect({ left: 300, top: 250, scaleX: 2, scaleY: 3 });
+    const previous = makePrevious({ contentWidth: 800 });
+
+    const result = scaleFaceRectOnResize(rect, previous, { ...previous, contentWidth: 1600 });
+
+    expect(result.scaleX).toBe(4);
+    expect(result.scaleY).toBe(6);
+  });
+
+  it('should handle rect at image origin (top-left of content area)', () => {
+    const rect = makeRect({ left: 100, top: 50 });
+    const previous = makePrevious({ offsetX: 100, offsetY: 50, contentWidth: 800 });
+
+    const result = scaleFaceRectOnResize(rect, previous, { offsetX: 200, offsetY: 100, contentWidth: 1600 });
+
+    // imageRelLeft = (100 - 100) * 2 = 0, new left = 200
+    // imageRelTop = (50 - 50) * 2 = 0, new top = 100
+    expect(result.left).toBe(200);
+    expect(result.top).toBe(100);
+  });
+});
--- a/web/src/lib/utils/people-utils.ts
+++ b/web/src/lib/utils/people-utils.ts
@@ -1,6 +1,6 @@
 import type { Faces } from '$lib/stores/people.store';
 import { getAssetMediaUrl } from '$lib/utils';
-import { mapNormalizedRectToContent, type Rect, type Size } from '$lib/utils/container-utils';
+import { mapNormalizedRectToContent, type ContentMetrics, type Rect, type Size } from '$lib/utils/container-utils';
 import { AssetTypeEnum, type AssetFaceResponseDto } from '@immich/sdk';

 export type BoundingBox = Rect & { id: string };
@@ -21,6 +21,32 @@ export const getBoundingBox = (faces: Faces[], imageSize: Size): BoundingBox[] =
  return boxes;
 };

+export type FaceRectState = {
+  left: number;
+  top: number;
+  scaleX: number;
+  scaleY: number;
+};
+
+export type ResizeContext = Pick<ContentMetrics, 'contentWidth' | 'offsetX' | 'offsetY'>;
+
+export const scaleFaceRectOnResize = (
+  faceRect: FaceRectState,
+  previous: ResizeContext,
+  current: ResizeContext,
+): FaceRectState => {
+  const scale = current.contentWidth / previous.contentWidth;
+  const imageRelativeLeft = (faceRect.left - previous.offsetX) * scale;
+  const imageRelativeTop = (faceRect.top - previous.offsetY) * scale;
+
+  return {
+    left: current.offsetX + imageRelativeLeft,
+    top: current.offsetY + imageRelativeTop,
+    scaleX: faceRect.scaleX * scale,
+    scaleY: faceRect.scaleY * scale,
+  };
+};
+
 export const zoomImageToBase64 = async (
  face: AssetFaceResponseDto,
  assetId: string,