From 776aa3982327a5f8023999d33970ad2ce484a824 Mon Sep 17 00:00:00 2001
From: Lincoln Stein <lincoln.stein@gmail.com>
Date: Sun, 4 Oct 2026 18:55:56 -0400
Subject: [PATCH 1/3] Cache a screen-sized copy of TIFF/HEIC images served by
 /images/

/images/ re-encoded every TIFF/HEIC to a full-resolution PNG on every
request, with no validators, so each view and slideshow preload paid for
the decode and a 30-70 MB encode again. It now serves a JPEG (WebP when
the image has transparency) capped at 4096px on the long edge, cached in
the album's thumbnail directory and served with a content ETag/304.

- Named with the tile digest, so the reindex sweep and the per-image
  delete reclaim display copies with no second keep-set.
- Per-file lock plus write-then-rename: concurrent requests convert once
  and never read a partial file. Abandoned temporaries are swept.
- Rebuilt when the source is newer; a failed cache write still serves.
- 16-bit scans are reduced to 8-bit after _png_safe's rescale.

On a 6000x4000 LZW TIFF: 2.55 s / 53 MB before, 0.67 s / 3.9 MB cold,
~1 ms warm. Downloads keep using ?original=1.

Fixes #414

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 photomap/backend/media_types.py       |   2 +-
 photomap/backend/routers/search.py    | 178 ++++++++++++++++++++++----
 photomap/backend/thumbnail_cache.py   |  50 +++++++-
 tests/backend/test_image_formats.py   | 173 ++++++++++++++++++++++++-
 tests/backend/test_thumbnail_cache.py |  29 +++++
 5 files changed, 401 insertions(+), 31 deletions(-)

diff --git a/photomap/backend/media_types.py b/photomap/backend/media_types.py
index 7074b09d..19d66cb4 100644
--- a/photomap/backend/media_types.py
+++ b/photomap/backend/media_types.py
@@ -69,7 +69,7 @@
 )
 
 # Images only Safari (TIFF) or nothing (HEIC in Chrome/Firefox) renders
-# natively, so ``/images/`` serves them converted to PNG instead of raw.
+# natively, so ``/images/`` serves them as a cached JPEG/WebP copy instead of raw.
 BROWSER_CONVERTED_EXTENSIONS: frozenset[str] = frozenset({".tif", ".tiff", ".heif", ".heic"})
 
 # Container -> MIME map, and the single source of truth for which containers
diff --git a/photomap/backend/routers/search.py b/photomap/backend/routers/search.py
index 7d1f84ba..5d6e4efe 100644
--- a/photomap/backend/routers/search.py
+++ b/photomap/backend/routers/search.py
@@ -12,6 +12,8 @@
 import json
 import os
 import re
+import tempfile
+import threading
 import zipfile
 from io import BytesIO
 from logging import getLogger
@@ -28,8 +30,8 @@
 from ..embeddings import SUPPORTED_EXTENSIONS, MediaFilter
 from ..media_types import is_video, needs_browser_conversion, video_media_type
 from ..metadata_modules import SlideSummary, video_external_link_html
