feat: heap convert-to-folder + surface exact-duplicate detection

Two related polish items.

1. Heap convert to folder
   Closes a long-standing TODO from spec §6.10.
   - Backend: POST /heaps/{id}/convert with body
       { target_id, mode: 'move'|'copy', delete_heap: bool }
     target_id resolves either as a Folder id or a SourceRoot id (same
     convention as /photos/move). For each member photo, dispatches
     either shutil.move + photo.folder_id update, or shutil.copy2 +
     a new is_duplicate=true Photo row with all metadata copied. Name
     collisions on copy use the same " (copy N)" suffix scheme as
     /photos/copy. The heap row is optionally deleted on success.
     Per-photo failures are collected into the response instead of
     aborting the batch.
   - Frontend: new HeapConvertDialog with a target-folder dropdown
     (currently from sourceFolders.list, sub-folder picking is a
     follow-up), move/copy radio, and a "delete heap" checkbox.
     HeapsPanel rows get a hover FolderOutput button that opens it.
     Toast on success names the verb + count and notes whether the
     heap was deleted; invalidates heaps + photos + folders queries.

2. Surface exact-duplicate detection
   The scanner already sets Photo.is_duplicate=true when a SHA-256
   match is found, but nothing surfaced it. Now:
   - Backend list_photos accepts an optional is_duplicate query
     param so the frontend can filter duplicates-only views.
   - filterStore gains a duplicates: boolean field with setter, URL
     sync (?duplicates=true), filtersToParams entry, and a
     hasActiveFilters check.
   - LeftSidebar gets a new "Duplicates" library node (Copy icon)
     that clearAllFilters() + setDuplicates(true). isItemActive
     follows the filter so the highlight stays in sync after
     external filter changes.
   - PhotoThumbnail renders a small dark badge with the Copy icon
     bottom-right when photo.is_duplicate. Sits next to the existing
     basket / discard badges so the user can spot duplicates at a
     glance.
   - Photo TS type adds is_duplicate.

Perceptual-hash duplicate detection (re-encoded / resized matches)
is intentionally a follow-up — needs an imagehash dep, a phash
column, a backfill job, and similarity-search endpoint with
hamming-distance grouping. This commit only surfaces what the
scanner already finds via byte-level SHA-256 comparison.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

backend/app/routers/heaps.py

@@ -1,16 +1,22 @@
 """
 Heaps API router
 """
-from typing import Optional
+import os
+import shutil
+import logging
+from typing import Optional, Literal
 from fastapi import APIRouter, Depends, HTTPException
 from pydantic import BaseModel
 from sqlalchemy import select, func, update, insert, delete
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.database import get_db
-from app.models import Heap
+from app.models import Heap, Photo, Folder
+from app.models.folders import SourceRoot
 from app.models.heaps import heap_photos
 
+logger = logging.getLogger(__name__)
+
 router = APIRouter()
 
 
@@ -29,6 +35,12 @@ class HeapPhotosBody(BaseModel):
     photo_ids: list[str]
 
 
+class HeapConvertBody(BaseModel):
+    target_id: str  # folder id OR source root id
+    mode: Literal['move', 'copy'] = 'move'
+    delete_heap: bool = False
+
+
 # ── Endpoints ─────────────────────────────────────────────────────────────
 
 @router.get("")