-from ..thumbnail_cache import thumbnail_dir, tile_hash
-from ..util import is_cuda_oom
+from ..thumbnail_cache import display_copy_stem, thumbnail_dir, tile_hash
+from ..util import BoundedLRU, is_cuda_oom
 from ..video_cache import VideoFrameCache
 from ..video_transcode import (
     HLS_PLAYLIST_NAME,
@@ -384,7 +386,7 @@ def _video_placeholder_response(size: int) -> Response:
 _THUMBNAIL_CACHE_HEADERS = {"Cache-Control": "no-cache"}
 
 
-def _thumbnail_response(request: Request, path: Path) -> Response:
+def _thumbnail_response(request: Request, path: Path, media_type: str = "image/png") -> Response:
     """A tile, or a 304 if the caller already has it.
 
     ``no-cache`` above means the browser revalidates every time, and
@@ -409,13 +411,17 @@ def _thumbnail_response(request: Request, path: Path) -> Response:
         # the next request rebuilds it; 404 rather than a 500 so it reads as
         # a missing tile instead of a broken server.
         raise HTTPException(status_code=404, detail="Thumbnail is no longer available") from None
+    return _validated_response(request, payload, media_type)
 
+
+def _validated_response(request: Request, payload: bytes, media_type: str) -> Response:
+    """``payload`` with a content ETag, or a 304 if the caller already has it."""
     etag = f'"{hashlib.md5(payload, usedforsecurity=False).hexdigest()}"'
     if request.headers.get("if-none-match") == etag:
         return Response(status_code=304, headers={**_THUMBNAIL_CACHE_HEADERS, "etag": etag})
     return Response(
         content=payload,
-        media_type="image/png",
+        media_type=media_type,
         headers={**_THUMBNAIL_CACHE_HEADERS, "etag": etag},
     )
 
@@ -581,12 +587,15 @@ async def serve_video_frame(
 # or a converted stream and FastAPI refuses to work with Union types
 # in response_model.
 @search_router.get("/images/{album_key}/{path:path}", tags=["Search"])
-async def serve_image(album_key: str, path: str, album_config: AlbumDep, original: bool = False):
+async def serve_image(
+    request: Request, album_key: str, path: str, album_config: AlbumDep, original: bool = False
+):
     """Serve images from different albums dynamically.
 
-    Formats browsers cannot render are converted to PNG unless ``original`` is
-    set, which the download button uses so a saved ``.tif`` is the user's file
-    rather than a flattened, first-page-only PNG under the same name.
+    Formats browsers cannot render are served as a cached, screen-sized JPEG
+    (WebP if the image has transparency) unless ``original`` is set, which the
+    download button uses so a saved ``.tif`` is the user's file rather than a
+    flattened, downscaled, first-page-only copy under the same name.
     """
     image_path = config_manager.find_image_in_album(album_key, path)
     if not image_path:
@@ -607,9 +616,14 @@ async def serve_image(album_key: str, path: str, album_config: AlbumDep, origina
         raise HTTPException(status_code=404, detail="File not found")
 
     if needs_browser_conversion(image_path) and not original:
+        stem = None
+        relative_path = config_manager.get_relative_path(str(image_path), album_key)
+        if album_config.index and relative_path is not None:
+            stem = display_copy_stem(thumbnail_dir(Path(album_config.index)), relative_path)
         # Decoding a large scanned TIFF takes long enough to stall every other
         # request if done on the loop, so it runs in a worker thread.
-        return await asyncio.to_thread(serve_image_with_conversion, image_path)
+        payload, media_type = await asyncio.to_thread(_display_copy, image_path, stem)
+        return _validated_response(request, payload, media_type)
     return FileResponse(image_path)
 
 
@@ -660,8 +674,8 @@ async def serve_video(
 
     Returns a ``FileResponse`` specifically: Starlette implements HTTP Range
     on it, which is what makes the ``<video>`` scrubber able to seek.  A
-    ``StreamingResponse`` (as the HEIC conversion path uses) has no range
-    support and would silently break seeking.
+    plain ``Response`` or ``StreamingResponse`` has no range support and would
+    silently break seeking.
     """
     video_path = _resolve_album_video(album_key, path, album_config)
 
@@ -1229,20 +1243,136 @@ def _png_safe(im: Image.Image) -> Image.Image:
     return converted
 
 
-def serve_image_with_conversion(image_path: Path) -> StreamingResponse:
-    """Serve an image browsers cannot render (HEIC, TIFF) re-encoded as PNG,
-    with EXIF rotation applied. Blocking: call it off the event loop."""
+# The copy ``/images/`` shows in place of a TIFF or HEIC. A full-resolution PNG
+# of a 24 MP scan is 30-70 MB and took seconds to encode on every view; capped
+# at this long edge and saved as JPEG it is a few MB, still sharper than any
+# screen it is shown on. Downloads ask for ``?original=1`` and never see it.
+_DISPLAY_MAX_EDGE = 4096
+_DISPLAY_QUALITY = 90
+
+# Suffix -> media type, for each format a display copy may be cached in.
+_DISPLAY_FORMATS = {".jpg": "image/jpeg", ".webp": "image/webp"}
+
+# Serializes conversions of one file, so the swiper preloading a slide that is
+# also being shown converts it once rather than twice. Bounded like
+# video_cache's locks: evicting an idle lock costs at worst one duplicate
+# conversion, which the atomic write already makes harmless.
+_display_locks: BoundedLRU[str, threading.Lock] = BoundedLRU(1024)
+_display_locks_guard = threading.Lock()
+
+
+def _display_lock(key: str) -> threading.Lock:
+    with _display_locks_guard:
+        lock = _display_locks.get(key)
+        if lock is None:
+            lock = threading.Lock()
+            _display_locks.put(key, lock)
+        return lock
+
+
+def _display_safe(im: Image.Image) -> Image.Image:
+    """Return ``im`` as 8-bit L, RGB or RGBA — what JPEG and WebP can store."""
+    im = _png_safe(im)
+    if im.mode == "I;16":
+        # _png_safe has already mapped deep data onto 0-65535 without
+        # clipping; JPEG has no 16-bit mode, so take the top eight bits.
+        arr = np.asarray(im, dtype=np.uint16)
+        return Image.fromarray((arr >> 8).astype(np.uint8))
+    if im.mode == "1":
+        return im.convert("L")
+    if im.mode == "P":
+        return im.convert("RGBA" if "transparency" in im.info else "RGB")
+    if im.mode == "LA":
+        return im.convert("RGBA")
+    return im
+
+
+def _encode_display_copy(image_path: Path) -> tuple[bytes, str]:
+    """The display copy of ``image_path`` and the suffix it should be stored
+    under: EXIF rotation applied, long edge capped, JPEG unless the image has
+    transparency worth keeping. Blocking."""
+    with Image.open(image_path) as im:
+        # Before anything else: a TIFF keeps its orientation in its own tag
+        # directory, which the first convert() would drop.
+        im = ImageOps.exif_transpose(im)
+        im = _display_safe(im)
+        im.thumbnail((_DISPLAY_MAX_EDGE, _DISPLAY_MAX_EDGE), Image.Resampling.LANCZOS)
+        icc = im.info.get("icc_profile")
+        if im.mode == "RGBA" and im.getchannel("A").getextrema() == (255, 255):
+            # Scanners often write an alpha channel with nothing in it.
+            im = im.convert("RGB")
+        buf = BytesIO()
+        extra = {"icc_profile": icc} if icc else {}
+        if im.mode == "RGBA":
+            im.save(buf, format="WEBP", quality=_DISPLAY_QUALITY, **extra)
+            return buf.getvalue(), ".webp"
+        im.save(buf, format="JPEG", quality=_DISPLAY_QUALITY, **extra)
+        return buf.getvalue(), ".jpg"
+
+
+def _read_fresh_display_copy(stem: Path, image_path: Path) -> tuple[bytes, str] | None:
+    for suffix, media_type in _DISPLAY_FORMATS.items():
+        path = stem.with_name(stem.name + suffix)
+        if not _thumbnail_is_fresh(path, image_path):
+            continue
+        try:
+            payload = path.read_bytes()
+        except OSError:
+            continue  # swept since the freshness check; rebuild it
+        if payload:
+            return payload, media_type
+    return None
+
+
+def _store_display_copy(stem: Path, payload: bytes, suffix: str) -> None:
+    """Publish ``payload`` atomically, and drop the copy in the other format.
+
+    Write-then-rename so a concurrent reader never sees half a file. A failed
+    write is logged, not raised: the caller still has the bytes to serve, and
+    an index directory on a read-only mount should cost speed, not pictures.
+    """
+    target = stem.with_name(stem.name + suffix)
+    tmp_path: Path | None = None
+    try:
+        stem.parent.mkdir(parents=True, exist_ok=True)
+        fd, tmp_name = tempfile.mkstemp(dir=stem.parent, prefix=f"{stem.name}.", suffix=".tmp")
+        tmp_path = Path(tmp_name)
+        with os.fdopen(fd, "wb") as handle:
+            handle.write(payload)
+        os.replace(tmp_path, target)
+        tmp_path = None
+        for other in _DISPLAY_FORMATS:
+            if other != suffix:
+                # An image edited to gain or lose transparency changes format;
+                # the old copy is stale and nothing would ever ask for it.
+                stem.with_name(stem.name + other).unlink(missing_ok=True)
+    except OSError as e:
+        logger.warning(f"Could not cache the display copy {target}: {e}")
+    finally:
+        if tmp_path is not None:
+            tmp_path.unlink(missing_ok=True)
+
+
+def _display_copy(image_path: Path, stem: Path | None) -> tuple[bytes, str]:
+    """The display copy of an image browsers cannot render, as (bytes, media
+    type), from the cache at ``stem`` when it is newer than the source.
+
+    ``stem`` is ``None`` when the album has nowhere to cache it; the copy is
+    then built for this request only. Blocking: call it off the event loop.
+    """
     try:
-        with Image.open(image_path) as im:
-            im = ImageOps.exif_transpose(im)
-            im = _png_safe(im)
-            buf = BytesIO()
-            format = "PNG"
-            # Fast compression: a 24 MP scan takes several seconds to encode
-            # at the default level, and these bytes only cross localhost.
-            im.save(buf, format=format, compress_level=1)
-            buf.seek(0)
-            return StreamingResponse(buf, media_type=f"image/{format.lower()}")
+        if stem is None:
+            payload, suffix = _encode_display_copy(image_path)
+            return payload, _DISPLAY_FORMATS[suffix]
+        if (cached := _read_fresh_display_copy(stem, image_path)) is not None:
+            return cached
+        with _display_lock(str(stem)):
+            # Another request may have built it while this one waited.
+            if (cached := _read_fresh_display_copy(stem, image_path)) is not None:
+                return cached
+            payload, suffix = _encode_display_copy(image_path)
+            _store_display_copy(stem, payload, suffix)
+            return payload, _DISPLAY_FORMATS[suffix]
     except Exception as e:
         logger.warning(f"Error converting image {image_path} for display: {e}")
         raise HTTPException(status_code=500, detail=f"Image processing error: {e}") from e
diff --git a/photomap/backend/thumbnail_cache.py b/photomap/backend/thumbnail_cache.py
index 0da67acc..fb08f6d3 100644
--- a/photomap/backend/thumbnail_cache.py
+++ b/photomap/backend/thumbnail_cache.py
@@ -5,6 +5,11 @@
 image's album-relative path plus the size (and, for the UMAP landmark overlay,
 a colour and corner radius), so one source file can have several live tiles.
 
+The same directory holds the *display copies* ``/images/`` serves in place of
+a TIFF or HEIC the browser cannot render: one screen-sized JPEG (or WebP, when
+the image has transparency) per source file, named with the same digest so the
+sweep and the per-file discard cover them without a second keep-set.
+
 The key logic lives here rather than in the route because the sweeper has to
 compute exactly the same digest the route does. Two copies of that rule would
 drift the first time either changed, and the failure would be silent: the
@@ -14,6 +19,7 @@
 import hashlib
 import logging
 import re
+import time
 from pathlib import Path
 
 from .video import FRAME_SELECTION_GENERATION
@@ -25,6 +31,15 @@
 # What tile_hash emits: blake2b-128, rendered lowercase.
 _DIGEST_RE = re.compile(r"[0-9a-f]{32}")
 
+# Every suffix this module's writers produce: PNG tiles, JPEG/WebP display
+# copies, and the temporaries a display copy is written through.
+_CACHE_SUFFIXES = frozenset({".png", ".jpg", ".webp", ".tmp"})
+
+# A temporary is only ever live for the length of one conversion. One older
+# than this belongs to a writer that crashed or was killed, and is swept even
+# when its source image still exists.
+_STALE_TMP_SECONDS = 3600.0
+
 
 def thumbnail_dir(index_path: Path | str) -> Path:
     """The tile directory for an album with its index at ``index_path``."""
@@ -65,6 +80,18 @@ def tile_hash(relative_path: str, *, video: bool) -> str:
     ).hexdigest()
 
 
+def display_copy_stem(directory: Path, relative_path: str) -> Path:
+    """Where the display copy of a TIFF/HEIC is cached, minus its suffix.
+
+    The suffix is the format (``.jpg``, or ``.webp`` for an image with
+    transparency), and is chosen when the copy is written. Keyed with
+    :func:`tile_hash` so :func:`prune` and :func:`discard` reclaim it along
+    with the file's tiles — a separate digest would need its own keep-set,
+    and the sweep would delete every display copy if the two ever disagreed.
+    """
+    return directory / f"{tile_hash(relative_path, video=False)}_display"
+
+
 def prune(directory: Path, keep_hashes: set[str]) -> int:
     """Delete every tile whose source file is no longer in ``keep_hashes``.
 
@@ -91,15 +118,18 @@ def prune(directory: Path, keep_hashes: set[str]) -> int:
         return 0
 
     removed = 0
+    now = time.time()
     for entry in entries:
-        if entry.suffix != ".png":
+        if entry.suffix not in _CACHE_SUFFIXES:
             continue
         # "<32 lowercase hex digits>_<size>[...]"; anything else was not
         # written by the route and is left alone rather than guessed at. The
         # hex check is part of that promise: a 32-character stem is not
         # necessarily a digest, and this code deletes files.
         digest = entry.stem.split("_", 1)[0]
-        if not _DIGEST_RE.fullmatch(digest) or digest in keep_hashes:
+        if not _DIGEST_RE.fullmatch(digest):
+            continue
+        if digest in keep_hashes and not _is_abandoned_tmp(entry, now):
             continue
         try:
             entry.unlink()
@@ -110,7 +140,8 @@ def prune(directory: Path, keep_hashes: set[str]) -> int:
 
 
 def discard(directory: Path, relative_path: str, *, video: bool) -> int:
-    """Remove every tile of one source file, whatever size or colour.
+    """Remove every tile of one source file, whatever size or colour, and its
+    display copy.
 
     The counterpart to :func:`prune` for a single deletion. The full sweep
     only runs when the index is rewritten wholesale, and the delete endpoints
@@ -124,7 +155,9 @@ def discard(directory: Path, relative_path: str, *, video: bool) -> int:
         return 0
     digest = tile_hash(relative_path, video=video)
     removed = 0
-    for entry in directory.glob(f"{digest}_*.png"):
+    for entry in directory.glob(f"{digest}_*"):
+        if entry.suffix not in _CACHE_SUFFIXES:
+            continue
         try:
             entry.unlink()
             removed += 1
@@ -133,6 +166,15 @@ def discard(directory: Path, relative_path: str, *, video: bool) -> int:
     return removed
 
 
+def _is_abandoned_tmp(entry: Path, now: float) -> bool:
+    if entry.suffix != ".tmp":
+        return False
+    try:
+        return now - entry.stat().st_mtime > _STALE_TMP_SECONDS
+    except OSError:
+        return False
+
+
 def keep_hashes_for(filenames, image_roots, is_video) -> set[str]:
     """Every tile digest the album's current contents can legitimately ask for.
 