@@ -180,6 +192,141 @@ async def add_photos_to_heap(
     return {"status": "success", "added": len(new_ids), "already_present": len(existing_ids)}
 
 
+@router.post("/{heap_id}/convert")
+async def convert_heap_to_folder(
+    heap_id: str,
+    body: HeapConvertBody,
+    db: AsyncSession = Depends(get_db),
+):
+    """Convert a heap into a folder by moving (or copying) every member
+    photo into the target directory. Optionally deletes the heap row at
+    the end.
+
+    target_id may be a Folder id or a SourceRoot id (matches the
+    /photos/move convention so the same dropdown can populate it).
+    """
+    heap_result = await db.execute(select(Heap).where(Heap.id == heap_id))
+    heap = heap_result.scalar_one_or_none()
+    if not heap:
+        raise HTTPException(status_code=404, detail="Heap not found")
+
+    # Resolve target_id → (target_dir, target_folder)
+    sr_check = await db.execute(
+        select(SourceRoot).where(SourceRoot.id == body.target_id)
+    )
+    source_root = sr_check.scalar_one_or_none()
+
+    if source_root is not None:
+        target_dir = source_root.path
+        from app.tasks.scan import get_or_create_folder
+        target_folder = await get_or_create_folder(db, target_dir, source_root.id)
+    else:
+        folder_check = await db.execute(
+            select(Folder).where(Folder.id == body.target_id)
+        )
+        target_folder = folder_check.scalar_one_or_none()
+        if target_folder is None:
+            raise HTTPException(status_code=404, detail="Target folder not found")
+        target_dir = target_folder.path
+
+    if not os.path.isdir(target_dir):
+        raise HTTPException(
+            status_code=400,
+            detail=f"Target directory does not exist: {target_dir}",
+        )
+
+    # Fetch the heap's photos via the join table.
+    photo_result = await db.execute(
+        select(Photo)
+        .join(heap_photos, Photo.id == heap_photos.c.photo_id)
+        .where(heap_photos.c.heap_id == heap_id)
+    )
+    photos = photo_result.scalars().all()
+
+    moved = 0
+    copied = 0
+    errors: list[dict] = []
+
+    def _unique_target_name(directory: str, filename: str) -> Optional[str]:
+        if not os.path.exists(os.path.join(directory, filename)):
+            return filename
+        stem, ext = os.path.splitext(filename)
+        for i in range(1, 100):
+            suffix = '' if i == 1 else f' {i}'
+            candidate = f"{stem} (copy{suffix}){ext}"
+            if not os.path.exists(os.path.join(directory, candidate)):
+                return candidate
+        return None
+
+    for photo in photos:
+        if not os.path.exists(photo.filepath):
+            errors.append({"id": photo.id, "error": "source file missing"})
+            continue
+
+        if body.mode == 'move':
+            if photo.folder_id == target_folder.id:
+                continue  # already there
+            new_path = os.path.join(target_dir, photo.filename)
+            if os.path.exists(new_path):
+                errors.append({"id": photo.id, "error": f"name collision: {photo.filename}"})
+                continue
+            try:
+                shutil.move(photo.filepath, new_path)
+            except OSError as e:
+                errors.append({"id": photo.id, "error": str(e)})
+                continue
+            photo.filepath = new_path
+            photo.folder_id = target_folder.id
+            moved += 1
+        else:  # copy
+            new_name = _unique_target_name(target_dir, photo.filename)
+            if new_name is None:
+                errors.append({"id": photo.id, "error": "too many name collisions"})
+                continue
+            new_path = os.path.join(target_dir, new_name)
+            try:
+                shutil.copy2(photo.filepath, new_path)
+            except OSError as e:
+                errors.append({"id": photo.id, "error": str(e)})
+                continue
+            new_photo = Photo(
+                filepath=new_path,
+                filename=new_name,
+                folder_id=target_folder.id,
+                file_hash=photo.file_hash,
+                media_type=photo.media_type,
+                original_format=photo.original_format,
+                width=photo.width,
+                height=photo.height,
+                file_size=photo.file_size,
+                taken_at=photo.taken_at,
+                taken_at_source=photo.taken_at_source,
+                user_title=photo.user_title,
+                user_notes=photo.user_notes,
+                rating=photo.rating,
+                color_label=photo.color_label,
+                exif_json=photo.exif_json,
+                is_duplicate=True,
+                processing_status='pending',
+            )
+            db.add(new_photo)
+            copied += 1
+
+    if body.delete_heap:
+        await db.delete(heap)
+
+    await db.commit()
+
+    return {
+        "status": "success",
+        "mode": body.mode,
+        "moved": moved,
+        "copied": copied,
+        "errors": errors,
+        "heap_deleted": body.delete_heap,
+    }
+
+
 @router.delete("/{heap_id}/photos")
 async def remove_photos_from_heap(
     heap_id: str, body: HeapPhotosBody, db: AsyncSession = Depends(get_db)

backend/app/routers/photos.py

@@ -37,6 +37,7 @@ async def list_photos(
     rating_max: Optional[int] = Query(None, ge=0, le=5),
     color_label: Optional[str] = None,
     is_discarded: Optional[bool] = False,
+    is_duplicate: Optional[bool] = None,
     heap_id: Optional[str] = None,
     sort: str = "taken_at",
     order: str = "desc",
@@ -113,6 +114,11 @@ async def list_photos(
     # Discard filter — defaults to hiding discarded photos
     filters.append(Photo.is_discarded == is_discarded)
 
+    # Duplicate filter — only applied when explicitly set, so the default
+    # view shows everything regardless of duplicate status.
+    if is_duplicate is not None:
+        filters.append(Photo.is_duplicate == is_duplicate)
+
     # Heap membership filter — restrict to photos that belong to the heap.
     if heap_id:
         filters.append(