diff --git a/tests/backend/test_image_formats.py b/tests/backend/test_image_formats.py
index 26f56628..2da7b8c7 100644
--- a/tests/backend/test_image_formats.py
+++ b/tests/backend/test_image_formats.py
@@ -115,14 +115,14 @@ def test_image_suffix_is_served_in_a_browser_renderable_form(client, format_albu
     response = client.get(f"/images/format_album/{name}")
     assert response.status_code == 200, response.text
     if Path(name).suffix in BROWSER_CONVERTED_EXTENSIONS:
-        assert response.headers["content-type"] == "image/png"
+        assert response.headers["content-type"] == "image/jpeg"
     with Image.open(BytesIO(response.content)) as im:
         assert im.size == (300, 300)
 
 
 def test_original_flag_serves_the_untouched_file(client, format_album, tmp_path):
     """Downloads ask for ``?original=1`` and must get the TIFF itself, not the
-    PNG the viewer is shown."""
+    JPEG the viewer is shown."""
     response = client.get("/images/format_album/cmyk.tif", params={"original": 1})
     assert response.status_code == 200
     assert response.content == (tmp_path / "formats" / "cmyk.tif").read_bytes()
@@ -144,3 +144,172 @@ def test_deep_tiffs_are_not_clipped_to_a_blank_page(tmp_path, make):
     # 40000 and 0.5 are both mid-grey; a clipping convert gives 255 or 0.
     value = im.getpixel((0, 0))
     assert 30000 < value < 50000, value
+
+
+# --- Issue #414: the display copy is downscaled and cached -------------------
+
+
+@pytest.fixture
+def encode_calls(monkeypatch):
+    """Count the conversions /images/ actually performs."""
+    from photomap.backend.routers import search
+
+    calls: list[Path] = []
+    real = search._encode_display_copy
+
+    def counting(image_path):
+        calls.append(Path(image_path))
+        return real(image_path)
+
+    monkeypatch.setattr(search, "_encode_display_copy", counting)
+    return calls
+
+
+def test_a_second_request_is_served_from_the_cache_with_a_304(client, format_album, encode_calls):
+    first = client.get("/images/format_album/img.tif")
+    assert first.status_code == 200
+    etag = first.headers["etag"]
+    assert len(encode_calls) == 1
+
+    again = client.get("/images/format_album/img.tif")
+    assert again.status_code == 200
+    assert again.content == first.content
+    assert again.headers["etag"] == etag
+
+    revalidated = client.get("/images/format_album/img.tif", headers={"If-None-Match": etag})
+    assert revalidated.status_code == 304
+    assert revalidated.content == b""
+    assert len(encode_calls) == 1
+
+
+def test_touching_the_source_rebuilds_the_copy(client, format_album, encode_calls, tmp_path):
+    import os
+
+    assert client.get("/images/format_album/img.tif").status_code == 200
+    source = tmp_path / "formats" / "img.tif"
+    future = source.stat().st_mtime + 60
+    os.utime(source, (future, future))
+    assert client.get("/images/format_album/img.tif").status_code == 200
+    assert len(encode_calls) == 2
+
+
+def test_the_copy_is_capped_at_the_display_size(client, format_album, tmp_path):
+    from photomap.backend.routers.search import _DISPLAY_MAX_EDGE
+
+    Image.new("RGB", (_DISPLAY_MAX_EDGE * 2, 64), (10, 200, 30)).save(tmp_path / "formats" / "wide.tif")
+    response = client.get("/images/format_album/wide.tif")
+    assert response.status_code == 200
+    with Image.open(BytesIO(response.content)) as im:
+        assert im.size == (_DISPLAY_MAX_EDGE, 32)
+    # The download still gets every pixel.
+    original = client.get("/images/format_album/wide.tif", params={"original": 1})
+    with Image.open(BytesIO(original.content)) as im:
+        assert im.size == (_DISPLAY_MAX_EDGE * 2, 64)
+
+
+def test_transparency_is_kept_as_webp_and_an_empty_alpha_is_not(client, format_album, tmp_path):
+    img_dir = tmp_path / "formats"
+    clear = Image.new("RGBA", (40, 40), (255, 0, 0, 255))
+    clear.putpixel((0, 0), (0, 0, 0, 0))
+    clear.save(img_dir / "alpha.tif")
+    Image.new("RGBA", (40, 40), (255, 0, 0, 255)).save(img_dir / "opaque.tif")
+
+    alpha = client.get("/images/format_album/alpha.tif")
+    assert alpha.headers["content-type"] == "image/webp"
+    with Image.open(BytesIO(alpha.content)) as im:
+        assert im.mode == "RGBA"
+        assert im.getpixel((0, 0))[3] == 0
+
+    opaque = client.get("/images/format_album/opaque.tif")
+    assert opaque.headers["content-type"] == "image/jpeg"
+
+
+def test_a_16_bit_scan_is_not_clipped_in_the_jpeg(client, format_album, tmp_path):
+    Image.new("I;16", (32, 32), 40000).save(tmp_path / "formats" / "deep.tif")
+    response = client.get("/images/format_album/deep.tif")
+    assert response.status_code == 200
+    with Image.open(BytesIO(response.content)) as im:
+        value = im.convert("L").getpixel((0, 0))
+    assert 140 < value < 170, value  # 40000/65535 of full scale, not 255
+
+
+def test_the_exif_orientation_is_applied(client, format_album, tmp_path):
+    im = Image.new("RGB", (60, 20), (0, 0, 255))
+    exif = im.getexif()
+    exif[0x0112] = 6  # rotate 90 CW on display
+    im.save(tmp_path / "formats" / "rotated.tif", exif=exif)
+    response = client.get("/images/format_album/rotated.tif")
+    with Image.open(BytesIO(response.content)) as shown:
+        assert shown.size == (20, 60)
+
+
+def test_an_unwritable_cache_still_serves_the_image(client, format_album, encode_calls, monkeypatch):
+    from photomap.backend.routers import search
+
+    def refuse(*a, **k):
+        raise PermissionError("read-only index directory")
+
+    monkeypatch.setattr(search.tempfile, "mkstemp", refuse)
+    for _ in range(2):
+        response = client.get("/images/format_album/img.tif")
+        assert response.status_code == 200
+        with Image.open(BytesIO(response.content)) as im:
+            assert im.size == (300, 300)
+    assert len(encode_calls) == 2
+
+
+def test_concurrent_requests_convert_once(tmp_path, monkeypatch):
+    import threading
+
+    from photomap.backend.routers import search
+
+    source = tmp_path / "scan.tif"
+    Image.new("RGB", (50, 50), (1, 2, 3)).save(source)
+    stem = tmp_path / "thumbnails" / "abc_display"
+
+    calls = []
+    release = threading.Event()
+    real = search._encode_display_copy
+
+    def slow(image_path):
+        calls.append(image_path)
+        release.wait(5)
+        return real(image_path)
+
+    monkeypatch.setattr(search, "_encode_display_copy", slow)
+    results = []
+    threads = [
+        threading.Thread(target=lambda: results.append(search._display_copy(source, stem))) for _ in range(3)
+    ]
+    for t in threads:
+        t.start()
+    # Let every thread reach the lock before the first conversion finishes.
+    deadline = threading.Event()
+    deadline.wait(0.3)
+    release.set()
+    for t in threads:
+        t.join(10)
+    assert len(calls) == 1
+    assert len(results) == 3 and len({r[0] for r in results}) == 1
+    assert sorted(p.name for p in stem.parent.iterdir()) == ["abc_display.jpg"]
+
+
+def test_the_reindex_sweep_keeps_live_display_copies_only(client, format_album, tmp_path):
+    from photomap.backend.thumbnail_cache import keep_hashes_for, prune, thumbnail_dir
+
+    img_dir = tmp_path / "formats"
+    for name in ("img.tif", "img.heic"):
+        assert client.get(f"/images/format_album/{name}").status_code == 200
+    tiles = thumbnail_dir(tmp_path / "formats.npz")
+    assert len(list(tiles.glob("*_display.jpg"))) == 2
+
+    # img.heic has since been deleted from the album.
+    live = [str((img_dir / "img.tif").resolve())]
+    removed = prune(tiles, keep_hashes_for(live, [str(img_dir)], lambda p: False))
+    assert removed == 1
+    remaining = list(tiles.glob("*_display.jpg"))
+    assert len(remaining) == 1
+    # And the survivor is the one the route still asks for.
+    with_cache = client.get("/images/format_album/img.tif")
+    assert with_cache.status_code == 200
+    assert remaining[0].read_bytes() == with_cache.content
diff --git a/tests/backend/test_thumbnail_cache.py b/tests/backend/test_thumbnail_cache.py
index b0839095..e3446001 100644
--- a/tests/backend/test_thumbnail_cache.py
+++ b/tests/backend/test_thumbnail_cache.py
@@ -503,3 +503,32 @@ def test_deleting_an_image_takes_its_tiles_with_it(self, client, mixed_album):
         assert response.status_code == 200, response.text
 
         assert not list(tiles.glob("*_64.png")), "the deleted image kept its tile"
+
+
+class TestDisplayCopies:
+    """The /images/ display copies share the tiles' directory and digest."""
+
+    def test_discard_takes_the_display_copy_too(self, tmp_path):
+        from photomap.backend.thumbnail_cache import display_copy_stem
+
+        stem = display_copy_stem(tmp_path, "scans/a.tif")
+        for suffix in (".jpg", ".webp"):
+            stem.with_name(stem.name + suffix).write_bytes(b"x")
+        other = display_copy_stem(tmp_path, "scans/b.tif").with_suffix(".jpg")
+        other.write_bytes(b"x")
+        assert thumbnail_cache.discard(tmp_path, "scans/a.tif", video=False) == 2
+        assert [p.name for p in tmp_path.iterdir()] == [other.name]
+
+    def test_an_abandoned_temporary_is_swept_even_for_a_live_image(self, tmp_path):
+        import os
+        import time
+
+        digest = tile_hash("a.tif", video=False)
+        fresh = tmp_path / f"{digest}_display.abc.tmp"
+        stale = tmp_path / f"{digest}_display.def.tmp"
+        fresh.write_bytes(b"x")
+        stale.write_bytes(b"x")
+        old = time.time() - 2 * 3600
+        os.utime(stale, (old, old))
+        assert prune(tmp_path, {digest}) == 1
+        assert fresh.exists() and not stale.exists()

From fabf2865674713d4c16de641f19783e01971ad8c Mon Sep 17 00:00:00 2001
From: Lincoln Stein <lincoln.stein@gmail.com>
Date: Sun, 4 Oct 2026 19:05:48 -0400
Subject: [PATCH 2/3] Key display copies on resolved path, album and source
 stamp

Adversarial review found the cached copy could show the wrong picture:
same-named files under a symlinked root (or a mapped Windows drive)
shared one copy, as did albums whose indexes share a directory, and a
source replaced with an older mtime, or edited mid-conversion, kept its
old copy. The copy's name now carries the album and a digest of the
source's mtime+size taken before decoding; the relative path is taken
from the resolved file, as the index stores it. Also: a copy written
after its source was deleted is removed, a greyscale profile is not
carried onto RGBA pixels, and an unwritable cache warns once.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 photomap/backend/routers/search.py    |  95 +++++++++++++-----
 photomap/backend/thumbnail_cache.py   |  16 ++-
 tests/backend/test_image_formats.py   | 139 +++++++++++++++++++++++++-
 tests/backend/test_thumbnail_cache.py |   7 +-
 4 files changed, 219 insertions(+), 38 deletions(-)

diff --git a/photomap/backend/routers/search.py b/photomap/backend/routers/search.py
index 5d6e4efe..d30a5f58 100644
--- a/photomap/backend/routers/search.py
+++ b/photomap/backend/routers/search.py
@@ -617,9 +617,18 @@ async def serve_image(
 
     if needs_browser_conversion(image_path) and not original:
         stem = None
-        relative_path = config_manager.get_relative_path(str(image_path), album_key)
-        if album_config.index and relative_path is not None:
-            stem = display_copy_stem(thumbnail_dir(Path(album_config.index)), relative_path)
+        try:
+            # Resolved, as the index stores it: get_relative_path resolves the
+            # roots, so an unresolved path under a symlinked root (or a mapped
+            # Windows drive) would fall back to the bare filename — keying
+            # every same-named image in the album onto one cached copy, and
+            # onto a digest the sweep and the delete path never produce.
+            resolved = image_path.resolve()
+        except (OSError, RuntimeError):
+            resolved = None
+        relative_path = resolved and config_manager.get_relative_path(str(resolved), album_key)
+        if album_config.index and relative_path:
+            stem = display_copy_stem(thumbnail_dir(Path(album_config.index)), relative_path, album_key)
         # Decoding a large scanned TIFF takes long enough to stall every other
         # request if done on the loop, so it runs in a worker thread.
         payload, media_type = await asyncio.to_thread(_display_copy, image_path, stem)
@@ -1273,17 +1282,21 @@ def _display_lock(key: str) -> threading.Lock:
 def _display_safe(im: Image.Image) -> Image.Image:
     """Return ``im`` as 8-bit L, RGB or RGBA — what JPEG and WebP can store."""
     im = _png_safe(im)
+    source_mode = im.mode
     if im.mode == "I;16":
         # _png_safe has already mapped deep data onto 0-65535 without
         # clipping; JPEG has no 16-bit mode, so take the top eight bits.
         arr = np.asarray(im, dtype=np.uint16)
         return Image.fromarray((arr >> 8).astype(np.uint8))
     if im.mode == "1":
-        return im.convert("L")
-    if im.mode == "P":
-        return im.convert("RGBA" if "transparency" in im.info else "RGB")
-    if im.mode == "LA":
-        return im.convert("RGBA")
+        im = im.convert("L")
+    elif im.mode == "P":
+        im = im.convert("RGBA" if "transparency" in im.info else "RGB")
+    elif im.mode == "LA":
+        im = im.convert("RGBA")
+    if im.mode != source_mode:
+        # As in _png_safe: a greyscale profile on RGB pixels misleads browsers.
+        im.info.pop("icc_profile", None)
     return im
 
 
@@ -1310,28 +1323,44 @@ def _encode_display_copy(image_path: Path) -> tuple[bytes, str]:
         return buf.getvalue(), ".jpg"
 
 
-def _read_fresh_display_copy(stem: Path, image_path: Path) -> tuple[bytes, str] | None:
+def _source_stamp(image_path: Path) -> str:
+    """A digest of the source's mtime and size, taken before it is decoded.
+
+    Part of the cached copy's name rather than compared against its mtime.
+    "Copy newer than source" misses a file replaced by one with an *older*
+    mtime (``cp -p``, a backup restore, a move out of an import folder), and
+    an edit saved while a slow scan was still being decoded — the copy is
+    written after the edit, so it looks fresh while showing the old picture.
+    A name derived from the stat taken up front misses neither.
+    """
+    st = image_path.stat()
+    return hashlib.blake2b(f"{st.st_mtime_ns}|{st.st_size}".encode(), digest_size=6).hexdigest()
+
+
+def _read_display_copy(base: Path) -> tuple[bytes, str] | None:
     for suffix, media_type in _DISPLAY_FORMATS.items():
-        path = stem.with_name(stem.name + suffix)
-        if not _thumbnail_is_fresh(path, image_path):
-            continue
         try:
-            payload = path.read_bytes()
+            payload = base.with_name(base.name + suffix).read_bytes()
         except OSError:
-            continue  # swept since the freshness check; rebuild it
+            continue  # not built yet, or swept since; rebuild it
         if payload:
             return payload, media_type
     return None
 
 
-def _store_display_copy(stem: Path, payload: bytes, suffix: str) -> None:
-    """Publish ``payload`` atomically, and drop the copy in the other format.
+# Index directories already warned about being unwritable. Once is enough: on
+# a read-only mount every view would otherwise log the same warning.
+_unwritable_display_dirs: set[Path] = set()
+
+
+def _store_display_copy(stem: Path, base: Path, payload: bytes, suffix: str, image_path: Path) -> None:
+    """Publish ``payload`` atomically, then drop every other copy of the file.
 
     Write-then-rename so a concurrent reader never sees half a file. A failed
     write is logged, not raised: the caller still has the bytes to serve, and
     an index directory on a read-only mount should cost speed, not pictures.
     """
-    target = stem.with_name(stem.name + suffix)
+    target = base.with_name(base.name + suffix)
     tmp_path: Path | None = None
     try:
         stem.parent.mkdir(parents=True, exist_ok=True)
@@ -1341,13 +1370,21 @@ def _store_display_copy(stem: Path, payload: bytes, suffix: str) -> None:
             handle.write(payload)
         os.replace(tmp_path, target)
         tmp_path = None
-        for other in _DISPLAY_FORMATS:
-            if other != suffix:
-                # An image edited to gain or lose transparency changes format;
-                # the old copy is stale and nothing would ever ask for it.
-                stem.with_name(stem.name + other).unlink(missing_ok=True)
+        # Copies of earlier versions of the source, or in the other format,
+        # can never be asked for again. (Temporaries are "<stem>.*.tmp" and
+        # so do not match.)
+        for stale in stem.parent.glob(f"{stem.name}_*"):
+            if stale != target and stale.suffix in _DISPLAY_FORMATS:
+                stale.unlink(missing_ok=True)
+        if not image_path.exists():
+            # Deleted while it was being converted: the delete's discard ran
+            # before this file existed, and a screen-sized copy of what may
+            # be a private image should not outlive it.
+            target.unlink(missing_ok=True)
     except OSError as e:
-        logger.warning(f"Could not cache the display copy {target}: {e}")
+        if stem.parent not in _unwritable_display_dirs:
+            _unwritable_display_dirs.add(stem.parent)
+            logger.warning(f"Could not cache the display copy {target}: {e}")
     finally:
         if tmp_path is not None:
             tmp_path.unlink(missing_ok=True)
@@ -1355,7 +1392,8 @@ def _store_display_copy(stem: Path, payload: bytes, suffix: str) -> None:
 
 def _display_copy(image_path: Path, stem: Path | None) -> tuple[bytes, str]:
     """The display copy of an image browsers cannot render, as (bytes, media
-    type), from the cache at ``stem`` when it is newer than the source.
+    type), from the cache at ``stem`` when one matches the source's current
+    mtime and size.
 
     ``stem`` is ``None`` when the album has nowhere to cache it; the copy is
     then built for this request only. Blocking: call it off the event loop.
@@ -1364,15 +1402,18 @@ def _display_copy(image_path: Path, stem: Path | None) -> tuple[bytes, str]:
         if stem is None:
             payload, suffix = _encode_display_copy(image_path)
             return payload, _DISPLAY_FORMATS[suffix]
-        if (cached := _read_fresh_display_copy(stem, image_path)) is not None:
+        base = stem.with_name(f"{stem.name}_{_source_stamp(image_path)}")
+        if (cached := _read_display_copy(base)) is not None:
             return cached
         with _display_lock(str(stem)):
             # Another request may have built it while this one waited.
-            if (cached := _read_fresh_display_copy(stem, image_path)) is not None:
+            if (cached := _read_display_copy(base)) is not None:
                 return cached
             payload, suffix = _encode_display_copy(image_path)
-            _store_display_copy(stem, payload, suffix)
+            _store_display_copy(stem, base, payload, suffix, image_path)
             return payload, _DISPLAY_FORMATS[suffix]
+    except FileNotFoundError:
+        raise HTTPException(status_code=404, detail="File not found") from None
     except Exception as e:
         logger.warning(f"Error converting image {image_path} for display: {e}")
         raise HTTPException(status_code=500, detail=f"Image processing error: {e}") from e
diff --git a/photomap/backend/thumbnail_cache.py b/photomap/backend/thumbnail_cache.py
index fb08f6d3..61a59556 100644
--- a/photomap/backend/thumbnail_cache.py
+++ b/photomap/backend/thumbnail_cache.py
@@ -80,16 +80,22 @@ def tile_hash(relative_path: str, *, video: bool) -> str:
     ).hexdigest()
 
 
-def display_copy_stem(directory: Path, relative_path: str) -> Path:
-    """Where the display copy of a TIFF/HEIC is cached, minus its suffix.
+def display_copy_stem(directory: Path, relative_path: str, album_key: str) -> Path:
+    """The common prefix of every display copy of one TIFF/HEIC in one album.
 
-    The suffix is the format (``.jpg``, or ``.webp`` for an image with
-    transparency), and is chosen when the copy is written. Keyed with
+    The route appends a stamp of the source's mtime and size and a format
+    suffix (``.jpg``, or ``.webp`` for an image with transparency). Keyed with
     :func:`tile_hash` so :func:`prune` and :func:`discard` reclaim it along
     with the file's tiles — a separate digest would need its own keep-set,
     and the sweep would delete every display copy if the two ever disagreed.
+
+    The album key rides along because the directory is addressed by index
+    location, not album: two albums whose index files sit side by side share
+    it, and camera filenames collide routinely, so without it one album's
+    ``IMG_0001.tif`` would be shown in place of the other's.
     """
-    return directory / f"{tile_hash(relative_path, video=False)}_display"
+    album_tag = hashlib.blake2b(album_key.encode("utf-8", "surrogateescape"), digest_size=4).hexdigest()
+    return directory / f"{tile_hash(relative_path, video=False)}_display_{album_tag}"
 
 
 def prune(directory: Path, keep_hashes: set[str]) -> int:
diff --git a/tests/backend/test_image_formats.py b/tests/backend/test_image_formats.py
index 2da7b8c7..fcf209b1 100644
--- a/tests/backend/test_image_formats.py
+++ b/tests/backend/test_image_formats.py
@@ -291,7 +291,8 @@ def slow(image_path):
         t.join(10)
     assert len(calls) == 1
     assert len(results) == 3 and len({r[0] for r in results}) == 1
-    assert sorted(p.name for p in stem.parent.iterdir()) == ["abc_display.jpg"]
+    names = [p.name for p in stem.parent.iterdir()]
+    assert len(names) == 1 and names[0].startswith("abc_display_") and names[0].endswith(".jpg"), names
 
 
 def test_the_reindex_sweep_keeps_live_display_copies_only(client, format_album, tmp_path):
@@ -301,15 +302,147 @@ def test_the_reindex_sweep_keeps_live_display_copies_only(client, format_album,
     for name in ("img.tif", "img.heic"):
         assert client.get(f"/images/format_album/{name}").status_code == 200
     tiles = thumbnail_dir(tmp_path / "formats.npz")
-    assert len(list(tiles.glob("*_display.jpg"))) == 2
+    assert len(list(tiles.glob("*_display_*.jpg"))) == 2
 
     # img.heic has since been deleted from the album.
     live = [str((img_dir / "img.tif").resolve())]
     removed = prune(tiles, keep_hashes_for(live, [str(img_dir)], lambda p: False))
     assert removed == 1
-    remaining = list(tiles.glob("*_display.jpg"))
+    remaining = list(tiles.glob("*_display_*.jpg"))
     assert len(remaining) == 1
     # And the survivor is the one the route still asks for.
     with_cache = client.get("/images/format_album/img.tif")
     assert with_cache.status_code == 200
     assert remaining[0].read_bytes() == with_cache.content
+
+
+def _solid_tif(path: Path, color, mtime: float | None = None) -> None:
+    import os
+
+    path.parent.mkdir(parents=True, exist_ok=True)
+    Image.new("RGB", (40, 40), color).save(path)
+    if mtime is not None:
+        os.utime(path, (mtime, mtime))
+
+
+def _shown_color(response):
+    assert response.status_code == 200, response.text
+    with Image.open(BytesIO(response.content)) as im:
+        return im.convert("RGB").getpixel((20, 20))
+
+
+def _add_album(client, key, root: Path, index: Path):
+    response = client.post(
+        "/add_album/",
+        json={
+            "key": key,
+            "name": key,
+            "image_paths": [root.as_posix()],
+            "index": index.as_posix(),
+            "umap_eps": 0.1,
+            "description": "",
+        },
+    )
+    assert response.status_code == 201, response.text
+
+
+def test_a_source_replaced_with_an_older_mtime_is_reconverted(client, format_album, tmp_path):
+    """``cp -p`` of an edited file, or a restore from backup."""
+    target = tmp_path / "formats" / "swap.tif"
+    _solid_tif(target, (255, 0, 0))
+    assert _shown_color(client.get("/images/format_album/swap.tif"))[0] > 200
+    _solid_tif(target, (0, 0, 255), mtime=target.stat().st_mtime - 3600)
+    assert _shown_color(client.get("/images/format_album/swap.tif"))[2] > 200
+
+
+def test_an_edit_during_conversion_is_not_cached_as_current(client, format_album, tmp_path, monkeypatch):
+    from photomap.backend.routers import search
+
+    import time
+
+    target = tmp_path / "formats" / "race.tif"
+    _solid_tif(target, (255, 0, 0), mtime=time.time() - 100)
+    real = search._encode_display_copy
+
+    def edited_meanwhile(image_path):
+        result = real(image_path)  # decoded the red version...
+        # ...then it was saved, before the copy was written.
+        _solid_tif(target, (0, 0, 255), mtime=time.time() - 50)
+        return result
+
+    monkeypatch.setattr(search, "_encode_display_copy", edited_meanwhile)
+    client.get("/images/format_album/race.tif")
+    monkeypatch.setattr(search, "_encode_display_copy", real)
+    assert _shown_color(client.get("/images/format_album/race.tif"))[2] > 200
+
+
+def test_same_named_images_under_a_symlinked_root_do_not_share_a_copy(client, tmp_path):
+    real = tmp_path / "real"
+    _solid_tif(real / "a" / "scan.tif", (255, 0, 0))
+    _solid_tif(real / "b" / "scan.tif", (0, 0, 255))
+    link = tmp_path / "link"
+    link.symlink_to(real, target_is_directory=True)
+    _add_album(client, "symlinked", link, tmp_path / "idx" / "embeddings.npz")
+    try:
+        assert _shown_color(client.get("/images/symlinked/a/scan.tif"))[0] > 200
+        assert _shown_color(client.get("/images/symlinked/b/scan.tif"))[2] > 200
+    finally:
+        client.delete("/delete_album/symlinked")
+
+
+def test_albums_sharing_an_index_directory_do_not_share_copies(client, tmp_path):
+    _solid_tif(tmp_path / "ra" / "IMG_0001.tif", (255, 0, 0))
+    _solid_tif(tmp_path / "rb" / "IMG_0001.tif", (0, 0, 255))
+    _add_album(client, "side_a", tmp_path / "ra", tmp_path / "indexes" / "a.npz")
+    _add_album(client, "side_b", tmp_path / "rb", tmp_path / "indexes" / "b.npz")
+    try:
+        assert _shown_color(client.get("/images/side_a/IMG_0001.tif"))[0] > 200
+        assert _shown_color(client.get("/images/side_b/IMG_0001.tif"))[2] > 200
+    finally:
+        client.delete("/delete_album/side_a")
+        client.delete("/delete_album/side_b")
+
+
+def test_an_edit_leaves_one_copy_behind_not_two(client, format_album, tmp_path):
+    from photomap.backend.thumbnail_cache import thumbnail_dir
+
+    target = tmp_path / "formats" / "edited.tif"
+    _solid_tif(target, (255, 0, 0))
+    client.get("/images/format_album/edited.tif")
+    _solid_tif(target, (0, 0, 255), mtime=target.stat().st_mtime + 5)
+    client.get("/images/format_album/edited.tif")
+    tiles = thumbnail_dir(tmp_path / "formats.npz")
+    before = {p.name for p in tiles.glob("*_display_*")}
+    client.get("/images/format_album/img.tif")
+    assert len({p.name for p in tiles.glob("*_display_*")} - before) == 1
+    assert len(before) == 1
+
+
+def test_an_image_deleted_mid_conversion_leaves_no_copy(client, format_album, tmp_path, monkeypatch):
+    from photomap.backend.routers import search
+    from photomap.backend.thumbnail_cache import thumbnail_dir
+
+    target = tmp_path / "formats" / "doomed.tif"
+    _solid_tif(target, (255, 0, 0))
+    real = search._encode_display_copy
+
+    def deleted_meanwhile(image_path):
+        result = real(image_path)
+        target.unlink()
+        return result
+
+    monkeypatch.setattr(search, "_encode_display_copy", deleted_meanwhile)
+    assert client.get("/images/format_album/doomed.tif").status_code == 200
+    assert not list(thumbnail_dir(tmp_path / "formats.npz").glob("*_display*"))
+
+
+def test_a_profile_is_dropped_when_the_mode_changes(tmp_path):
+    from PIL import ImageCms
+
+    from photomap.backend.routers.search import _display_safe
+
+    im = Image.new("LA", (4, 4), (100, 255))
+    im.info["icc_profile"] = ImageCms.ImageCmsProfile(ImageCms.createProfile("sRGB")).tobytes()
+    out = _display_safe(im)
+    assert out.mode == "RGBA"
+    assert "icc_profile" not in out.info
diff --git a/tests/backend/test_thumbnail_cache.py b/tests/backend/test_thumbnail_cache.py
index e3446001..110f2bce 100644
--- a/tests/backend/test_thumbnail_cache.py
+++ b/tests/backend/test_thumbnail_cache.py
@@ -511,10 +511,11 @@ class TestDisplayCopies:
     def test_discard_takes_the_display_copy_too(self, tmp_path):
         from photomap.backend.thumbnail_cache import display_copy_stem
 
-        stem = display_copy_stem(tmp_path, "scans/a.tif")
+        stem = display_copy_stem(tmp_path, "scans/a.tif", "album")
         for suffix in (".jpg", ".webp"):
-            stem.with_name(stem.name + suffix).write_bytes(b"x")
-        other = display_copy_stem(tmp_path, "scans/b.tif").with_suffix(".jpg")
+            stem.with_name(f"{stem.name}_0123456789ab{suffix}").write_bytes(b"x")
+        other = display_copy_stem(tmp_path, "scans/b.tif", "album")
+        other = other.with_name(f"{other.name}_0123456789ab.jpg")
         other.write_bytes(b"x")
         assert thumbnail_cache.discard(tmp_path, "scans/a.tif", video=False) == 2
         assert [p.name for p in tmp_path.iterdir()] == [other.name]

From 3d1f8f7564eb8bcdf6e78a67e50928c2115ee484 Mon Sep 17 00:00:00 2001
From: Lincoln Stein <lincoln.stein@gmail.com>
Date: Sun, 4 Oct 2026 19:11:46 -0400
Subject: [PATCH 3/3] Sweep only exact cache names; don't file an edit under
 the old stamp

From a second adversarial review:
- prune/discard matched any <32 hex>.jpg/.webp/.png, so a hash-named
  user photo beside a custom index path could be deleted. Both now match
  only the exact names the routes write.
- A source edited between the up-front stat and the decode was cached
  under the old stamp; restoring the original then showed the edit.
  Re-stat after encoding and serve without caching if it moved.
- A temporary swept mid-write marked the directory unwritable for good,
  silencing real failures; one undeletable sibling skipped the
  vanished-source check. Each step now handles its own errors.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 photomap/backend/routers/search.py    | 62 +++++++++++++++++++--------
 photomap/backend/thumbnail_cache.py   | 36 +++++++++-------
 tests/backend/test_image_formats.py   | 48 ++++++++++++++++++++-
 tests/backend/test_thumbnail_cache.py | 16 ++++++-
 4 files changed, 124 insertions(+), 38 deletions(-)

diff --git a/photomap/backend/routers/search.py b/photomap/backend/routers/search.py
index d30a5f58..b6c44fab 100644
--- a/photomap/backend/routers/search.py
+++ b/photomap/backend/routers/search.py
@@ -1361,33 +1361,48 @@ def _store_display_copy(stem: Path, base: Path, payload: bytes, suffix: str, ima
     an index directory on a read-only mount should cost speed, not pictures.
     """
     target = base.with_name(base.name + suffix)
-    tmp_path: Path | None = None
     try:
         stem.parent.mkdir(parents=True, exist_ok=True)
         fd, tmp_name = tempfile.mkstemp(dir=stem.parent, prefix=f"{stem.name}.", suffix=".tmp")
         tmp_path = Path(tmp_name)
         with os.fdopen(fd, "wb") as handle:
             handle.write(payload)
-        os.replace(tmp_path, target)
-        tmp_path = None
-        # Copies of earlier versions of the source, or in the other format,
-        # can never be asked for again. (Temporaries are "<stem>.*.tmp" and
-        # so do not match.)
-        for stale in stem.parent.glob(f"{stem.name}_*"):
-            if stale != target and stale.suffix in _DISPLAY_FORMATS:
-                stale.unlink(missing_ok=True)
-        if not image_path.exists():
-            # Deleted while it was being converted: the delete's discard ran
-            # before this file existed, and a screen-sized copy of what may
-            # be a private image should not outlive it.
-            target.unlink(missing_ok=True)
     except OSError as e:
         if stem.parent not in _unwritable_display_dirs:
             _unwritable_display_dirs.add(stem.parent)
             logger.warning(f"Could not cache the display copy {target}: {e}")
-    finally:
-        if tmp_path is not None:
-            tmp_path.unlink(missing_ok=True)
+        return
+    try:
+        os.replace(tmp_path, target)
+    except OSError as e:
+        # Usually a delete or sweep that took the temporary away mid-write —
+        # not a sign the directory is unwritable, so not remembered as one.
+        logger.debug(f"Could not publish the display copy {target}: {e}")
+        tmp_path.unlink(missing_ok=True)
+        return
+    # Copies of earlier versions of the source, or in the other format, can
+    # never be asked for again. (Temporaries are "<stem>.*.tmp" and so do not
+    # match.) One at a time: a copy another request still has open cannot be
+    # unlinked on Windows, and that must not skip the rest — least of all the
+    # vanished-source check below.
+    try:
+        siblings = list(stem.parent.glob(f"{stem.name}_*"))
+    except OSError:
+        siblings = []
+    for stale in siblings:
+        if stale != target and stale.suffix in _DISPLAY_FORMATS:
+            try:
+                stale.unlink(missing_ok=True)
+            except OSError as e:
+                logger.debug(f"Could not remove the stale display copy {stale}: {e}")
+    if not image_path.exists():
+        # Deleted while it was being converted: the delete's discard ran
+        # before this file existed, and a screen-sized copy of what may be a
+        # private image should not outlive it.
+        try:
+            target.unlink(missing_ok=True)
+        except OSError as e:
+            logger.debug(f"Could not remove the display copy of deleted {image_path}: {e}")
 
 
 def _display_copy(image_path: Path, stem: Path | None) -> tuple[bytes, str]:
@@ -1402,7 +1417,8 @@ def _display_copy(image_path: Path, stem: Path | None) -> tuple[bytes, str]:
         if stem is None:
             payload, suffix = _encode_display_copy(image_path)
             return payload, _DISPLAY_FORMATS[suffix]
-        base = stem.with_name(f"{stem.name}_{_source_stamp(image_path)}")
+        stamp = _source_stamp(image_path)
+        base = stem.with_name(f"{stem.name}_{stamp}")
         if (cached := _read_display_copy(base)) is not None:
             return cached
         with _display_lock(str(stem)):
@@ -1410,7 +1426,15 @@ def _display_copy(image_path: Path, stem: Path | None) -> tuple[bytes, str]:
             if (cached := _read_display_copy(base)) is not None:
                 return cached
             payload, suffix = _encode_display_copy(image_path)
-            _store_display_copy(stem, base, payload, suffix, image_path)
+            try:
+                unchanged = _source_stamp(image_path) == stamp
+            except FileNotFoundError:
+                unchanged = False  # deleted meanwhile; serve, don't cache
+            if unchanged:
+                # Otherwise the pixels may be the new version filed under the
+                # old version's name, and restoring the old file (cp -p, a
+                # backup) would then show the edit.
+                _store_display_copy(stem, base, payload, suffix, image_path)
             return payload, _DISPLAY_FORMATS[suffix]
     except FileNotFoundError:
         raise HTTPException(status_code=404, detail="File not found") from None
diff --git a/photomap/backend/thumbnail_cache.py b/photomap/backend/thumbnail_cache.py
index 61a59556..341af7d2 100644
--- a/photomap/backend/thumbnail_cache.py
+++ b/photomap/backend/thumbnail_cache.py
@@ -28,12 +28,24 @@
 
 THUMBNAIL_DIRNAME = "thumbnails"
 
-# What tile_hash emits: blake2b-128, rendered lowercase.
-_DIGEST_RE = re.compile(r"[0-9a-f]{32}")
-
-# Every suffix this module's writers produce: PNG tiles, JPEG/WebP display
-# copies, and the temporaries a display copy is written through.
-_CACHE_SUFFIXES = frozenset({".png", ".jpg", ".webp", ".tmp"})
+# Exactly the names the routes write, with the tile_hash digest (blake2b-128,
+# lowercase) captured: PNG tiles "<digest>_<size>[_<colour>_r<radius>].png",
+# display copies "<digest>_display_<album tag>_<stamp>.<jpg|webp>", and the
+# temporaries a display copy is written through. Anything else was not written
+# by this code and is left alone rather than guessed at — this code deletes
+# files, and a directory beside a custom index path may hold the user's own
+# hash-named photos.
+_OWNED_NAME_RE = re.compile(
+    r"(?P<digest>[0-9a-f]{32})"
+    r"(?:_\d+(?:_[0-9A-Fa-f,]+_r\d+)?\.png"
+    r"|_display_[0-9a-f]{8}_[0-9a-f]{12}\.(?:jpg|webp)"
+    r"|_display_[0-9a-f]{8}\.[^/]+\.tmp)"
+)
+
+
+def _owned_digest(name: str) -> str | None:
+    match = _OWNED_NAME_RE.fullmatch(name)
+    return match["digest"] if match else None
 
 # A temporary is only ever live for the length of one conversion. One older
 # than this belongs to a writer that crashed or was killed, and is swept even
@@ -126,14 +138,8 @@ def prune(directory: Path, keep_hashes: set[str]) -> int:
     removed = 0
     now = time.time()
     for entry in entries:
-        if entry.suffix not in _CACHE_SUFFIXES:
-            continue
-        # "<32 lowercase hex digits>_<size>[...]"; anything else was not
-        # written by the route and is left alone rather than guessed at. The
-        # hex check is part of that promise: a 32-character stem is not
-        # necessarily a digest, and this code deletes files.
-        digest = entry.stem.split("_", 1)[0]
-        if not _DIGEST_RE.fullmatch(digest):
+        digest = _owned_digest(entry.name)
+        if digest is None:
             continue
         if digest in keep_hashes and not _is_abandoned_tmp(entry, now):
             continue
@@ -162,7 +168,7 @@ def discard(directory: Path, relative_path: str, *, video: bool) -> int:
     digest = tile_hash(relative_path, video=video)
     removed = 0
     for entry in directory.glob(f"{digest}_*"):
-        if entry.suffix not in _CACHE_SUFFIXES:
+        if _owned_digest(entry.name) != digest:
             continue
         try:
             entry.unlink()
diff --git a/tests/backend/test_image_formats.py b/tests/backend/test_image_formats.py
index fcf209b1..1af31561 100644
--- a/tests/backend/test_image_formats.py
+++ b/tests/backend/test_image_formats.py
@@ -356,10 +356,10 @@ def test_a_source_replaced_with_an_older_mtime_is_reconverted(client, format_alb
 
 
 def test_an_edit_during_conversion_is_not_cached_as_current(client, format_album, tmp_path, monkeypatch):
-    from photomap.backend.routers import search
-
     import time
 
+    from photomap.backend.routers import search
+
     target = tmp_path / "formats" / "race.tif"
     _solid_tif(target, (255, 0, 0), mtime=time.time() - 100)
     real = search._encode_display_copy
@@ -446,3 +446,47 @@ def test_a_profile_is_dropped_when_the_mode_changes(tmp_path):
     out = _display_safe(im)
     assert out.mode == "RGBA"
     assert "icc_profile" not in out.info
+
+
+def test_an_edit_before_decoding_is_not_filed_under_the_old_stamp(client, format_album, tmp_path, monkeypatch):
+    """Otherwise restoring the original (``cp -p``, a backup) shows the edit."""
+    import os
+
+    from photomap.backend.routers import search
+
+    target = tmp_path / "formats" / "restore.tif"
+    _solid_tif(target, (255, 0, 0))
+    original = target.stat()
+    backup = tmp_path / "restore.bak"
+    backup.write_bytes(target.read_bytes())
+    real = search._encode_display_copy
+
+    def edited_first(image_path):
+        # Same size, as an uncompressed TIFF of fixed dimensions would be.
+        _solid_tif(target, (0, 0, 255), mtime=original.st_mtime + 10)
+        return real(image_path)
+
+    monkeypatch.setattr(search, "_encode_display_copy", edited_first)
+    client.get("/images/format_album/restore.tif")
+    monkeypatch.setattr(search, "_encode_display_copy", real)
+
+    target.write_bytes(backup.read_bytes())
+    os.utime(target, ns=(original.st_atime_ns, original.st_mtime_ns))
+    assert _shown_color(client.get("/images/format_album/restore.tif"))[0] > 200
+
+
+def test_a_temporary_swept_mid_write_does_not_silence_later_warnings(tmp_path, monkeypatch, caplog):
+    from photomap.backend.routers import search
+
+    source = tmp_path / "scan.tif"
+    Image.new("RGB", (10, 10)).save(source)
+    stem = tmp_path / "thumbs" / ("0" * 32 + "_display_00000000")
+    real_replace = search.os.replace
+
+    def swept(src, dst):
+        Path(src).unlink()
+        return real_replace(src, dst)
+
+    monkeypatch.setattr(search.os, "replace", swept)
+    search._display_copy(source, stem)
+    assert stem.parent not in search._unwritable_display_dirs
diff --git a/tests/backend/test_thumbnail_cache.py b/tests/backend/test_thumbnail_cache.py
index 110f2bce..3ed4c67c 100644
--- a/tests/backend/test_thumbnail_cache.py
+++ b/tests/backend/test_thumbnail_cache.py
@@ -525,11 +525,23 @@ def test_an_abandoned_temporary_is_swept_even_for_a_live_image(self, tmp_path):
         import time
 
         digest = tile_hash("a.tif", video=False)
-        fresh = tmp_path / f"{digest}_display.abc.tmp"
-        stale = tmp_path / f"{digest}_display.def.tmp"
+        fresh = tmp_path / f"{digest}_display_00000000.abc.tmp"
+        stale = tmp_path / f"{digest}_display_00000000.def.tmp"
         fresh.write_bytes(b"x")
         stale.write_bytes(b"x")
         old = time.time() - 2 * 3600
         os.utime(stale, (old, old))
         assert prune(tmp_path, {digest}) == 1
         assert fresh.exists() and not stale.exists()
+
+    def test_the_sweep_leaves_hash_named_user_photos_alone(self, tmp_path):
+        """A thumbnails/ folder beside a custom index path may be the user's."""
+        for name in (
+            "d41d8cd98f00b204e9800998ecf8427e.jpg",
+            "d41d8cd98f00b204e9800998ecf8427e.webp",
+            "d41d8cd98f00b204e9800998ecf8427e.png",
+            "d41d8cd98f00b204e9800998ecf8427e_holiday.jpg",
+        ):
+            (tmp_path / name).write_bytes(b"x")
+        assert prune(tmp_path, set()) == 0
+        assert thumbnail_cache.discard(tmp_path, "x", video=False) == 0