feat(compose): opt-in GPU overlay for VA-API ffmpeg accel

Layer docker-compose.gpu.yml to mount /dev/dri/{card0,renderD128}
into pp-app, add it to render (992) + video (44) groups, and set
PHOTOPRISM_FFMPEG_ENCODER=vaapi. Hosts without a VA-API device just
skip the overlay (`-f docker-compose.yml -f docker-compose.gpu.yml`
becomes opt-in per deploy).

Drops video transcode + thumbnail generation from CPU to the iGPU
where present — large win for HEVC libraries. README documents the
flag; default behavior on the base compose is unchanged.

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

.env

@@ -1,20 +0,0 @@
-# Mulita / PhotoVault local environment.
-# See .env.example for the full list of knobs and their docs.
-
-# REQUIRED — host path to your photo library.
-PHOTO_DIRS=/Users/dtoro/Pictures/MulitaTest
-
-# Ports — change if 3000 / 8001 collide with other services on the host.
-FRONTEND_PORT=3000
-BACKEND_PORT=8001
-REDIS_PORT=6379
-
-# CORS — wildcard for local dev. Lock down for real deployments.
-ALLOWED_ORIGINS=*
-
-# Logging + timezone.
-LOG_LEVEL=INFO
-TZ=UTC
-
-# Celery worker pool.
-CELERYD_CONCURRENCY=4

.env.example

@@ -1,83 +1,70 @@
-# ─────────────────────────────────────────────────────────────────────────────
-# Mulita / PhotoVault — example environment file
+# Example environment file. Copy to `.env` and adjust.
 #
-# Copy this file to `.env` and adjust the values for your setup. Every key
-# below has a sensible default in docker-compose.yml, so you only need to
-# uncomment the ones you actually want to change.
-# ─────────────────────────────────────────────────────────────────────────────
+#   podman-compose --env-file .env \
+#     -f docker-compose.yml -f docker-compose.podman.yml up -d
 
 
 # ── REQUIRED ─────────────────────────────────────────────────────────────────
 
-# Host path to your photo library. The compose file mounts this at /photos
-# inside the backend + worker containers. The backend creates a default
-# source root pointing at /photos on first boot, so once this is set the
-# library is scanned with zero further configuration.
+# Host path to your photo library. PhotoPrism reads this in place and
+# writes EXIF backwrites next to originals (when PP_ORIGINALS_MODE=rw).
+PHOTO_DIRS=/mnt/library/homecloud/admin/files/
+
+# Bootstrap admin password. The first PhotoPrism boot creates an `admin`
+# account with this password. Rotate after first login from the UI.
+PP_ADMIN_PASSWORD=please-change-me
+
+# MariaDB passwords. Generate with `openssl rand -hex 24`.
+PP_DB_PASSWORD=please-change-me
+PP_DB_ROOT_PASSWORD=please-change-me
+
+
+# ── OPTIONAL ─────────────────────────────────────────────────────────────────
+
+# Loopback host port for PhotoPrism's API (and UI, if you tunnel to it).
+# Vite proxies /api/v1/* here and the host-mode sidecar reaches it on
+# localhost. Not published on the public interface.
+PP_PORT=2342
+
+# Site URL — used for share links, OIDC redirect URI, and reverse-proxy aware
+# URL generation. Set to the public hostname once the proxy is in front.
+PP_SITE_URL=http://localhost:2342/
+
+# Auth mode — "password" for username/password (default), "public" for an
+# unauthenticated kiosk mode (don't use this on a multi-user library).
+PP_AUTH_MODE=password
+
+# Library mount mode. "rw" allows rename / folder mutations / EXIF backwrite;
+# "ro" is safe-for-archives but disables those sidecar endpoints. Set in
+# lockstep with PP_READONLY below.
+PP_ORIGINALS_MODE=rw
+PP_READONLY=false
+
+# UID/GID inside the PhotoPrism container. Set these to the host UID/GID that
+# owns ${PHOTO_DIRS}. `id -u` and `id -g`.
+PP_UID=1000
+PP_GID=1000
+
+
+# ── OIDC SSO (Authentik or equivalent) ───────────────────────────────────────
+# Leave blank to keep OIDC dormant. Fill in to enable the "Sign in with OIDC"
+# button on the login page; OIDC_REGISTER=true auto-creates accounts at role
+# `user` (override to `admin` to grant full access on first SSO login).
 #
-# Examples:
-#   macOS / Linux:    PHOTO_DIRS=/Users/you/Pictures
-#   Network share:    PHOTO_DIRS=/mnt/nas/photos
-#   Windows (WSL):    PHOTO_DIRS=/mnt/c/Users/you/Pictures
-PHOTO_DIRS=./photos
+# The compose file reads these and maps them to PhotoPrism's actual env-var
+# names (PHOTOPRISM_OIDC_URI / _CLIENT / _SECRET / _PROVIDER) — see the
+# comment in docker-compose.yml. The PhotoPrism callback URI is auto-derived
+# from PP_SITE_URL; do not set it manually.
+
+# OIDC_PROVIDER_NAME=Authentik
+# OIDC_ISSUER_URL=https://auth.example.com/application/o/photoprism/
+# OIDC_CLIENT_ID=...
+# OIDC_CLIENT_SECRET=...
+# OIDC_SCOPES=openid profile email
+# OIDC_REGISTER=true
+# OIDC_ROLE=user
 
 
-# ── PORTS ────────────────────────────────────────────────────────────────────
+# ── LOGGING ──────────────────────────────────────────────────────────────────
 
-# Host port the SPA is served on. Browse to http://<host>:<FRONTEND_PORT>/.
-FRONTEND_PORT=3000
-
-# Host port for the backend API. Almost never needed directly — the frontend
-# nginx proxies /api/ to the backend over the internal compose network. Kept
-# exposed for debugging / curl.
-BACKEND_PORT=8001
-
-# Redis host port. Internal services reach Redis on its container name; this
-# is just for local debugging.
-REDIS_PORT=6379
-
-
-# ── CORS ─────────────────────────────────────────────────────────────────────
-
-# Comma-separated list of allowed origins for direct browser access to the
-# backend. Same-origin requests through the nginx / vite proxy never trip
-# CORS, so this only matters when something hits the backend port directly
-# from a different origin (e.g. another machine, dev tools, a reverse proxy
-# under a different hostname).
-#
-# Default "*" is permissive, fine for a single-user homelab. Lock it down in
-# real deployments:
-#   ALLOWED_ORIGINS=https://photos.example.com
-#   ALLOWED_ORIGINS=https://photos.example.com,http://192.168.1.10:3000
-ALLOWED_ORIGINS=*
-
-
-# ── LOGGING / TIMEZONE ───────────────────────────────────────────────────────
-
-# Python log level for the backend and Celery worker. Bump to DEBUG when
-# chasing scan / thumbnail issues.
-LOG_LEVEL=INFO
-
-# Container timezone. Affects the timestamps in logs and the "added at"
-# field on newly imported photos. Defaults to UTC.
-#   TZ=Europe/Berlin
-#   TZ=America/New_York
-TZ=UTC
-
-
-# ── WORKER CONCURRENCY ───────────────────────────────────────────────────────
-
-# How many parallel Celery worker processes to spin up. Each one can run
-# one scan / thumbnail / metadata job at a time. Bump on a beefy host with a
-# big library; lower on a Pi.
-CELERYD_CONCURRENCY=4
-
-
-# ── INTERNAL (rarely overridden) ─────────────────────────────────────────────
-
-# These point at the in-compose Redis and the bind-mounted SQLite db. Override
-# only if you're running Mulita without docker-compose or against an external
-# Redis.
-# REDIS_URL=redis://redis:6379
-# CELERY_BROKER_URL=redis://redis:6379
-# CELERY_RESULT_BACKEND=redis://redis:6379
-# DATABASE_URL=sqlite+aiosqlite:////data/db/mulita.db
+PP_LOG_LEVEL=info

.gitignore

@@ -34,6 +34,7 @@ dist-ssr/
 .DS_Store
 
 # Environment
+.env
 .env.local
 .env.*.local
 
@@ -60,9 +61,18 @@ build/
 # Docker
 docker-compose.override.yml
 
+# PhotoPrism state (sidecars, cache, thumbs, db backups) — regenerable.
+/pp/storage/
+/pp/import/
+
+# Sidecar runtime state (per-user marks etc.) — generated, not seed data.
+/sidecar/data/
+
+# Sidecar Go build output.
+/sidecar/mule-sidecar
+
 # Photos (for development)
 /photos/
 
 # Thumbnails
 /thumbs/
-/trash/

README.md

@@ -1,227 +1,140 @@
-# Mulita - Self-Hosted Photo Management Application
+# mule-image
 
-A self-hosted, Docker-deployed photo management application inspired by Lightroom's workflow. Mulita provides a fast, keyboard-driven interface to browse, organize, tag, and manage your photo library.
-
-## Features
-
-- **Photo Organization**: Browse photos in a timeline view with virtual scrolling for performance
-- **Thumbnail Generation**: Automatic thumbnail generation for all photo formats including RAW
-- **Metadata Extraction**: Full EXIF/XMP metadata extraction and search
-- **Keyboard Shortcuts**: Lightroom-style keyboard navigation and actions
-- **File Support**: JPEG, PNG, RAW formats (CR2, CR3, NEF, ARW, etc.), HEIC/HEIF, and videos
-- **Heaps**: Temporary collections for organizing photos
-- **Tags & Ratings**: Organize with tags, star ratings, and color labels
-- **Dark Mode**: Photography-optimized dark interface
-
-## Tech Stack
-
-### Backend
-- Python 3.12 with FastAPI
-- SQLite with SQLAlchemy (async)
-- Celery + Redis for background tasks
-- pyvips for fast thumbnail generation
-- ExifTool for metadata extraction
-
-### Frontend
-- React 18 with TypeScript
-- Vite for fast development
-- TanStack Query for data fetching
-- TanStack Virtual for virtualized scrolling
-- Tailwind CSS for styling
-- Zustand for state management
-
-## Quick Start
-
-### Prerequisites
-- Docker and Docker Compose
-
-### Setup (one variable)
-
-1. Clone the repo:
-```bash
-git clone <repository-url>
-cd muleimage
-```
-
-2. Copy the example env file and set **one** variable — the **host**
-   directory that contains your photo library. Whatever you point at
-   will become your library inside Mulita.
-
-   ```bash
-   cp .env.example .env
-   # then edit .env and set PHOTO_DIRS:
-   #   macOS / Linux:    PHOTO_DIRS=/Users/you/Pictures
-   #   Network share:    PHOTO_DIRS=/mnt/nas/photos
-   #   Windows (WSL):    PHOTO_DIRS=/mnt/c/Users/you/Pictures
-   ```
-
-3. Start the stack:
-```bash
-docker compose up -d
-```
-
-4. Open `http://localhost:3000`. On first boot Mulita will:
-   - Mount your `PHOTO_DIRS` at `/photos` inside the container
-   - Auto-create a source root called **Library** pointing at `/photos`
-   - Queue an initial scan, generate thumbnails, and start serving them
-
-You don't need to touch `mulita.yml` or the API to get started.
-
-### Configuration knobs
-
-Everything is environment-driven. `PHOTO_DIRS` is the only required
-value; the rest have sensible defaults documented in `.env.example`:
-
-| Variable             | Default | Notes                                              |
-|----------------------|---------|----------------------------------------------------|
-| `PHOTO_DIRS`         | —       | **Required.** Host path mounted at `/photos`.      |
-| `FRONTEND_PORT`      | `3000`  | SPA host port. Bump if `3000` is taken.            |
-| `BACKEND_PORT`       | `8001`  | Direct backend port (debug only — frontend uses internal nginx proxy). |
-| `REDIS_PORT`         | `6379`  | Redis host port (internal services don't need it). |
-| `ALLOWED_ORIGINS`    | `*`     | Comma-separated CORS origins for direct backend access. Lock down for prod, e.g. `https://photos.example.com`. |
-| `LOG_LEVEL`          | `INFO`  | Backend + worker log level. `DEBUG` for chasing scan issues. |
-| `TZ`                 | `UTC`   | Container timezone. Affects log timestamps and "added at". |
-| `CELERYD_CONCURRENCY`| `4`     | Parallel worker processes (scans, thumbs, metadata). Lower on a Pi, higher on a beefy host. |
-
-### Accessing from another machine
-
-The frontend talks to the backend through its bundled nginx, which
-proxies `/api/` to the backend on the internal compose network. That
-means requests are always **same-origin** as the page, so accessing
-Mulita from another host works without any CORS dance:
-
-```
-http://<your-server-ip>:3000
-```
-
-If you want to put it behind a reverse proxy at e.g.
-`https://photos.your.tld`, set `ALLOWED_ORIGINS` to that host so the
-backend's direct port (`BACKEND_PORT`) also accepts cross-origin
-requests if anything bypasses the proxy.
-
-### How libraries are managed
-
-Mulita is **config-driven**: the host directory you mount via
-`PHOTO_DIRS` becomes your library, and the backend automatically
-registers it as a source root on startup. There is no UI for adding
-or removing source roots — to change what Mulita scans, edit `.env`
-(or `docker-compose.yml` for multi-mount setups) and restart the
-stack.
-
-This keeps the model simple: **the docker mount IS the library**.
-No two layers, no confusion about which view to use.
-
-### Changing or adding libraries
-
-To point at a different library:
-1. Edit `PHOTO_DIRS` in `.env`
-2. `docker compose down`
-3. (Optional, for a clean slate) `docker volume rm muleimage_db_data muleimage_thumbs_data muleimage_proxies_data`
-4. `docker compose up -d`
-
-The new library shows up automatically. Without step 3 the old
-library's metadata stays in the DB and you'll see a warning at
-startup that the old source root's path is missing on disk —
-that's a hint to clean up.
-
-For multiple libraries, edit `docker-compose.yml` and add additional
-mount lines:
-
-```yaml
-volumes:
-  - ${PHOTO_DIRS}:/photos:rw
-  - /Volumes/Archive:/archive:rw   # additional library
-```
-
-Each mounted directory will need a corresponding source root row in
-the DB; today that means `POST /api/v1/folders` via curl, or wait
-for the multi-mount auto-registration that's on the roadmap.
-
-### Read-only libraries
-
-The default mount is `:rw` because file operations (rename, move,
-empty discard pile) need to mutate the filesystem. If you want a
-strict read-only library — pointing at a network share, an
-authoritative archive, etc. — flip `:rw` to `:ro` in
-`docker-compose.yml`. Mulita will keep working for browsing, rating,
-color labels, picks, heaps, and the (soft) discard flag, but the
-following will return an OS error:
-
-- `PATCH /photos/{id}` with a new `filename` (rename)
-- `POST /photos/move` (bulk move)
-- `DELETE /discard/empty` (file unlinks)
-
-**Heads up**: with `:rw`, Mulita has full write access to whatever
-host directory you mount. Treat the same way you would Lightroom's
-catalog folder.
+Self-hosted photo management built on top of [PhotoPrism][pp]. A SvelteKit
+frontend ([`web/`](web/)) plus a small Go service ([`sidecar/`](sidecar/))
+fill in the keyboard-driven UI and the file/folder/mark endpoints
+PhotoPrism's REST API does not expose. PhotoPrism itself handles
+indexing, originals, thumbnails, and the database; we never re-implement
+those.
 
 ## Architecture
 
-The application consists of 5 Docker services:
-
-- **frontend**: React SPA served by Nginx
-- **backend**: FastAPI REST API
-- **worker**: Celery workers for background tasks
-- **redis**: Message broker for Celery
-- **db**: SQLite database (file-based)
-
-## Keyboard Shortcuts
-
-| Key | Action |
-|-----|--------|
-| `←` `→` `↑` `↓` | Navigate photos |
-| `Space` | Quick preview |
-| `Enter` | Open loupe view |
-| `P` | Pick photo |
-| `X` | Reject photo |
-| `1-5` | Set star rating |
-| `Tab` | Toggle left sidebar |
-| `I` | Toggle metadata panel |
-| `G` | Grid view |
-| `E` | Loupe view |
-| `Delete` | Move to trash |
-
-## Development
-
-### Backend Development
-```bash
-cd backend
-pip install -r requirements.txt
-uvicorn app.main:app --reload
+```text
+┌──────────────────┐    /api/v1/*      ┌──────────────┐
+│  SvelteKit web/  │ ───────────────▶  │  photoprism  │ ──▶ mariadb
+│  (Vite : 5173)   │    /api/sidecar/* │   :2342      │
+│                  │ ─────────┐        └──────────────┘
+└──────────────────┘          ▼
+                      ┌──────────────┐
+                      │  sidecar     │ ──▶ mariadb (mule_sidecar.*)
+                      │  :8000       │ ──▶ originals FS (rename / folders / dups)
+                      └──────────────┘
 ```
 
-### Frontend Development
+Three compose services — `mariadb`, `photoprism`, `sidecar` — plus the
+SvelteKit `web/` app served separately. PhotoPrism's port `2342` is
+**bound to `127.0.0.1` only**; it isn't a user-facing surface. The
+SvelteKit app is.
+
+What the sidecar adds on top of PhotoPrism (full list in
+[`sidecar/README.md`](sidecar/README.md)):
+
+- Per-photo marks (rating + color) persisted to `mule_sidecar.marks`
+- File rename + folder create/rename/delete with PhotoPrism reindex
+- Heap (album) → folder conversion
+- Perceptual-hash duplicate scan + archive
+
+## Quick start
+
 ```bash
-cd frontend
+cp .env.example .env
+# edit .env: set PHOTO_DIRS to the host path holding your library
+# rotate PP_ADMIN_PASSWORD, PP_DB_PASSWORD, PP_DB_ROOT_PASSWORD
+# before any non-local deployment.
+
+podman-compose --env-file .env \
+  -f docker-compose.yml \
+  -f docker-compose.podman.yml \
+  up -d
+```
+
+Then serve the frontend. For local use the simplest path is the Vite
+dev server:
+
+```bash
+cd web
 npm install
 npm run dev
+# open http://localhost:5173
 ```
 
+For a static deployment, `npm run build` produces a bundle under
+`web/build/` that any static file host (nginx, Caddy, GitHub Pages-style)
+can serve. Reverse-proxy `/api/v1/*` to `http://127.0.0.1:2342` and
+`/api/sidecar/*` to `http://127.0.0.1:8000`.
+
+PhotoPrism's own UI is still reachable from the host at
+`http://127.0.0.1:2342` if you need admin features (user management,
+settings) — set up an SSH tunnel from your laptop if the server is
+remote.
+
 ## Configuration
 
-Source roots are managed by the UI / API (the database owns them). Edit
-`mulita.yml` to configure operational settings only:
+All knobs live in [`.env.example`](.env.example). The required ones:
 
-- Thumbnail sizes, quality, and format
-- Scanner behaviour (watch, batch size, initial scan)
-- Performance tuning (concurrency, cache TTLs, DB pool)
+| Variable             | Notes                                                                                         |
+|----------------------|-----------------------------------------------------------------------------------------------|
+| `PHOTO_DIRS`         | Host path mounted at `/photoprism/originals`. The library.                                    |
+| `PP_ADMIN_PASSWORD`  | First-boot admin password. Rotate.                                                            |
+| `PP_DB_PASSWORD`     | MariaDB password for the `photoprism` user. Rotate.                                           |
+| `PP_DB_ROOT_PASSWORD`| MariaDB root password. Rotate.                                                                |
+| `PP_UID` / `PP_GID`  | Host UID/GID that owns `PHOTO_DIRS`. PhotoPrism + sidecar drop to this user inside.           |
+| `PP_PORT`            | Loopback host port for PhotoPrism (default `2342`).                                           |
+| `PP_ORIGINALS_MODE`  | `rw` (default) or `ro` — see [Read-only libraries](#read-only-libraries).                     |
+| `SIDECAR_PORT`       | Loopback host port for the sidecar (default `8000`).                                          |
 
-## Performance
+Sidecar-specific env (DB DSN, `USER_BASEPATHS`, etc.) is documented in
+[`sidecar/README.md`](sidecar/README.md).
 
-- Handles 100,000+ photos efficiently
-- Virtual scrolling for smooth timeline navigation
-- Thumbnail generation at 10+ photos/second
-- SQLite FTS5 for fast full-text search
+## Read-only libraries
 
-## Future Features (Phase 2)
+The default originals mount is `:rw` because file operations (rename,
+folder mutations, duplicate archive, heap convert) need to mutate the
+filesystem. To run against a read-only archive, set
+`PP_ORIGINALS_MODE=ro` in `.env`. Browsing, marks, ratings, and color
+labels still work; the following sidecar endpoints return an OS error:
 
-- AI-powered scene classification
-- Face detection and clustering
-- Smart albums
-- Duplicate detection
-- Export presets
-- Multi-user support
+- `POST /api/sidecar/files/:uid/rename`
+- `POST /api/sidecar/folders` / `:rel/rename` / `DELETE /:rel`
+- `POST /api/sidecar/albums/:uid/convert`
+- `POST /api/sidecar/duplicates/archive`
 
-## License
+PhotoPrism's `PHOTOPRISM_READONLY` is controlled separately by
+`PP_READONLY` and gates its own backwrite / import paths.
 
-MIT
+## Dev iteration loop
+
+For fast iteration on the sidecar without rebuilding its image on every
+change, run it as a host process — bring up just `mariadb` and
+`photoprism` from compose, then build and run the Go binary locally.
+Full instructions in [`sidecar/README.md`](sidecar/README.md#dev-iteration-loop-host-build).
+
+## Layout
+
+```text
+.
+├── docker-compose.yml         base stack: mariadb + photoprism + sidecar
+├── docker-compose.podman.yml  rootless-podman overlay (keep-id mapping)
+├── docker-compose.gpu.yml     opt-in VA-API GPU passthrough overlay
+├── .env.example               required env vars (copy to .env)
+├── mariadb/init/              first-boot SQL: creates mule_sidecar DB + user
+├── pp/                        PhotoPrism bind-mounted state (storage, import)
+├── sidecar/                   Go service — see sidecar/README.md
+└── web/                       SvelteKit frontend
+```
+
+## GPU video acceleration (optional)
+
+Hosts with a VA-API-capable GPU (Intel iGPU, AMD APU, etc.) can layer
+[`docker-compose.gpu.yml`](docker-compose.gpu.yml) to hand `/dev/dri/*`
+to PhotoPrism and switch ffmpeg to hardware encode/decode — a large
+perf win for video thumbnails and HEVC→H.264 transcodes:
+
+```bash
+docker compose -f docker-compose.yml -f docker-compose.gpu.yml up -d
+```
+
+Set `PP_FFMPEG_ENCODER=vaapi` in `.env` (default for the overlay). Verify
+with `docker exec pp-app photoprism show config | grep -i ffmpeg`.
+
+[pp]: https://photoprism.app/

backend/Dockerfile

@@ -1,39 +0,0 @@
-FROM python:3.12-slim
-
-# Install system dependencies
-RUN apt-get update && apt-get install -y \
-    # Build dependencies
-    gcc \
-    g++ \
-    make \
-    # Image processing libraries
-    libvips42 \
-    libvips-dev \
-    # ExifTool for metadata extraction
-    libimage-exiftool-perl \
-    # FFmpeg for video processing
-    ffmpeg \
-    # Git for some Python packages
-    git \
-    # PostgreSQL client (for potential future use)
-    postgresql-client \
-    # Clean up
-    && rm -rf /var/lib/apt/lists/*
-
-WORKDIR /app
-
-# Copy requirements first for better caching
-COPY requirements.txt .
-RUN pip install --no-cache-dir -r requirements.txt
-
-# Copy application code
-COPY . .
-
-# Create necessary directories
-RUN mkdir -p /data/thumbs /data/db /data/proxies /app/config
-
-# Expose port
-EXPOSE 8000
-
-# Run the application
-CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000", "--reload"]

backend/app/config.py

@@ -1,133 +0,0 @@
-"""
-Application configuration using Pydantic Settings
-"""
-from pydantic_settings import BaseSettings
-from pydantic import BaseModel, Field
-from typing import Optional
-import yaml
-from pathlib import Path
-
-class ThumbnailSettings(BaseModel):
-    """Thumbnail generation settings"""
-    small: int = 240
-    medium: int = 640
-    large: int = 1280
-    quality: int = 85
-    format: str = "webp"
-
-class ScannerSettings(BaseModel):
-    """File scanner settings"""
-    watch: bool = True
-    initial_scan_on_start: bool = True
-    batch_size: int = 100
-    concurrent_workers: int = 4
-
-class PerformanceSettings(BaseModel):
-    """Performance tuning settings"""
-    max_concurrent_thumbnails: int = 10
-    cache_ttl: int = 3600
-    db_pool_size: int = 20
-    db_pool_recycle: int = 3600
-
-class MulitaConfig(BaseModel):
-    """Main configuration from YAML file. Source roots and the discard
-    workflow are owned by the database now — only operational settings
-    live here."""
-    thumbnails: ThumbnailSettings = ThumbnailSettings()
-    scanner: ScannerSettings = ScannerSettings()
-    performance: PerformanceSettings = PerformanceSettings()
-
-class Settings(BaseSettings):
-    """Application settings"""
-    # Database
-    database_url: str = Field(
-        default="sqlite+aiosqlite:///data/db/mulita.db",
-        env="DATABASE_URL"
-    )
-    
-    # Redis
-    redis_url: str = Field(
-        default="redis://localhost:6379",
-        env="REDIS_URL"
-    )
-    
-    # Celery
-    celery_broker_url: str = Field(
-        default="redis://localhost:6379",
-        env="CELERY_BROKER_URL"
-    )
-    celery_result_backend: str = Field(
-        default="redis://localhost:6379",
-        env="CELERY_RESULT_BACKEND"
-    )
-    
-    # Photo directories
-    photo_dirs: str = Field(
-        default="/photos",
-        env="PHOTO_DIRS"
-    )
-    
-    # API settings
-    api_host: str = Field(default="0.0.0.0", env="API_HOST")
-    api_port: int = Field(default=8000, env="API_PORT")
-
-    # CORS — comma-separated list of allowed origins, or "*" for any.
-    # Same-origin requests (the normal case behind nginx / vite proxy)
-    # never trip CORS, so this is only for direct browser access from
-    # other origins (LAN IP, reverse proxy, dev tools).
-    allowed_origins: str = Field(default="*", env="ALLOWED_ORIGINS")
-
-    # Logging — accepts standard python levels (DEBUG, INFO, WARNING,
-    # ERROR, CRITICAL). Bumped from INFO when chasing a problem.
-    log_level: str = Field(default="INFO", env="LOG_LEVEL")
-
-    @property
-    def cors_origins(self) -> list[str]:
-        """Parse the ALLOWED_ORIGINS env var into a list. Accepts:
-          - "*" → wildcard (single-element list ["*"])
-          - "http://a.com,http://b.com" → split + strip
-        Empty entries are dropped.
-        """
-        raw = (self.allowed_origins or "").strip()
-        if not raw or raw == "*":
-            return ["*"]
-        return [o.strip() for o in raw.split(",") if o.strip()]
-
-    # App configuration from YAML
-    _config: Optional[MulitaConfig] = None
-    
-    @property
-    def config(self) -> MulitaConfig:
-        """Load configuration from YAML file"""
-        if self._config is None:
-            config_path = Path("/app/config/mulita.yml")
-            if not config_path.exists():
-                config_path = Path("mulita.yml")
-            
-            if config_path.exists():
-                with open(config_path, "r") as f:
-                    config_data = yaml.safe_load(f)
-                    self._config = MulitaConfig(**config_data)
-            else:
-                self._config = MulitaConfig()
-        
-        return self._config
-    
-    @property
-    def thumbnails(self) -> ThumbnailSettings:
-        return self.config.thumbnails
-    
-    @property
-    def scanner(self) -> ScannerSettings:
-        return self.config.scanner
-
-    @property
-    def performance(self) -> PerformanceSettings:
-        return self.config.performance
-
-    class Config:
-        env_file = ".env"
-        case_sensitive = False
-
-# Global settings instance
-settings = Settings()

backend/app/database.py

@@ -1,129 +0,0 @@
-"""
-Database configuration and session management
-"""
-from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine, async_sessionmaker
-from sqlalchemy.orm import declarative_base
-from sqlalchemy import event, text
-import logging
-import os
-from pathlib import Path
-
-from app.config import settings
-
-logger = logging.getLogger(__name__)
-
-# Create database directory if it doesn't exist
-db_path = Path(settings.database_url.replace("sqlite+aiosqlite:///", ""))
-db_path.parent.mkdir(parents=True, exist_ok=True)
-
-# Create async engine
-# SQLite doesn't support pool configuration
-if "sqlite" in settings.database_url:
-    engine = create_async_engine(
-        settings.database_url,
-        echo=False,  # Set to True for SQL debugging
-        connect_args={
-            "check_same_thread": False,  # SQLite specific
-            "timeout": 30
-        }
-    )
-else:
-    engine = create_async_engine(
-        settings.database_url,
-        echo=False,  # Set to True for SQL debugging
-        pool_size=settings.performance.db_pool_size,
-        pool_recycle=settings.performance.db_pool_recycle
-    )
-
-# Create async session factory
-AsyncSessionLocal = async_sessionmaker(
-    engine,
-    class_=AsyncSession,
-    expire_on_commit=False
-)
-
-# Base class for models
-Base = declarative_base()
-
-async def get_db() -> AsyncSession:
-    """Dependency to get database session"""
-    async with AsyncSessionLocal() as session:
-        try:
-            yield session
-        finally:
-            await session.close()
-
-async def init_db():
-    """Initialize database, create tables if they don't exist"""
-    async with engine.begin() as conn:
-        # Import all models to register them with Base
-        from app.models import Photo, Folder, SourceRoot, Tag, PhotoTag, Heap, HeapPhoto, Embedding
-
-        # Create all tables. Note: create_all only creates *missing* tables —
-        # it does NOT add new columns to existing tables when the model gains
-        # them. Anything new on an existing table needs an explicit ALTER
-        # below.
-        await conn.run_sync(Base.metadata.create_all)
-
-        # Enable WAL mode for SQLite (better concurrency)
-        if "sqlite" in settings.database_url:
-            await conn.execute(text("PRAGMA journal_mode=WAL"))
-            await conn.execute(text("PRAGMA synchronous=NORMAL"))
-            await conn.execute(text("PRAGMA cache_size=10000"))
-            await conn.execute(text("PRAGMA temp_store=MEMORY"))
-
-        # ── Idempotent column adds ────────────────────────────────────────
-        # The project does not use Alembic; we lean on create_all + a small
-        # set of inline ALTER TABLE statements for the columns we've added
-        # post-launch. SQLite supports ADD COLUMN but not "IF NOT EXISTS"
-        # for columns, so introspect via PRAGMA first. Each entry is
-        # (column_name, ALTER statement). Add new columns at the bottom.
-        if "sqlite" in settings.database_url:
-            existing_cols = {
-                row[1]
-                for row in (
-                    await conn.execute(text("PRAGMA table_info(photos)"))
-                ).fetchall()
-            }
-            pending_alters: list[tuple[str, str]] = [
-                ("phash", "ALTER TABLE photos ADD COLUMN phash VARCHAR(16)"),
-                (
-                    "duplicate_group_id",
-                    "ALTER TABLE photos ADD COLUMN duplicate_group_id VARCHAR",
-                ),
-            ]
-            for col_name, alter_sql in pending_alters:
-                if col_name not in existing_cols:
-                    logger.info(f"Adding photos.{col_name} column")
-                    await conn.execute(text(alter_sql))
-            # Indexes for the new duplicate-detection columns. CREATE INDEX
-            # IF NOT EXISTS is supported on SQLite so this is safe to run
-            # every startup.
-            await conn.execute(
-                text("CREATE INDEX IF NOT EXISTS ix_photos_phash ON photos(phash)")
-            )
-            await conn.execute(
-                text(
-                    "CREATE INDEX IF NOT EXISTS ix_photos_duplicate_group_id "
-                    "ON photos(duplicate_group_id)"
-                )
-            )
-
-        logger.info("Database initialized successfully")
-
-async def create_fts_table():
-    """Create Full-Text Search table for SQLite"""
-    if "sqlite" in settings.database_url:
-        async with engine.begin() as conn:
-            # Create FTS5 virtual table for full-text search
-            await conn.execute(text("""
-                CREATE VIRTUAL TABLE IF NOT EXISTS photos_fts USING fts5(
-                    photo_id UNINDEXED,
-                    filename,
-                    user_title,
-                    user_notes,
-                    exif_text,
-                    tokenize='unicode61'
-                )
-            """))
-            logger.info("FTS5 table created successfully")

backend/app/main.py

@@ -1,107 +0,0 @@
-"""
-Mulita - Photo Management Application
-Main FastAPI application entry point
-"""
-from contextlib import asynccontextmanager
-from fastapi import FastAPI
-from fastapi.middleware.cors import CORSMiddleware
-from fastapi.staticfiles import StaticFiles
-import logging
-import os
-
-from app.config import settings
-from app.database import init_db
-from app.routers import photos, folders, heaps, tags, discard, library
-from app.services.scanner import start_initial_scan, bootstrap_default_source_root
-from app.services.cleanup import cleanup_data_integrity
-
-# Configure logging
-logging.basicConfig(
-    level=logging.INFO,
-    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
-)
-logger = logging.getLogger(__name__)
-
-@asynccontextmanager
-async def lifespan(app: FastAPI):
-    """Manage application lifecycle"""
-    logger.info("Starting Mulita application...")
-
-    # Initialize database
-    await init_db()
-
-    # First-boot convenience: if there are no source roots in the DB yet,
-    # create one for the default /photos mount so the user sees their
-    # library immediately without configuring anything in the UI.
-    try:
-        await bootstrap_default_source_root()
-    except Exception as e:
-        logger.error(f"Bootstrap source root failed (continuing): {e}")
-
-    # One-shot cleanup of duplicate source_roots / folders left over from
-    # earlier scanner versions that didn't normalize paths. Idempotent.
-    try:
-        await cleanup_data_integrity()
-    except Exception as e:
-        logger.error(f"Startup cleanup failed (continuing): {e}")
-
-    # Start initial scan if configured
-    if settings.scanner.initial_scan_on_start:
-        logger.info("Starting initial library scan...")
-        await start_initial_scan()
-
-    yield
-
-    logger.info("Shutting down Mulita application...")
-
-# Create FastAPI app
-app = FastAPI(
-    title="Mulita Photo Management API",
-    description="Self-hosted photo management application inspired by Lightroom",
-    version="1.0.0",
-    lifespan=lifespan
-)
-
-# Configure CORS. The frontend normally talks to the backend through the
-# nginx (prod) or vite (dev) proxy, so requests are same-origin and never
-# trip CORS. ALLOWED_ORIGINS in .env controls the fallback for direct
-# browser access from other origins (LAN IP, reverse proxy under a
-# different host). Defaults to "*" since this is a single-user homelab
-# tool; lock it down by setting e.g. ALLOWED_ORIGINS=https://photos.your.tld
-# in production deployments.
-_origins = settings.cors_origins
-app.add_middleware(
-    CORSMiddleware,
-    allow_origins=_origins,
-    # Wildcard origins can't be combined with credentials per the CORS
-    # spec, so credentials get auto-disabled in that case.
-    allow_credentials=_origins != ["*"],
-    allow_methods=["*"],
-    allow_headers=["*"],
-)
-
-# Mount static files for serving thumbnails (with X-Accel-Redirect support)
-if os.path.exists("/data/thumbs"):
-    app.mount("/thumbs", StaticFiles(directory="/data/thumbs"), name="thumbs")
-
-# Include routers
-app.include_router(photos.router, prefix="/api/v1/photos", tags=["photos"])
-app.include_router(folders.router, prefix="/api/v1/folders", tags=["folders"])
-app.include_router(heaps.router, prefix="/api/v1/heaps", tags=["heaps"])
-app.include_router(tags.router, prefix="/api/v1/tags", tags=["tags"])
-app.include_router(discard.router, prefix="/api/v1/discard", tags=["discard"])
-app.include_router(library.router, prefix="/api/v1/library", tags=["library"])
-
-@app.get("/")
-async def root():
-    """Root endpoint"""
-    return {
-        "name": "Mulita Photo Management API",
-        "version": "1.0.0",
-        "status": "running"
-    }
-
-@app.get("/health")
-async def health_check():
-    """Health check endpoint for Docker"""
-    return {"status": "healthy"}

backend/app/models/__init__.py

@@ -1,19 +0,0 @@
-"""
-Database models for Mulita
-"""
-from app.models.photos import Photo
-from app.models.folders import Folder, SourceRoot
-from app.models.tags import Tag, PhotoTag
-from app.models.heaps import Heap, HeapPhoto
-from app.models.embeddings import Embedding
-
-__all__ = [
-    'Photo',
-    'Folder',
-    'SourceRoot',
-    'Tag',
-    'PhotoTag',
-    'Heap',
-    'HeapPhoto',
-    'Embedding'
-]

backend/app/models/embeddings.py

@@ -1,17 +0,0 @@
-"""
-Embedding model definition (placeholder for AI features)
-"""
-from sqlalchemy import Column, String, ForeignKey, LargeBinary
-import uuid
-
-from app.database import Base
-
-class Embedding(Base):
-    """
-    Placeholder table for future AI embeddings (CLIP, face recognition, etc.)
-    """
-    __tablename__ = 'embeddings'
-    
-    photo_id = Column(String, ForeignKey('photos.id', ondelete='CASCADE'), primary_key=True)
-    model = Column(String)  # e.g., 'clip-vit-b32', 'face-recognition', etc.
-    vector = Column(LargeBinary)  # raw float32 bytes for embedding vector

backend/app/models/folders.py

@@ -1,43 +0,0 @@
-"""
-Folder and SourceRoot model definitions
-"""
-from sqlalchemy import Column, String, Integer, Boolean, DateTime, ForeignKey, Index
-from sqlalchemy.sql import func
-from sqlalchemy.orm import relationship
-import uuid
-
-from app.database import Base
-
-class SourceRoot(Base):
-    __tablename__ = 'source_roots'
-    
-    id = Column(String, primary_key=True, default=lambda: str(uuid.uuid4()))
-    name = Column(String, nullable=False)
-    path = Column(String, unique=True, nullable=False)
-    is_active = Column(Boolean, default=True)
-    added_at = Column(DateTime, server_default=func.now())
-    
-    # Relationships
-    folders = relationship("Folder", back_populates="source_root")
-
-class Folder(Base):
-    __tablename__ = 'folders'
-    
-    id = Column(String, primary_key=True, default=lambda: str(uuid.uuid4()))
-    name = Column(String, nullable=False)
-    path = Column(String, unique=True, nullable=False)
-    parent_id = Column(String, ForeignKey('folders.id'))
-    source_root_id = Column(String, ForeignKey('source_roots.id'))
-    photo_count = Column(Integer, default=0)
-    last_scanned = Column(DateTime)
-    
-    # Relationships
-    source_root = relationship("SourceRoot", back_populates="folders")
-    photos = relationship("Photo", backref="folder")
-    
-    # Indexes
-    __table_args__ = (
-        Index('ix_folders_path', 'path'),
-        Index('ix_folders_parent_id', 'parent_id'),
-        Index('ix_folders_source_root_id', 'source_root_id'),
-    )

backend/app/models/heaps.py

@@ -1,37 +0,0 @@
-"""
-Heap model definitions
-"""
-from sqlalchemy import Column, String, Integer, Boolean, DateTime, ForeignKey, Table, Index
-from sqlalchemy.sql import func
-from sqlalchemy.orm import relationship
-import uuid
-
-from app.database import Base
-
-# Association table for many-to-many relationship with additional fields
-heap_photos = Table(
-    'heap_photos',
-    Base.metadata,
-    Column('heap_id', String, ForeignKey('heaps.id', ondelete='CASCADE'), primary_key=True),
-    Column('photo_id', String, ForeignKey('photos.id', ondelete='CASCADE'), primary_key=True),
-    Column('added_at', DateTime, server_default=func.now()),
-    Column('sort_order', Integer, default=0),
-    Index('ix_heap_photos_heap_id', 'heap_id'),
-    Index('ix_heap_photos_photo_id', 'photo_id'),
-)
-
-class Heap(Base):
-    __tablename__ = 'heaps'
-    
-    id = Column(String, primary_key=True, default=lambda: str(uuid.uuid4()))
-    name = Column(String, nullable=False)
-    created_at = Column(DateTime, server_default=func.now())
-    updated_at = Column(DateTime, onupdate=func.now())
-    is_active = Column(Boolean, default=False)  # For active heap feature
-    
-    # Relationships
-    photos = relationship("Photo", secondary=heap_photos, backref="heaps")
-
-class HeapPhoto:
-    """Helper class for heap-photo associations (not a table model)"""
-    pass

backend/app/models/photos.py

@@ -1,94 +0,0 @@
-"""
-Photo model definition
-"""
-from sqlalchemy import Column, String, Integer, Boolean, DateTime, ForeignKey, Text, Index
-from sqlalchemy.sql import func
-from datetime import datetime
-import uuid
-
-from app.database import Base
-
-class Photo(Base):
-    __tablename__ = 'photos'
-    
-    # Primary key
-    id = Column(String, primary_key=True, default=lambda: str(uuid.uuid4()))
-    
-    # File information
-    filepath = Column(String, unique=True, nullable=False)
-    filename = Column(String, nullable=False)
-    folder_id = Column(String, ForeignKey('folders.id'))
-    file_hash = Column(String, index=True)  # SHA-256 hash for duplicate detection
-    
-    # Media information
-    media_type = Column(String, nullable=False)  # 'photo' | 'video' | 'raw' | 'heic'
-    original_format = Column(String)  # 'CR3', 'NEF', 'HEIC', 'MP4', 'JPEG', etc.
-    width = Column(Integer)
-    height = Column(Integer)
-    file_size = Column(Integer)
-    
-    # Timestamps
-    taken_at = Column(DateTime)  # from EXIF DateTimeOriginal, fallback to file mtime
-    taken_at_source = Column(String)  # 'exif' | 'filesystem' | 'manual'
-    added_at = Column(DateTime, server_default=func.now())
-    updated_at = Column(DateTime, onupdate=func.now())
-    
-    # Discard status. The DB column names stay is_trashed/trashed_at to avoid
-    # a migration; only the Python attribute name reflects the rename.
-    is_discarded = Column('is_trashed', Boolean, default=False)
-    discarded_at = Column('trashed_at', DateTime)
-    
-    # Thumbnail paths
-    thumb_small = Column(String)  # path to 240px thumb
-    thumb_medium = Column(String)  # path to 640px thumb
-    thumb_large = Column(String)  # path to 1280px thumb
-    
-    # Processing status
-    processing_status = Column(String, default='pending')  # 'pending' | 'processing' | 'completed' | 'failed'
-    processing_error = Column(Text)
-    
-    # Metadata
-    exif_json = Column(Text)  # full EXIF/XMP blob as JSON
-    
-    # User-editable fields
-    user_title = Column(String)
-    user_notes = Column(Text)
-    rating = Column(Integer, default=0)  # 0-5 stars
-    color_label = Column(String)  # 'red'|'orange'|'yellow'|'green'|'blue'|'purple'|NULL
-    # Note: is_rejected was merged into is_discarded (a single soft "discarded"
-    # concept). is_picked was unified with active-heap membership — picking a
-    # photo just means adding it to the active heap. Both DB columns may still
-    # exist on legacy installs but are no longer read or written.
-    
-    # Duplicate detection.
-    #
-    #   - file_hash (above): SHA-256 of the raw bytes. Catches byte-identical
-    #     copies but not visually-identical re-encodes / resizes / screenshots.
-    #   - phash: 16-char hex of a 64-bit perceptual hash, computed by the
-    #     thumbs worker from the decoded original frame. Robust to resize and
-    #     re-compression — this is what actually identifies "the same photo
-    #     saved twice with different JPEG quality".
-    #   - duplicate_group_id: shared by every photo in the same duplicate
-    #     cluster. Maintained by app.services.duplicates.regroup_duplicates,
-    #     not on individual writes — recomputed in batches after scans / on
-    #     demand from the Settings panel.
-    #   - is_duplicate: derived boolean (group_id IS NOT NULL). Kept as a real
-    #     column so the existing PhotoThumbnail badge and /library/stats
-    #     duplicates count don't have to change.
-    is_duplicate = Column(Boolean, default=False)
-    phash = Column(String(16), index=True)
-    duplicate_group_id = Column(String, index=True)
-    
-    # Live photo support
-    live_photo_video_id = Column(String, ForeignKey('photos.id'))
-    
-    # Indexes for performance
-    __table_args__ = (
-        Index('ix_photos_taken_at', 'taken_at'),
-        Index('ix_photos_folder_id', 'folder_id'),
-        Index('ix_photos_is_trashed', 'is_trashed'),
-        Index('ix_photos_rating', 'rating'),
-        Index('ix_photos_color_label', 'color_label'),
-        Index('ix_photos_media_type', 'media_type'),
-        Index('ix_photos_processing_status', 'processing_status'),
-    )

backend/app/models/tags.py

@@ -1,32 +0,0 @@
-"""
-Tag model definitions
-"""
-from sqlalchemy import Column, String, ForeignKey, Table, Index
-from sqlalchemy.orm import relationship
-import uuid
-
-from app.database import Base
-
-# Association table for many-to-many relationship
-photo_tags = Table(
-    'photo_tags',
-    Base.metadata,
-    Column('photo_id', String, ForeignKey('photos.id', ondelete='CASCADE'), primary_key=True),
-    Column('tag_id', String, ForeignKey('tags.id', ondelete='CASCADE'), primary_key=True),
-    Index('ix_photo_tags_photo_id', 'photo_id'),
-    Index('ix_photo_tags_tag_id', 'tag_id'),
-)
-
-class Tag(Base):
-    __tablename__ = 'tags'
-    
-    id = Column(String, primary_key=True, default=lambda: str(uuid.uuid4()))
-    name = Column(String, unique=True, nullable=False, index=True)
-    color = Column(String)  # Hex color code for UI display
-    
-    # Relationships
-    photos = relationship("Photo", secondary=photo_tags, backref="tags")
-
-class PhotoTag:
-    """Helper class for photo-tag associations (not a table model)"""
-    pass

backend/app/routers/discard.py

@@ -1,94 +0,0 @@
-"""
-Discard API router
-"""
-import os
-import logging
-from fastapi import APIRouter, Depends, HTTPException, Body
-from sqlalchemy import select, and_
-from sqlalchemy.ext.asyncio import AsyncSession
-
-from app.database import get_db
-from app.models import Photo
-
-logger = logging.getLogger(__name__)
-
-router = APIRouter()
-
-@router.get("")
-async def list_discarded(db: AsyncSession = Depends(get_db)):
-    """List discarded photos"""
-    result = await db.execute(
-        select(Photo).where(Photo.is_discarded == True)
-    )
-    photos = result.scalars().all()
-    return photos
-
-@router.post("/restore")
-async def restore_photos(photo_ids: list[str], db: AsyncSession = Depends(get_db)):
-    """Restore photos from the discard pile"""
-    result = await db.execute(
-        select(Photo).where(and_(Photo.id.in_(photo_ids), Photo.is_discarded == True))
-    )
-    photos = result.scalars().all()
-
-    for photo in photos:
-        photo.is_discarded = False
-        photo.discarded_at = None
-
-    await db.commit()
-    return {"status": "success", "restored": len(photos)}
-
-@router.delete("/empty")
-async def empty_discard(db: AsyncSession = Depends(get_db)):
-    """Permanently delete all discarded photos and unlink their files from
-    disk. Failures on individual files are logged but don't abort the batch.
-    """
-    result = await db.execute(
-        select(Photo).where(Photo.is_discarded == True)
-    )
-    photos = result.scalars().all()
-    return await _permanently_delete(db, photos)
-
-
-@router.delete("")
-async def delete_discarded(
-    photo_ids: list[str] = Body(..., embed=True),
-    db: AsyncSession = Depends(get_db),
-):
-    """Permanently delete a specific subset of discarded photos. The photos
-    must already be in the discard pile — non-discarded ids are skipped so
-    this can never bypass the soft-delete safety net.
-    """
-    if not photo_ids:
-        return {"status": "success", "deleted": 0, "file_errors": 0}
-    result = await db.execute(
-        select(Photo).where(
-            and_(Photo.id.in_(photo_ids), Photo.is_discarded == True)
-        )
-    )
-    photos = result.scalars().all()
-    return await _permanently_delete(db, photos)
-
-
-async def _permanently_delete(db: AsyncSession, photos: list[Photo]) -> dict:
-    """Shared helper: unlink files for the given photos and delete their
-    rows. Per-file errors are counted but don't abort the batch.
-    """
-    deleted = 0
-    file_errors = 0
-    for photo in photos:
-        try:
-            if photo.filepath and os.path.exists(photo.filepath):
-                os.unlink(photo.filepath)
-        except OSError as e:
-            file_errors += 1
-            logger.error(f"Failed to unlink {photo.filepath}: {e}")
-        await db.delete(photo)
-        deleted += 1
-
-    await db.commit()
-    return {
-        "status": "success",
-        "deleted": deleted,
-        "file_errors": file_errors,
-    }

backend/app/routers/folders.py

@@ -1,439 +0,0 @@
-"""
-Folders API router. Source roots themselves are config-driven (PHOTO_DIRS
-in .env → backend bootstrap on startup) — adding or removing one is a
-docker-compose change. Sub-folders inside a source root can be created,
-renamed, and deleted from the UI; those changes are mirrored to disk.
-"""
-import logging
-import os
-import shutil
-from typing import Literal, Optional
-
-from fastapi import APIRouter, Depends, HTTPException, Query
-from pydantic import BaseModel
-from sqlalchemy import select, func, update as sql_update, delete as sql_delete
-from sqlalchemy.ext.asyncio import AsyncSession
-
-from app.database import get_db
-from app.models import Folder, SourceRoot, Photo
-
-logger = logging.getLogger(__name__)
-
-router = APIRouter()
-
-
-class FolderRename(BaseModel):
-    name: str
-
-
-class FolderCreate(BaseModel):
-    name: str
-    parent_id: str  # Folder.id (NOT a SourceRoot id)
-
-
-def _validate_folder_name(name: str) -> str:
-    """Trim + sanity-check a folder name. Rejects names that contain a
-    path separator or that resolve to a parent traversal — those would
-    let the user escape the parent directory through this endpoint.
-    """
-    name = (name or '').strip()
-    if not name:
-        raise HTTPException(status_code=400, detail="Name cannot be empty")
-    if '/' in name or '\\' in name or name in ('.', '..'):
-        raise HTTPException(status_code=400, detail="Invalid folder name")
-    return name
-
-@router.get("")
-async def get_folders(db: AsyncSession = Depends(get_db)):
-    """Get all source folders"""
-    # Get source roots instead of regular folders
-    result = await db.execute(select(SourceRoot).where(SourceRoot.is_active == True))
-    source_roots = result.scalars().all()
-    
-    folders_list = []
-    for root in source_roots:
-        # Get photo count for this source root
-        folder_result = await db.execute(
-            select(Folder).where(Folder.source_root_id == root.id)
-        )
-        folders = folder_result.scalars().all()
-        photo_count = sum(f.photo_count for f in folders)
-        
-        folders_list.append({
-            "id": root.id,
-            "name": root.name or os.path.basename(root.path),
-            "path": root.path,
-            "photo_count": photo_count
-        })
-    
-    return {"folders": folders_list}
-
-@router.get("/tree")
-async def get_folder_tree(db: AsyncSession = Depends(get_db)):
-    """Recursive folder tree, one root per active SourceRoot. The tree
-    starts at the Folder row matching the SourceRoot.path (the scanner
-    creates one for every walked directory), with the SourceRoot's
-    display name overlaid so the top-level entry reads as "Library"
-    instead of "/photos".
-
-    Returns a list of root nodes; each node has:
-        { id, name, path, photo_count, children: [...] }
-
-    photo_count is **recursive** — every node reports the total non-
-    discarded photos in its own subtree, so the badge matches what the
-    user sees when they click the row (which also filters recursively).
-
-    The stored Folder.photo_count column is intentionally NOT trusted;
-    the scanner's bookkeeping for that field has historically been
-    wrong (it leaks the global total into whichever folder os.walk
-    visited last). We compute counts here from the photos table.
-
-    Sub-folders that physically belong to the same source root but
-    weren't created on disk (e.g. the / row the scanner sometimes
-    creates as a parent walk) are skipped via path-prefix filtering.
-    """
-    sr_result = await db.execute(
-        select(SourceRoot).where(SourceRoot.is_active == True)  # noqa: E712
-    )
-    source_roots = sr_result.scalars().all()
-
-    out = []
-    for sr in source_roots:
-        # Folders physically inside this source root, by path prefix.
-        prefix = os.path.normpath(sr.path).rstrip(os.sep)
-        f_result = await db.execute(
-            select(Folder).where(
-                Folder.source_root_id == sr.id,
-                # Either the folder IS the source root, or it sits beneath it.
-                (Folder.path == prefix) | (Folder.path.like(prefix + os.sep + '%'))
-            )
-        )
-        folders = f_result.scalars().all()
-        if not folders:
-            continue
-
-        # Direct (non-recursive) photo counts per folder, computed from
-        # the photos table. Excludes discarded.
-        folder_ids = [f.id for f in folders]
-        direct_counts: dict[str, int] = {}
-        if folder_ids:
-            count_result = await db.execute(
-                select(Photo.folder_id, func.count(Photo.id))
-                .where(
-                    Photo.is_discarded == False,  # noqa: E712
-                    Photo.folder_id.in_(folder_ids),
-                )
-                .group_by(Photo.folder_id)
-            )
-            direct_counts = {row[0]: int(row[1]) for row in count_result.all()}
-
-        # Build a path → node map so we can attach children regardless of
-        # parent_id consistency. We populate photo_count with the direct
-        # count first, then accumulate descendants in a post-order pass.
-        nodes = {
-            f.path: {
-                "id": f.id,
-                "name": f.name or os.path.basename(f.path),
-                "path": f.path,
-                "photo_count": direct_counts.get(f.id, 0),
-                "children": [],
-            }
-            for f in folders
-        }
-
-        root_node = None
-        for f in folders:
-            node = nodes[f.path]
-            if f.path == prefix:
-                root_node = node
-                # Override the display name with the source root's label.
-                node["name"] = sr.name or node["name"]
-                continue
-            parent_path = os.path.normpath(os.path.dirname(f.path))
-            parent = nodes.get(parent_path)
-            if parent is not None:
-                parent["children"].append(node)
-            # If parent isn't in the set (orphan from a partial scan), drop
-            # the node — it can't be rendered consistently.
-
-        if root_node is not None:
-            # Sort children alphabetically at every level.
-            def sort_recursive(n):
-                n["children"].sort(key=lambda c: c["name"].lower())
-                for c in n["children"]:
-                    sort_recursive(c)
-            sort_recursive(root_node)
-
-            # Post-order: each node's recursive count is its own direct
-            # count plus the sum of every descendant's recursive count.
-            def accumulate(n) -> int:
-                total = n["photo_count"]
-                for c in n["children"]:
-                    total += accumulate(c)
-                n["photo_count"] = total
-                return total
-            accumulate(root_node)
-
-            out.append(root_node)
-
-    return out
-
-
-@router.patch("/{folder_id}")
-async def rename_folder(
-    folder_id: str,
-    body: FolderRename,
-    db: AsyncSession = Depends(get_db),
-):
-    """Rename a folder. Two cases:
-
-      - SourceRoot id  → just change the display label. The on-disk path
-                         is owned by the docker mount and never moves.
-      - Folder id      → rename the directory on disk AND update every
-                         descendant Folder.path + Photo.filepath that
-                         lived under the old prefix. Refuses to rename
-                         the source-root folder itself (= the row that
-                         matches the SourceRoot.path) because that would
-                         require renaming the docker mount.
-    """
-    name = _validate_folder_name(body.name)
-
-    # Try SourceRoot first (display-only rename).
-    sr_result = await db.execute(
-        select(SourceRoot).where(SourceRoot.id == folder_id)
-    )
-    source_root = sr_result.scalar_one_or_none()
-    if source_root:
-        source_root.name = name
-        await db.commit()
-        return {
-            "id": source_root.id,
-            "name": source_root.name,
-            "path": source_root.path,
-        }
-
-    # Otherwise it's a Folder row.
-    folder_result = await db.execute(select(Folder).where(Folder.id == folder_id))
-    folder = folder_result.scalar_one_or_none()
-    if not folder:
-        raise HTTPException(status_code=404, detail="Folder not found")
-
-    # Refuse to rename the bare source root mount through here.
-    sr_check = await db.execute(
-        select(SourceRoot).where(SourceRoot.id == folder.source_root_id)
-    )
-    sr = sr_check.scalar_one_or_none()
-    if sr and os.path.normpath(folder.path) == os.path.normpath(sr.path):
-        raise HTTPException(
-            status_code=400,
-            detail="Cannot rename the source root mount; rename the docker mount instead.",
-        )
-
-    old_path = os.path.normpath(folder.path).rstrip(os.sep)
-    parent_dir = os.path.dirname(old_path)
-    new_path = os.path.join(parent_dir, name)
-
-    if os.path.exists(new_path):
-        raise HTTPException(
-            status_code=400,
-            detail=f"A folder named '{name}' already exists here",
-        )
-
-    try:
-        shutil.move(old_path, new_path)
-    except OSError as e:
-        raise HTTPException(status_code=500, detail=f"Rename failed: {e}")
-
-    # Update folder paths: this row + every descendant. SQLite REPLACE
-    # rewrites the prefix; we use the trailing separator on the LIKE
-    # pattern so a folder named "foo" doesn't accidentally match "foobar".
-    await db.execute(
-        sql_update(Folder)
-        .where(Folder.id == folder.id)
-        .values(path=new_path, name=name)
-    )
-    descendant_prefix = old_path + os.sep
-    descendants = await db.execute(
-        select(Folder).where(Folder.path.like(descendant_prefix + '%'))
-    )
-    for d in descendants.scalars().all():
-        d.path = new_path + d.path[len(old_path):]
-
-    # Update every photo whose filepath lives under the old prefix.
-    photos_result = await db.execute(
-        select(Photo).where(Photo.filepath.like(descendant_prefix + '%'))
-    )
-    for p in photos_result.scalars().all():
-        p.filepath = new_path + p.filepath[len(old_path):]
-    # Photos directly inside this folder (not in a subdir) won't match
-    # the descendant_prefix LIKE if their old path was old_path + '/file'
-    # — actually they DO match, since 'oldpath/file' starts with
-    # 'oldpath/'. So the loop above already covers them.
-
-    await db.commit()
-    return {
-        "id": folder.id,
-        "name": folder.name,
-        "path": folder.path,
-    }
-
-
-@router.post("", status_code=201)
-async def create_folder(body: FolderCreate, db: AsyncSession = Depends(get_db)):
-    """Create a new sub-folder under an existing Folder. Mirrors the
-    create to disk so the next scan sees it. Body: { name, parent_id }.
-    parent_id MUST be an existing Folder row id (any descendant of a
-    source root); creating a brand-new top-level mount is a docker
-    operation, not a UI one.
-    """
-    name = _validate_folder_name(body.name)
-
-    parent_result = await db.execute(
-        select(Folder).where(Folder.id == body.parent_id)
-    )
-    parent = parent_result.scalar_one_or_none()
-    if not parent:
-        raise HTTPException(status_code=404, detail="Parent folder not found")
-
-    new_path = os.path.join(parent.path, name)
-    if os.path.exists(new_path):
-        raise HTTPException(
-            status_code=400,
-            detail=f"A folder named '{name}' already exists here",
-        )
-
-    try:
-        os.makedirs(new_path, exist_ok=False)
-    except OSError as e:
-        raise HTTPException(status_code=500, detail=f"Create failed: {e}")
-
-    new_folder = Folder(
-        name=name,
-        path=new_path,
-        source_root_id=parent.source_root_id,
-        photo_count=0,
-    )
-    db.add(new_folder)
-    await db.commit()
-    await db.refresh(new_folder)
-    return {
-        "id": new_folder.id,
-        "name": new_folder.name,
-        "path": new_folder.path,
-        "parent_id": parent.id,
-    }
-
-
-@router.delete("/{folder_id}")
-async def delete_folder(
-    folder_id: str,
-    mode: Literal['discard', 'permanent'] = Query('discard'),
-    db: AsyncSession = Depends(get_db),
-):
-    """Delete a folder. Behavior depends on mode:
-
-      - mode=discard (default): mark every photo whose filepath lives
-        under this folder as is_discarded=true. The folder row, its
-        descendant rows, and the on-disk directory are LEFT INTACT —
-        the user can still recover photos from the discard pile, and
-        a re-scan won't double-import them.
-
-      - mode=permanent: unlink every photo file under this folder,
-        remove the photo + folder rows from the DB, and rmtree the
-        on-disk directory. Irreversible.
-
-    Refuses to delete the bare source-root mount in either mode (deleting
-    the docker mount through the UI would be a footgun).
-    """
-    folder_result = await db.execute(select(Folder).where(Folder.id == folder_id))
-    folder = folder_result.scalar_one_or_none()
-    if not folder:
-        raise HTTPException(status_code=404, detail="Folder not found")
-
-    sr_check = await db.execute(
-        select(SourceRoot).where(SourceRoot.id == folder.source_root_id)
-    )
-    sr = sr_check.scalar_one_or_none()
-    if sr and os.path.normpath(folder.path) == os.path.normpath(sr.path):
-        raise HTTPException(
-            status_code=400,
-            detail="Cannot delete the source root mount through the UI",
-        )
-
-    folder_path = os.path.normpath(folder.path).rstrip(os.sep)
-    descendant_prefix = folder_path + os.sep
-
-    # Collect every photo under this folder OR any descendant. We match
-    # by filepath prefix instead of folder_id because that catches photos
-    # in nested subfolders without a recursive folder walk.
-    photos_result = await db.execute(
-        select(Photo).where(
-            (Photo.filepath == folder_path)
-            | (Photo.filepath.like(descendant_prefix + '%'))
-        )
-    )
-    photos = photos_result.scalars().all()
-
-    if mode == 'discard':
-        from datetime import datetime
-        now = datetime.utcnow()
-        for p in photos:
-            p.is_discarded = True
-            p.discarded_at = now
-        await db.commit()
-        return {
-            "status": "success",
-            "mode": "discard",
-            "discarded": len(photos),
-        }
-
-    # mode == 'permanent'
-    file_errors = 0
-    for p in photos:
-        try:
-            if p.filepath and os.path.exists(p.filepath):
-                os.unlink(p.filepath)
-        except OSError as e:
-            file_errors += 1
-            logger.error(f"Failed to unlink {p.filepath}: {e}")
-        await db.delete(p)
-
-    # Delete this folder + every descendant Folder row.
-    await db.execute(
-        sql_delete(Folder).where(
-            (Folder.id == folder.id)
-            | (Folder.path.like(descendant_prefix + '%'))
-        )
-    )
-
-    try:
-        if os.path.isdir(folder_path):
-            shutil.rmtree(folder_path)
-    except OSError as e:
-        logger.error(f"Failed to rmtree {folder_path}: {e}")
-        # Don't raise — DB rows are already gone, leaving an orphan
-        # directory is the lesser evil.
-
-    await db.commit()
-    return {
-        "status": "success",
-        "mode": "permanent",
-        "deleted_photos": len(photos),
-        "file_errors": file_errors,
-    }
-
-
-@router.post("/{folder_id}/scan")
-async def scan_folder(folder_id: str, db: AsyncSession = Depends(get_db)):
-    """Trigger manual re-scan of source root folder"""
-    from app.tasks.celery import celery_app
-    
-    result = await db.execute(select(SourceRoot).where(SourceRoot.id == folder_id))
-    source_root = result.scalar_one_or_none()
-    
-    if not source_root:
-        raise HTTPException(status_code=404, detail="Source folder not found")
-    
-    # Queue scan task using the task name defined in the decorator
-    task = celery_app.send_task('scan_folder', args=[source_root.path, source_root.id])
-    return {"status": "success", "message": f"Scan queued for {source_root.path}", "task_id": task.id}

backend/app/routers/heaps.py

@@ -1,423 +0,0 @@
-"""
-Heaps API router
-"""
-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, Photo, Folder
-from app.models.folders import SourceRoot
-from app.models.heaps import heap_photos
-
-logger = logging.getLogger(__name__)
-
-router = APIRouter()
-
-
-# ── Schemas ───────────────────────────────────────────────────────────────
-
-class HeapCreate(BaseModel):
-    name: str
-
-
-class HeapUpdate(BaseModel):
-    name: Optional[str] = None
-    is_active: Optional[bool] = None
-
-
-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
-    # Optional subfolder name to create inside the target. If provided, the
-    # actual destination is target_dir/subfolder_name (created if missing).
-    # Path separators and dot-segments are rejected.
-    subfolder_name: Optional[str] = None
-
-
-# ── Endpoints ─────────────────────────────────────────────────────────────
-
-@router.get("")
-async def list_heaps(db: AsyncSession = Depends(get_db)):
-    """List all heaps with photo counts."""
-    # LEFT JOIN heap_photos and group so we can return counts in one query.
-    count_subq = (
-        select(
-            heap_photos.c.heap_id,
-            func.count(heap_photos.c.photo_id).label("photo_count"),
-        )
-        .group_by(heap_photos.c.heap_id)
-        .subquery()
-    )
-
-    stmt = (
-        select(Heap, count_subq.c.photo_count)
-        .outerjoin(count_subq, Heap.id == count_subq.c.heap_id)
-        .order_by(Heap.created_at.asc())
-    )
-    result = await db.execute(stmt)
-    rows = result.all()
-
-    return [
-        {
-            "id": h.id,
-            "name": h.name,
-            "is_active": bool(h.is_active),
-            "created_at": h.created_at,
-            "updated_at": h.updated_at,
-            "photo_count": int(count or 0),
-        }
-        for h, count in rows
-    ]
-
-
-@router.post("", status_code=201)
-async def create_heap(body: HeapCreate, db: AsyncSession = Depends(get_db)):
-    """Create a new heap."""
-    name = (body.name or "").strip()
-    if not name:
-        raise HTTPException(status_code=400, detail="Heap name is required")
-    heap = Heap(name=name)
-    db.add(heap)
-    await db.commit()
-    await db.refresh(heap)
-    return {
-        "id": heap.id,
-        "name": heap.name,
-        "is_active": bool(heap.is_active),
-        "created_at": heap.created_at,
-        "updated_at": heap.updated_at,
-        "photo_count": 0,
-    }
-
-
-@router.patch("/{heap_id}")
-async def update_heap(
-    heap_id: str, body: HeapUpdate, db: AsyncSession = Depends(get_db)
-):
-    """Rename a heap and/or toggle active state. Setting is_active=true on
-    one heap deactivates all others (single-active invariant)."""
-    result = await db.execute(select(Heap).where(Heap.id == heap_id))
-    heap = result.scalar_one_or_none()
-    if not heap:
-        raise HTTPException(status_code=404, detail="Heap not found")
-
-    if body.name is not None:
-        name = body.name.strip()
-        if not name:
-            raise HTTPException(status_code=400, detail="Heap name is required")
-        heap.name = name
-
-    if body.is_active is not None:
-        if body.is_active:
-            # Clear active flag on all other heaps in one statement
-            await db.execute(update(Heap).values(is_active=False))
-            heap.is_active = True
-        else:
-            heap.is_active = False
-
-    await db.commit()
-    await db.refresh(heap)
-    return {
-        "id": heap.id,
-        "name": heap.name,
-        "is_active": bool(heap.is_active),
-        "created_at": heap.created_at,
-        "updated_at": heap.updated_at,
-    }
-
-
-@router.post("/{heap_id}/duplicate", status_code=201)
-async def duplicate_heap(heap_id: str, db: AsyncSession = Depends(get_db)):
-    """Create a new heap with the same membership as an existing one. The
-    new heap is named "{original} (copy)" and is never the active target —
-    duplicating shouldn't quietly steal the user's T-key destination.
-    """
-    result = await db.execute(select(Heap).where(Heap.id == heap_id))
-    source = result.scalar_one_or_none()
-    if not source:
-        raise HTTPException(status_code=404, detail="Heap not found")
-
-    new_heap = Heap(name=f"{source.name} (copy)", is_active=False)
-    db.add(new_heap)
-    await db.flush()  # populate new_heap.id without committing yet
-
-    # Bulk-copy the membership rows. SELECT photo_id FROM heap_photos WHERE
-    # heap_id = :src — INSERT each into the new heap. Done as a single
-    # INSERT...SELECT to avoid round-tripping ids through Python.
-    member_rows = await db.execute(
-        select(heap_photos.c.photo_id).where(heap_photos.c.heap_id == heap_id)
-    )
-    photo_ids = [row[0] for row in member_rows.all()]
-    if photo_ids:
-        await db.execute(
-            insert(heap_photos),
-            [{"heap_id": new_heap.id, "photo_id": pid} for pid in photo_ids],
-        )
-
-    await db.commit()
-    await db.refresh(new_heap)
-    return {
-        "id": new_heap.id,
-        "name": new_heap.name,
-        "is_active": False,
-        "photo_count": len(photo_ids),
-        "created_at": new_heap.created_at,
-        "updated_at": new_heap.updated_at,
-    }
-
-
-@router.delete("/{heap_id}", status_code=204)
-async def delete_heap(heap_id: str, db: AsyncSession = Depends(get_db)):
-    """Delete a heap. Photos themselves are unaffected — only the membership
-    rows in heap_photos cascade-delete."""
-    result = await db.execute(select(Heap).where(Heap.id == heap_id))
-    heap = result.scalar_one_or_none()
-    if not heap:
-        raise HTTPException(status_code=404, detail="Heap not found")
-    await db.delete(heap)
-    await db.commit()
-    return None
-
-
-@router.get("/{heap_id}/photo_ids")
-async def get_heap_photo_ids(heap_id: str, db: AsyncSession = Depends(get_db)):
-    """Return just the photo ids belonging to a heap. Used by the frontend
-    to maintain a fast client-side membership lookup for the active heap
-    (for the basket affordance on thumbnails) without fetching full photo
-    records."""
-    result = await db.execute(
-        select(heap_photos.c.photo_id).where(heap_photos.c.heap_id == heap_id)
-    )
-    return [row[0] for row in result.all()]
-
-
-@router.post("/{heap_id}/photos")
-async def add_photos_to_heap(
-    heap_id: str, body: HeapPhotosBody, db: AsyncSession = Depends(get_db)
-):
-    """Add photos to a heap. Idempotent: re-adding existing members is a
-    no-op (handled by an INSERT OR IGNORE-style filter on duplicates)."""
-    result = await db.execute(select(Heap).where(Heap.id == heap_id))
-    heap = result.scalar_one_or_none()
-    if not heap:
-        raise HTTPException(status_code=404, detail="Heap not found")
-
-    if not body.photo_ids:
-        return {"status": "success", "added": 0}
-
-    # Find which ids are already members so we don't violate the PK.
-    existing = await db.execute(
-        select(heap_photos.c.photo_id).where(
-            heap_photos.c.heap_id == heap_id,
-            heap_photos.c.photo_id.in_(body.photo_ids),
-        )
-    )
-    existing_ids = {row[0] for row in existing.all()}
-    new_ids = [pid for pid in body.photo_ids if pid not in existing_ids]
-
-    if new_ids:
-        await db.execute(
-            insert(heap_photos),
-            [{"heap_id": heap_id, "photo_id": pid} for pid in new_ids],
-        )
-        await db.commit()
-
-    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:
-        parent_dir = source_root.path
-        parent_source_root_id = source_root.id
-    else:
-        folder_check = await db.execute(
-            select(Folder).where(Folder.id == body.target_id)
-        )
-        parent_folder = folder_check.scalar_one_or_none()
-        if parent_folder is None:
-            raise HTTPException(status_code=404, detail="Target folder not found")
-        parent_dir = parent_folder.path
-        parent_source_root_id = parent_folder.source_root_id
-
-    if not os.path.isdir(parent_dir):
-        raise HTTPException(
-            status_code=400,
-            detail=f"Target parent does not exist: {parent_dir}",
-        )
-
-    # Resolve target_dir, creating an optional subfolder if requested.
-    if body.subfolder_name is not None:
-        sub = body.subfolder_name.strip()
-        if not sub:
-            raise HTTPException(status_code=400, detail="Subfolder name cannot be empty")
-        if '/' in sub or '\\' in sub or sub in ('.', '..'):
-            raise HTTPException(status_code=400, detail="Invalid subfolder name")
-        target_dir = os.path.join(parent_dir, sub)
-        if not os.path.exists(target_dir):
-            try:
-                os.makedirs(target_dir)
-            except OSError as e:
-                raise HTTPException(
-                    status_code=500,
-                    detail=f"Failed to create subfolder: {e}",
-                )
-        elif not os.path.isdir(target_dir):
-            raise HTTPException(
-                status_code=400,
-                detail=f"{target_dir} exists but is not a directory",
-            )
-    else:
-        target_dir = parent_dir
-
-    # Ensure a Folder row for the target, reusing the scanner helper so
-    # path normalization + dedupe stay consistent.
-    from app.tasks.scan import get_or_create_folder
-    target_folder = await get_or_create_folder(db, target_dir, parent_source_root_id)
-
-    # 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)
-):
-    """Remove photos from a heap. Removing a non-member is a no-op."""
-    result = await db.execute(select(Heap).where(Heap.id == heap_id))
-    heap = result.scalar_one_or_none()
-    if not heap:
-        raise HTTPException(status_code=404, detail="Heap not found")
-
-    if not body.photo_ids:
-        return {"status": "success", "removed": 0}
-
-    res = await db.execute(
-        delete(heap_photos).where(
-            heap_photos.c.heap_id == heap_id,
-            heap_photos.c.photo_id.in_(body.photo_ids),
-        )
-    )
-    await db.commit()
-    return {"status": "success", "removed": res.rowcount or 0}

backend/app/routers/library.py

@@ -1,574 +0,0 @@
-"""
-Library API router for stats, scanning, and maintenance.
-
-The /maintenance/* endpoints are surfaced through the frontend Settings
-panel. They're intentionally idempotent and operate by re-queueing the
-existing Celery tasks rather than doing any heavy lifting in the
-request thread.
-"""
-import logging
-import os
-import shutil
-from typing import List, Optional
-
-from fastapi import APIRouter, Depends
-from pydantic import BaseModel, Field
-from sqlalchemy import select, func, update
-from sqlalchemy.ext.asyncio import AsyncSession
-
-from app.database import get_db
-from app.models import Photo
-
-logger = logging.getLogger(__name__)
-
-router = APIRouter()
-
-# Media types we accept in the regenerate-thumbnails request body. Mirrors
-# the values produced by `app.tasks.scan.get_media_type`.
-_VALID_MEDIA_TYPES = {'photo', 'raw', 'heic', 'video'}
-
-@router.get("/stats")
-async def get_library_stats(db: AsyncSession = Depends(get_db)):
-    """Get library statistics + per-section counts. Each section count
-    matches the filter the sidebar applies when you click it, so the
-    sidebar badges and the timeline below them stay in sync.
-
-      - all_photos:   non-discarded photos + videos (matches the All
-                      Photos section's default filter)
-      - rated:        non-discarded with rating >= 1
-      - duplicates:   non-discarded with is_duplicate = true
-      - discarded:    is_discarded = true
-      - total_size:   raw bytes across every row, including discarded
-    """
-    not_discarded = Photo.is_discarded.is_(False)
-
-    all_photos_count = (
-        await db.execute(select(func.count(Photo.id)).where(not_discarded))
-    ).scalar() or 0
-
-    rated_count = (
-        await db.execute(
-            select(func.count(Photo.id)).where(not_discarded, Photo.rating >= 1)
-        )
-    ).scalar() or 0
-
-    duplicates_count = (
-        await db.execute(
-            select(func.count(Photo.id)).where(
-                not_discarded, Photo.is_duplicate.is_(True)
-            )
-        )
-    ).scalar() or 0
-
-    discarded_count = (
-        await db.execute(
-            select(func.count(Photo.id)).where(Photo.is_discarded.is_(True))
-        )
-    ).scalar() or 0
-
-    # Legacy split (kept for the existing /stats consumers).
-    photo_count = (
-        await db.execute(
-            select(func.count(Photo.id)).where(
-                Photo.media_type.in_(['photo', 'heic', 'raw'])
-            )
-        )
-    ).scalar() or 0
-    video_count = (
-        await db.execute(
-            select(func.count(Photo.id)).where(Photo.media_type == 'video')
-        )
-    ).scalar() or 0
-
-    size = (await db.execute(select(func.sum(Photo.file_size)))).scalar() or 0
-
-    return {
-        "all_photos": all_photos_count,
-        "rated": rated_count,
-        "duplicates": duplicates_count,
-        "discarded": discarded_count,
-        "total_photos": photo_count,
-        "total_videos": video_count,
-        "total_size": size,
-        "total_size_gb": round(size / (1024**3), 2) if size else 0,
-    }
-
-@router.post("/scan")
-async def trigger_scan():
-    """Trigger full library re-scan"""
-    from app.tasks.scan import scan_all_source_roots
-    
-    scan_all_source_roots.delay()
-    
-    return {"status": "success", "message": "Library scan started"}
-
-@router.get("/scan/status")
-async def get_scan_status(db: AsyncSession = Depends(get_db)):
-    """Get current scan status"""
-    import redis
-    from app.config import settings
-    
-    # Connect to Redis to get scan status
-    r = redis.Redis.from_url(settings.redis_url)
-    
-    # Get scan status from Redis (set by worker tasks)
-    is_scanning = r.get('scan:active') == b'true'
-    current_folder = r.get('scan:current_folder')
-    processed_files = int(r.get('scan:processed_files') or 0)
-    total_files = int(r.get('scan:total_files') or 0)
-    errors = r.lrange('scan:errors', 0, -1)
-    
-    return {
-        "is_scanning": is_scanning,
-        "current_folder": current_folder.decode() if current_folder else None,
-        "processed_files": processed_files,
-        "total_files": total_files,
-        "errors": [e.decode() for e in errors] if errors else []
-    }
-
-
-# ---------------------------------------------------------------------------
-# Maintenance endpoints — surfaced via the Settings panel.
-# ---------------------------------------------------------------------------
-
-class RegenerateThumbnailsRequest(BaseModel):
-    """Optional filters narrowing which photos get re-queued. With both
-    fields omitted the request resets every photo in the library."""
-    media_types: Optional[List[str]] = Field(
-        default=None,
-        description="Restrict to these media_type values (photo/raw/heic/video).",
-    )
-    only_failed: bool = Field(
-        default=False,
-        description="If true, only re-queue photos whose processing_status is 'failed'.",
-    )
-    only_pending: bool = Field(
-        default=False,
-        description="If true, only (re-)queue photos whose processing_status is 'pending'. "
-                    "Useful for kicking rows that were created by a scan but never had "
-                    "their thumbnail task picked up.",
-    )
-
-
-@router.get("/maintenance/thumbnail-stats")
-async def get_thumbnail_stats(db: AsyncSession = Depends(get_db)):
-    """Counts of photos by processing_status, plus a media-type breakdown
-    so the Settings panel can show the user what's outstanding."""
-    status_rows = (
-        await db.execute(
-            select(Photo.processing_status, func.count(Photo.id)).group_by(
-                Photo.processing_status
-            )
-        )
-    ).all()
-
-    media_rows = (
-        await db.execute(
-            select(Photo.media_type, func.count(Photo.id)).group_by(Photo.media_type)
-        )
-    ).all()
-
-    by_status = {status or 'unknown': count for status, count in status_rows}
-    by_media_type = {media or 'unknown': count for media, count in media_rows}
-    total = sum(by_status.values())
-
-    return {
-        "total": total,
-        "pending": by_status.get('pending', 0),
-        "processing": by_status.get('processing', 0),
-        "completed": by_status.get('completed', 0),
-        "failed": by_status.get('failed', 0),
-        "by_media_type": by_media_type,
-    }
-
-
-@router.post("/maintenance/regenerate-thumbnails")
-async def regenerate_thumbnails(
-    body: RegenerateThumbnailsRequest,
-    db: AsyncSession = Depends(get_db),
-):
-    """Reset matching photos' on-disk thumbnail directories and re-queue
-    Celery thumbnail generation. Used by the Settings panel for the
-    'regenerate video thumbnails' / 'regenerate failed' buttons.
-
-    Files on disk are removed under /data/thumbs/<photo_id>/ so the next
-    request to /photos/{id}/thumb/{size} actually re-generates instead of
-    serving the stale placeholder.
-    """
-    from app.tasks.thumbs import generate_thumbnails
-
-    # Validate media_types early so a typo can't silently match nothing.
-    media_types = body.media_types
-    if media_types is not None:
-        invalid = [m for m in media_types if m not in _VALID_MEDIA_TYPES]
-        if invalid:
-            return {
-                "status": "error",
-                "message": f"Invalid media_types: {invalid}. "
-                           f"Allowed: {sorted(_VALID_MEDIA_TYPES)}",
-            }
-
-    query = select(Photo)
-    if media_types:
-        query = query.where(Photo.media_type.in_(media_types))
-    if body.only_failed:
-        query = query.where(Photo.processing_status == 'failed')
-    if body.only_pending:
-        query = query.where(Photo.processing_status == 'pending')
-
-    photos = (await db.execute(query)).scalars().all()
-
-    cleared_dirs = 0
-    file_errors = 0
-    for photo in photos:
-        thumb_dir = f"/data/thumbs/{photo.id}"
-        if os.path.isdir(thumb_dir):
-            try:
-                shutil.rmtree(thumb_dir)
-                cleared_dirs += 1
-            except OSError as e:
-                file_errors += 1
-                logger.warning(f"Could not clear thumb dir {thumb_dir}: {e}")
-        photo.processing_status = 'pending'
-        photo.processing_error = None
-        photo.thumb_small = None
-        photo.thumb_medium = None
-        photo.thumb_large = None
-
-    await db.commit()
-
-    # Queue celery tasks AFTER the commit so the worker sees the reset
-    # state when it picks the job up.
-    queued = 0
-    for photo in photos:
-        try:
-            generate_thumbnails.delay(photo.id)
-            queued += 1
-        except Exception as e:
-            logger.warning(f"Could not queue thumbnail job for {photo.id}: {e}")
-
-    return {
-        "status": "success",
-        "matched": len(photos),
-        "queued": queued,
-        "cleared_dirs": cleared_dirs,
-        "file_errors": file_errors,
-        "filters": {
-            "media_types": media_types,
-            "only_failed": body.only_failed,
-        },
-    }
-
-
-@router.get("/maintenance/worker-status")
-async def get_worker_status(db: AsyncSession = Depends(get_db)):
-    """Diagnostics for the Celery worker fleet + recent task failures.
-
-    Surfaced in the Settings panel so the user can spot a stuck queue or
-    a worker that's gone away without tailing container logs. Returns:
-
-      - workers: list of {name, status, active, concurrency, queues}
-        derived from celery_app.control.inspect(). `status` is 'online'
-        when ping succeeds, 'unreachable' otherwise. Empty list means no
-        workers are responding at all (broker down, container crashed,
-        wrong queue routing, etc.).
-      - queues: per-queue depth read from Redis (LLEN of each queue key
-        used by celery.kombu). Mirrors what tasks are waiting to be
-        picked up.
-      - failures: aggregate count of photos with processing_status='failed'
-        plus the most recent N error messages so the user can see *why*
-        things failed without opening the DB.
-      - broker_ok: bool — could we even reach Redis?
-    """
-    from app.tasks.celery import celery_app
-    from app.config import settings
-    import redis as _redis
-
-    # ----- Celery inspect (workers + active tasks) -------------------------
-    # Each inspect.* call is a separate broadcast-and-wait with its own
-    # timeout, so running them serially multiplies the wait. Fan them out
-    # to threads and gather, collapsing 6 × timeout into ~1 × timeout.
-    # Timeout dropped to 0.5s — a responsive worker answers within a few
-    # ms; anything past that is effectively "not responding" for the
-    # purposes of a settings dashboard.
-    import asyncio
-    workers: list[dict] = []
-    inspect_error: Optional[str] = None
-    try:
-        inspect = celery_app.control.inspect(timeout=0.5)
-        ping, active, reserved, scheduled, stats, active_queues = await asyncio.gather(
-            asyncio.to_thread(inspect.ping),
-            asyncio.to_thread(inspect.active),
-            asyncio.to_thread(inspect.reserved),
-            asyncio.to_thread(inspect.scheduled),
-            asyncio.to_thread(inspect.stats),
-            asyncio.to_thread(inspect.active_queues),
-        )
-        ping = ping or {}
-        active = active or {}
-        reserved = reserved or {}
-        scheduled = scheduled or {}
-        stats = stats or {}
-        active_queues = active_queues or {}
-
-        worker_names = set(ping) | set(active) | set(stats)
-        for name in sorted(worker_names):
-            wstats = stats.get(name) or {}
-            pool = wstats.get('pool') or {}
-            workers.append({
-                "name": name,
-                "status": "online" if name in ping else "unreachable",
-                "active": len(active.get(name, []) or []),
-                "reserved": len(reserved.get(name, []) or []),
-                "scheduled": len(scheduled.get(name, []) or []),
-                "concurrency": pool.get('max-concurrency'),
-                "processed": (wstats.get('total') or {}),
-                "queues": [q.get('name') for q in (active_queues.get(name) or [])],
-                "active_tasks": [
-                    {
-                        "id": t.get('id'),
-                        "name": t.get('name'),
-                        "args": t.get('args'),
-                        "time_start": t.get('time_start'),
-                    }
-                    for t in (active.get(name) or [])[:10]
-                ],
-            })
-    except Exception as e:
-        inspect_error = str(e)
-        logger.warning(f"Celery inspect failed: {e}")
-
-    # ----- Broker / queue depth --------------------------------------------
-    broker_ok = False
-    queue_depths: dict[str, int] = {}
-    broker_error: Optional[str] = None
-    try:
-        r = _redis.Redis.from_url(settings.redis_url, socket_timeout=1.0)
-        r.ping()
-        broker_ok = True
-        for q in ('default', 'high', 'low'):
-            try:
-                queue_depths[q] = int(r.llen(q) or 0)
-            except Exception:
-                queue_depths[q] = 0
-    except Exception as e:
-        broker_error = str(e)
-        logger.warning(f"Redis broker unreachable: {e}")
-
-    # ----- Recent task failures from the photos table ----------------------
-    failed_total = (
-        await db.execute(
-            select(func.count(Photo.id)).where(Photo.processing_status == 'failed')
-        )
-    ).scalar() or 0
-
-    recent_failed_rows = (
-        await db.execute(
-            select(
-                Photo.id,
-                Photo.filename,
-                Photo.media_type,
-                Photo.processing_error,
-                Photo.updated_at,
-            )
-            .where(Photo.processing_status == 'failed')
-            .order_by(Photo.updated_at.desc().nullslast())
-            .limit(20)
-        )
-    ).all()
-
-    recent_failures = [
-        {
-            "photo_id": row[0],
-            "filename": row[1],
-            "media_type": row[2],
-            "error": (row[3] or '')[:500],
-            "updated_at": row[4].isoformat() if row[4] else None,
-        }
-        for row in recent_failed_rows
-    ]
-
-    # ----- Most recent scan errors (Redis list) ----------------------------
-    scan_errors: list[str] = []
-    try:
-        if broker_ok:
-            r = _redis.Redis.from_url(settings.redis_url, socket_timeout=1.0)
-            raw = r.lrange('scan:errors', 0, 19) or []
-            scan_errors = [e.decode(errors='replace') for e in raw]
-    except Exception as e:
-        logger.debug(f"Could not read scan:errors: {e}")
-
-    return {
-        "broker_ok": broker_ok,
-        "broker_error": broker_error,
-        "inspect_error": inspect_error,
-        "workers": workers,
-        "worker_count": len(workers),
-        "queues": queue_depths,
-        "failures": {
-            "total": failed_total,
-            "recent": recent_failures,
-        },
-        "scan_errors": scan_errors,
-    }
-
-
-@router.get("/maintenance/missing-stats")
-async def get_missing_stats():
-    """Count photos whose files no longer exist on disk under a mounted
-    source root. Surfaced in Settings so the user can see a number before
-    pulling the trigger on prune-missing. Cheap enough to call freely."""
-    from app.services.cleanup import prune_missing_photos
-    return await prune_missing_photos(dry_run=True)
-
-
-@router.post("/maintenance/prune-missing")
-async def run_prune_missing():
-    """Actually delete the orphaned photo rows reported by /missing-stats.
-    Common cause: PHOTO_DIRS in .env was repointed at a different library
-    leaving every old row dangling. Skips any photo whose source root
-    isn't currently mounted (almost always means an unmounted drive)."""
-    from app.services.cleanup import prune_missing_photos
-    try:
-        return {"status": "success", **(await prune_missing_photos(dry_run=False))}
-    except Exception as e:
-        logger.error(f"Prune missing failed: {e}")
-        return {"status": "error", "message": str(e)}
-
-
-@router.post("/maintenance/cleanup")
-async def run_data_integrity_cleanup():
-    """Re-run the source-roots / folders / photos data-integrity cleanup
-    that normally only runs on backend startup. Idempotent."""
-    from app.services.cleanup import cleanup_data_integrity
-
-    try:
-        await cleanup_data_integrity()
-        return {"status": "success"}
-    except Exception as e:
-        logger.error(f"Manual cleanup failed: {e}")
-        return {"status": "error", "message": str(e)}
-
-
-# ─────────────────────────────────────────────────────────────────────────
-# Duplicate detection
-# ─────────────────────────────────────────────────────────────────────────
-
-@router.get("/duplicates/groups")
-async def get_duplicate_groups(db: AsyncSession = Depends(get_db)):
-    """Return every duplicate group with its members.
-
-    Drives the frontend grouped grid view in the Duplicates section. One
-    SQL query, bucketed in Python — no N+1, no per-member fetch. Groups
-    are sorted by member_count DESC then earliest taken_at DESC so the
-    biggest / most recent clusters bubble to the top.
-
-    Each group also carries a `reason` field:
-      * "exact"   — every member shares the same SHA-256 (true byte
-                    duplicates that the perceptual hash trivially caught)
-      * "similar" — members differ at the byte level but match perceptually
-    """
-    rows = (
-        await db.execute(
-            select(
-                Photo.id,
-                Photo.filename,
-                Photo.taken_at,
-                Photo.file_size,
-                Photo.width,
-                Photo.height,
-                Photo.thumb_small,
-                Photo.file_hash,
-                Photo.folder_id,
-                Photo.media_type,
-                Photo.duplicate_group_id,
-            )
-            .where(Photo.duplicate_group_id.is_not(None))
-            .where(Photo.is_discarded.is_(False))
-            .order_by(Photo.duplicate_group_id)
-        )
-    ).all()
-
-    # Bucket members by group_id.
-    groups: dict[str, list[dict]] = {}
-    for row in rows:
-        member = {
-            "id": row[0],
-            "filename": row[1],
-            "taken_at": row[2].isoformat() if row[2] else None,
-            "file_size": row[3],
-            "width": row[4],
-            "height": row[5],
-            "thumb_small": row[6],
-            "file_hash": row[7],
-            "folder_id": row[8],
-            "media_type": row[9],
-        }
-        groups.setdefault(row[10], []).append(member)
-
-    def earliest(g: list[dict]) -> str:
-        # Used as a secondary sort key. Photos with no taken_at sort last
-        # by returning a far-future sentinel.
-        taken = [m["taken_at"] for m in g if m["taken_at"]]
-        return min(taken) if taken else "9999"
-
-    out = []
-    for group_id, members in groups.items():
-        if len(members) < 2:
-            # Defensive: a regroup race could leave a singleton briefly.
-            # Skip it so the UI never shows a "group of 1".
-            continue
-        # exact iff every member shares the same non-null file_hash
-        # (true byte-identical copies that pHash also caught). Anything
-        # else — different hashes, missing hashes — counts as "similar".
-        all_hashes = [m["file_hash"] for m in members]
-        reason = (
-            "exact"
-            if len(set(all_hashes)) == 1 and all_hashes[0] is not None
-            else "similar"
-        )
-        out.append({
-            "group_id": group_id,
-            "member_count": len(members),
-            "reason": reason,
-            "members": members,
-        })
-
-    out.sort(key=lambda g: (-g["member_count"], earliest(g["members"])))
-    return {
-        "groups": out,
-        "total_groups": len(out),
-        "total_members": sum(g["member_count"] for g in out),
-    }
-
-
-@router.post("/maintenance/regroup-duplicates")
-async def trigger_regroup_duplicates():
-    """Recompute duplicate groups from current perceptual hashes.
-
-    Fires the celery `regroup_duplicates` task which walks every photo's
-    phash, clusters by Hamming distance, and rewrites duplicate_group_id /
-    is_duplicate columns. Idempotent."""
-    from app.tasks.thumbs import regroup_duplicates_task
-    try:
-        regroup_duplicates_task.delay()
-        return {"status": "queued"}
-    except Exception as e:
-        logger.error(f"Regroup queue failed: {e}")
-        return {"status": "error", "message": str(e)}
-
-
-@router.post("/maintenance/backfill-phashes")
-async def trigger_backfill_phashes():
-    """Compute perceptual hashes for every photo currently missing one.
-
-    One-shot recovery path for libraries that existed before the phash
-    column was added — the thumbs worker computes phash for everything
-    new, but old rows need a backfill pass."""
-    from app.tasks.thumbs import backfill_phashes
-    try:
-        backfill_phashes.delay()
-        return {"status": "queued"}
-    except Exception as e:
-        logger.error(f"Backfill queue failed: {e}")
-        return {"status": "error", "message": str(e)}

backend/app/routers/photos.py

@@ -1,936 +0,0 @@
-"""
-Photos API router
-"""
-from typing import List, Optional, Dict, Any
-from datetime import datetime
-from pathlib import Path
-from fastapi import APIRouter, Depends, HTTPException, Query, Response
-from fastapi.responses import FileResponse
-from pydantic import BaseModel
-from sqlalchemy import select, and_, or_, func
-from sqlalchemy.ext.asyncio import AsyncSession
-from sqlalchemy.orm import selectinload
-import json
-import os
-import logging
-
-logger = logging.getLogger(__name__)
-
-from app.database import get_db
-from app.models import Photo, Folder, Tag
-from app.models.folders import SourceRoot
-from app.models.heaps import heap_photos
-from app.models.tags import photo_tags
-from app.schemas.photos import PhotoResponse, PhotoUpdate, PhotoListResponse, BulkAction
-from app.config import settings
-
-router = APIRouter()
-
-@router.get("")
-async def list_photos(
-    q: Optional[str] = None,
-    date_from: Optional[datetime] = None,
-    date_to: Optional[datetime] = None,
-    folder_id: Optional[str] = None,
-    tag_ids: Optional[str] = None,
-    media_type: Optional[str] = None,
-    rating_min: Optional[int] = Query(None, ge=0, le=5),
-    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",
-    page: int = Query(1, ge=1),
-    per_page: int = Query(100, ge=1, le=500),
-    db: AsyncSession = Depends(get_db)
-):
-    """List photos with filters and pagination"""
-    
-    # Build query — eager-load tags so the response can include them
-    # without an N+1 round-trip per photo.
-    query = select(Photo).options(selectinload(Photo.tags))
-    
-    # Apply filters
-    filters = []
-    
-    # Text search (would use FTS5 in production)
-    if q:
-        search_pattern = f"%{q}%"
-        filters.append(
-            or_(
-                Photo.filename.ilike(search_pattern),
-                Photo.user_title.ilike(search_pattern),
-                Photo.user_notes.ilike(search_pattern),
-                Photo.exif_json.ilike(search_pattern)
-            )
-        )
-    
-    # Date range
-    if date_from:
-        filters.append(Photo.taken_at >= date_from)
-    if date_to:
-        filters.append(Photo.taken_at <= date_to)
-    
-    # Folder filter. The sidebar can pass either a SourceRoot id or a
-    # Folder id; both should include descendants so clicking a parent
-    # folder shows everything under it (Lightroom semantics).
-    if folder_id:
-        sr_check = await db.execute(
-            select(SourceRoot).where(SourceRoot.id == folder_id)
-        )
-        sr_row = sr_check.scalar_one_or_none()
-
-        if sr_row is not None:
-            # Source root → all folders under it (any depth).
-            child_folders = await db.execute(
-                select(Folder.id).where(Folder.source_root_id == folder_id)
-            )
-            child_ids = [row[0] for row in child_folders.all()]
-            if child_ids:
-                filters.append(Photo.folder_id.in_(child_ids))
-            else:
-                filters.append(Photo.id == '__no_match__')
-        else:
-            # Folder id → that folder + every descendant by path prefix.
-            target_check = await db.execute(
-                select(Folder).where(Folder.id == folder_id)
-            )
-            target = target_check.scalar_one_or_none()
-            if target is None:
-                filters.append(Photo.id == '__no_match__')
-            else:
-                target_path = os.path.normpath(target.path).rstrip(os.sep)
-                desc_result = await db.execute(
-                    select(Folder.id).where(
-                        (Folder.path == target_path)
-                        | (Folder.path.like(target_path + os.sep + '%'))
-                    )
-                )
-                desc_ids = [row[0] for row in desc_result.all()]
-                filters.append(Photo.folder_id.in_(desc_ids))
-    
-    # Media type filter
-    if media_type:
-        types = media_type.split(',')
-        filters.append(Photo.media_type.in_(types))
-    
-    # Rating filter
-    if rating_min is not None:
-        filters.append(Photo.rating >= rating_min)
-    if rating_max is not None:
-        filters.append(Photo.rating <= rating_max)
-    
-    # Color label filter
-    if color_label:
-        if color_label == 'none':
-            filters.append(Photo.color_label.is_(None))
-        else:
-            filters.append(Photo.color_label == color_label)
-    
-    # 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(
-            Photo.id.in_(
-                select(heap_photos.c.photo_id).where(heap_photos.c.heap_id == heap_id)
-            )
-        )
-
-    # Tag filter — comma-separated tag ids, AND semantics. A photo must
-    # have a row in photo_tags for EVERY listed tag. Implemented as a
-    # single GROUP BY ... HAVING COUNT(DISTINCT) = N subquery so the cost
-    # is independent of the number of tags being filtered.
-    if tag_ids:
-        tag_id_list = [t.strip() for t in tag_ids.split(',') if t.strip()]
-        if tag_id_list:
-            matching_photos = (
-                select(photo_tags.c.photo_id)
-                .where(photo_tags.c.tag_id.in_(tag_id_list))
-                .group_by(photo_tags.c.photo_id)
-                .having(
-                    func.count(func.distinct(photo_tags.c.tag_id)) == len(tag_id_list)
-                )
-            )
-            filters.append(Photo.id.in_(matching_photos))
-
-    # Apply all filters
-    if filters:
-        query = query.where(and_(*filters))
-    
-    # Apply sorting. The sort field is whitelisted so a malicious client
-    # can't pass an arbitrary column name (e.g. "filepath" leaks paths or
-    # any other Photo attribute the model exposes).
-    SORT_WHITELIST = {
-        "taken_at": Photo.taken_at,
-        "added_at": Photo.added_at,
-        "filename": Photo.filename,
-        "file_size": Photo.file_size,
-        "rating": Photo.rating,
-    }
-    sort_column = SORT_WHITELIST.get(sort, Photo.taken_at)
-    if order == "desc":
-        query = query.order_by(sort_column.desc())
-    else:
-        query = query.order_by(sort_column.asc())
-    
-    # Count total results
-    count_query = select(func.count()).select_from(query.subquery())
-    total_result = await db.execute(count_query)
-    total = total_result.scalar()
-    
-    # Apply pagination
-    offset = (page - 1) * per_page
-    query = query.offset(offset).limit(per_page)
-    
-    # Execute query
-    result = await db.execute(query)
-    photos = result.scalars().all()
-    
-    # Convert to response, attaching tags inline so the frontend can group
-    # client-side without a second round-trip.
-    photo_dicts = []
-    for photo in photos:
-        d = PhotoResponse.from_orm(photo).dict()
-        d["tags"] = [
-            {"id": t.id, "name": t.name, "color": t.color}
-            for t in (photo.tags or [])
-        ]
-        photo_dicts.append(d)
-
-    return {
-        "photos": photo_dicts,
-        "total": total,
-        "page": page,
-        "per_page": per_page,
-        "pages": (total + per_page - 1) // per_page if total else 0,
-    }
-
-@router.get("/{photo_id}")
-async def get_photo(
-    photo_id: str,
-    db: AsyncSession = Depends(get_db)
-):
-    """Get single photo with full EXIF and its tags."""
-    result = await db.execute(
-        select(Photo).where(Photo.id == photo_id)
-    )
-    photo = result.scalar_one_or_none()
-
-    if not photo:
-        raise HTTPException(status_code=404, detail="Photo not found")
-
-    # Fetch tags via the join table so we don't need to declare a
-    # relationship on the Photo model side.
-    tag_result = await db.execute(
-        select(Tag)
-        .join(photo_tags, Tag.id == photo_tags.c.tag_id)
-        .where(photo_tags.c.photo_id == photo_id)
-        .order_by(Tag.name.asc())
-    )
-    tags = tag_result.scalars().all()
-
-    base = PhotoResponse.from_orm(photo).dict()
-    base["tags"] = [
-        {"id": t.id, "name": t.name, "color": t.color} for t in tags
-    ]
-    return base
-
-
-@router.post("/{photo_id}/tags", status_code=201)
-async def add_photo_tags(
-    photo_id: str,
-    body: dict,
-    db: AsyncSession = Depends(get_db),
-):
-    """Add one or more tags to a photo. Body: { tag_ids: [str, ...] }.
-    Idempotent: re-adding existing members is a no-op."""
-    photo_result = await db.execute(select(Photo).where(Photo.id == photo_id))
-    if photo_result.scalar_one_or_none() is None:
-        raise HTTPException(status_code=404, detail="Photo not found")
-
-    tag_ids = body.get("tag_ids") or []
-    if not isinstance(tag_ids, list) or not tag_ids:
-        return {"status": "success", "added": 0}
-
-    existing = await db.execute(
-        select(photo_tags.c.tag_id).where(
-            photo_tags.c.photo_id == photo_id,
-            photo_tags.c.tag_id.in_(tag_ids),
-        )
-    )
-    existing_ids = {row[0] for row in existing.all()}
-    new_ids = [tid for tid in tag_ids if tid not in existing_ids]
-
-    if new_ids:
-        from sqlalchemy import insert
-        await db.execute(
-            insert(photo_tags),
-            [{"photo_id": photo_id, "tag_id": tid} for tid in new_ids],
-        )
-        await db.commit()
-
-    return {"status": "success", "added": len(new_ids)}
-
-
-@router.delete("/{photo_id}/tags/{tag_id}", status_code=204)
-async def remove_photo_tag(
-    photo_id: str,
-    tag_id: str,
-    db: AsyncSession = Depends(get_db),
-):
-    """Remove a tag from a photo. Removing a non-member is a no-op."""
-    from sqlalchemy import delete as sql_delete
-    await db.execute(
-        sql_delete(photo_tags).where(
-            photo_tags.c.photo_id == photo_id,
-            photo_tags.c.tag_id == tag_id,
-        )
-    )
-    await db.commit()
-    return None
-
-@router.get("/{photo_id}/thumb/{size}")
-async def get_thumbnail(
-    photo_id: str,
-    size: str,
-    response: Response,
-    db: AsyncSession = Depends(get_db)
-):
-    """Serve thumbnail (with Nginx X-Accel-Redirect support)"""
-    if size not in ['small', 'medium', 'large']:
-        raise HTTPException(status_code=400, detail="Invalid thumbnail size")
-    
-    result = await db.execute(
-        select(Photo).where(Photo.id == photo_id)
-    )
-    photo = result.scalar_one_or_none()
-    
-    if not photo:
-        raise HTTPException(status_code=404, detail="Photo not found")
-    
-    # Check if thumbnail exists, generate if not
-    thumb_dir = f"/data/thumbs/{photo_id}"
-    thumb_path = f"{thumb_dir}/{size}.webp"
-    
-    if not os.path.exists(thumb_path):
-        # Queue background generation (handles RAW/HEIC/video properly)
-        from app.tasks.thumbs import generate_thumbnails
-        generate_thumbnails.delay(photo_id)
-
-        # Best-effort inline fallback for standard images so the first
-        # request doesn't have to wait for the worker. RAW/HEIC/video
-        # and missing source files fall through to a clean 404 below.
-        if photo.filepath and os.path.exists(photo.filepath):
-            from PIL import Image
-            try:
-                os.makedirs(thumb_dir, exist_ok=True)
-                img = Image.open(photo.filepath)
-                
-                # Auto-rotate based on EXIF
-                from PIL import ExifTags
-                try:
-                    for orientation in ExifTags.TAGS.keys():
-                        if ExifTags.TAGS[orientation] == 'Orientation':
-                            break
-                    exif = img._getexif()
-                    if exif is not None:
-                        orient = exif.get(orientation)
-                        if orient == 3:
-                            img = img.rotate(180, expand=True)
-                        elif orient == 6:
-                            img = img.rotate(270, expand=True)
-                        elif orient == 8:
-                            img = img.rotate(90, expand=True)
-                except:
-                    pass
-                
-                # Generate thumbnail size
-                sizes = {'small': 150, 'medium': 400, 'large': 800}
-                target_size = sizes.get(size, 400)
-                img.thumbnail((target_size, target_size), Image.Resampling.LANCZOS)
-                
-                # Save as WebP
-                img.save(thumb_path, 'WEBP', quality=85, optimize=True)
-                
-            except HTTPException:
-                raise
-            except Exception as e:
-                logger.warning(
-                    f"Inline thumbnail fallback failed for {photo_id} ({size}); "
-                    f"waiting on worker: {e}"
-                )
-
-    # If the inline fallback didn't (or couldn't) produce the file,
-    # tell the client to retry instead of crashing in FileResponse/nginx.
-    if not os.path.exists(thumb_path):
-        raise HTTPException(
-            status_code=404,
-            detail="Thumbnail not ready",
-            headers={"Retry-After": "2"},
-        )
-
-    # Check if we're behind Nginx
-    if os.environ.get('USE_X_ACCEL_REDIRECT'):
-        # Use Nginx X-Accel-Redirect for better performance
-        response.headers['X-Accel-Redirect'] = f'/internal_thumbs/{photo_id}/{size}.webp'
-        response.headers['Content-Type'] = 'image/webp'
-        return Response()
-    else:
-        # Direct file serving for development
-        return FileResponse(thumb_path, media_type='image/webp')
-
-@router.get("/{photo_id}/original")
-async def get_original(
-    photo_id: str,
-    db: AsyncSession = Depends(get_db)
-):
-    """Serve original file (download for RAW, inline for web-safe formats)"""
-    result = await db.execute(
-        select(Photo).where(Photo.id == photo_id)
-    )
-    photo = result.scalar_one_or_none()
-
-    if not photo:
-        raise HTTPException(status_code=404, detail="Photo not found")
-
-    if not os.path.exists(photo.filepath):
-        raise HTTPException(status_code=404, detail="File not found")
-
-    # Pick a media type the browser can render inline for web-safe formats
-    # so the loupe view and <video> tags work without forcing a download.
-    ext = Path(photo.filepath).suffix.lower()
-    inline_types = {
-        '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg',
-        '.png': 'image/png', '.webp': 'image/webp', '.gif': 'image/gif',
-        '.mp4': 'video/mp4', '.mov': 'video/quicktime',
-        '.webm': 'video/webm', '.mkv': 'video/x-matroska',
-    }
-    media_type = inline_types.get(ext, 'application/octet-stream')
-
-    return FileResponse(
-        photo.filepath,
-        filename=photo.filename if media_type == 'application/octet-stream' else None,
-        media_type=media_type,
-    )
-
-
-# Extensions that the browser can decode natively. Anything else (RAW, HEIC,
-# TIFF) needs the /proxy endpoint to convert to WebP for display.
-_WEB_SAFE_DISPLAY_EXTS = {'.jpg', '.jpeg', '.png', '.webp', '.gif'}
-
-
-def _generate_proxy_webp(src_path: str, dst_path: str) -> None:
-    """Decode src_path with the appropriate backend and write a full-res WebP
-    to dst_path. Used by GET /photos/{id}/proxy for RAW/HEIC/TIFF display.
-
-    Conservative: catches per-format failures and falls back to extracting an
-    embedded preview where possible (RAW), so a single broken file never
-    crashes the request.
-    """
-    from PIL import Image
-    ext = Path(src_path).suffix.lower()
-
-    img = None
-
-    # RAW formats — decode via rawpy at full size
-    raw_exts = {'.cr2', '.cr3', '.nef', '.nrw', '.arw', '.srf',
-                '.raf', '.rw2', '.orf', '.srw', '.pef', '.rwl', '.dng'}
-    if ext in raw_exts:
-        try:
-            import rawpy
-            with rawpy.imread(src_path) as raw:
-                rgb = raw.postprocess(use_camera_wb=True, no_auto_bright=False)
-            img = Image.fromarray(rgb, 'RGB')
-        except Exception as e:
-            logger.warning(f"rawpy decode failed for {src_path}: {e}; trying embedded preview")
-            try:
-                import rawpy
-                with rawpy.imread(src_path) as raw:
-                    thumb = raw.extract_thumb()
-                    if thumb.format == rawpy.ThumbFormat.JPEG:
-                        from io import BytesIO
-                        img = Image.open(BytesIO(thumb.data))
-            except Exception as e2:
-                logger.error(f"RAW preview extraction also failed for {src_path}: {e2}")
-                raise HTTPException(status_code=415, detail="Unable to decode RAW file")
-
-    # HEIC/HEIF — pillow-heif registers a PIL plugin
-    elif ext in {'.heic', '.heif'}:
-        try:
-            from pillow_heif import register_heif_opener
-            register_heif_opener()
-            img = Image.open(src_path)
-        except Exception as e:
-            logger.error(f"HEIC decode failed for {src_path}: {e}")
-            raise HTTPException(status_code=415, detail="Unable to decode HEIC file")
-
-    # TIFF and any other PIL-supported format
-    else:
-        try:
-            img = Image.open(src_path)
-        except Exception as e:
-            logger.error(f"PIL open failed for {src_path}: {e}")
-            raise HTTPException(status_code=415, detail="Unable to decode image")
-
-    # Auto-rotate via EXIF
-    try:
-        from PIL import ImageOps
-        img = ImageOps.exif_transpose(img)
-    except Exception:
-        pass
-
-    if img.mode not in ('RGB', 'RGBA'):
-        img = img.convert('RGB')
-
-    os.makedirs(os.path.dirname(dst_path), exist_ok=True)
-    img.save(dst_path, 'WEBP', quality=90, method=4)
-
-
-@router.get("/{photo_id}/proxy")
-async def get_proxy(
-    photo_id: str,
-    response: Response,
-    db: AsyncSession = Depends(get_db),
-):
-    """Serve a full-resolution WebP proxy for non-web-safe formats (RAW, HEIC,
-    TIFF) so the loupe view can display them inline. Web-safe formats are
-    redirected to /original to avoid pointless transcoding.
-
-    Cached at /data/proxies/{photo_id}.webp; subsequent requests serve the
-    cached file (with optional X-Accel-Redirect for production).
-    """
-    result = await db.execute(select(Photo).where(Photo.id == photo_id))
-    photo = result.scalar_one_or_none()
-
-    if not photo:
-        raise HTTPException(status_code=404, detail="Photo not found")
-
-    if not os.path.exists(photo.filepath):
-        raise HTTPException(status_code=404, detail="File not found")
-
-    ext = Path(photo.filepath).suffix.lower()
-
-    # Web-safe formats don't need a proxy — serve the original directly so the
-    # browser uses its native decoder. Saves disk and CPU.
-    if ext in _WEB_SAFE_DISPLAY_EXTS:
-        return FileResponse(
-            photo.filepath,
-            media_type={
-                '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg',
-                '.png': 'image/png', '.webp': 'image/webp', '.gif': 'image/gif',
-            }[ext],
-        )
-
-    proxy_dir = "/data/proxies"
-    proxy_path = f"{proxy_dir}/{photo_id}.webp"
-
-    if not os.path.exists(proxy_path):
-        try:
-            _generate_proxy_webp(photo.filepath, proxy_path)
-        except HTTPException:
-            raise
-        except Exception as e:
-            logger.error(f"Proxy generation failed for {photo_id}: {e}")
-            raise HTTPException(status_code=500, detail="Proxy generation failed")
-
-    if os.environ.get('USE_X_ACCEL_REDIRECT'):
-        response.headers['X-Accel-Redirect'] = f'/internal_proxies/{photo_id}.webp'
-        response.headers['Content-Type'] = 'image/webp'
-        return Response()
-
-    return FileResponse(proxy_path, media_type='image/webp')
-
-@router.patch("/{photo_id}", response_model=PhotoResponse)
-async def update_photo(
-    photo_id: str,
-    update: PhotoUpdate,
-    db: AsyncSession = Depends(get_db)
-):
-    """Update photo metadata. If `filename` is included, also rename the
-    file on disk in its current directory (no cross-folder moves through
-    this endpoint).
-    """
-    result = await db.execute(
-        select(Photo).where(Photo.id == photo_id)
-    )
-    photo = result.scalar_one_or_none()
-
-    if not photo:
-        raise HTTPException(status_code=404, detail="Photo not found")
-
-    update_data = update.dict(exclude_unset=True)
-
-    # Filename rename: validate, rename on disk, then update both filename
-    # and filepath atomically. Done before any other field changes so a
-    # filesystem failure leaves the rest of the row untouched.
-    if 'filename' in update_data:
-        new_name = (update_data.pop('filename') or '').strip()
-        if not new_name:
-            raise HTTPException(status_code=400, detail="Filename cannot be empty")
-        # Reject path separators and parent traversal — same-directory only.
-        if '/' in new_name or '\\' in new_name or new_name in ('.', '..'):
-            raise HTTPException(status_code=400, detail="Invalid filename")
-
-        if new_name != photo.filename:
-            current_dir = os.path.dirname(photo.filepath)
-            new_path = os.path.join(current_dir, new_name)
-
-            if not os.path.exists(photo.filepath):
-                raise HTTPException(status_code=404, detail="Source file missing on disk")
-            if os.path.exists(new_path):
-                raise HTTPException(status_code=409, detail="A file with that name already exists")
-
-            try:
-                os.rename(photo.filepath, new_path)
-            except OSError as e:
-                logger.error(f"Failed to rename {photo.filepath} -> {new_path}: {e}")
-                raise HTTPException(status_code=500, detail=f"Rename failed: {e}")
-
-            photo.filename = new_name
-            photo.filepath = new_path
-
-    # Apply remaining updates
-    for field, value in update_data.items():
-        setattr(photo, field, value)
-
-    await db.commit()
-    await db.refresh(photo)
-    
-    return PhotoResponse.from_orm(photo)
-
-@router.delete("/{photo_id}")
-async def discard_photo(
-    photo_id: str,
-    db: AsyncSession = Depends(get_db)
-):
-    """Soft-discard a photo: sets is_discarded=true. The file stays on disk so
-    restore is just a flag flip. Permanent deletion happens via DELETE
-    /discard/{id} or DELETE /discard/empty.
-    """
-    result = await db.execute(
-        select(Photo).where(Photo.id == photo_id)
-    )
-    photo = result.scalar_one_or_none()
-
-    if not photo:
-        raise HTTPException(status_code=404, detail="Photo not found")
-
-    photo.is_discarded = True
-    photo.discarded_at = datetime.utcnow()
-    await db.commit()
-
-    return {"status": "success", "message": "Photo discarded"}
-
-class MoveRequest(BaseModel):
-    photo_ids: list[str]
-    target_id: str  # folder id OR source root id
-
-
-class CopyRequest(BaseModel):
-    photo_ids: list[str]
-    target_id: str  # folder id OR source root id
-
-
-@router.post("/copy")
-async def copy_photos(
-    body: CopyRequest,
-    db: AsyncSession = Depends(get_db),
-):
-    """Copy photos into a target folder. Same target resolution as /move
-    (folder id or source root id), but uses shutil.copy2 and creates new
-    Photo rows for each copied file. Original photos are unaffected.
-
-    Each new row gets is_duplicate=true so the user can spot the
-    duplicates later. The new file's name is suffixed with " (copy)" if
-    a name collision would otherwise happen, and " (copy 2)", etc., for
-    further conflicts.
-    """
-    import shutil
-
-    # 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}",
-        )
-
-    if not body.photo_ids:
-        return {"status": "success", "copied": 0, "errors": []}
-
-    photos_result = await db.execute(
-        select(Photo).where(Photo.id.in_(body.photo_ids))
-    )
-    photos_to_copy = photos_result.scalars().all()
-
-    copied = 0
-    errors: list[dict] = []
-
-    def _unique_target_name(directory: str, filename: str) -> Optional[str]:
-        """Find a non-colliding filename in `directory` based on `filename`,
-        suffixing " (copy)", " (copy 2)", ... if needed. Gives up after 100
-        attempts."""
-        if not os.path.exists(os.path.join(directory, filename)):
-            return filename
-        stem, ext = os.path.splitext(filename)
-        for i in range(1, 100):
-            candidate = f"{stem} (copy{'' if i == 1 else f' {i}'}){ext}"
-            if not os.path.exists(os.path.join(directory, candidate)):
-                return candidate
-        return None
-
-    for photo in photos_to_copy:
-        if not os.path.exists(photo.filepath):
-            errors.append({"id": photo.id, "error": "source file missing"})
-            continue
-
-        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
-
-        # Create a new Photo row pointing at the copy. Most metadata is
-        # copied verbatim; the file_hash stays so the duplicate flag does
-        # the right thing across the library.
-        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
-
-    await db.commit()
-
-    return {
-        "status": "success",
-        "copied": copied,
-        "errors": errors,
-    }
-
-
-@router.post("/move")
-async def move_photos(
-    body: MoveRequest,
-    db: AsyncSession = Depends(get_db),
-):
-    """Move photos into a target folder. The target can be either a Folder
-    id or a SourceRoot id (since the LeftSidebar only exposes source roots
-    today). The handler resolves the target to an on-disk directory, calls
-    shutil.move for each photo, and updates photo.filepath + folder_id.
-
-    Per-file failures (target name collision, missing source) are collected
-    and returned in the response so a single bad photo doesn't abort the
-    batch.
-    """
-    import shutil
-
-    # 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
-        # We need a Folder row to point photo.folder_id at. Reuse the
-        # scanner's get_or_create helper so we don't duplicate the dedupe
-        # / normalization logic.
-        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}",
-        )
-
-    if not body.photo_ids:
-        return {"status": "success", "moved": 0, "errors": []}
-
-    # Fetch the photo rows
-    photos_result = await db.execute(
-        select(Photo).where(Photo.id.in_(body.photo_ids))
-    )
-    photos_to_move = photos_result.scalars().all()
-
-    moved = 0
-    errors: list[dict] = []
-
-    for photo in photos_to_move:
-        # Skip if already in the target folder.
-        if photo.folder_id == target_folder.id:
-            continue
-
-        new_path = os.path.join(target_dir, photo.filename)
-
-        if not os.path.exists(photo.filepath):
-            errors.append({"id": photo.id, "error": "source file missing"})
-            continue
-        if os.path.exists(new_path):
-            errors.append({"id": photo.id, "error": f"name already exists in target: {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
-
-    await db.commit()
-
-    return {
-        "status": "success",
-        "moved": moved,
-        "errors": errors,
-    }
-
-
-@router.post("/bulk")
-async def bulk_action(
-    action: BulkAction,
-    db: AsyncSession = Depends(get_db)
-):
-    """Perform bulk actions on multiple photos"""
-    # Get photos
-    result = await db.execute(
-        select(Photo).where(Photo.id.in_(action.ids))
-    )
-    photos = result.scalars().all()
-    
-    if not photos:
-        raise HTTPException(status_code=404, detail="No photos found")
-    
-    # Perform action based on type
-    if action.action == 'discard':
-        for photo in photos:
-            photo.is_discarded = True
-            photo.discarded_at = datetime.utcnow()
-    elif action.action == 'restore':
-        for photo in photos:
-            photo.is_discarded = False
-            photo.discarded_at = None
-    elif action.action == 'set_rating':
-        for photo in photos:
-            photo.rating = action.value
-    elif action.action == 'set_color':
-        for photo in photos:
-            photo.color_label = action.value
-    elif action.action == 'add_tags':
-        # value is a list of tag ids. We bulk-insert (photo_id, tag_id)
-        # rows for every (photo, tag) combination that doesn't already
-        # exist, so the operation is idempotent.
-        tag_ids = action.value or []
-        if not isinstance(tag_ids, list) or not tag_ids:
-            return {"status": "success", "added": 0, "message": "No tags supplied"}
-        photo_ids = [p.id for p in photos]
-        existing = await db.execute(
-            select(photo_tags.c.photo_id, photo_tags.c.tag_id).where(
-                photo_tags.c.photo_id.in_(photo_ids),
-                photo_tags.c.tag_id.in_(tag_ids),
-            )
-        )
-        existing_pairs = {(row[0], row[1]) for row in existing.all()}
-        new_rows = [
-            {"photo_id": pid, "tag_id": tid}
-            for pid in photo_ids
-            for tid in tag_ids
-            if (pid, tid) not in existing_pairs
-        ]
-        if new_rows:
-            from sqlalchemy import insert
-            await db.execute(insert(photo_tags), new_rows)
-        await db.commit()
-        return {
-            "status": "success",
-            "added": len(new_rows),
-            "message": f"Added {len(new_rows)} tag link{'s' if len(new_rows) != 1 else ''}",
-        }
-    elif action.action == 'remove_tags':
-        tag_ids = action.value or []
-        if not isinstance(tag_ids, list) or not tag_ids:
-            return {"status": "success", "removed": 0, "message": "No tags supplied"}
-        photo_ids = [p.id for p in photos]
-        from sqlalchemy import delete as sql_delete
-        result = await db.execute(
-            sql_delete(photo_tags).where(
-                photo_tags.c.photo_id.in_(photo_ids),
-                photo_tags.c.tag_id.in_(tag_ids),
-            )
-        )
-        await db.commit()
-        return {
-            "status": "success",
-            "removed": result.rowcount or 0,
-            "message": f"Removed tag link{'s' if (result.rowcount or 0) != 1 else ''}",
-        }
-    else:
-        raise HTTPException(status_code=400, detail="Invalid action")
-    
-    await db.commit()
-    
-    return {
-        "status": "success",
-        "message": f"{action.action} applied to {len(photos)} photos"
-    }

backend/app/routers/tags.py

@@ -1,114 +0,0 @@
-"""
-Tags API router
-"""
-from typing import Optional
-from fastapi import APIRouter, Depends, HTTPException
-from pydantic import BaseModel
-from sqlalchemy import select, func, insert, delete
-from sqlalchemy.ext.asyncio import AsyncSession
-
-from app.database import get_db
-from app.models import Tag
-from app.models.tags import photo_tags
-
-router = APIRouter()
-
-
-# ── Schemas ───────────────────────────────────────────────────────────────
-
-class TagCreate(BaseModel):
-    name: str
-    color: Optional[str] = None
-
-
-class TagUpdate(BaseModel):
-    name: Optional[str] = None
-    color: Optional[str] = None
-
-
-# ── Endpoints ─────────────────────────────────────────────────────────────
-
-@router.get("")
-async def list_tags(db: AsyncSession = Depends(get_db)):
-    """List all tags with their photo counts."""
-    count_subq = (
-        select(
-            photo_tags.c.tag_id,
-            func.count(photo_tags.c.photo_id).label("photo_count"),
-        )
-        .group_by(photo_tags.c.tag_id)
-        .subquery()
-    )
-    stmt = (
-        select(Tag, count_subq.c.photo_count)
-        .outerjoin(count_subq, Tag.id == count_subq.c.tag_id)
-        .order_by(Tag.name.asc())
-    )
-    result = await db.execute(stmt)
-    rows = result.all()
-
-    return [
-        {
-            "id": tag.id,
-            "name": tag.name,
-            "color": tag.color,
-            "photo_count": int(count or 0),
-        }
-        for tag, count in rows
-    ]
-
-
-@router.post("", status_code=201)
-async def create_tag(body: TagCreate, db: AsyncSession = Depends(get_db)):
-    """Create a new tag. Names are unique — re-creating an existing name
-    returns the existing row instead of erroring (idempotent for the
-    autocomplete UI flow)."""
-    name = (body.name or "").strip()
-    if not name:
-        raise HTTPException(status_code=400, detail="Tag name is required")
-
-    existing = await db.execute(select(Tag).where(Tag.name == name))
-    found = existing.scalar_one_or_none()
-    if found:
-        return {"id": found.id, "name": found.name, "color": found.color, "photo_count": 0}
-
-    tag = Tag(name=name, color=body.color)
-    db.add(tag)
-    await db.commit()
-    await db.refresh(tag)
-    return {"id": tag.id, "name": tag.name, "color": tag.color, "photo_count": 0}
-
-
-@router.patch("/{tag_id}")
-async def update_tag(
-    tag_id: str, body: TagUpdate, db: AsyncSession = Depends(get_db)
-):
-    """Rename or recolor a tag."""
-    result = await db.execute(select(Tag).where(Tag.id == tag_id))
-    tag = result.scalar_one_or_none()
-    if not tag:
-        raise HTTPException(status_code=404, detail="Tag not found")
-
-    if body.name is not None:
-        name = body.name.strip()
-        if not name:
-            raise HTTPException(status_code=400, detail="Tag name is required")
-        tag.name = name
-    if body.color is not None:
-        tag.color = body.color or None
-
-    await db.commit()
-    await db.refresh(tag)
-    return {"id": tag.id, "name": tag.name, "color": tag.color}
-
-
-@router.delete("/{tag_id}", status_code=204)
-async def delete_tag(tag_id: str, db: AsyncSession = Depends(get_db)):
-    """Delete a tag. Photo associations cascade-delete via the FK."""
-    result = await db.execute(select(Tag).where(Tag.id == tag_id))
-    tag = result.scalar_one_or_none()
-    if not tag:
-        raise HTTPException(status_code=404, detail="Tag not found")
-    await db.delete(tag)
-    await db.commit()
-    return None

backend/app/schemas/photos.py

@@ -1,69 +0,0 @@
-"""
-Pydantic schemas for photos
-"""
-from pydantic import BaseModel, Field
-from typing import Optional, List, Dict, Any
-from datetime import datetime
-
-class PhotoBase(BaseModel):
-    """Base photo schema"""
-    filename: str
-    media_type: str
-    original_format: Optional[str] = None
-    width: Optional[int] = None
-    height: Optional[int] = None
-    file_size: Optional[int] = None
-    taken_at: Optional[datetime] = None
-    taken_at_source: Optional[str] = None
-    user_title: Optional[str] = None
-    user_notes: Optional[str] = None
-    rating: int = 0
-    color_label: Optional[str] = None
-
-class PhotoResponse(PhotoBase):
-    """Photo response schema"""
-    id: str
-    filepath: str
-    folder_id: Optional[str] = None
-    file_hash: Optional[str] = None
-    added_at: datetime
-    updated_at: Optional[datetime] = None
-    is_discarded: bool = False
-    discarded_at: Optional[datetime] = None
-    thumb_small: Optional[str] = None
-    thumb_medium: Optional[str] = None
-    thumb_large: Optional[str] = None
-    processing_status: str = 'pending'
-    processing_error: Optional[str] = None
-    exif_json: Optional[str] = None
-    is_duplicate: bool = False
-    live_photo_video_id: Optional[str] = None
-    # tags: List[Dict[str, Any]] = []  # TODO: Enable when using eager loading
-    
-    class Config:
-        orm_mode = True
-        from_attributes = True
-
-class PhotoUpdate(BaseModel):
-    """Photo update schema"""
-    filename: Optional[str] = None
-    user_title: Optional[str] = None
-    user_notes: Optional[str] = None
-    rating: Optional[int] = Field(None, ge=0, le=5)
-    color_label: Optional[str] = None
-    is_discarded: Optional[bool] = None
-    taken_at: Optional[datetime] = None
-
-class PhotoListResponse(BaseModel):
-    """Photo list response with pagination"""
-    photos: List[PhotoResponse]
-    total: int
-    page: int
-    per_page: int
-    pages: int
-
-class BulkAction(BaseModel):
-    """Bulk action on photos"""
-    ids: List[str]
-    action: str  # 'discard', 'restore', 'delete_permanent', 'move', 'copy', 'add_tag', 'remove_tag', 'set_rating', 'set_color'
-    value: Optional[Any] = None  # For actions that need a value (rating, color, tag_id, folder_id)

backend/app/services/cleanup.py

@@ -1,275 +0,0 @@
-"""
-One-shot data integrity cleanup for source_roots / folders / photos.
-
-Earlier versions of the scanner stored paths verbatim, so trailing slashes
-and redundant separators produced duplicate SourceRoot and Folder rows for
-the same physical directory. The watcher also auto-created source roots
-when fired with a parent dir. This module merges the duplicates and
-re-points photos to the canonical folder so the data lines up with the
-post-fix scanner.
-
-Idempotent: safe to run on every backend startup.
-"""
-import os
-import logging
-from datetime import datetime
-from sqlalchemy import select, update, func
-from sqlalchemy.ext.asyncio import AsyncSession
-
-from app.database import AsyncSessionLocal
-from app.models import Photo, Folder, SourceRoot
-
-logger = logging.getLogger(__name__)
-
-
-def _normalize_path(path: str) -> str:
-    return os.path.normpath(path)
-
-
-async def _dedupe_source_roots(session: AsyncSession) -> int:
-    """Group source roots by normalized path and merge duplicates. Returns
-    the number of rows deleted."""
-    result = await session.execute(select(SourceRoot))
-    rows = result.scalars().all()
-
-    groups: dict[str, list[SourceRoot]] = {}
-    for sr in rows:
-        norm = _normalize_path(sr.path)
-        groups.setdefault(norm, []).append(sr)
-
-    deleted = 0
-    for norm, srs in groups.items():
-        if len(srs) == 1:
-            # Make sure the canonical row's path is normalized too.
-            if srs[0].path != norm:
-                srs[0].path = norm
-            continue
-        # Pick the canonical row: prefer one with a non-empty name and the
-        # earliest added_at (most likely the original).
-        canonical = sorted(
-            srs,
-            key=lambda s: (not bool(s.name), s.added_at or datetime.max),
-        )[0]
-        canonical.path = norm
-        for sr in srs:
-            if sr.id == canonical.id:
-                continue
-            # Re-point folders that referenced the duplicate root.
-            await session.execute(
-                update(Folder)
-                .where(Folder.source_root_id == sr.id)
-                .values(source_root_id=canonical.id)
-            )
-            await session.delete(sr)
-            deleted += 1
-
-    return deleted
-
-
-async def _dedupe_folders(session: AsyncSession) -> int:
-    """Group folders by normalized path and merge duplicates. Returns the
-    number of rows deleted."""
-    result = await session.execute(select(Folder))
-    rows = result.scalars().all()
-
-    groups: dict[str, list[Folder]] = {}
-    for f in rows:
-        norm = _normalize_path(f.path)
-        groups.setdefault(norm, []).append(f)
-
-    deleted = 0
-    for norm, folders in groups.items():
-        if len(folders) == 1:
-            if folders[0].path != norm:
-                folders[0].path = norm
-            continue
-        # Canonical = the one with the most photos already attached, then
-        # the lowest-id (deterministic tiebreaker).
-        canonical = sorted(
-            folders,
-            key=lambda f: (-(f.photo_count or 0), f.id),
-        )[0]
-        canonical.path = norm
-        for f in folders:
-            if f.id == canonical.id:
-                continue
-            # Re-point photos to the canonical folder.
-            await session.execute(
-                update(Photo)
-                .where(Photo.folder_id == f.id)
-                .values(folder_id=canonical.id)
-            )
-            await session.delete(f)
-            deleted += 1
-
-    return deleted
-
-
-async def _recompute_folder_counts(session: AsyncSession) -> None:
-    """Set folder.photo_count to the actual non-discarded photo count."""
-    result = await session.execute(select(Folder))
-    folders = result.scalars().all()
-    for f in folders:
-        count_result = await session.execute(
-            select(func.count(Photo.id)).where(
-                Photo.folder_id == f.id,
-                Photo.is_discarded == False,  # noqa: E712
-            )
-        )
-        f.photo_count = int(count_result.scalar() or 0)
-
-
-async def _warn_stale_source_roots(session: AsyncSession) -> int:
-    """Log a warning for any active source root whose path no longer exists
-    on disk. Doesn't delete — a missing path could be a temporarily
-    unmounted drive, and silently dropping user data is worse than
-    surfacing a noisy log line.
-    """
-    result = await session.execute(select(SourceRoot))
-    rows = result.scalars().all()
-    stale = 0
-    for sr in rows:
-        if not os.path.isdir(sr.path):
-            stale += 1
-            logger.warning(
-                f"Source root '{sr.name}' path is missing on disk: {sr.path} "
-                f"— is the docker mount still in place? "
-                f"(Edit docker-compose.yml or PHOTO_DIRS in .env to fix.)"
-            )
-    return stale
-
-
-async def find_missing(
-    session: AsyncSession,
-) -> tuple[list[str], list[str], list[str]]:
-    """Walk every non-discarded photo + every folder and check whether
-    they still resolve on disk. Returns
-    (deletable_photo_ids, deletable_folder_ids, skipped_photo_ids).
-
-    Skipped rows are photos/folders whose owning source_root path itself
-    doesn't resolve — that's almost always an unmounted drive, and
-    silently deleting those rows would be data loss. The caller can
-    surface the skip count separately so the user knows the cleanup
-    wasn't a no-op by accident.
-    """
-    sr_rows = (await session.execute(select(SourceRoot))).scalars().all()
-    sr_mounted: dict[str, bool] = {sr.id: os.path.isdir(sr.path) for sr in sr_rows}
-
-    photos = (await session.execute(
-        select(Photo.id, Photo.filepath, Photo.folder_id)
-        .where(Photo.is_discarded.is_(False))
-    )).all()
-
-    folders = (await session.execute(
-        select(Folder.id, Folder.path, Folder.source_root_id)
-    )).all()
-    folder_to_sr = {fid: srid for fid, _path, srid in folders}
-
-    deletable_photos: list[str] = []
-    skipped: list[str] = []
-    for pid, fp, folder_id in photos:
-        sr_id = folder_to_sr.get(folder_id)
-        if sr_id is None or not sr_mounted.get(sr_id, False):
-            skipped.append(pid)
-            continue
-        if not os.path.exists(fp):
-            deletable_photos.append(pid)
-
-    deletable_folders: list[str] = []
-    for fid, fpath, sr_id in folders:
-        if sr_id is None or not sr_mounted.get(sr_id, False):
-            continue
-        if not os.path.isdir(fpath):
-            deletable_folders.append(fid)
-
-    return deletable_photos, deletable_folders, skipped
-
-
-async def prune_missing_photos(dry_run: bool = True) -> dict:
-    """Delete photo + folder rows whose paths are no longer on disk *and*
-    whose source root is currently mounted. Common cause: PHOTO_DIRS in
-    .env was repointed at a different library, leaving every old row
-    orphaned.
-
-    Set dry_run=False to actually delete. The default is intentionally
-    safe so the matching count can be surfaced in the UI before the
-    user commits to it.
-
-    Function name kept for backwards compatibility — it now also prunes
-    folders, not just photos.
-    """
-    from sqlalchemy import delete
-    async with AsyncSessionLocal() as session:
-        try:
-            deletable_photos, deletable_folders, skipped = await find_missing(session)
-            if not dry_run:
-                CHUNK = 500
-                # Photos first (folders may FK from them via folder_id).
-                for i in range(0, len(deletable_photos), CHUNK):
-                    await session.execute(
-                        delete(Photo).where(
-                            Photo.id.in_(deletable_photos[i:i + CHUNK])
-                        )
-                    )
-                # Then drop folders that ALSO no longer have any photos
-                # pointing at them. We re-check after the photo delete so
-                # we don't strand a folder that legitimately exists on
-                # disk but happened to match the orphan list.
-                if deletable_folders:
-                    for i in range(0, len(deletable_folders), CHUNK):
-                        chunk = deletable_folders[i:i + CHUNK]
-                        # Only delete folders that now have zero photos
-                        # left attached (defensive — should always be 0
-                        # if the path is gone, but a concurrent scan
-                        # could re-create rows).
-                        still_used = (await session.execute(
-                            select(Photo.folder_id)
-                            .where(Photo.folder_id.in_(chunk))
-                            .distinct()
-                        )).scalars().all()
-                        safe = [f for f in chunk if f not in set(still_used)]
-                        if safe:
-                            await session.execute(
-                                delete(Folder).where(Folder.id.in_(safe))
-                            )
-                await session.commit()
-                logger.info(
-                    f"Pruned {len(deletable_photos)} photo rows + "
-                    f"{len(deletable_folders)} folder rows"
-                )
-            key_p = "would_delete" if dry_run else "deleted"
-            key_f = "would_delete_folders" if dry_run else "deleted_folders"
-            return {
-                key_p: len(deletable_photos),
-                key_f: len(deletable_folders),
-                "skipped_unmounted": len(skipped),
-                "dry_run": dry_run,
-            }
-        except Exception as e:
-            logger.error(f"prune_missing_photos failed: {e}")
-            await session.rollback()
-            raise
-
-
-async def cleanup_data_integrity() -> dict:
-    """Top-level entry point. Runs the dedupe + count refresh in a single
-    transaction. Returns a small summary dict for logging."""
-    async with AsyncSessionLocal() as session:
-        try:
-            sr_deleted = await _dedupe_source_roots(session)
-            f_deleted = await _dedupe_folders(session)
-            await _recompute_folder_counts(session)
-            stale = await _warn_stale_source_roots(session)
-            await session.commit()
-            summary = {
-                "source_roots_merged": sr_deleted,
-                "folders_merged": f_deleted,
-                "source_roots_stale": stale,
-            }
-            if sr_deleted or f_deleted:
-                logger.info(f"Cleanup merged duplicates: {summary}")
-            return summary
-        except Exception as e:
-            logger.error(f"Cleanup failed: {e}")
-            await session.rollback()
-            raise

backend/app/services/duplicates.py

@@ -1,227 +0,0 @@
-"""
-Duplicate detection: group photos by perceptual-hash similarity.
-
-Strategy
---------
-Each photo carries a 16-char hex perceptual hash (`Photo.phash`) computed
-by the thumbnail worker from the original-resolution decoded frame
-(`app.tasks.thumbs._generate_thumbnails_async`). pHash is robust to
-resize / re-encoding / mild edits, so two photos that are visually the
-"same shot" land at small Hamming distance even when their bytes are
-completely different.
-
-This module turns those per-photo hashes into explicit *groups*. The
-result is persisted in two columns:
-
-  * `Photo.duplicate_group_id`  — shared by every member of a group
-  * `Photo.is_duplicate`         — derived: True iff group_id IS NOT NULL
-                                  (kept as a column so the existing
-                                  PhotoThumbnail badge and /library/stats
-                                  count don't have to change).
-
-The grouping is recomputed in batches by `regroup_duplicates`, NOT on
-individual writes — that lets us use a single in-memory pass instead of
-maintaining a per-row similarity index. Triggered automatically after
-each scan and on demand from the Settings panel.
-
-Complexity
-----------
-Pairwise O(N²) over photos with a non-null phash. At ~5 µs per Hamming
-distance in CPython this is roughly:
-
-    1k photos →   ~5 s
-    5k photos →  ~125 s
-    10k photos → ~500 s
-
-That's the wrong shape for libraries past ~5k. The drop-in replacement
-is a BK-tree (e.g. `pybktree`) which gives O(log N) lookups for a fixed
-Hamming threshold; swap it in here when someone trips the limit. The
-public function signature stays the same.
-
-Out of scope (deferred)
------------------------
-* Dismissing a group / "intentional duplicates" — would need a per-group
-  or per-pair flag plus a skip-set in this function so re-grouping
-  doesn't bring them back. Add when there's a real user need.
-* Incremental updates on individual photo writes — currently we just
-  re-run the whole job after each scan, which is fine while the cost is
-  bounded.
-"""
-
-from __future__ import annotations
-
-import logging
-import uuid
-from typing import Optional
-
-from sqlalchemy import select, update
-
-from app.database import AsyncSessionLocal
-from app.models.photos import Photo
-
-logger = logging.getLogger(__name__)
-
-
-# Hamming distance threshold under which two phashes are considered
-# "the same image". 6 bits out of 64 is the rule-of-thumb sweet spot for
-# pHash — tight enough to avoid false positives between unrelated photos,
-# loose enough to catch JPEG re-encodes, slight crops, and a screenshot
-# of a screenshot.
-DEFAULT_THRESHOLD = 6
-
-
-def _hex_to_int(h: str) -> int:
-    """Parse a 16-char hex pHash to a Python int. Returns -1 on bad input
-    so the pairwise loop can skip the row without raising."""
-    try:
-        return int(h, 16)
-    except (TypeError, ValueError):
-        return -1
-
-
-def _hamming(a: int, b: int) -> int:
-    """Population count of XOR — the canonical hash distance metric.
-    `int.bit_count()` is C-implemented in CPython 3.10+ and is by far
-    the fastest path; the `bin(...).count('1')` fallback is here only
-    so the function still works on older interpreters."""
-    x = a ^ b
-    try:
-        return x.bit_count()  # type: ignore[attr-defined]
-    except AttributeError:
-        return bin(x).count('1')
-
-
-class _UnionFind:
-    """Tiny union-find / disjoint-set used to merge similar phashes into
-    connected components. Inlined here (rather than pulled from a dep)
-    because it's ~15 lines and we don't need anything fancy."""
-
-    def __init__(self, n: int) -> None:
-        self.parent = list(range(n))
-        self.rank = [0] * n
-
-    def find(self, x: int) -> int:
-        # Path compression — flattens the tree on lookup so subsequent
-        # finds are amortized O(α(N)) ≈ O(1).
-        while self.parent[x] != x:
-            self.parent[x] = self.parent[self.parent[x]]
-            x = self.parent[x]
-        return x
-
-    def union(self, a: int, b: int) -> None:
-        ra, rb = self.find(a), self.find(b)
-        if ra == rb:
-            return
-        if self.rank[ra] < self.rank[rb]:
-            ra, rb = rb, ra
-        self.parent[rb] = ra
-        if self.rank[ra] == self.rank[rb]:
-            self.rank[ra] += 1
-
-
-async def regroup_duplicates(threshold: int = DEFAULT_THRESHOLD) -> dict:
-    """Recompute every photo's duplicate_group_id from current phashes.
-
-    Idempotent — safe to call as often as you like. Returns a small
-    summary dict the maintenance endpoint surfaces back to the UI.
-
-    Photos that end up alone in a component (size 1) get
-    `duplicate_group_id=NULL` and `is_duplicate=False`. This is what
-    cleans up "dead" groups after the user discards N-1 members from
-    one.
-    """
-    async with AsyncSessionLocal() as session:
-        # Pull (id, phash) for every non-discarded photo with a hash.
-        # Discarded photos are excluded so we don't keep showing groups
-        # made up of trashed copies.
-        rows = (
-            await session.execute(
-                select(Photo.id, Photo.phash)
-                .where(Photo.phash.is_not(None))
-                .where(Photo.is_discarded.is_(False))
-            )
-        ).all()
-
-        n = len(rows)
-        if n == 0:
-            # Still need to clear stale group_ids in case the user just
-            # discarded the last surviving member of every group.
-            await _clear_all_groups(session)
-            await session.commit()
-            return {
-                'photos_considered': 0,
-                'groups': 0,
-                'members': 0,
-            }
-
-        ids: list[str] = [row[0] for row in rows]
-        hashes: list[int] = [_hex_to_int(row[1]) for row in rows]
-
-        uf = _UnionFind(n)
-
-        # O(N²) pairwise comparison. See module docstring for the
-        # scaling analysis and the BK-tree upgrade path.
-        for i in range(n):
-            hi = hashes[i]
-            if hi < 0:
-                continue
-            for j in range(i + 1, n):
-                hj = hashes[j]
-                if hj < 0:
-                    continue
-                if _hamming(hi, hj) <= threshold:
-                    uf.union(i, j)
-
-        # Collect components. Each connected component of size >= 2 gets
-        # a fresh group id; size-1 components are intentionally dropped.
-        components: dict[int, list[int]] = {}
-        for i in range(n):
-            root = uf.find(i)
-            components.setdefault(root, []).append(i)
-
-        # First pass: clear EVERY photo's group_id so survivors of an
-        # earlier grouping that no longer match anyone end up clean. This
-        # is one bulk UPDATE rather than per-photo to keep the cost low
-        # even on big libraries.
-        await _clear_all_groups(session)
-
-        # Second pass: write the new group ids for components of size 2+.
-        groups_created = 0
-        members_total = 0
-        for members in components.values():
-            if len(members) < 2:
-                continue
-            group_id = str(uuid.uuid4())
-            member_ids = [ids[i] for i in members]
-            await session.execute(
-                update(Photo)
-                .where(Photo.id.in_(member_ids))
-                .values(
-                    duplicate_group_id=group_id,
-                    is_duplicate=True,
-                )
-            )
-            groups_created += 1
-            members_total += len(member_ids)
-
-        await session.commit()
-
-        logger.info(
-            f"regroup_duplicates: considered {n} photos, "
-            f"created {groups_created} group(s) covering {members_total} member(s)"
-        )
-
-        return {
-            'photos_considered': n,
-            'groups': groups_created,
-            'members': members_total,
-        }
-
-
-async def _clear_all_groups(session) -> None:
-    """Reset duplicate_group_id / is_duplicate on every photo. Used as
-    the first half of a regroup pass so photos that no longer cluster
-    with anyone end up clean instead of carrying a stale group id."""
-    await session.execute(
-        update(Photo).values(duplicate_group_id=None, is_duplicate=False)
-    )

backend/app/services/metadata.py

@@ -1,183 +0,0 @@
-"""
-Metadata extraction service using ExifTool
-"""
-import json
-import logging
-import asyncio
-from datetime import datetime
-from typing import Dict, Optional
-import subprocess
-from pathlib import Path
-
-from celery import shared_task
-from sqlalchemy import select
-
-from app.database import AsyncSessionLocal
-from app.models import Photo
-
-logger = logging.getLogger(__name__)
-
-def parse_exif_datetime(date_str: str) -> Optional[datetime]:
-    """Parse EXIF datetime string to Python datetime"""
-    if not date_str:
-        return None
-    
-    # Common EXIF datetime formats
-    formats = [
-        "%Y:%m:%d %H:%M:%S",
-        "%Y-%m-%d %H:%M:%S",
-        "%Y:%m:%d %H:%M:%S.%f",
-        "%Y-%m-%dT%H:%M:%S",
-        "%Y-%m-%dT%H:%M:%S.%f",
-        "%Y-%m-%dT%H:%M:%S%z"
-    ]
-    
-    for fmt in formats:
-        try:
-            return datetime.strptime(date_str, fmt)
-        except ValueError:
-            continue
-    
-    return None
-
-def extract_key_metadata(exif_data: Dict) -> Dict:
-    """Extract key metadata fields for FTS indexing"""
-    key_fields = []
-    
-    # Camera information
-    if 'Make' in exif_data:
-        key_fields.append(exif_data['Make'])
-    if 'Model' in exif_data:
-        key_fields.append(exif_data['Model'])
-    if 'LensModel' in exif_data:
-        key_fields.append(exif_data['LensModel'])
-    
-    # Location information
-    if 'GPSLatitude' in exif_data and 'GPSLongitude' in exif_data:
-        key_fields.append(f"GPS: {exif_data['GPSLatitude']}, {exif_data['GPSLongitude']}")
-    
-    # IPTC/XMP keywords
-    if 'Keywords' in exif_data:
-        if isinstance(exif_data['Keywords'], list):
-            key_fields.extend(exif_data['Keywords'])
-        else:
-            key_fields.append(exif_data['Keywords'])
-    
-    # Copyright and creator
-    if 'Copyright' in exif_data:
-        key_fields.append(exif_data['Copyright'])
-    if 'Creator' in exif_data:
-        key_fields.append(exif_data['Creator'])
-    if 'Artist' in exif_data:
-        key_fields.append(exif_data['Artist'])
-    
-    return {
-        'exif_text': ' '.join(key_fields),
-        'camera_make': exif_data.get('Make'),
-        'camera_model': exif_data.get('Model'),
-        'lens_model': exif_data.get('LensModel'),
-        'gps_latitude': exif_data.get('GPSLatitude'),
-        'gps_longitude': exif_data.get('GPSLongitude'),
-    }
-
-@shared_task(name='extract_metadata')
-def extract_metadata(photo_id: str):
-    """Extract metadata from a photo using ExifTool"""
-    return asyncio.run(_extract_metadata_async(photo_id))
-
-async def _extract_metadata_async(photo_id: str):
-    """Async implementation of metadata extraction"""
-    async with AsyncSessionLocal() as session:
-        try:
-            # Get photo from database
-            result = await session.execute(
-                select(Photo).where(Photo.id == photo_id)
-            )
-            photo = result.scalar_one_or_none()
-            
-            if not photo:
-                logger.error(f"Photo not found: {photo_id}")
-                return {'status': 'error', 'message': 'Photo not found'}
-            
-            # Check if file exists
-            if not Path(photo.filepath).exists():
-                logger.error(f"File not found: {photo.filepath}")
-                return {'status': 'error', 'message': 'File not found'}
-            
-            # Run ExifTool to extract metadata
-            cmd = [
-                'exiftool',
-                '-j',  # JSON output
-                '-G',  # Group names
-                '-s',  # Short output format
-                '-All',  # All metadata
-                photo.filepath
-            ]
-            
-            try:
-                result = subprocess.run(
-                    cmd,
-                    capture_output=True,
-                    text=True,
-                    timeout=30
-                )
-                
-                if result.returncode != 0:
-                    logger.error(f"ExifTool error: {result.stderr}")
-                    return {'status': 'error', 'message': result.stderr}
-                
-                # Parse JSON output
-                metadata = json.loads(result.stdout)
-                if metadata and len(metadata) > 0:
-                    exif_data = metadata[0]
-                    
-                    # Store full metadata as JSON
-                    photo.exif_json = json.dumps(exif_data)
-                    
-                    # Extract taken_at date
-                    date_fields = [
-                        'EXIF:DateTimeOriginal',
-                        'EXIF:CreateDate',
-                        'QuickTime:MediaCreateDate',
-                        'EXIF:ModifyDate'
-                    ]
-                    
-                    for field in date_fields:
-                        if field in exif_data:
-                            taken_at = parse_exif_datetime(exif_data[field])
-                            if taken_at:
-                                photo.taken_at = taken_at
-                                photo.taken_at_source = 'exif'
-                                break
-                    
-                    # Extract dimensions if not already set
-                    if not photo.width:
-                        photo.width = exif_data.get('EXIF:ImageWidth') or exif_data.get('File:ImageWidth')
-                    if not photo.height:
-                        photo.height = exif_data.get('EXIF:ImageHeight') or exif_data.get('File:ImageHeight')
-                    
-                    # Extract and store key metadata for search
-                    key_metadata = extract_key_metadata(exif_data)
-                    
-                    # Update FTS table (would be done via trigger in production)
-                    # For now, we'll store it in a comment
-                    
-                    await session.commit()
-                    
-                    logger.info(f"Metadata extracted for photo {photo_id}")
-                    return {
-                        'status': 'success',
-                        'photo_id': photo_id,
-                        'taken_at': photo.taken_at.isoformat() if photo.taken_at else None
-                    }
-                
-            except subprocess.TimeoutExpired:
-                logger.error(f"ExifTool timeout for {photo.filepath}")
-                return {'status': 'error', 'message': 'ExifTool timeout'}
-            except json.JSONDecodeError as e:
-                logger.error(f"Failed to parse ExifTool output: {e}")
-                return {'status': 'error', 'message': 'Invalid ExifTool output'}
-            
-        except Exception as e:
-            logger.error(f"Error extracting metadata for {photo_id}: {e}")
-            return {'status': 'error', 'message': str(e)}

backend/app/services/scanner.py

@@ -1,65 +0,0 @@
-"""
-Scanner service for initial library scan and one-time bootstrap of the
-default source root on first boot.
-"""
-import os
-import logging
-from sqlalchemy import select
-
-from app.database import AsyncSessionLocal
-from app.models import SourceRoot
-from app.tasks.scan import scan_all_source_roots
-from app.config import settings
-
-logger = logging.getLogger(__name__)
-
-# The single host → container mount path. The compose file mounts whatever
-# the user set as PHOTO_DIRS at this path.
-DEFAULT_LIBRARY_PATH = "/photos"
-DEFAULT_LIBRARY_NAME = "Library"
-
-
-async def bootstrap_default_source_root() -> None:
-    """If no source roots exist in the DB, create one pointing at the default
-    library mount. Lets a fresh install pick up photos with zero
-    configuration: the user only needs to set PHOTO_DIRS in .env.
-    """
-    if not os.path.isdir(DEFAULT_LIBRARY_PATH):
-        logger.warning(
-            f"Default library path {DEFAULT_LIBRARY_PATH} is not mounted; "
-            "set PHOTO_DIRS in .env and recreate the container."
-        )
-        return
-
-    async with AsyncSessionLocal() as session:
-        result = await session.execute(select(SourceRoot))
-        if result.scalars().first() is not None:
-            return  # Already have at least one source root, leave it alone.
-
-        source_root = SourceRoot(
-            name=DEFAULT_LIBRARY_NAME,
-            path=DEFAULT_LIBRARY_PATH,
-        )
-        session.add(source_root)
-        await session.commit()
-        logger.info(
-            f"Bootstrapped default source root: {DEFAULT_LIBRARY_NAME} → "
-            f"{DEFAULT_LIBRARY_PATH}"
-        )
-
-
-async def start_initial_scan():
-    """Start the initial library scan.
-
-    NOTE: the folder watcher (watch_folders task) is intentionally NOT
-    dispatched here. It's an infinite loop celery task and every backend
-    restart was queuing a new instance, eventually pinning every worker
-    and starving scan_folder dispatches. Re-enabling it needs a Redis
-    lock or a dedicated long-running container — until then the user
-    triggers scans manually via "Scan all folders".
-    """
-    try:
-        scan_all_source_roots.delay()
-        logger.info("Initial scan queued successfully")
-    except Exception as e:
-        logger.error(f"Failed to start initial scan: {e}")

backend/app/tasks/__init__.py

@@ -1,15 +0,0 @@
-"""
-Celery tasks module
-"""
-from app.tasks.celery import celery_app
-from app.tasks.scan import scan_folder, scan_all_source_roots, watch_folders
-from app.tasks.thumbs import generate_thumbnails, regenerate_all_thumbnails
-
-__all__ = [
-    'celery_app',
-    'scan_folder',
-    'scan_all_source_roots',
-    'watch_folders',
-    'generate_thumbnails',
-    'regenerate_all_thumbnails'
-]

backend/app/tasks/celery.py

@@ -1,31 +0,0 @@
-"""
-Celery configuration and app initialization
-"""
-from celery import Celery
-from app.config import settings
-
-# Create Celery app
-celery_app = Celery(
-    'mulita',
-    broker=settings.celery_broker_url,
-    backend=settings.celery_result_backend,
-    include=['app.tasks.scan', 'app.tasks.thumbs']
-)
-
-# Configure Celery
-celery_app.conf.update(
-    task_serializer='json',
-    accept_content=['json'],
-    result_serializer='json',
-    timezone='UTC',
-    enable_utc=True,
-    task_routes={
-        'app.tasks.thumbs.*': {'queue': 'high'},
-        'app.tasks.scan.*': {'queue': 'low'},
-    },
-    task_default_queue='default',
-    task_default_exchange='default',
-    task_default_exchange_type='direct',
-    task_default_routing_key='default',
-    broker_connection_retry_on_startup=True,
-)

backend/app/tasks/scan.py

@@ -1,471 +0,0 @@
-"""
-Celery tasks for scanning folders and indexing photos
-"""
-import os
-import hashlib
-import asyncio
-from pathlib import Path
-from datetime import datetime
-import logging
-import json
-from typing import List, Dict, Optional
-
-from celery import shared_task
-from sqlalchemy import select, func
-from sqlalchemy.ext.asyncio import AsyncSession
-import aiofiles
-import redis
-
-from app.database import AsyncSessionLocal
-from app.models import Photo, Folder, SourceRoot
-from app.config import settings
-from app.tasks.thumbs import generate_thumbnails
-from app.services.metadata import extract_metadata
-
-logger = logging.getLogger(__name__)
-
-
-# Redis keys read by GET /api/v1/library/scan/status. The frontend
-# ScanProgress widget polls that endpoint, so anything we want to surface
-# in the UI lives here.
-REDIS_KEY_ACTIVE = 'scan:active'
-REDIS_KEY_CURRENT_FOLDER = 'scan:current_folder'
-REDIS_KEY_PROCESSED = 'scan:processed_files'
-REDIS_KEY_TOTAL = 'scan:total_files'
-REDIS_KEY_ERRORS = 'scan:errors'
-MAX_ERROR_ENTRIES = 50  # cap the errors list so a noisy scan doesn't blow Redis
-
-
-def _get_redis():
-    """Connect to the broker for progress writes. Returns None on failure
-    so a Redis outage doesn't prevent the scan itself from running."""
-    try:
-        return redis.Redis.from_url(settings.celery_broker_url)
-    except Exception as e:
-        logger.warning(f"Could not reach Redis for scan progress: {e}")
-        return None
-
-# Supported file extensions
-PHOTO_EXTENSIONS = {'.jpg', '.jpeg', '.png', '.tiff', '.tif', '.webp', '.bmp'}
-RAW_EXTENSIONS = {'.cr2', '.cr3', '.nef', '.arw', '.raf', '.dng', '.orf', '.rw2', '.pef', '.srw'}
-HEIC_EXTENSIONS = {'.heic', '.heif'}
-VIDEO_EXTENSIONS = {'.mp4', '.mov', '.avi', '.mkv', '.mts', '.m2ts', '.3gp', '.wmv', '.flv'}
-
-SUPPORTED_EXTENSIONS = PHOTO_EXTENSIONS | RAW_EXTENSIONS | HEIC_EXTENSIONS | VIDEO_EXTENSIONS
-
-def get_media_type(filepath: str) -> str:
-    """Determine media type from file extension"""
-    ext = Path(filepath).suffix.lower()
-    if ext in PHOTO_EXTENSIONS:
-        return 'photo'
-    elif ext in RAW_EXTENSIONS:
-        return 'raw'
-    elif ext in HEIC_EXTENSIONS:
-        return 'heic'
-    elif ext in VIDEO_EXTENSIONS:
-        return 'video'
-    return 'unknown'
-
-async def calculate_file_hash(filepath: str) -> str:
-    """Calculate SHA-256 hash of a file"""
-    hash_sha256 = hashlib.sha256()
-    try:
-        async with aiofiles.open(filepath, 'rb') as f:
-            while chunk := await f.read(8192):
-                hash_sha256.update(chunk)
-        return hash_sha256.hexdigest()
-    except Exception as e:
-        logger.error(f"Error calculating hash for {filepath}: {e}")
-        return ""
-
-@shared_task(bind=True, name='scan_folder')
-def scan_folder(self, folder_path: str, source_root_id: Optional[str] = None):
-    """
-    Scan a folder and index all photos/videos
-    """
-    # Run async function in sync context
-    return asyncio.run(_scan_folder_async(folder_path, source_root_id, self))
-
-async def _scan_folder_async(folder_path: str, source_root_id: Optional[str], task):
-    """Async implementation of folder scanning. Writes progress to Redis so
-    GET /api/v1/library/scan/status can surface it to the frontend
-    ScanProgress widget."""
-    logger.info(f"Starting scan of folder: {folder_path}")
-
-    r = _get_redis()
-
-    def progress_set(key: str, value) -> None:
-        if r is None:
-            return
-        try:
-            r.set(key, str(value))
-        except Exception as e:
-            logger.debug(f"scan progress set failed: {e}")
-
-    def progress_push_error(message: str) -> None:
-        if r is None:
-            return
-        try:
-            r.lpush(REDIS_KEY_ERRORS, message)
-            r.ltrim(REDIS_KEY_ERRORS, 0, MAX_ERROR_ENTRIES - 1)
-        except Exception as e:
-            logger.debug(f"scan progress push_error failed: {e}")
-
-    # Mark scan active immediately so the UI starts polling fast.
-    progress_set(REDIS_KEY_ACTIVE, 'true')
-    progress_set(REDIS_KEY_CURRENT_FOLDER, folder_path)
-
-    async with AsyncSessionLocal() as session:
-        try:
-            # Get or create source root
-            if not source_root_id:
-                source_root = await get_or_create_source_root(session, folder_path)
-                source_root_id = source_root.id
-
-            # Pre-walk to compute the total file count upfront. Without this
-            # the progress bar would jump every time a new subfolder is
-            # encountered because the running total kept growing.
-            total_files = 0
-            for _root, _dirs, files in os.walk(folder_path):
-                total_files += sum(
-                    1 for f in files if Path(f).suffix.lower() in SUPPORTED_EXTENSIONS
-                )
-            progress_set(REDIS_KEY_TOTAL, total_files)
-            progress_set(REDIS_KEY_PROCESSED, 0)
-
-            processed_files = 0
-            errors = []
-
-            for root, dirs, files in os.walk(folder_path):
-                # Get or create folder entry
-                folder = await get_or_create_folder(session, root, source_root_id)
-                progress_set(REDIS_KEY_CURRENT_FOLDER, root)
-
-                # Filter supported files
-                supported_files = [f for f in files if Path(f).suffix.lower() in SUPPORTED_EXTENSIONS]
-
-                # Process files in batches
-                batch_size = settings.scanner.batch_size
-                for i in range(0, len(supported_files), batch_size):
-                    batch = supported_files[i:i + batch_size]
-                    # Defer task dispatch until AFTER commit so workers don't
-                    # query for rows that aren't visible to other sessions yet.
-                    pending_dispatch: list[str] = []
-
-                    for filename in batch:
-                        filepath = os.path.join(root, filename)
-
-                        try:
-                            # Check if file already exists in database
-                            existing = await session.execute(
-                                select(Photo).where(Photo.filepath == filepath)
-                            )
-                            if existing.scalar_one_or_none():
-                                logger.debug(f"File already indexed: {filepath}")
-                                processed_files += 1
-                                progress_set(REDIS_KEY_PROCESSED, processed_files)
-                                continue
-
-                            # Get file stats
-                            stat = os.stat(filepath)
-
-                            # Calculate file hash for duplicate detection
-                            file_hash = await calculate_file_hash(filepath)
-
-                            # Check for duplicate by hash. We only care
-                            # whether *any* other photo shares this hash, so
-                            # use a count rather than scalar_one_or_none()
-                            # which raises "Multiple rows were found" the
-                            # moment the library has 2+ copies of the same
-                            # file (i.e. exactly the case we're trying to
-                            # flag).
-                            is_dup = False
-                            if file_hash:
-                                dup_count = (await session.execute(
-                                    select(func.count(Photo.id)).where(
-                                        Photo.file_hash == file_hash
-                                    )
-                                )).scalar() or 0
-                                is_dup = dup_count > 0
-
-                            # Create photo entry
-                            photo = Photo(
-                                filepath=filepath,
-                                filename=filename,
-                                folder_id=folder.id,
-                                file_hash=file_hash,
-                                media_type=get_media_type(filepath),
-                                original_format=Path(filepath).suffix.upper()[1:],
-                                file_size=stat.st_size,
-                                taken_at=datetime.fromtimestamp(stat.st_mtime),
-                                taken_at_source='filesystem',
-                                is_duplicate=is_dup,
-                                processing_status='pending'
-                            )
-
-                            session.add(photo)
-                            await session.flush()  # Assign defaults / FK ids
-
-                            # Queue dispatch happens after the batch commit
-                            # below; otherwise the worker can race the writer
-                            # and see "Photo not found".
-                            pending_dispatch.append(photo.id)
-
-                            processed_files += 1
-                            progress_set(REDIS_KEY_PROCESSED, processed_files)
-
-                            # Celery internal progress (used by celery tooling)
-                            if processed_files % 10 == 0:
-                                task.update_state(
-                                    state='PROGRESS',
-                                    meta={
-                                        'current': processed_files,
-                                        'total': total_files,
-                                        'folder': root,
-                                    }
-                                )
-
-                        except Exception as e:
-                            logger.error(f"Error processing file {filepath}: {e}")
-                            errors.append({'file': filepath, 'error': str(e)})
-                            progress_push_error(f"{filepath}: {e}")
-                            continue
-
-                    # Commit batch, then queue worker tasks. Dispatch order
-                    # matters: commit first so workers can find the rows.
-                    await session.commit()
-
-                    for photo_id in pending_dispatch:
-                        generate_thumbnails.delay(photo_id)
-                        extract_metadata.delay(photo_id)
-
-            # Update folder scan timestamp
-            folder.last_scanned = datetime.utcnow()
-            folder.photo_count = processed_files
-            await session.commit()
-
-            logger.info(f"Scan complete. Processed {processed_files}/{total_files} files. Errors: {len(errors)}")
-
-            return {
-                'status': 'completed',
-                'processed': processed_files,
-                'total': total_files,
-                'errors': errors,
-            }
-
-        except Exception as e:
-            logger.error(f"Scan failed: {e}")
-            progress_push_error(f"scan failed: {e}")
-            await session.rollback()
-            raise
-        finally:
-            # Always mark inactive on the way out so a crashed scan doesn't
-            # leave the UI thinking we're still scanning.
-            progress_set(REDIS_KEY_ACTIVE, 'false')
-
-def _normalize_path(path: str) -> str:
-    """Canonicalise a filesystem path so we don't get duplicate DB rows for
-    the same physical directory due to trailing slashes, redundant separators,
-    or `.` segments. Symlinks are NOT resolved (we want to keep mount paths
-    intact for cross-machine portability)."""
-    return os.path.normpath(path)
-
-
-async def get_or_create_source_root(session: AsyncSession, path: str) -> SourceRoot:
-    """Get or create a source root entry, matching by normalized path."""
-    from sqlalchemy import select
-
-    norm = _normalize_path(path)
-    result = await session.execute(
-        select(SourceRoot).where(SourceRoot.path == norm)
-    )
-    source_root = result.scalar_one_or_none()
-
-    if not source_root:
-        source_root = SourceRoot(
-            name=Path(norm).name,
-            path=norm,
-        )
-        session.add(source_root)
-        await session.flush()
-
-    return source_root
-
-
-async def get_or_create_folder(session: AsyncSession, path: str, source_root_id: str) -> Folder:
-    """Get or create a folder entry, matching by normalized path."""
-    from sqlalchemy import select
-
-    norm = _normalize_path(path)
-    result = await session.execute(
-        select(Folder).where(Folder.path == norm)
-    )
-    folder = result.scalar_one_or_none()
-
-    if not folder:
-        parent_path = _normalize_path(str(Path(norm).parent))
-
-        if parent_path != norm:  # Not the filesystem root
-            parent_result = await session.execute(
-                select(Folder).where(Folder.path == parent_path)
-            )
-            parent = parent_result.scalar_one_or_none()
-            if parent:
-                parent_id = parent.id
-            else:
-                # Recursively create parent
-                parent = await get_or_create_folder(session, parent_path, source_root_id)
-                parent_id = parent.id
-        else:
-            parent_id = None
-
-        folder = Folder(
-            name=Path(norm).name,
-            path=norm,
-            parent_id=parent_id,
-            source_root_id=source_root_id,
-        )
-        session.add(folder)
-        await session.flush()
-
-    return folder
-
-@shared_task(name='scan_all_source_roots')
-def scan_all_source_roots():
-    """Scan every active source root currently registered in the DB."""
-    # Clear stale per-scan progress before queuing new work so the UI sees
-    # a clean slate even if a previous run crashed mid-flight.
-    r = _get_redis()
-    if r is not None:
-        try:
-            r.delete(REDIS_KEY_ERRORS)
-            r.set(REDIS_KEY_PROCESSED, 0)
-            r.set(REDIS_KEY_TOTAL, 0)
-        except Exception as e:
-            logger.debug(f"scan_all_source_roots redis reset failed: {e}")
-
-    return asyncio.run(_scan_all_source_roots_async())
-
-
-async def _scan_all_source_roots_async():
-    """Read every active SourceRoot from the DB and queue a scan_folder task
-    for each. Source roots whose path no longer exists on disk are skipped
-    with a warning (the cleanup service surfaces those at startup too).
-
-    After dispatching the scans, queue a delayed `regroup_duplicates`
-    pass so duplicate clusters are recomputed once the new photos have
-    finished thumbnailing (and therefore picked up phashes). The
-    countdown is a best-effort hint — on a big library the user can
-    still hit Settings → Re-detect duplicates to force a fresh pass.
-    """
-    from app.tasks.thumbs import regroup_duplicates_task
-
-    async with AsyncSessionLocal() as session:
-        result = await session.execute(
-            select(SourceRoot).where(SourceRoot.is_active == True)  # noqa: E712
-        )
-        source_roots = result.scalars().all()
-        dispatched = 0
-        for sr in source_roots:
-            if os.path.exists(sr.path):
-                scan_folder.delay(sr.path, sr.id)
-                dispatched += 1
-            else:
-                logger.warning(f"Source root path does not exist: {sr.path}")
-
-    if dispatched > 0:
-        # 60s gives the thumbs worker a window to compute phashes for
-        # the new photos before regrouping. The task is idempotent, so
-        # firing too early just means the next manual run picks up the
-        # late arrivals — no corrupted state.
-        try:
-            regroup_duplicates_task.apply_async(countdown=60)
-        except Exception as e:
-            logger.warning(f"Could not queue post-scan regroup: {e}")
-
-
-@shared_task(name='watch_folders')
-def watch_folders():
-    """
-    Watch folders for changes using watchfiles. Long-running task that
-    monitors filesystem events under every active source root.
-    """
-    from watchfiles import watch
-
-    # Read source roots from the DB instead of the (now-removed) YAML
-    # config. We need both the path and the id so we can dispatch
-    # scan_folder with the source_root_id when an event fires.
-    roots: list[tuple[str, str]] = []
-    try:
-        async def _load_roots():
-            async with AsyncSessionLocal() as session:
-                result = await session.execute(
-                    select(SourceRoot).where(SourceRoot.is_active == True)  # noqa: E712
-                )
-                return [
-                    (os.path.normpath(sr.path), sr.id)
-                    for sr in result.scalars().all()
-                    if os.path.exists(sr.path)
-                ]
-        roots = asyncio.run(_load_roots())
-    except Exception as e:
-        logger.error(f"watch_folders could not load source roots: {e}")
-        return
-
-    if not roots:
-        logger.warning("No valid source roots to watch")
-        return
-
-    paths = [p for p, _ in roots]
-    logger.info(f"Starting folder watcher for: {paths}")
-
-    def find_source_root_for(path: str) -> Optional[str]:
-        """Return the source_root id whose path contains `path`, or None."""
-        normalized = os.path.normpath(path)
-        for root_path, root_id in roots:
-            if normalized == root_path or normalized.startswith(root_path + os.sep):
-                return root_id
-        return None
-
-    for changes in watch(*paths):
-        for change_type, filepath in changes:
-            filepath = str(filepath)
-
-            # Check if it's a supported file type
-            if Path(filepath).suffix.lower() not in SUPPORTED_EXTENSIONS:
-                continue
-
-            if change_type == 'added' or change_type == 'modified':
-                # Queue scan for the parent folder, with the source_root_id
-                # resolved by ancestor lookup so scan_folder doesn't
-                # auto-create a new SourceRoot for an arbitrary subdir.
-                parent_dir = str(Path(filepath).parent)
-                source_root_id = find_source_root_for(parent_dir)
-                if source_root_id is None:
-                    logger.debug(
-                        f"watcher event for {filepath}: parent {parent_dir} "
-                        f"not under any active source root, ignoring"
-                    )
-                    continue
-                scan_folder.delay(parent_dir, source_root_id)
-                logger.info(f"File {change_type}: {filepath}, queued scan for {parent_dir}")
-            elif change_type == 'deleted':
-                # Handle file deletion
-                asyncio.run(handle_file_deletion(filepath))
-
-async def handle_file_deletion(filepath: str):
-    """Handle deletion of a file from the filesystem"""
-    from sqlalchemy import select
-    
-    async with AsyncSessionLocal() as session:
-        result = await session.execute(
-            select(Photo).where(Photo.filepath == filepath)
-        )
-        photo = result.scalar_one_or_none()
-        
-        if photo:
-            # Mark as missing or delete from database
-            photo.is_discarded = True
-            photo.discarded_at = datetime.utcnow()
-            await session.commit()
-            logger.info(f"Marked photo as discarded: {filepath}")

backend/app/tasks/thumbs.py

@@ -1,427 +0,0 @@
-"""
-Celery tasks for thumbnail generation
-"""
-import os
-import asyncio
-from pathlib import Path
-import logging
-from typing import Tuple, Optional
-import json
-
-from celery import shared_task
-from sqlalchemy import select
-from sqlalchemy.ext.asyncio import AsyncSession
-from PIL import Image
-import imageio
-from pillow_heif import register_heif_opener
-import ffmpeg
-
-# Try to import optional libraries
-try:
-    import pyvips
-    PYVIPS_AVAILABLE = True
-except ImportError:
-    PYVIPS_AVAILABLE = False
-    print("pyvips not available, using Pillow for image processing")
-
-try:
-    import rawpy
-    RAWPY_AVAILABLE = True
-except ImportError:
-    RAWPY_AVAILABLE = False
-    print("rawpy not available, using exiftool for RAW preview extraction")
-
-from app.database import AsyncSessionLocal
-from app.models import Photo
-from app.config import settings
-
-# Register HEIF opener with Pillow
-register_heif_opener()
-
-logger = logging.getLogger(__name__)
-
-# Thumbnail sizes configuration
-THUMB_SIZES = {
-    'small': settings.thumbnails.small,
-    'medium': settings.thumbnails.medium,
-    'large': settings.thumbnails.large
-}
-
-def get_thumb_path(photo_id: str, size: str) -> str:
-    """Get the path for a thumbnail file"""
-    thumb_dir = f"/data/thumbs/{photo_id}"
-    os.makedirs(thumb_dir, exist_ok=True)
-    return f"{thumb_dir}/{size}.{settings.thumbnails.format}"
-
-def process_standard_image(filepath: str) -> Image.Image:
-    """Process standard image formats (JPEG, PNG, etc.)"""
-    return Image.open(filepath)
-
-def process_raw_image(filepath: str) -> Image.Image:
-    """Process RAW image formats"""
-    if RAWPY_AVAILABLE:
-        try:
-            with rawpy.imread(filepath) as raw:
-                # Use half_size for faster processing
-                rgb = raw.postprocess(use_camera_wb=True, half_size=True)
-                # Convert numpy array to PIL Image
-                return Image.fromarray(rgb, 'RGB')
-        except Exception as e:
-            logger.error(f"Error processing RAW file {filepath}: {e}")
-            # Try to extract embedded JPEG preview
-            return extract_raw_preview(filepath)
-    else:
-        # Use exiftool to extract embedded preview
-        return extract_raw_preview(filepath)
-
-def extract_raw_preview(filepath: str) -> Optional[Image.Image]:
-    """Extract embedded JPEG preview from RAW file"""
-    try:
-        # Use exiftool to extract preview
-        import subprocess
-        import tempfile
-        
-        with tempfile.NamedTemporaryFile(suffix='.jpg', delete=False) as tmp:
-            cmd = ['exiftool', '-b', '-PreviewImage', filepath]
-            result = subprocess.run(cmd, capture_output=True)
-            
-            if result.returncode == 0 and result.stdout:
-                tmp.write(result.stdout)
-                tmp.flush()
-                return Image.open(tmp.name)
-    except Exception as e:
-        logger.error(f"Error extracting RAW preview from {filepath}: {e}")
-    
-    return None
-
-def process_heic_image(filepath: str) -> Image.Image:
-    """Process HEIC/HEIF image formats"""
-    try:
-        # Use pillow-heif to open the image
-        img = Image.open(filepath)
-        # Convert to RGB if needed
-        if img.mode != 'RGB':
-            img = img.convert('RGB')
-        return img
-    except Exception as e:
-        logger.error(f"Error processing HEIC file {filepath}: {e}")
-        raise
-
-def process_video_thumbnail(filepath: str) -> Image.Image:
-    """Extract a still frame from a video file as a PIL Image."""
-    import tempfile
-    from io import BytesIO
-
-    tmp_path: Optional[str] = None
-    try:
-        # Find a usable seek timestamp. Some camera MOVs only expose
-        # duration at the format level, and stream 0 isn't always the
-        # video stream — search explicitly and fall back to the format
-        # duration, then to t=0 if neither is available.
-        probe = ffmpeg.probe(filepath)
-        duration: Optional[float] = None
-        for stream_info in probe.get('streams', []):
-            if stream_info.get('codec_type') != 'video':
-                continue
-            raw_duration = stream_info.get('duration')
-            if raw_duration is not None:
-                try:
-                    duration = float(raw_duration)
-                    break
-                except (TypeError, ValueError):
-                    pass
-        if duration is None:
-            raw_duration = probe.get('format', {}).get('duration')
-            if raw_duration is not None:
-                try:
-                    duration = float(raw_duration)
-                except (TypeError, ValueError):
-                    duration = None
-
-        # Seek to 10% in for a representative frame; clamp very short
-        # clips to t=0 so we don't seek past the end.
-        timestamp = max(0.0, (duration or 0.0) * 0.1)
-
-        # NamedTemporaryFile creates the file on disk, so we MUST tell
-        # ffmpeg to overwrite it (otherwise it prompts on stdin and the
-        # call hangs/fails — which is why videos were getting the gray
-        # placeholder). We close the handle immediately and clean up
-        # in `finally` ourselves.
-        with tempfile.NamedTemporaryFile(suffix='.jpg', delete=False) as tmp:
-            tmp_path = tmp.name
-
-        stream = ffmpeg.input(filepath, ss=timestamp)
-        stream = ffmpeg.output(
-            stream,
-            tmp_path,
-            vframes=1,
-            format='image2',
-            vcodec='mjpeg',
-        )
-        ffmpeg.run(
-            stream,
-            capture_stdout=True,
-            capture_stderr=True,
-            overwrite_output=True,
-        )
-
-        # Load the frame fully into memory so we can delete the temp
-        # file immediately. Pillow's `Image.open` is lazy, which would
-        # otherwise leave the file dangling.
-        with open(tmp_path, 'rb') as fh:
-            data = fh.read()
-        if not data:
-            raise RuntimeError("ffmpeg produced an empty frame")
-        return Image.open(BytesIO(data)).copy()
-    except ffmpeg.Error as e:
-        stderr = (e.stderr or b'').decode('utf-8', errors='replace')
-        logger.error(
-            f"ffmpeg failed extracting video thumbnail from {filepath}: {stderr}"
-        )
-        return create_placeholder_thumbnail('video')
-    except Exception as e:
-        logger.error(f"Error extracting video thumbnail from {filepath}: {e}")
-        return create_placeholder_thumbnail('video')
-    finally:
-        if tmp_path and os.path.exists(tmp_path):
-            try:
-                os.unlink(tmp_path)
-            except OSError:
-                pass
-
-def create_placeholder_thumbnail(media_type: str) -> Image.Image:
-    """Create a placeholder thumbnail for failed processing"""
-    # Create a simple gray placeholder
-    img = Image.new('RGB', (640, 480), color=(128, 128, 128))
-    return img
-
-def auto_rotate_image(image: Image.Image) -> Image.Image:
-    """Auto-rotate image based on EXIF orientation"""
-    try:
-        # Get EXIF data
-        exif = image._getexif()
-        if exif:
-            orientation = exif.get(274)  # Orientation tag
-            
-            rotation_map = {
-                3: 180,
-                6: 270,  # Note: PIL uses different rotation values than vips
-                8: 90
-            }
-            
-            if orientation in rotation_map:
-                image = image.rotate(rotation_map[orientation], expand=True)
-    except:
-        pass  # No orientation data available
-    
-    return image
-
-def generate_thumbnail(image: Image.Image, size: int, output_path: str):
-    """Generate a thumbnail of the specified size"""
-    # Maintain aspect ratio
-    image.thumbnail((size, size), Image.Resampling.LANCZOS)
-    
-    # Save as WebP with specified quality
-    image.save(
-        output_path,
-        'WEBP',
-        quality=settings.thumbnails.quality,
-        method=4  # Balance between speed and compression
-    )
-
-@shared_task(bind=True, name='generate_thumbnails')
-def generate_thumbnails(self, photo_id: str):
-    """Generate thumbnails for a photo"""
-    return asyncio.run(_generate_thumbnails_async(photo_id, self))
-
-async def _generate_thumbnails_async(photo_id: str, task):
-    """Async implementation of thumbnail generation"""
-    async with AsyncSessionLocal() as session:
-        try:
-            # Get photo from database
-            result = await session.execute(
-                select(Photo).where(Photo.id == photo_id)
-            )
-            photo = result.scalar_one_or_none()
-            
-            if not photo:
-                logger.error(f"Photo not found: {photo_id}")
-                return {'status': 'error', 'message': 'Photo not found'}
-            
-            # Check if file exists
-            if not os.path.exists(photo.filepath):
-                logger.error(f"File not found: {photo.filepath}")
-                photo.processing_status = 'failed'
-                photo.processing_error = 'File not found'
-                await session.commit()
-                return {'status': 'error', 'message': 'File not found'}
-            
-            # Update processing status
-            photo.processing_status = 'processing'
-            await session.commit()
-            
-            # Load and process the image based on type
-            image = None
-            
-            if photo.media_type == 'photo':
-                image = process_standard_image(photo.filepath)
-            elif photo.media_type == 'raw':
-                image = process_raw_image(photo.filepath)
-            elif photo.media_type == 'heic':
-                image = process_heic_image(photo.filepath)
-            elif photo.media_type == 'video':
-                image = process_video_thumbnail(photo.filepath)
-            else:
-                logger.error(f"Unsupported media type: {photo.media_type}")
-                image = create_placeholder_thumbnail(photo.media_type)
-            
-            if not image:
-                raise Exception("Failed to process image")
-            
-            # Auto-rotate based on EXIF
-            image = auto_rotate_image(image)
-
-            # Store original dimensions
-            photo.width = image.width
-            photo.height = image.height
-
-            # Perceptual hash from the original-resolution decoded frame.
-            # pHash is robust to resize/recompression but the thumbnail
-            # loop below mutates `image` in place, so this MUST run before
-            # the loop sees it. Failures are non-fatal — phash is a
-            # nice-to-have, not a blocker for thumbnail generation.
-            try:
-                import imagehash
-                photo.phash = str(imagehash.phash(image))  # 16-char hex
-            except Exception as e:
-                logger.warning(f"phash failed for {photo_id}: {e}")
-                photo.phash = None
-
-            # Generate thumbnails for each size
-            for size_name, size_value in THUMB_SIZES.items():
-                thumb_path = get_thumb_path(photo_id, size_name)
-                generate_thumbnail(image, size_value, thumb_path)
-                
-                # Update database with thumbnail path
-                setattr(photo, f'thumb_{size_name}', thumb_path)
-                
-                # Update progress
-                task.update_state(
-                    state='PROGRESS',
-                    meta={'current_size': size_name, 'photo_id': photo_id}
-                )
-            
-            # Update processing status
-            photo.processing_status = 'completed'
-            photo.processing_error = None
-            await session.commit()
-            
-            logger.info(f"Thumbnails generated for photo {photo_id}")
-            return {'status': 'success', 'photo_id': photo_id}
-            
-        except Exception as e:
-            logger.error(f"Error generating thumbnails for {photo_id}: {e}")
-            
-            # Update error status
-            if photo:
-                photo.processing_status = 'failed'
-                photo.processing_error = str(e)
-                await session.commit()
-            
-            return {'status': 'error', 'message': str(e)}
-
-@shared_task(name='regenerate_all_thumbnails')
-def regenerate_all_thumbnails():
-    """Regenerate thumbnails for all photos"""
-    return asyncio.run(_regenerate_all_thumbnails_async())
-
-async def _regenerate_all_thumbnails_async():
-    """Async implementation of regenerating all thumbnails"""
-    async with AsyncSessionLocal() as session:
-        # Get all photos that need thumbnails
-        result = await session.execute(
-            select(Photo).where(
-                Photo.processing_status.in_(['pending', 'failed'])
-            )
-        )
-        photos = result.scalars().all()
-
-        logger.info(f"Regenerating thumbnails for {len(photos)} photos")
-
-        for photo in photos:
-            generate_thumbnails.delay(photo.id)
-
-        return {'status': 'queued', 'count': len(photos)}
-
-
-# ── Perceptual hash backfill ────────────────────────────────────────────
-#
-# When phash was added post-launch, every existing photo has phash=NULL.
-# This task fills them in by reading the existing thumb_large (the cheap
-# option — pHash is robust to scale, and the thumb is already on local
-# disk so we avoid re-decoding the original RAW/HEIC). Falls back to the
-# original filepath if the thumb isn't available for some reason. Runs
-# in batches to keep memory bounded and to give the user incremental
-# progress visible in the worker logs.
-
-@shared_task(name='backfill_phashes')
-def backfill_phashes():
-    """Compute and persist phash for every photo currently missing one."""
-    return asyncio.run(_backfill_phashes_async())
-
-
-async def _backfill_phashes_async():
-    import imagehash
-    from PIL import Image as _PILImage
-
-    BATCH = 100
-    total_done = 0
-    total_failed = 0
-
-    async with AsyncSessionLocal() as session:
-        while True:
-            result = await session.execute(
-                select(Photo)
-                .where(Photo.phash.is_(None))
-                .where(Photo.processing_status == 'completed')
-                .limit(BATCH)
-            )
-            batch = result.scalars().all()
-            if not batch:
-                break
-
-            for photo in batch:
-                source = photo.thumb_large or photo.filepath
-                try:
-                    if not source or not os.path.exists(source):
-                        photo.phash = None
-                        total_failed += 1
-                        continue
-                    with _PILImage.open(source) as im:
-                        photo.phash = str(imagehash.phash(im))
-                    total_done += 1
-                except Exception as e:
-                    logger.warning(f"phash backfill failed for {photo.id}: {e}")
-                    total_failed += 1
-
-            await session.commit()
-            logger.info(
-                f"Backfilled phashes: {total_done} done, {total_failed} failed"
-            )
-
-    return {
-        'status': 'success',
-        'computed': total_done,
-        'failed': total_failed,
-    }
-
-
-@shared_task(name='regroup_duplicates')
-def regroup_duplicates_task():
-    """Celery wrapper around app.services.duplicates.regroup_duplicates.
-
-    Importing the service inside the task body avoids a circular import
-    at worker boot (the service uses AsyncSessionLocal which is also
-    imported here at module top)."""
-    from app.services.duplicates import regroup_duplicates
-    return asyncio.run(regroup_duplicates())

backend/requirements.txt

@@ -1,50 +0,0 @@
-# Core dependencies
-fastapi==0.109.0
-uvicorn[standard]==0.27.0
-python-multipart==0.0.6
-
-# Database
-sqlalchemy[asyncio]==2.0.25
-aiosqlite==0.19.0
-alembic==1.13.1
-
-# Redis and Celery
-redis==5.0.1
-celery==5.3.6
-flower==2.0.1
-
-# Image processing
-# pyvips==2.2.1  # Optional - having compatibility issues, using Pillow as fallback
-# rawpy==0.19.0  # Optional - numpy compatibility issues, using Pillow as fallback
-pillow==10.2.0
-pillow-heif==0.15.0
-imagehash==4.3.1  # perceptual hash for duplicate detection
-imageio==2.33.1
-imageio-ffmpeg==0.4.9
-
-# Video processing
-ffmpeg-python==0.2.0
-
-# Metadata extraction
-pyexiftool==0.5.6
-
-# File watching
-watchfiles==0.21.0
-
-# Utilities
-pyyaml==6.0.1
-pydantic==2.5.3
-pydantic-settings==2.1.0
-python-dotenv==1.0.0
-httpx==0.26.0
-aiofiles==23.2.1
-
-# Security and authentication
-python-jose[cryptography]==3.3.0
-passlib[bcrypt]==1.7.4
-
-# Development
-pytest==7.4.4
-pytest-asyncio==0.23.3
-black==23.12.1
-ruff==0.1.11

docker-compose.gpu.yml

@@ -0,0 +1,24 @@
+# Overlay for hosts with a VA-API-capable GPU passed through (Intel
+# QSV, AMD VCN/VCE, any VA-API driver). PhotoPrism's :latest image
+# ships VA-API-enabled ffmpeg; this file just wires the device + group
+# membership + encoder selection. Layered in by the deploy script on
+# hosts where /dev/dri/renderD128 exists.
+#
+# Usage:
+#   docker compose -f docker-compose.yml -f docker-compose.gpu.yml up -d
+
+services:
+  photoprism:
+    devices:
+      - /dev/dri/renderD128:/dev/dri/renderD128
+      - /dev/dri/card0:/dev/dri/card0
+    # Match host GIDs (render=992, video=44 on Debian). PhotoPrism's
+    # container user (PP_UID:PP_GID, typically 33:10000) is not in
+    # these groups by default; group_add grants access to the device
+    # nodes without changing the primary user.
+    group_add:
+      - "992"
+      - "44"
+    environment:
+      PHOTOPRISM_FFMPEG_ENCODER: ${PP_FFMPEG_ENCODER:-vaapi}
+      PHOTOPRISM_FFMPEG_BITRATE: ${PP_FFMPEG_BITRATE:-32}

docker-compose.podman.yml

@@ -0,0 +1,34 @@
+# Podman-rootless overlay for the PhotoPrism stack.
+#
+# Apply alongside the base compose file:
+#   podman-compose --env-file .env \
+#     -f docker-compose.yml \
+#     -f docker-compose.podman.yml \
+#     up -d
+#
+# Adds the podman-specific bits that would break a vanilla docker compose run:
+#   - userns_mode: keep-id maps container UID to the invoking host UID, so
+#     PhotoPrism (running as PP_UID:PP_GID inside) can actually read the
+#     bind-mounted originals volume on the host (which is owned by the host
+#     user, not by uid 1000-in-the-container-namespace).
+#   - the explicit security_opt entries on the base file work in podman as-is.
+
+services:
+  # MariaDB writes to a named volume managed by podman; its in-container
+  # `mysql` user expects to own that volume. keep-id breaks this by mapping
+  # in-container UID 999 to a podman-subuid that doesn't own the volume,
+  # so let mariadb use the default userns mapping (root-in-namespace).
+  mariadb:
+    # No userns_mode override — use podman defaults.
+    init: true
+
+  # PhotoPrism does need keep-id, so its container UID maps back to the
+  # host UID that owns the bind-mounted originals/.
+  photoprism:
+    userns_mode: keep-id
+
+  # Sidecar mutates the originals tree (rename / folder ops / heap
+  # convert / .duplicates archive) — same keep-id mapping so its writes
+  # land as the host user, not as a podman-subuid the host doesn't own.
+  sidecar:
+    userns_mode: keep-id

docker-compose.yml

@@ -1,105 +1,209 @@
-version: '3.8'
+# Compose stack for the PhotoPrism-backed photo app: mariadb + photoprism +
+# Go sidecar. The SvelteKit web/ frontend runs separately (Vite in dev,
+# static build in prod) and proxies /api/v1/* to photoprism and
+# /api/sidecar/* to the sidecar.
+#
+#   podman-compose --env-file .env \
+#     -f docker-compose.yml -f docker-compose.podman.yml up -d
 
 services:
-  frontend:
-    build:
-      context: ./frontend
-      dockerfile: Dockerfile
-    container_name: mulita-frontend
-    ports:
-      # Host port is configurable via FRONTEND_PORT in .env so multiple
-      # instances / other services on the same host don't collide.
-      - "${FRONTEND_PORT:-3000}:80"
-    depends_on:
-      - backend
-    networks:
-      - mulita-network
+  mariadb:
+    # Fully-qualified for podman (which refuses short names by default).
+    # Docker resolves the same digest.
+    image: docker.io/library/mariadb:11
+    container_name: pp-mariadb
     restart: unless-stopped
-
-  backend:
-    build:
-      context: ./backend
-      dockerfile: Dockerfile
-    container_name: mulita-backend
-    ports:
-      # Direct backend access on the host is rarely needed (the frontend
-      # talks to it through the nginx /api proxy on the same network),
-      # but it's exposed for debugging / curl. Override with BACKEND_PORT.
-      - "${BACKEND_PORT:-8001}:8000"
-    volumes:
-      - ./mulita.yml:/app/config/mulita.yml:ro
-      # The single host → container mount for your photo library. Set
-      # PHOTO_DIRS in .env to your library root. Mounted :rw because file
-      # operations (rename, move, empty discard pile) need to mutate the
-      # filesystem; flip to :ro for a strict read-only library and the
-      # write endpoints will return EROFS.
-      - ${PHOTO_DIRS:-./photos}:/photos:rw
-      - thumbs_data:/data/thumbs
-      - proxies_data:/data/proxies
-      - db_data:/data/db
+    command:
+      - --innodb-buffer-pool-size=512M
+      - --transaction-isolation=READ-COMMITTED
+      - --character-set-server=utf8mb4
+      - --collation-server=utf8mb4_unicode_ci
+      - --max-connections=512
+      - --innodb-rollback-on-timeout=OFF
+      - --innodb-lock-wait-timeout=120
     environment:
-      - DATABASE_URL=sqlite+aiosqlite:////data/db/mulita.db
-      - REDIS_URL=redis://redis:6379
-      - CELERY_BROKER_URL=redis://redis:6379
-      - CELERY_RESULT_BACKEND=redis://redis:6379
-      - PHOTO_DIRS=${PHOTO_DIRS:-/photos}
-      - ALLOWED_ORIGINS=${ALLOWED_ORIGINS:-*}
-      - LOG_LEVEL=${LOG_LEVEL:-INFO}
-      - TZ=${TZ:-UTC}
-    depends_on:
-      - redis
-    networks:
-      - mulita-network
-    restart: unless-stopped
-
-  worker:
-    build:
-      context: ./backend
-      dockerfile: Dockerfile
-    container_name: mulita-worker
-    command: celery -A app.tasks.celery worker --loglevel=${LOG_LEVEL:-info} --concurrency=${CELERYD_CONCURRENCY:-4}
-    volumes:
-      - ./mulita.yml:/app/config/mulita.yml:ro
-      - ${PHOTO_DIRS:-./photos}:/photos:rw
-      - thumbs_data:/data/thumbs
-      - proxies_data:/data/proxies
-      - db_data:/data/db
-    environment:
-      - DATABASE_URL=sqlite+aiosqlite:////data/db/mulita.db
-      - REDIS_URL=redis://redis:6379
-      - CELERY_BROKER_URL=redis://redis:6379
-      - CELERY_RESULT_BACKEND=redis://redis:6379
-      - PHOTO_DIRS=${PHOTO_DIRS:-/photos}
-      - CELERYD_CONCURRENCY=${CELERYD_CONCURRENCY:-4}
-      - LOG_LEVEL=${LOG_LEVEL:-INFO}
-      - TZ=${TZ:-UTC}
-    depends_on:
-      - redis
-      - backend
-    networks:
-      - mulita-network
-    restart: unless-stopped
-
-  redis:
-    image: redis:7-alpine
-    container_name: mulita-redis
-    # Host port exposed only for local debugging; the backend / worker
-    # reach Redis via the internal mulita-network on its container name.
+      MARIADB_AUTO_UPGRADE: "1"
+      MARIADB_INITDB_SKIP_TZINFO: "1"
+      MARIADB_DATABASE: ${PP_DB_NAME:-photoprism}
+      MARIADB_USER: ${PP_DB_USER:-photoprism}
+      MARIADB_PASSWORD: ${PP_DB_PASSWORD:?set PP_DB_PASSWORD in .env}
+      MARIADB_ROOT_PASSWORD: ${PP_DB_ROOT_PASSWORD:?set PP_DB_ROOT_PASSWORD in .env}
+    # Loopback-only host port so the mule-sidecar (running as a host process
+    # in M4) can reach `mule_sidecar.*` over TCP. Not exposed beyond
+    # 127.0.0.1; the photoprism container still resolves mariadb by service
+    # name on the photoprism-network bridge.
     ports:
-      - "${REDIS_PORT:-6379}:6379"
+      - "127.0.0.1:${PP_DB_PORT:-3306}:3306"
     volumes:
-      - redis_data:/data
-    networks:
-      - mulita-network
+      - pp_mariadb_data:/var/lib/mysql
+      # The init script creates the mule_sidecar database + user that the Go
+      # sidecar service will use in M4. Idempotent; no-op on subsequent boots.
+      # ":Z" is the SELinux private-relabel flag — needed on Fedora/RHEL hosts,
+      # silently no-op on Debian/Ubuntu and macOS Docker Desktop.
+      - ./mariadb/init:/docker-entrypoint-initdb.d:ro,Z
+    healthcheck:
+      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
+      interval: 10s
+      timeout: 5s
+      retries: 12
+      start_period: 60s
+    networks: [photoprism-network]
+
+  photoprism:
+    image: docker.io/photoprism/photoprism:latest
+    container_name: pp-app
     restart: unless-stopped
-    command: redis-server --appendonly yes
+    depends_on:
+      mariadb:
+        condition: service_healthy
+    # PhotoPrism's container drops to a non-root user via PHOTOPRISM_UID /
+    # PHOTOPRISM_GID. Match the host user that owns ${PHOTO_DIRS} so the
+    # process can read originals (and later write sidecars).
+    user: "${PP_UID:-1000}:${PP_GID:-1000}"
+    security_opt:
+      - seccomp:unconfined
+      - apparmor:unconfined
+    ports:
+      # Loopback only — the SvelteKit web/ app (Vite dev or built bundle)
+      # is the user-facing surface; PhotoPrism's own UI stays off the
+      # public interface. Vite proxies /api/v1/* here, and the host-mode
+      # sidecar reaches PHOTOPRISM_BASE_URL=http://localhost:2342. Admin
+      # access to PP's UI is via SSH tunnel only.
+      - "127.0.0.1:${PP_PORT:-2342}:2342"
+    environment:
+      PHOTOPRISM_ADMIN_USER: ${PP_ADMIN_USER:-admin}
+      PHOTOPRISM_ADMIN_PASSWORD: ${PP_ADMIN_PASSWORD:?set PP_ADMIN_PASSWORD in .env}
+      PHOTOPRISM_AUTH_MODE: ${PP_AUTH_MODE:-password}
+      PHOTOPRISM_SITE_URL: ${PP_SITE_URL:-http://localhost:2342/}
+      PHOTOPRISM_ORIGINALS_LIMIT: ${PP_ORIGINALS_LIMIT:-50000}
+      PHOTOPRISM_HTTP_COMPRESSION: gzip
+      PHOTOPRISM_LOG_LEVEL: ${PP_LOG_LEVEL:-info}
+      # Indexer concurrency. Defaults to NumCPU/2 (= 3 on a 6-core LXC),
+      # but each worker forks TF + ffmpeg + libvips so effective load is
+      # much higher — a fresh index of 1.2k photos on M0 pushed the LXC
+      # load to 50+ and starved sibling containers. Pin to a low value
+      # for shared hosts; raise on dedicated machines.
+      PHOTOPRISM_WORKERS: ${PP_WORKERS:-2}
+      # podman-compose doesn't expand nested ${A:-${B:-…}}, so keep this
+      # one-level. Override both PP_WORKERS and PP_INDEX_WORKERS if you
+      # want them to differ.
+      PHOTOPRISM_INDEX_WORKERS: ${PP_INDEX_WORKERS:-2}
+      # M0 safety: keep originals read-only. Flip to "false" in M2 when the
+      # right-sidebar enables metadata edits and we want EXIF backwrite.
+      PHOTOPRISM_READONLY: ${PP_READONLY:-true}
+      PHOTOPRISM_EXPERIMENTAL: "false"
+      PHOTOPRISM_DISABLE_CHOWN: "true"
+      PHOTOPRISM_DISABLE_WEBDAV: ${PP_DISABLE_WEBDAV:-false}
+      PHOTOPRISM_DISABLE_SETTINGS: "false"
+      PHOTOPRISM_DISABLE_TLS: "true"
+      PHOTOPRISM_DEFAULT_TLS: "false"
+      # AI/vision pipeline back on — per plan we re-introduce TF labels + faces.
+      PHOTOPRISM_TENSORFLOW_OFF: "false"
+      PHOTOPRISM_DETECT_NSFW: "true"
+      PHOTOPRISM_UPLOAD_NSFW: "true"
+      # Database
+      PHOTOPRISM_DATABASE_DRIVER: mysql
+      PHOTOPRISM_DATABASE_SERVER: mariadb:3306
+      PHOTOPRISM_DATABASE_NAME: ${PP_DB_NAME:-photoprism}
+      PHOTOPRISM_DATABASE_USER: ${PP_DB_USER:-photoprism}
+      PHOTOPRISM_DATABASE_PASSWORD: ${PP_DB_PASSWORD}
+      # Sidecars next to originals — read by the migrator at M5.
+      PHOTOPRISM_SIDECAR_PATH: ""
+      PHOTOPRISM_SIDECAR_YAML: "true"
+      # EXIF backwrite — disabled in M0 (READONLY blocks writes anyway).
+      # Override in .env: PP_BACKUP_DATABASE=true.
+      PHOTOPRISM_DISABLE_BACKUPS: "false"
+      PHOTOPRISM_BACKUP_DATABASE: ${PP_BACKUP_DATABASE:-true}
+      PHOTOPRISM_DISABLE_EXIFTOOL: "false"
+      # OIDC — set in .env when the IdP (Authentik) is wired up.
+      # Empty values keep OIDC dormant; the username/password login still works.
+      # PhotoPrism's CLI flags are --oidc-uri / --oidc-client / --oidc-secret
+      # / --oidc-provider, so the env-var names it actually reads are
+      # PHOTOPRISM_OIDC_URI / _CLIENT / _SECRET / _PROVIDER (NOT _ISSUER_URL
+      # / _CLIENT_ID / _CLIENT_SECRET / _PROVIDER_NAME — those are silently
+      # ignored, OIDC stays dormant, and `photoprism show config` reports
+      # blank oidc-uri / oidc-client). PHOTOPRISM_OIDC_REDIRECT is a bool
+      # (auto-redirect-from-/library/login), not a URL — PhotoPrism builds
+      # the callback from PHOTOPRISM_SITE_URL.
+      PHOTOPRISM_OIDC_PROVIDER: ${OIDC_PROVIDER_NAME:-${OIDC_PROVIDER:-}}
+      PHOTOPRISM_OIDC_URI: ${OIDC_ISSUER_URL:-${OIDC_URI:-}}
+      PHOTOPRISM_OIDC_CLIENT: ${OIDC_CLIENT_ID:-${OIDC_CLIENT:-}}
+      PHOTOPRISM_OIDC_SECRET: ${OIDC_CLIENT_SECRET:-${OIDC_SECRET:-}}
+      PHOTOPRISM_OIDC_SCOPES: ${OIDC_SCOPES:-openid profile email}
+      PHOTOPRISM_OIDC_REGISTER: ${OIDC_REGISTER:-true}
+      PHOTOPRISM_OIDC_ROLE: ${OIDC_ROLE:-user}
+      PHOTOPRISM_OIDC_REDIRECT: ${OIDC_REDIRECT:-false}
+    working_dir: /photoprism
+    volumes:
+      # Existing photo library — mounted read-only in M0; flip to :rw in M2
+      # when the right-sidebar starts saving edits. ",Z" relabels for SELinux
+      # on Fedora/RHEL; silent no-op elsewhere.
+      - "${PHOTO_DIRS:?set PHOTO_DIRS in .env}:/photoprism/originals:${PP_ORIGINALS_MODE:-ro},Z"
+      - "./pp/storage:/photoprism/storage:Z"
+      - "./pp/import:/photoprism/import:Z"
+    networks: [photoprism-network]
+
+  # mule-sidecar — Go + Gin + GORM service for endpoints PhotoPrism's API
+  # does not expose (file rename, folder mutations, heap convert, duplicate
+  # scan, per-photo marks). Same wire contract as the M3 Node prototype;
+  # the SvelteKit dev server proxies /api/sidecar/* here.
+  sidecar:
+    build:
+      context: ./sidecar
+    container_name: pp-sidecar
+    restart: unless-stopped
+    depends_on:
+      mariadb:
+        condition: service_healthy
+      photoprism:
+        condition: service_started
+    # Match PhotoPrism's UID/GID so renames/folder mutations preserve the
+    # ownership the indexer expects on the bind-mounted originals.
+    user: "${PP_UID:-1000}:${PP_GID:-1000}"
+    ports:
+      # Loopback only — Vite (host) proxies /api/sidecar/* to this port.
+      # Behind a reverse proxy in production; never published beyond the
+      # host.
+      - "127.0.0.1:${SIDECAR_PORT:-8000}:8000"
+    environment:
+      ORIGINALS_ROOT: /photoprism/originals
+      PHOTOPRISM_BASE_URL: http://photoprism:2342
+      # Bind on all interfaces inside the container so the host-side
+      # 127.0.0.1:8000 port mapping can reach the listener. The Go
+      # binary defaults to 127.0.0.1 for the host-mode dev loop.
+      SIDECAR_LISTEN_ADDR: 0.0.0.0
+      SIDECAR_PORT: "8000"
+      SIDECAR_DB_HOST: mariadb
+      SIDECAR_DB_PORT: "3306"
+      SIDECAR_DB_USER: sidecar
+      # Rotate before any non-local deployment. Provisioned by
+      # mariadb/init/01-sidecar.sql on first boot of the mariadb volume.
+      SIDECAR_DB_PASSWORD: ${SIDECAR_DB_PASSWORD:-replace-at-m4-bringup}
+      SIDECAR_DB_NAME: mule_sidecar
+      # Second DB connection for poking PhotoPrism's own schema (only
+      # used by the user-basepath reconciler today). Stays inert if
+      # PP_DB_PASSWORD is empty — the reconciler then silently no-ops.
+      PP_DB_HOST: mariadb
+      PP_DB_PORT: "3306"
+      PP_DB_USER: ${PP_DB_USER:-photoprism}
+      PP_DB_PASSWORD: ${PP_DB_PASSWORD:-}
+      PP_DB_NAME: ${PP_DB_NAME:-photoprism}
+      # Declarative username → originals-relative BasePath mapping.
+      # Format: comma-separated `user:path` pairs. Sidecar applies it
+      # to auth_users on boot and every 60s, and `mkdir -p`s each
+      # target subdirectory so PhotoPrism's ACL filter has somewhere to
+      # point. Leave empty to disable.
+      #   USER_BASEPATHS="test:test, alice:family/alice"
+      USER_BASEPATHS: ${USER_BASEPATHS:-}
+    volumes:
+      # Sidecar mutates originals (rename, folder mutations, heap
+      # convert) — always rw regardless of PhotoPrism's mount mode.
+      - "${PHOTO_DIRS:?set PHOTO_DIRS in .env}:/photoprism/originals:rw,Z"
+    networks: [photoprism-network]
 
 networks:
-  mulita-network:
+  photoprism-network:
     driver: bridge
 
 volumes:
-  thumbs_data:
-  proxies_data:
-  db_data:
-  redis_data:
+  pp_mariadb_data:

frontend/Dockerfile

@@ -1,31 +0,0 @@
-# Build stage
-FROM node:18-alpine as build
-
-WORKDIR /app
-
-# Copy package files
-COPY package*.json ./
-
-# Install dependencies
-RUN npm ci
-
-# Copy source code
-COPY . .
-
-# Build the application
-RUN npm run build
-
-# Production stage
-FROM nginx:alpine
-
-# Copy built assets from build stage
-COPY --from=build /app/dist /usr/share/nginx/html
-
-# Copy nginx configuration
-COPY nginx.conf /etc/nginx/conf.d/default.conf
-
-# Expose port
-EXPOSE 80
-
-# Start nginx
-CMD ["nginx", "-g", "daemon off;"]

frontend/index.html

@@ -1,15 +0,0 @@
-<!doctype html>
-<html lang="en" class="dark">
-  <head>
-    <meta charset="UTF-8" />
-    <link rel="icon" type="image/png" href="/favicon.png" />
-    <link rel="apple-touch-icon" href="/favicon.png" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <meta name="theme-color" content="#0f0f0f" />
-    <title>Mulimago</title>
-  </head>
-  <body>
-    <div id="root"></div>
-    <script type="module" src="/src/main.tsx"></script>
-  </body>
-</html>

frontend/nginx.conf

@@ -1,54 +0,0 @@
-server {
-    listen 80;
-    server_name localhost;
-    root /usr/share/nginx/html;
-    index index.html;
-
-    # Enable gzip
-    gzip on;
-    gzip_vary on;
-    gzip_min_length 1024;
-    gzip_types text/plain text/css text/xml text/javascript application/javascript application/xml+rss application/json;
-
-    # API proxy
-    location /api/ {
-        proxy_pass http://backend:8000;
-        proxy_set_header Host $host;
-        proxy_set_header X-Real-IP $remote_addr;
-        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_set_header X-Forwarded-Proto $scheme;
-        
-        # WebSocket support for real-time updates
-        proxy_http_version 1.1;
-        proxy_set_header Upgrade $http_upgrade;
-        proxy_set_header Connection "upgrade";
-    }
-
-    # Thumbnail serving with X-Accel-Redirect
-    location /internal_thumbs/ {
-        internal;
-        alias /data/thumbs/;
-    }
-
-    # SPA routing - serve index.html for all routes
-    location / {
-        try_files $uri $uri/ /index.html;
-    }
-
-    # Never cache index.html (or any HTML). The asset filenames are
-    # content-hashed by Vite, so a fresh index.html is the only thing
-    # that tells the browser to fetch the new bundle. Without this the
-    # browser happily serves a stale index.html → stale bundle hash →
-    # users see the old build until they hard-reload.
-    location = /index.html {
-        add_header Cache-Control "no-cache, no-store, must-revalidate";
-        add_header Pragma "no-cache";
-        expires 0;
-    }
-
-    # Cache static assets (filenames are content-hashed, so 1y is safe)
-    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
-        expires 1y;
-        add_header Cache-Control "public, immutable";
-    }
-}

frontend/package.json

@@ -1,62 +0,0 @@
-{
-  "name": "mulita-frontend",
-  "private": true,
-  "version": "1.0.0",
-  "type": "module",
-  "scripts": {
-    "dev": "vite",
-    "build": "tsc && vite build",
-    "preview": "vite preview",
-    "lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0"
-  },
-  "dependencies": {
-    "@radix-ui/react-accordion": "^1.1.2",
-    "@radix-ui/react-alert-dialog": "^1.0.5",
-    "@radix-ui/react-checkbox": "^1.0.4",
-    "@radix-ui/react-context-menu": "^2.1.5",
-    "@radix-ui/react-dialog": "^1.0.5",
-    "@radix-ui/react-dropdown-menu": "^2.0.6",
-    "@radix-ui/react-label": "^2.0.2",
-    "@radix-ui/react-popover": "^1.0.7",
-    "@radix-ui/react-scroll-area": "^1.0.5",
-    "@radix-ui/react-select": "^2.0.0",
-    "@radix-ui/react-separator": "^1.0.3",
-    "@radix-ui/react-slider": "^1.1.2",
-    "@radix-ui/react-switch": "^1.0.3",
-    "@radix-ui/react-tabs": "^1.0.4",
-    "@radix-ui/react-toast": "^1.1.5",
-    "@radix-ui/react-tooltip": "^1.0.7",
-    "@tanstack/react-query": "^5.17.0",
-    "@tanstack/react-virtual": "^3.0.1",
-    "axios": "^1.6.5",
-    "clsx": "^2.1.0",
-    "date-fns": "^3.2.0",
-    "framer-motion": "^10.18.0",
-    "leaflet": "^1.9.4",
-    "lucide-react": "^0.303.0",
-    "react": "^18.2.0",
-    "react-dom": "^18.2.0",
-    "react-hotkeys-hook": "^4.4.3",
-    "react-intersection-observer": "^9.5.3",
-    "react-leaflet": "^4.2.1",
-    "tailwind-merge": "^2.2.0",
-    "zustand": "^4.4.7"
-  },
-  "devDependencies": {
-    "@tanstack/react-query-devtools": "^5.96.2",
-    "@types/leaflet": "^1.9.8",
-    "@types/react": "^18.2.46",
-    "@types/react-dom": "^18.2.18",
-    "@typescript-eslint/eslint-plugin": "^6.17.0",
-    "@typescript-eslint/parser": "^6.17.0",
-    "@vitejs/plugin-react": "^4.2.1",
-    "autoprefixer": "^10.4.16",
-    "eslint": "^8.56.0",
-    "eslint-plugin-react-hooks": "^4.6.0",
-    "eslint-plugin-react-refresh": "^0.4.5",
-    "postcss": "^8.4.33",
-    "tailwindcss": "^3.4.0",
-    "typescript": "^5.3.3",
-    "vite": "^5.0.10"
-  }
-}

frontend/postcss.config.js

@@ -1,6 +0,0 @@
-export default {
-  plugins: {
-    tailwindcss: {},
-    autoprefixer: {},
-  },
-}

frontend/src/App.tsx

@@ -1,116 +0,0 @@
-import { useState } from 'react'
-import { Timeline } from './components/timeline/Timeline'
-import { DuplicatesView } from './components/duplicates/DuplicatesView'
-import { LeftSidebar } from './components/layout/LeftSidebar'
-import { RightSidebar } from './components/layout/RightSidebar'
-import { TopBar } from './components/layout/TopBar'
-import { ScanProgress } from './components/ScanProgress'
-import { ToastContainer } from './components/ToastContainer'
-import { KeyboardHints } from './components/KeyboardHints'
-import { PreviewView } from './components/preview/PreviewView'
-import { FilterBar } from './components/filter/FilterBar'
-import { DiscardActionBar } from './components/discard/DiscardActionBar'
-import { SettingsDialog } from './components/dialogs/SettingsDialog'
-import { usePhotoStore } from './store/photoStore'
-import { useFilterStore } from './store/filterStore'
-import { useKeyboardShortcuts } from './hooks/useKeyboardShortcuts'
-import { useFilterUrlSync } from './hooks/useFilterUrlSync'
-import { usePhotosQuery } from './hooks/usePhotosQuery'
-
-function App() {
-  const [leftSidebarOpen, setLeftSidebarOpen] = useState(true)
-  const [rightSidebarOpen, setRightSidebarOpen] = useState(true)
-  const [settingsOpen, setSettingsOpen] = useState(false)
-  const viewMode = usePhotoStore((state) => state.viewMode)
-  const currentSection = useFilterStore((s) => s.currentSection)
-
-  // Bidirectional sync of filter store with URL query params.
-  useFilterUrlSync()
-
-  // Subscribe to the same photos query the Timeline uses, so the keyboard
-  // "open preview on first photo" path can read from the live cache regardless
-  // of what filter key it's stored under.
-  const { data: allPhotos } = usePhotosQuery()
-
-  // Set up global keyboard shortcuts
-  useKeyboardShortcuts({
-    onToggleLeftSidebar: () => setLeftSidebarOpen(!leftSidebarOpen),
-    onToggleRightSidebar: () => setRightSidebarOpen(!rightSidebarOpen),
-    getFirstPhotoId: () => allPhotos?.[0]?.id ?? null,
-  })
-
-  // Right sidebar stays open by default and shows whatever's selected
-  // (or an empty state if nothing is). User can still toggle it manually.
-  const showRightSidebar = rightSidebarOpen && viewMode === 'grid'
-
-  return (
-    <div className="flex flex-col h-screen bg-bg text-text">
-      <TopBar
-        leftSidebarOpen={leftSidebarOpen}
-        rightSidebarOpen={showRightSidebar}
-        onExpandLeft={() => setLeftSidebarOpen(true)}
-        onExpandRight={() => setRightSidebarOpen(true)}
-      />
-
-      <div className="flex flex-1 overflow-hidden">
-        {/* Left Sidebar */}
-        <div
-          className={`transition-all duration-200 ${
-            leftSidebarOpen ? 'w-60' : 'w-0'
-          } overflow-hidden border-r border-border bg-surface`}
-        >
-          <LeftSidebar
-            onCollapse={() => setLeftSidebarOpen(false)}
-            onOpenSettings={() => setSettingsOpen(true)}
-          />
-        </div>
-
-        {/* Main column — filter bar, discard bar, timeline. Lives to the
-         *  right of the left sidebar so the filter row doesn't bleed
-         *  across the sidebar. relative so the KeyboardHints overlay
-         *  centers against this column, not the viewport. */}
-        <div className="relative flex min-w-0 flex-1 flex-col">
-          <FilterBar />
-          <DiscardActionBar />
-          <div className="flex-1 overflow-auto">
-            {/* The Duplicates section gets its own grouped grid view —
-             *  the regular timeline can't represent groups, and a flat
-             *  filtered list of "is_duplicate=true" photos was the old
-             *  half-broken UX. */}
-            {currentSection === 'duplicates' ? <DuplicatesView /> : <Timeline />}
-          </div>
-          {/* Floating keyboard hints — bottom-center of the main column,
-           *  glassy. Mounted here so it's centered against the timeline,
-           *  not the viewport (which would be offset by the sidebars). */}
-          <KeyboardHints />
-        </div>
-
-        {/* Right Sidebar */}
-        <div
-          className={`transition-all duration-200 ${
-            showRightSidebar ? 'w-72' : 'w-0'
-          } overflow-hidden border-l border-border bg-surface`}
-        >
-          <RightSidebar onCollapse={() => setRightSidebarOpen(false)} />
-        </div>
-      </div>
-
-      {/* Scan Progress Indicator */}
-      <ScanProgress />
-
-      {/* Toast Notifications */}
-      <ToastContainer />
-
-      {/* Preview overlay — covers TopBar when active */}
-      {viewMode === 'preview' && <PreviewView />}
-
-      {/* Settings panel — admin/maintenance actions */}
-      <SettingsDialog
-        isOpen={settingsOpen}
-        onClose={() => setSettingsOpen(false)}
-      />
-    </div>
-  )
-}
-
-export default App

frontend/src/components/KeyboardHints.tsx

@@ -1,62 +0,0 @@
-import { usePhotoStore } from '../store/photoStore'
-
-export function KeyboardHints() {
-  const selectedCount = usePhotoStore((state) => state.selectedPhotos.length)
-  const viewMode = usePhotoStore((state) => state.viewMode)
-
-  // In preview mode the viewer has its own context, so the grid hints
-  // would just be confusing. Hide them.
-  if (viewMode === 'preview') return null
-
-  const hints = selectedCount > 0
-    ? [
-        { key: '1-5', action: 'Rate' },
-        { key: 'P', action: 'Pick → heap' },
-        { key: 'X', action: 'Discard' },
-        { key: 'Space', action: 'Preview' },
-        { key: 'I', action: 'Info panel' },
-        { key: 'Esc', action: 'Deselect' },
-      ]
-    : [
-        { key: '↑↓←→', action: 'Navigate' },
-        { key: 'Space', action: 'Preview' },
-        { key: 'Tab', action: 'Library panel' },
-        { key: 'I', action: 'Info panel' },
-        { key: '/', action: 'Search' },
-      ]
-
-  return (
-    // Absolute (not fixed) so the parent's flex/position context can
-    // center it relative to the timeline area, not the viewport. Mount
-    // inside the main column in App.tsx so it isn't offset by the
-    // sidebar widths.
-    <div className="pointer-events-none absolute bottom-4 left-1/2 z-30 -translate-x-1/2">
-      {/* Near-opaque dark pill so the hints stay legible against busy
-       *  thumbnails. The previous bg-surface/40 + 5% white ring left
-       *  text washed out when a bright photo sat directly behind it. */}
-      <div className="pointer-events-auto flex items-center gap-3 whitespace-nowrap rounded-full border border-white/15 bg-black/80 px-4 py-1.5 shadow-xl ring-1 ring-black/40 backdrop-blur-md">
-        {hints.map((hint, i) => (
-          <div key={i} className="flex items-center gap-1.5">
-            <kbd className="rounded bg-white/15 px-1.5 py-0.5 text-[11px] font-medium text-white shadow-sm">
-              {hint.key}
-            </kbd>
-            <span className="whitespace-nowrap text-xs text-white/85">
-              {hint.action}
-            </span>
-            {i < hints.length - 1 && (
-              <span className="ml-1 text-white/30">•</span>
-            )}
-          </div>
-        ))}
-        {selectedCount > 0 && (
-          <>
-            <span className="text-white/30">•</span>
-            <span className="whitespace-nowrap text-xs font-semibold text-primary">
-              {selectedCount} selected
-            </span>
-          </>
-        )}
-      </div>
-    </div>
-  )
-}

frontend/src/components/ScanProgress.tsx

@@ -1,185 +0,0 @@
-import { useEffect, useRef, useState } from 'react'
-import { FolderOpen, Loader2, Check, AlertCircle, X } from 'lucide-react'
-import { useQuery, useQueryClient } from '@tanstack/react-query'
-import { library } from '../services/api'
-import clsx from 'clsx'
-
-interface ScanStatus {
-  is_scanning: boolean
-  current_folder?: string
-  processed_files: number
-  total_files: number
-  errors: string[]
-}
-
-export function ScanProgress() {
-  const [isVisible, setIsVisible] = useState(false)
-  const [isMinimized, setIsMinimized] = useState(false)
-  const queryClient = useQueryClient()
-  const wasScanningRef = useRef(false)
-
-  // Poll scan status every 2 seconds when scanning
-  const { data: scanStatus } = useQuery<ScanStatus>({
-    queryKey: ['scan-status'],
-    queryFn: async () => {
-      const response = await library.scanStatus()
-      return response
-    },
-    refetchInterval: (query) => {
-      // Poll every 2 seconds if scanning, otherwise every 10 seconds
-      return query.state.data?.is_scanning ? 2000 : 10000
-    },
-    enabled: true,
-  })
-
-  useEffect(() => {
-    const isScanning = scanStatus?.is_scanning ?? false
-
-    if (isScanning) {
-      setIsVisible(true)
-      setIsMinimized(false)
-      wasScanningRef.current = true
-    } else if (wasScanningRef.current) {
-      // Just transitioned from scanning → done. THIS is the right moment
-      // to invalidate caches that might have new data: the photos query
-      // (new files indexed), the folder tree (new folders walked), the
-      // heap counts (in case a heap photo got reattached).
-      wasScanningRef.current = false
-      queryClient.invalidateQueries({ queryKey: ['photos'] })
-      queryClient.invalidateQueries({ queryKey: ['folders'] })
-      queryClient.invalidateQueries({ queryKey: ['folders', 'tree'] })
-      queryClient.invalidateQueries({ queryKey: ['heaps'] })
-      queryClient.invalidateQueries({ queryKey: ['tags'] })
-      queryClient.invalidateQueries({ queryKey: ['library', 'stats'] })
-
-      if (isVisible && (scanStatus?.processed_files ?? 0) > 0) {
-        // Keep showing for 3 seconds after scan completes
-        setTimeout(() => {
-          if (!scanStatus?.is_scanning) {
-            setIsVisible(false)
-          }
-        }, 3000)
-      }
-    }
-  }, [scanStatus?.is_scanning, scanStatus?.processed_files, isVisible, queryClient])
-
-  if (!isVisible || !scanStatus) return null
-
-  const progress = scanStatus.total_files > 0
-    ? (scanStatus.processed_files / scanStatus.total_files) * 100
-    : 0
-
-  const isComplete = !scanStatus.is_scanning && scanStatus.processed_files > 0
-  const hasErrors = scanStatus.errors && scanStatus.errors.length > 0
-
-  return (
-    <div
-      className={clsx(
-        'fixed bottom-4 right-4 z-40 overflow-hidden rounded-lg border border-border bg-surface shadow-xl transition-all duration-300',
-        isMinimized ? 'w-12' : 'w-80'
-      )}
-    >
-      {/* Header */}
-      <div
-        className="flex cursor-pointer items-center justify-between bg-surface-2 px-3 py-2"
-        onClick={() => setIsMinimized(!isMinimized)}
-      >
-        <div className="flex items-center gap-2">
-          {scanStatus.is_scanning ? (
-            <Loader2 className="h-4 w-4 animate-spin text-primary" />
-          ) : isComplete && !hasErrors ? (
-            <Check className="h-4 w-4 text-pick" />
-          ) : hasErrors ? (
-            <AlertCircle className="h-4 w-4 text-reject" />
-          ) : (
-            <FolderOpen className="h-4 w-4 text-text-muted" />
-          )}
-          {!isMinimized && (
-            <span className="text-sm font-medium text-text">
-              {scanStatus.is_scanning
-                ? 'Scanning Folders'
-                : isComplete
-                ? 'Scan Complete'
-                : 'Scan Status'}
-            </span>
-          )}
-        </div>
-        {!isMinimized && (
-          <button
-            onClick={(e) => {
-              e.stopPropagation()
-              setIsVisible(false)
-            }}
-            className="rounded p-0.5 text-text-muted hover:bg-surface-offset hover:text-text"
-          >
-            <X className="h-3 w-3" />
-          </button>
-        )}
-      </div>
-
-      {/* Content */}
-      {!isMinimized && (
-        <div className="p-3">
-          {/* Current folder */}
-          {scanStatus.current_folder && (
-            <div className="mb-2 text-xs text-text-muted">
-              <span className="font-mono">{scanStatus.current_folder}</span>
-            </div>
-          )}
-
-          {/* Progress bar */}
-          <div className="mb-2">
-            <div className="h-1.5 overflow-hidden rounded-full bg-surface-offset">
-              <div
-                className={clsx(
-                  'h-full transition-all duration-300',
-                  scanStatus.is_scanning
-                    ? 'bg-primary'
-                    : hasErrors
-                    ? 'bg-reject'
-                    : 'bg-pick'
-                )}
-                style={{ width: `${progress}%` }}
-              />
-            </div>
-          </div>
-
-          {/* Stats */}
-          <div className="flex items-center justify-between text-xs">
-            <span className="text-text-muted">
-              {scanStatus.processed_files} / {scanStatus.total_files || '?'} files
-            </span>
-            <span className={clsx(
-              'font-medium',
-              scanStatus.is_scanning ? 'text-primary' : hasErrors ? 'text-reject' : 'text-pick'
-            )}>
-              {scanStatus.is_scanning
-                ? `${Math.round(progress)}%`
-                : isComplete
-                ? 'Done'
-                : 'Idle'}
-            </span>
-          </div>
-
-          {/* Errors */}
-          {hasErrors && (
-            <div className="mt-2 max-h-20 overflow-y-auto rounded bg-reject/10 p-2">
-              <div className="text-xs text-reject">
-                {scanStatus.errors.slice(0, 3).map((error, i) => (
-                  <div key={i} className="truncate">
-                    • {error}
-                  </div>
-                ))}
-                {scanStatus.errors.length > 3 && (
-                  <div className="mt-1 text-text-muted">
-                    +{scanStatus.errors.length - 3} more errors
-                  </div>
-                )}
-              </div>
-            </div>
-          )}
-        </div>
-      )}
-    </div>
-  )
-}

frontend/src/components/ToastContainer.tsx

@@ -1,132 +0,0 @@
-import { useEffect, useState } from 'react'
-import { CheckCircle, XCircle, Info, AlertCircle, X } from 'lucide-react'
-import clsx from 'clsx'
-
-export interface ToastAction {
-  label: string
-  onClick: () => void
-}
-
-export interface Toast {
-  id: string
-  type: 'success' | 'error' | 'info' | 'warning'
-  title: string
-  message?: string
-  duration?: number
-  action?: ToastAction
-}
-
-// Global toast state (in production, use Zustand or Context)
-let toastListeners: ((toasts: Toast[]) => void)[] = []
-let toastList: Toast[] = []
-
-export const toast = {
-  success: (title: string, message?: string, action?: ToastAction) =>
-    addToast('success', title, message, 5000, action),
-  error: (title: string, message?: string, action?: ToastAction) =>
-    addToast('error', title, message, 5000, action),
-  info: (title: string, message?: string, action?: ToastAction) =>
-    addToast('info', title, message, 5000, action),
-  warning: (title: string, message?: string, action?: ToastAction) =>
-    addToast('warning', title, message, 5000, action),
-}
-
-function addToast(
-  type: Toast['type'],
-  title: string,
-  message?: string,
-  duration = 5000,
-  action?: ToastAction
-) {
-  const id = Date.now().toString() + Math.random().toString(36).slice(2, 6)
-  const newToast: Toast = { id, type, title, message, duration, action }
-  toastList = [...toastList, newToast]
-  toastListeners.forEach(listener => listener(toastList))
-
-  // Auto-remove after duration. Toasts with an action get a longer window
-  // so the user has time to actually click Undo.
-  const removeAfter = action ? Math.max(duration, 8000) : duration
-  setTimeout(() => {
-    removeToast(id)
-  }, removeAfter)
-}
-
-function removeToast(id: string) {
-  toastList = toastList.filter(t => t.id !== id)
-  toastListeners.forEach(listener => listener(toastList))
-}
-
-export function ToastContainer() {
-  const [toasts, setToasts] = useState<Toast[]>([])
-
-  useEffect(() => {
-    const listener = (newToasts: Toast[]) => setToasts(newToasts)
-    toastListeners.push(listener)
-    return () => {
-      toastListeners = toastListeners.filter(l => l !== listener)
-    }
-  }, [])
-
-  // Subdued icons — smaller and muted so the toast reads as a
-  // background notification rather than a modal. The colored tint
-  // comes from the border-left accent, not a filled background.
-  const icons = {
-    success: <CheckCircle className="h-3.5 w-3.5 text-pick" />,
-    error: <XCircle className="h-3.5 w-3.5 text-reject" />,
-    info: <Info className="h-3.5 w-3.5 text-primary" />,
-    warning: <AlertCircle className="h-3.5 w-3.5 text-star" />,
-  }
-
-  // Single thin left accent bar per type instead of a full-border +
-  // tinted fill. Keeps the toast visually quiet — the user can still
-  // glance it but it doesn't compete with the rest of the UI.
-  const accents = {
-    success: 'border-l-pick',
-    error: 'border-l-reject',
-    info: 'border-l-primary',
-    warning: 'border-l-star',
-  }
-
-  return (
-    <div className="pointer-events-none fixed bottom-4 left-4 z-50 flex flex-col gap-1.5">
-      {toasts.map((toast) => (
-        <div
-          key={toast.id}
-          className={clsx(
-            'pointer-events-auto flex items-start gap-2 rounded-md border border-border border-l-2 bg-surface/80 px-2.5 py-1.5 text-xs shadow-md backdrop-blur-md transition-all duration-300',
-            'animate-slide-up',
-            accents[toast.type]
-          )}
-          style={{ minWidth: '220px', maxWidth: '320px' }}
-        >
-          <div className="mt-0.5 flex-shrink-0">{icons[toast.type]}</div>
-          <div className="min-w-0 flex-1">
-            <div className="truncate font-medium text-text">{toast.title}</div>
-            {toast.message && (
-              <div className="mt-0.5 truncate text-[11px] text-text-muted">
-                {toast.message}
-              </div>
-            )}
-          </div>
-          {toast.action && (
-            <button
-              onClick={() => {
-                toast.action!.onClick()
-                removeToast(toast.id)
-              }}
-              className="pointer-events-auto self-center rounded border border-border bg-surface px-1.5 py-0.5 text-[11px] font-medium text-text hover:bg-surface-2"
-            >
-              {toast.action.label}
-            </button>
-          )}
-          <button
-            onClick={() => removeToast(toast.id)}
-            className="pointer-events-auto rounded p-0.5 text-text-faint hover:bg-surface-offset hover:text-text"
-          >
-            <X className="h-3 w-3" />
-          </button>
-        </div>
-      ))}
-    </div>
-  )
-}

frontend/src/components/dialogs/ConfirmDialog.tsx

@@ -1,75 +0,0 @@
-import { useEffect } from 'react'
-import clsx from 'clsx'
-
-interface ConfirmDialogProps {
-  isOpen: boolean
-  title: string
-  message: React.ReactNode
-  confirmLabel?: string
-  cancelLabel?: string
-  /** When true, the confirm button uses the destructive accent. */
-  destructive?: boolean
-  onConfirm: () => void
-  onClose: () => void
-}
-
-/**
- * Tiny modal-confirmation dialog. Mirrors the AddSourceFolderDialog overlay
- * pattern (custom fixed inset-0 backdrop, no shadcn Dialog dep). Esc closes.
- */
-export function ConfirmDialog({
-  isOpen,
-  title,
-  message,
-  confirmLabel = 'Confirm',
-  cancelLabel = 'Cancel',
-  destructive = false,
-  onConfirm,
-  onClose,
-}: ConfirmDialogProps) {
-  // Esc to close.
-  useEffect(() => {
-    if (!isOpen) return
-    const handler = (e: KeyboardEvent) => {
-      if (e.key === 'Escape') onClose()
-    }
-    window.addEventListener('keydown', handler)
-    return () => window.removeEventListener('keydown', handler)
-  }, [isOpen, onClose])
-
-  if (!isOpen) return null
-
-  return (
-    <div className="fixed inset-0 z-50">
-      <div
-        className="absolute inset-0 bg-black/60 backdrop-blur-sm"
-        onClick={onClose}
-      />
-      <div className="absolute left-1/2 top-1/2 -translate-x-1/2 -translate-y-1/2">
-        <div className="relative z-10 w-96 rounded-lg border border-border bg-surface p-5 shadow-2xl">
-          <h2 className="mb-2 text-base font-semibold text-text">{title}</h2>
-          <div className="mb-4 text-sm text-text-muted">{message}</div>
-          <div className="flex justify-end gap-2">
-            <button
-              onClick={onClose}
-              className="rounded border border-border px-3 py-1.5 text-sm text-text hover:bg-surface-2"
-            >
-              {cancelLabel}
-            </button>
-            <button
-              onClick={onConfirm}
-              className={clsx(
-                'rounded px-3 py-1.5 text-sm font-medium text-white',
-                destructive
-                  ? 'bg-reject hover:bg-reject/80'
-                  : 'bg-primary hover:bg-primary/80'
-              )}
-            >
-              {confirmLabel}
-            </button>
-          </div>
-        </div>
-      </div>
-    </div>
-  )
-}

frontend/src/components/dialogs/DeleteFolderDialog.tsx

@@ -1,164 +0,0 @@
-import { useEffect, useState } from 'react'
-import clsx from 'clsx'
-import { Trash2, Archive } from 'lucide-react'
-
-interface DeleteFolderDialogProps {
-  isOpen: boolean
-  folderName: string
-  /** Number of photos under this folder, including descendants. Surfaced
-   *  in the dialog copy so the user understands the blast radius. */
-  photoCount?: number
-  onClose: () => void
-  /** Called with the chosen mode when the user confirms. */
-  onConfirm: (mode: 'discard' | 'permanent') => void
-}
-
-/**
- * Two-mode folder delete dialog:
- *
- *  - Move to discard pile  (default, soft, recoverable)
- *  - Permanently delete    (destructive, irreversible)
- *
- * The user picks a mode via the radio cards then clicks Delete. Esc /
- * backdrop click cancels.
- */
-export function DeleteFolderDialog({
-  isOpen,
-  folderName,
-  photoCount,
-  onClose,
-  onConfirm,
-}: DeleteFolderDialogProps) {
-  const [mode, setMode] = useState<'discard' | 'permanent'>('discard')
-
-  // Reset mode when re-opening so the safe option is always the default.
-  useEffect(() => {
-    if (isOpen) setMode('discard')
-  }, [isOpen])
-
-  // Esc to close.
-  useEffect(() => {
-    if (!isOpen) return
-    const handler = (e: KeyboardEvent) => {
-      if (e.key === 'Escape') onClose()
-    }
-    window.addEventListener('keydown', handler)
-    return () => window.removeEventListener('keydown', handler)
-  }, [isOpen, onClose])
-
-  if (!isOpen) return null
-
-  const photoBlurb =
-    photoCount === undefined
-      ? 'photos in this folder'
-      : photoCount === 0
-      ? 'this empty folder'
-      : `${photoCount} photo${photoCount === 1 ? '' : 's'} in this folder`
-
-  return (
-    <div className="fixed inset-0 z-50">
-      <div
-        className="absolute inset-0 bg-black/60 backdrop-blur-sm"
-        onClick={onClose}
-      />
-      <div className="absolute left-1/2 top-1/2 -translate-x-1/2 -translate-y-1/2">
-        <div className="relative z-10 w-[420px] rounded-lg border border-border bg-surface p-5 shadow-2xl">
-          <h2 className="mb-1 text-base font-semibold text-text">
-            Delete folder "{folderName}"?
-          </h2>
-          <p className="mb-4 text-sm text-text-muted">
-            What should happen to {photoBlurb}?
-          </p>
-
-          <div className="space-y-2">
-            <ModeCard
-              icon={<Archive className="h-4 w-4" />}
-              title="Move photos to discard pile"
-              description="Photos can be restored later from Discarded. The folder and files stay on disk."
-              selected={mode === 'discard'}
-              onClick={() => setMode('discard')}
-            />
-            <ModeCard
-              icon={<Trash2 className="h-4 w-4" />}
-              title="Permanently delete folder and photos"
-              description="Removes the folder, every photo inside it, and the directory from disk. This cannot be undone."
-              selected={mode === 'permanent'}
-              destructive
-              onClick={() => setMode('permanent')}
-            />
-          </div>
-
-          <div className="mt-5 flex justify-end gap-2">
-            <button
-              onClick={onClose}
-              className="rounded border border-border px-3 py-1.5 text-sm text-text hover:bg-surface-2"
-            >
-              Cancel
-            </button>
-            <button
-              onClick={() => onConfirm(mode)}
-              className={clsx(
-                'rounded px-3 py-1.5 text-sm font-medium text-white',
-                mode === 'permanent'
-                  ? 'bg-reject hover:bg-reject/80'
-                  : 'bg-primary hover:bg-primary/80'
-              )}
-            >
-              {mode === 'permanent' ? 'Delete forever' : 'Move to discard pile'}
-            </button>
-          </div>
-        </div>
-      </div>
-    </div>
-  )
-}
-
-function ModeCard({
-  icon,
-  title,
-  description,
-  selected,
-  destructive = false,
-  onClick,
-}: {
-  icon: React.ReactNode
-  title: string
-  description: string
-  selected: boolean
-  destructive?: boolean
-  onClick: () => void
-}) {
-  return (
-    <button
-      onClick={onClick}
-      className={clsx(
-        'flex w-full gap-3 rounded-lg border p-3 text-left transition-colors',
-        selected
-          ? destructive
-            ? 'border-reject/60 bg-reject/10'
-            : 'border-primary/60 bg-primary/10'
-          : 'border-border bg-surface-2 hover:bg-surface-offset'
-      )}
-    >
-      <div
-        className={clsx(
-          'mt-0.5 flex-shrink-0',
-          selected ? (destructive ? 'text-reject' : 'text-primary') : 'text-text-muted'
-        )}
-      >
-        {icon}
-      </div>
-      <div className="flex-1">
-        <div
-          className={clsx(
-            'text-sm font-medium',
-            selected ? (destructive ? 'text-reject' : 'text-primary') : 'text-text'
-          )}
-        >
-          {title}
-        </div>
-        <div className="mt-0.5 text-xs text-text-muted">{description}</div>
-      </div>
-    </button>
-  )
-}

frontend/src/components/dialogs/SettingsDialog.tsx

@@ -1,835 +0,0 @@
-import { useEffect, useState, useCallback } from 'react'
-import {
-  X,
-  RefreshCw,
-  Wrench,
-  Film,
-  Image as ImageIcon,
-  AlertTriangle,
-  Database,
-  Loader2,
-  Cpu,
-  AlertCircle,
-  CheckCircle2,
-  Copy,
-  Sparkles,
-} from 'lucide-react'
-import clsx from 'clsx'
-import { useQuery, useQueryClient } from '@tanstack/react-query'
-import {
-  library,
-  type MediaType,
-} from '../../services/api'
-import { toast } from '../ToastContainer'
-
-// React Query keys for the settings panels. Kept here (not in a shared
-// hook module) since they're internal to this dialog and used by the
-// runAction refresh step to invalidate after mutations.
-const SETTINGS_THUMB_STATS_KEY = ['settings', 'thumbnail-stats'] as const
-const SETTINGS_LIB_STATS_KEY = ['settings', 'library-stats'] as const
-const SETTINGS_WORKER_STATUS_KEY = ['settings', 'worker-status'] as const
-const SETTINGS_MISSING_STATS_KEY = ['settings', 'missing-stats'] as const
-// Shared with the DuplicatesView so a regroup invalidates the same cache
-// the grid renders from. Imported via the canonical hook key.
-import { DUPLICATE_GROUPS_QUERY_KEY } from '../../hooks/useDuplicateGroupsQuery'
-
-interface SettingsDialogProps {
-  isOpen: boolean
-  onClose: () => void
-}
-
-/**
- * Catch-all "settings + admin" panel. Currently exposes the maintenance
- * endpoints exposed by /api/v1/library/maintenance/* — regenerate
- * thumbnails (with filters), run the data-integrity cleanup, and trigger
- * a full library re-scan. The thumbnail stats block is the entry point
- * users will look at to understand what's going on after a scan.
- *
- * Each action is gated by an in-flight flag so double-clicks don't
- * stack background jobs, and the stats block re-fetches whenever the
- * dialog opens or after any action completes.
- */
-export function SettingsDialog({ isOpen, onClose }: SettingsDialogProps) {
-  const queryClient = useQueryClient()
-  const [showAllErrors, setShowAllErrors] = useState(false)
-  // One key per action so each button has its own spinner without
-  // blocking the others.
-  const [busy, setBusy] = useState<Record<string, boolean>>({})
-
-  // All four panels fetch through React Query so cached data shows
-  // instantly on reopen while a background refetch updates the numbers.
-  // `enabled: isOpen` avoids firing requests while the dialog is closed,
-  // but the cache entries survive between opens (default gcTime = 5m).
-  const thumbStatsQuery = useQuery({
-    queryKey: SETTINGS_THUMB_STATS_KEY,
-    queryFn: library.maintenance.thumbnailStats,
-    enabled: isOpen,
-    // Treat as stale immediately so reopening the dialog triggers a
-    // background refetch on top of the cached view.
-    staleTime: 0,
-  })
-  const libStatsQuery = useQuery({
-    queryKey: SETTINGS_LIB_STATS_KEY,
-    queryFn: library.stats,
-    enabled: isOpen,
-    staleTime: 0,
-  })
-  // Worker status polls every 5s while the dialog is open — `refetchInterval`
-  // replaces the old setInterval loop. Missing-stats is relatively cheap
-  // but shares the same 5s rhythm to keep the orphan banner live.
-  const workerStatusQuery = useQuery({
-    queryKey: SETTINGS_WORKER_STATUS_KEY,
-    queryFn: library.maintenance.workerStatus,
-    enabled: isOpen,
-    refetchInterval: isOpen ? 5000 : false,
-    staleTime: 0,
-  })
-  const missingStatsQuery = useQuery({
-    queryKey: SETTINGS_MISSING_STATS_KEY,
-    queryFn: library.maintenance.missingStats,
-    enabled: isOpen,
-    refetchInterval: isOpen ? 5000 : false,
-    staleTime: 0,
-  })
-  // Duplicates: shares the cache with DuplicatesView so a regroup
-  // triggered from Settings updates the grid view immediately.
-  const duplicatesQuery = useQuery({
-    queryKey: DUPLICATE_GROUPS_QUERY_KEY,
-    queryFn: library.duplicates.groups,
-    enabled: isOpen,
-    staleTime: 0,
-  })
-
-  const thumbStats = thumbStatsQuery.data
-  const libStats = libStatsQuery.data
-  const workerStatus = workerStatusQuery.data
-  const missingStats = missingStatsQuery.data
-  // "loading" in the UI sense = fetching AND no cached data yet. Background
-  // refetches on top of cached data shouldn't flip the refresh spinners.
-  const loadingStats =
-    (thumbStatsQuery.isFetching && !thumbStatsQuery.data) ||
-    (libStatsQuery.isFetching && !libStatsQuery.data)
-  const loadingWorkers =
-    (workerStatusQuery.isFetching && !workerStatusQuery.data) ||
-    (missingStatsQuery.isFetching && !missingStatsQuery.data)
-
-  const refreshStats = useCallback(() => {
-    queryClient.invalidateQueries({ queryKey: SETTINGS_THUMB_STATS_KEY })
-    queryClient.invalidateQueries({ queryKey: SETTINGS_LIB_STATS_KEY })
-    queryClient.invalidateQueries({ queryKey: DUPLICATE_GROUPS_QUERY_KEY })
-  }, [queryClient])
-  const refreshWorkers = useCallback(() => {
-    queryClient.invalidateQueries({ queryKey: SETTINGS_WORKER_STATUS_KEY })
-    queryClient.invalidateQueries({ queryKey: SETTINGS_MISSING_STATS_KEY })
-  }, [queryClient])
-
-  // Surface fetch errors once (React Query de-dupes retries but we still
-  // want a single toast so the user knows something went wrong).
-  useEffect(() => {
-    if (!isOpen) return
-    if (thumbStatsQuery.error || libStatsQuery.error) {
-      console.error('Failed to load settings stats', thumbStatsQuery.error ?? libStatsQuery.error)
-      toast.error('Could not load library stats')
-    }
-  }, [isOpen, thumbStatsQuery.error, libStatsQuery.error])
-  useEffect(() => {
-    if (!isOpen) return
-    if (workerStatusQuery.error || missingStatsQuery.error) {
-      console.error('Failed to load worker status', workerStatusQuery.error ?? missingStatsQuery.error)
-      toast.error('Could not load worker status')
-    }
-  }, [isOpen, workerStatusQuery.error, missingStatsQuery.error])
-
-  // Esc closes.
-  useEffect(() => {
-    if (!isOpen) return
-    const handler = (e: KeyboardEvent) => {
-      if (e.key === 'Escape') onClose()
-    }
-    window.addEventListener('keydown', handler)
-    return () => window.removeEventListener('keydown', handler)
-  }, [isOpen, onClose])
-
-  const runAction = useCallback(
-    async <T,>(
-      key: string,
-      fn: () => Promise<T>,
-      successTitle: string,
-      describe?: (result: T) => string | undefined
-    ) => {
-      if (busy[key]) return
-      setBusy((b) => ({ ...b, [key]: true }))
-      try {
-        const result = await fn()
-        toast.success(successTitle, describe?.(result))
-        refreshStats()
-        refreshWorkers()
-      } catch (e: unknown) {
-        const message = e instanceof Error ? e.message : String(e)
-        toast.error(`${successTitle} failed`, message)
-      } finally {
-        setBusy((b) => ({ ...b, [key]: false }))
-      }
-    },
-    [busy, refreshStats, refreshWorkers]
-  )
-
-  const regenerate = useCallback(
-    (
-      key: string,
-      body: {
-        media_types?: MediaType[]
-        only_failed?: boolean
-        only_pending?: boolean
-      }
-    ) =>
-      runAction(
-        key,
-        () => library.maintenance.regenerateThumbnails(body),
-        'Regeneration queued',
-        (r) => `${r.queued} photos queued, ${r.cleared_dirs} thumb dirs cleared`
-      ),
-    [runAction]
-  )
-
-  if (!isOpen) return null
-
-  return (
-    <div className="fixed inset-0 z-50">
-      <div
-        className="absolute inset-0 bg-black/60 backdrop-blur-sm"
-        onClick={onClose}
-      />
-      <div className="absolute left-1/2 top-1/2 -translate-x-1/2 -translate-y-1/2">
-        <div className="relative z-10 flex max-h-[85vh] w-[640px] flex-col rounded-lg border border-border bg-surface shadow-2xl">
-          {/* Header */}
-          <div className="flex items-center justify-between border-b border-border px-5 py-3">
-            <h2 className="text-base font-semibold text-text">Settings</h2>
-            <button
-              onClick={onClose}
-              className="rounded p-1 text-text-muted hover:bg-surface-2 hover:text-text"
-              title="Close (Esc)"
-            >
-              <X className="h-4 w-4" />
-            </button>
-          </div>
-
-          <div className="flex-1 overflow-y-auto p-5">
-            {/* ----------------------------------------------------- */}
-            {/* Library overview                                       */}
-            {/* ----------------------------------------------------- */}
-            <Section
-              icon={<Database className="h-4 w-4" />}
-              title="Library"
-              right={
-                <button
-                  onClick={refreshStats}
-                  disabled={loadingStats}
-                  className="flex items-center gap-1 rounded border border-border px-2 py-1 text-xs text-text-muted hover:bg-surface-2 disabled:opacity-50"
-                >
-                  {loadingStats ? (
-                    <Loader2 className="h-3 w-3 animate-spin" />
-                  ) : (
-                    <RefreshCw className="h-3 w-3" />
-                  )}
-                  Refresh
-                </button>
-              }
-            >
-              <div className="grid grid-cols-3 gap-2 text-xs">
-                <Stat label="Photos" value={libStats?.total_photos} />
-                <Stat label="Videos" value={libStats?.total_videos} />
-                <Stat
-                  label="On disk"
-                  value={
-                    libStats ? `${libStats.total_size_gb.toFixed(1)} GB` : undefined
-                  }
-                />
-              </div>
-              <div className="mt-3">
-                <ActionButton
-                  loading={busy.scan}
-                  onClick={() =>
-                    runAction(
-                      'scan',
-                      () => library.scan(),
-                      'Library scan started'
-                    )
-                  }
-                >
-                  <RefreshCw className="h-4 w-4" />
-                  Re-scan source folders
-                </ActionButton>
-              </div>
-            </Section>
-
-            {/* ----------------------------------------------------- */}
-            {/* Duplicate detection                                    */}
-            {/* ----------------------------------------------------- */}
-            <Section
-              icon={<Copy className="h-4 w-4" />}
-              title="Duplicates"
-            >
-              <div className="grid grid-cols-2 gap-2 text-xs">
-                <Stat
-                  label="Groups"
-                  value={duplicatesQuery.data?.total_groups}
-                />
-                <Stat
-                  label="Members"
-                  value={duplicatesQuery.data?.total_members}
-                />
-              </div>
-              <p className="mt-3 text-xs text-text-muted">
-                Duplicates are detected by perceptual hash (pHash), which catches
-                visually-identical photos even when their bytes differ — re-encoded
-                JPEGs, screenshots, resized exports. Backfill computes hashes for
-                photos that existed before pHash was added; Re-detect re-runs
-                clustering across the whole library.
-              </p>
-              <div className="mt-2 flex flex-wrap gap-2">
-                <ActionButton
-                  loading={busy['backfill-phashes']}
-                  onClick={() =>
-                    runAction(
-                      'backfill-phashes',
-                      () => library.maintenance.backfillPhashes(),
-                      'pHash backfill queued'
-                    )
-                  }
-                >
-                  <Sparkles className="h-4 w-4" />
-                  Backfill perceptual hashes
-                </ActionButton>
-                <ActionButton
-                  loading={busy['regroup-duplicates']}
-                  onClick={() =>
-                    runAction(
-                      'regroup-duplicates',
-                      () => library.maintenance.regroupDuplicates(),
-                      'Duplicate detection queued'
-                    )
-                  }
-                >
-                  <Copy className="h-4 w-4" />
-                  Re-detect duplicates
-                </ActionButton>
-              </div>
-            </Section>
-
-            {/* ----------------------------------------------------- */}
-            {/* Thumbnail maintenance                                  */}
-            {/* ----------------------------------------------------- */}
-            <Section
-              icon={<ImageIcon className="h-4 w-4" />}
-              title="Thumbnails"
-            >
-              <div className="grid grid-cols-4 gap-2 text-xs">
-                <Stat
-                  label="Completed"
-                  value={thumbStats?.completed}
-                  tone="ok"
-                />
-                <Stat
-                  label="Pending"
-                  value={thumbStats?.pending}
-                  tone="muted"
-                />
-                <Stat
-                  label="Processing"
-                  value={thumbStats?.processing}
-                  tone="muted"
-                />
-                <Stat
-                  label="Failed"
-                  value={thumbStats?.failed}
-                  tone={thumbStats && thumbStats.failed > 0 ? 'warn' : 'muted'}
-                />
-              </div>
-
-              <p className="mt-3 text-xs text-text-muted">
-                Reset on-disk thumbnails and re-queue generation. Use after
-                upgrading the worker or to fix the gray placeholders left
-                behind by an earlier failure.
-              </p>
-
-              <div className="mt-2 flex flex-wrap gap-2">
-                <ActionButton
-                  loading={busy['regen-videos']}
-                  onClick={() =>
-                    regenerate('regen-videos', { media_types: ['video'] })
-                  }
-                >
-                  <Film className="h-4 w-4" />
-                  Regenerate video thumbnails
-                </ActionButton>
-
-                <ActionButton
-                  loading={busy['regen-failed']}
-                  onClick={() =>
-                    regenerate('regen-failed', { only_failed: true })
-                  }
-                  disabled={!!thumbStats && thumbStats.failed === 0}
-                >
-                  <AlertTriangle className="h-4 w-4" />
-                  Retry failed
-                  {thumbStats ? ` (${thumbStats.failed})` : ''}
-                </ActionButton>
-
-                <ActionButton
-                  loading={busy['regen-pending']}
-                  onClick={() =>
-                    regenerate('regen-pending', { only_pending: true })
-                  }
-                  disabled={!!thumbStats && thumbStats.pending === 0}
-                >
-                  <RefreshCw className="h-4 w-4" />
-                  Kick pending
-                  {thumbStats ? ` (${thumbStats.pending})` : ''}
-                </ActionButton>
-
-                <ActionButton
-                  loading={busy['regen-all']}
-                  destructive
-                  onClick={() => {
-                    if (
-                      !confirm(
-                        'Regenerate thumbnails for the entire library? ' +
-                          'This will queue every photo and may take a while.'
-                      )
-                    )
-                      return
-                    regenerate('regen-all', {})
-                  }}
-                >
-                  <RefreshCw className="h-4 w-4" />
-                  Regenerate all
-                </ActionButton>
-              </div>
-            </Section>
-
-            {/* ----------------------------------------------------- */}
-            {/* Worker fleet diagnostics                               */}
-            {/* ----------------------------------------------------- */}
-            <Section
-              icon={<Cpu className="h-4 w-4" />}
-              title="Workers"
-              right={
-                <button
-                  onClick={refreshWorkers}
-                  disabled={loadingWorkers}
-                  className="flex items-center gap-1 rounded border border-border px-2 py-1 text-xs text-text-muted hover:bg-surface-2 disabled:opacity-50"
-                >
-                  {loadingWorkers ? (
-                    <Loader2 className="h-3 w-3 animate-spin" />
-                  ) : (
-                    <RefreshCw className="h-3 w-3" />
-                  )}
-                  Refresh
-                </button>
-              }
-            >
-              {/* Top-line health */}
-              <div className="grid grid-cols-3 gap-2 text-xs">
-                <Stat
-                  label="Workers"
-                  value={workerStatus?.worker_count}
-                  tone={
-                    workerStatus
-                      ? workerStatus.worker_count > 0
-                        ? 'ok'
-                        : 'warn'
-                      : 'muted'
-                  }
-                />
-                <Stat
-                  label="Broker"
-                  value={
-                    workerStatus
-                      ? workerStatus.broker_ok
-                        ? 'OK'
-                        : 'DOWN'
-                      : undefined
-                  }
-                  tone={
-                    workerStatus
-                      ? workerStatus.broker_ok
-                        ? 'ok'
-                        : 'warn'
-                      : 'muted'
-                  }
-                />
-                <Stat
-                  label="Failed tasks"
-                  value={workerStatus?.failures.total}
-                  tone={
-                    workerStatus && workerStatus.failures.total > 0
-                      ? 'warn'
-                      : 'muted'
-                  }
-                />
-              </div>
-
-              {/* Inline error banners for the obvious failure modes */}
-              {workerStatus?.broker_error && (
-                <ErrorBanner
-                  title="Cannot reach Redis broker"
-                  detail={workerStatus.broker_error}
-                />
-              )}
-              {workerStatus?.inspect_error && (
-                <ErrorBanner
-                  title="Celery inspect failed"
-                  detail={workerStatus.inspect_error}
-                />
-              )}
-              {workerStatus &&
-                workerStatus.broker_ok &&
-                workerStatus.worker_count === 0 && (
-                  <ErrorBanner
-                    title="No workers responding"
-                    detail="Broker is reachable but no celery worker pinged back. Check the mulita-worker container logs."
-                  />
-                )}
-
-              {/* Queue depth */}
-              {workerStatus && (
-                <div className="mt-3">
-                  <div className="mb-1 text-[10px] uppercase tracking-wide text-text-muted">
-                    Queue depth
-                  </div>
-                  <div className="grid grid-cols-3 gap-2 text-xs">
-                    {Object.entries(workerStatus.queues).map(([name, depth]) => (
-                      <div
-                        key={name}
-                        className="flex items-center justify-between rounded bg-surface px-2 py-1"
-                      >
-                        <span className="text-text-muted">{name}</span>
-                        <span
-                          className={clsx(
-                            'font-mono font-semibold',
-                            depth > 0 ? 'text-text' : 'text-text-muted'
-                          )}
-                        >
-                          {depth}
-                        </span>
-                      </div>
-                    ))}
-                  </div>
-                </div>
-              )}
-
-              {/* Orphaned rows (files gone from disk) */}
-              {missingStats &&
-                ((missingStats.would_delete ?? 0) > 0 ||
-                  (missingStats.would_delete_folders ?? 0) > 0) && (
-                  <div className="mt-3 rounded border border-star/40 bg-star/10 p-2">
-                    <div className="flex items-center justify-between gap-2">
-                      <div className="text-xs">
-                        <div className="flex items-center gap-1.5 font-medium text-text">
-                          <AlertTriangle className="h-3.5 w-3.5 text-star" />
-                          Orphaned rows
-                        </div>
-                        <div className="mt-0.5 text-[10px] text-text-muted">
-                          {missingStats.would_delete ?? 0} photos and{' '}
-                          {missingStats.would_delete_folders ?? 0} folders
-                          point at paths that no longer exist on disk under a
-                          mounted source root. Usually means PHOTO_DIRS was
-                          repointed at a different library.
-                          {missingStats.skipped_unmounted > 0 && (
-                            <>
-                              {' '}
-                              {missingStats.skipped_unmounted} more rows are
-                              under unmounted roots and will not be touched.
-                            </>
-                          )}
-                        </div>
-                      </div>
-                      <ActionButton
-                        loading={busy['prune-missing']}
-                        destructive
-                        onClick={() => {
-                          const photos = missingStats.would_delete ?? 0
-                          const folders = missingStats.would_delete_folders ?? 0
-                          if (
-                            !confirm(
-                              `Delete ${photos} photo rows and ${folders} folder rows whose paths are missing? ` +
-                                'This cannot be undone.'
-                            )
-                          )
-                            return
-                          runAction(
-                            'prune-missing',
-                            () => library.maintenance.pruneMissing(),
-                            'Orphans pruned',
-                            (r) =>
-                              `${r.deleted ?? 0} photos + ${r.deleted_folders ?? 0} folders deleted`
-                          )
-                        }}
-                      >
-                        <AlertTriangle className="h-4 w-4" />
-                        Prune
-                      </ActionButton>
-                    </div>
-                  </div>
-                )}
-
-              {/* Per-worker breakdown */}
-              {workerStatus && workerStatus.workers.length > 0 && (
-                <div className="mt-3 space-y-2">
-                  <div className="text-[10px] uppercase tracking-wide text-text-muted">
-                    Worker fleet
-                  </div>
-                  {workerStatus.workers.map((w) => (
-                    <div
-                      key={w.name}
-                      className="rounded border border-border bg-surface p-2 text-xs"
-                    >
-                      <div className="flex items-center justify-between">
-                        <div className="flex items-center gap-2">
-                          {w.status === 'online' ? (
-                            <CheckCircle2 className="h-3.5 w-3.5 text-pick" />
-                          ) : (
-                            <AlertCircle className="h-3.5 w-3.5 text-reject" />
-                          )}
-                          <span className="font-mono text-text">{w.name}</span>
-                        </div>
-                        <span className="text-text-muted">
-                          {w.active}/{w.concurrency ?? '?'} active
-                        </span>
-                      </div>
-                      <div className="mt-1 flex flex-wrap gap-x-3 gap-y-0.5 text-[10px] text-text-muted">
-                        <span>reserved: {w.reserved}</span>
-                        <span>scheduled: {w.scheduled}</span>
-                        {w.queues.length > 0 && (
-                          <span>queues: {w.queues.join(', ')}</span>
-                        )}
-                      </div>
-                      {w.active_tasks.length > 0 && (
-                        <div className="mt-1.5 space-y-0.5 border-t border-border pt-1.5">
-                          {w.active_tasks.map((t) => (
-                            <div
-                              key={t.id}
-                              className="truncate font-mono text-[10px] text-text-muted"
-                              title={`${t.name} ${JSON.stringify(t.args)}`}
-                            >
-                              <span className="text-text">{t.name}</span>{' '}
-                              {Array.isArray(t.args)
-                                ? t.args.map((a) => String(a)).join(', ')
-                                : ''}
-                            </div>
-                          ))}
-                        </div>
-                      )}
-                    </div>
-                  ))}
-                </div>
-              )}
-
-              {/* Recent task failures */}
-              {workerStatus && workerStatus.failures.recent.length > 0 && (
-                <div className="mt-3">
-                  <div className="mb-1 flex items-center justify-between">
-                    <div className="text-[10px] uppercase tracking-wide text-text-muted">
-                      Recent failures ({workerStatus.failures.total})
-                    </div>
-                    {workerStatus.failures.recent.length > 5 && (
-                      <button
-                        onClick={() => setShowAllErrors((v) => !v)}
-                        className="text-[10px] text-text-muted hover:text-text"
-                      >
-                        {showAllErrors ? 'Show less' : 'Show all'}
-                      </button>
-                    )}
-                  </div>
-                  <div className="max-h-48 space-y-1 overflow-y-auto rounded border border-border bg-surface p-2">
-                    {(showAllErrors
-                      ? workerStatus.failures.recent
-                      : workerStatus.failures.recent.slice(0, 5)
-                    ).map((f) => (
-                      <div
-                        key={f.photo_id}
-                        className="border-b border-border/40 pb-1 last:border-b-0 last:pb-0"
-                      >
-                        <div className="flex items-center justify-between gap-2 text-[11px]">
-                          <span className="truncate font-mono text-text">
-                            {f.filename}
-                          </span>
-                          <span className="shrink-0 text-[10px] text-text-muted">
-                            {f.media_type}
-                          </span>
-                        </div>
-                        <div className="break-all font-mono text-[10px] text-reject">
-                          {f.error || '(no error message)'}
-                        </div>
-                      </div>
-                    ))}
-                  </div>
-                </div>
-              )}
-
-              {/* Recent scan errors (Redis list) */}
-              {workerStatus && workerStatus.scan_errors.length > 0 && (
-                <div className="mt-3">
-                  <div className="mb-1 text-[10px] uppercase tracking-wide text-text-muted">
-                    Scan errors
-                  </div>
-                  <div className="max-h-32 space-y-0.5 overflow-y-auto rounded border border-border bg-surface p-2 font-mono text-[10px] text-reject">
-                    {workerStatus.scan_errors.map((e, i) => (
-                      <div key={i} className="break-all">
-                        {e}
-                      </div>
-                    ))}
-                  </div>
-                </div>
-              )}
-
-              {!workerStatus && (
-                <div className="mt-3 flex items-center gap-2 text-xs text-text-muted">
-                  <Loader2 className="h-3 w-3 animate-spin" />
-                  Loading worker status…
-                </div>
-              )}
-            </Section>
-
-            {/* ----------------------------------------------------- */}
-            {/* Data integrity                                         */}
-            {/* ----------------------------------------------------- */}
-            <Section
-              icon={<Wrench className="h-4 w-4" />}
-              title="Maintenance"
-            >
-              <p className="text-xs text-text-muted">
-                Re-runs the source-roots / folders / photos integrity
-                cleanup that normally only runs on backend startup. Safe
-                to run any time.
-              </p>
-              <div className="mt-2">
-                <ActionButton
-                  loading={busy.cleanup}
-                  onClick={() =>
-                    runAction(
-                      'cleanup',
-                      () => library.maintenance.cleanup(),
-                      'Data integrity cleanup complete'
-                    )
-                  }
-                >
-                  <Wrench className="h-4 w-4" />
-                  Run data integrity cleanup
-                </ActionButton>
-              </div>
-            </Section>
-          </div>
-        </div>
-      </div>
-    </div>
-  )
-}
-
-// ---------------------------------------------------------------------------
-// Local presentational helpers — kept private to this file.
-// ---------------------------------------------------------------------------
-
-function Section({
-  icon,
-  title,
-  right,
-  children,
-}: {
-  icon: React.ReactNode
-  title: string
-  right?: React.ReactNode
-  children: React.ReactNode
-}) {
-  return (
-    <section className="mb-5 last:mb-0">
-      <div className="mb-2 flex items-center justify-between">
-        <h3 className="flex items-center gap-2 text-sm font-medium text-text">
-          {icon}
-          {title}
-        </h3>
-        {right}
-      </div>
-      <div className="rounded border border-border bg-bg p-3">{children}</div>
-    </section>
-  )
-}
-
-function Stat({
-  label,
-  value,
-  tone = 'muted',
-}: {
-  label: string
-  value: number | string | undefined
-  tone?: 'ok' | 'warn' | 'muted'
-}) {
-  const toneClass =
-    tone === 'ok'
-      ? 'text-pick'
-      : tone === 'warn'
-        ? 'text-reject'
-        : 'text-text'
-  return (
-    <div className="rounded bg-surface p-2">
-      <div className="text-[10px] uppercase tracking-wide text-text-muted">
-        {label}
-      </div>
-      <div className={clsx('text-base font-semibold', toneClass)}>
-        {value ?? '—'}
-      </div>
-    </div>
-  )
-}
-
-function ErrorBanner({ title, detail }: { title: string; detail: string }) {
-  return (
-    <div className="mt-3 rounded border border-reject/40 bg-reject/10 p-2 text-xs">
-      <div className="flex items-center gap-1.5 font-medium text-reject">
-        <AlertTriangle className="h-3.5 w-3.5" />
-        {title}
-      </div>
-      <div className="mt-0.5 break-all font-mono text-[10px] text-reject/80">
-        {detail}
-      </div>
-    </div>
-  )
-}
-
-function ActionButton({
-  loading,
-  disabled,
-  destructive,
-  onClick,
-  children,
-}: {
-  loading?: boolean
-  disabled?: boolean
-  destructive?: boolean
-  onClick: () => void
-  children: React.ReactNode
-}) {
-  return (
-    <button
-      onClick={onClick}
-      disabled={disabled || loading}
-      className={clsx(
-        'flex items-center gap-2 rounded border px-3 py-1.5 text-xs font-medium transition-colors',
-        destructive
-          ? 'border-reject/40 text-reject hover:bg-reject/10'
-          : 'border-border text-text hover:bg-surface-2',
-        (disabled || loading) && 'cursor-not-allowed opacity-50'
-      )}
-    >
-      {loading && <Loader2 className="h-4 w-4 animate-spin" />}
-      {!loading && children}
-      {loading && (
-        // Re-render only the textual children when loading by stripping
-        // the icon (children[0]) — we keep just the label so the spinner
-        // takes the icon slot.
-        Array.isArray(children) ? children.slice(1) : children
-      )}
-    </button>
-  )
-}

frontend/src/components/discard/DiscardActionBar.tsx

@@ -1,176 +0,0 @@
-import { useState } from 'react'
-import { RotateCcw, Trash2 } from 'lucide-react'
-import { useMutation, useQueryClient } from '@tanstack/react-query'
-import { usePhotoStore } from '../../store/photoStore'
-import { useFilterStore } from '../../store/filterStore'
-import { usePhotosQuery } from '../../hooks/usePhotosQuery'
-import { discard as discardApi, photos as photosApi } from '../../services/api'
-import { toast } from '../ToastContainer'
-import { ConfirmDialog } from '../dialogs/ConfirmDialog'
-import { registerUndoable } from '../../store/undoStore'
-import { LIBRARY_STATS_QUERY_KEY } from '../../hooks/useLibraryStatsQuery'
-
-/**
- * Top-of-timeline bar visible only when the discarded filter is active.
- * Shows a count, lets the user restore the current selection, and lets them
- * permanently empty the discard pile (with confirmation).
- */
-export function DiscardActionBar() {
-  const flag = useFilterStore((s) => s.flag)
-  const selectedPhotos = usePhotoStore((s) => s.selectedPhotos)
-  const clearSelection = usePhotoStore((s) => s.clearSelection)
-  const queryClient = useQueryClient()
-  const { data: photos = [] } = usePhotosQuery()
-
-  const [confirmOpen, setConfirmOpen] = useState(false)
-  const [deleteSelectedOpen, setDeleteSelectedOpen] = useState(false)
-
-  const restoreMutation = useMutation({
-    mutationFn: (ids: string[]) => discardApi.restore(ids),
-    onSuccess: (_, ids) => {
-      registerUndoable(
-        `Restored ${ids.length} photo${ids.length === 1 ? '' : 's'}`,
-        async () => {
-          await photosApi.bulkDiscard(ids)
-          queryClient.invalidateQueries({ queryKey: ['photos'] })
-      queryClient.invalidateQueries({ queryKey: LIBRARY_STATS_QUERY_KEY })
-        }
-      )
-      clearSelection()
-      queryClient.invalidateQueries({ queryKey: ['photos'] })
-      queryClient.invalidateQueries({ queryKey: LIBRARY_STATS_QUERY_KEY })
-    },
-    onError: (e: any) => toast.error('Restore failed', e.message || 'Unknown error'),
-  })
-
-  const deleteSelectedMutation = useMutation({
-    mutationFn: (ids: string[]) => discardApi.deletePermanent(ids),
-    onSuccess: (data: any) => {
-      const count = data?.deleted ?? 0
-      const errors = data?.file_errors ?? 0
-      if (errors > 0) {
-        toast.error(
-          `Deleted with ${errors} error${errors > 1 ? 's' : ''}`,
-          `${count} record${count === 1 ? '' : 's'} deleted; some files could not be removed`
-        )
-      } else {
-        toast.success(
-          'Permanently deleted',
-          `${count} photo${count === 1 ? '' : 's'} removed from disk`
-        )
-      }
-      clearSelection()
-      queryClient.invalidateQueries({ queryKey: ['photos'] })
-      queryClient.invalidateQueries({ queryKey: LIBRARY_STATS_QUERY_KEY })
-      setDeleteSelectedOpen(false)
-    },
-    onError: (e: any) =>
-      toast.error('Delete failed', e.message || 'Unknown error'),
-  })
-
-  const emptyMutation = useMutation({
-    mutationFn: () => discardApi.empty(),
-    onSuccess: (data: any) => {
-      const count = data?.deleted ?? 0
-      const errors = data?.file_errors ?? 0
-      if (errors > 0) {
-        toast.error(
-          `Emptied with ${errors} error${errors > 1 ? 's' : ''}`,
-          `${count} record${count > 1 ? 's' : ''} deleted; some files could not be removed`
-        )
-      } else {
-        toast.success('Discard pile emptied', `${count} photo${count > 1 ? 's' : ''} permanently deleted`)
-      }
-      clearSelection()
-      queryClient.invalidateQueries({ queryKey: ['photos'] })
-      queryClient.invalidateQueries({ queryKey: LIBRARY_STATS_QUERY_KEY })
-      setConfirmOpen(false)
-    },
-    onError: (e: any) => toast.error('Empty failed', e.message || 'Unknown error'),
-  })
-
-  if (flag !== 'discarded') return null
-
-  const total = photos.length
-  const selected = selectedPhotos.length
-
-  return (
-    <>
-      <div className="flex items-center justify-between gap-3 border-b border-border bg-reject/10 px-4 py-2 text-sm">
-        <div className="flex items-center gap-2 text-text">
-          <Trash2 className="h-4 w-4 text-reject" />
-          <span className="font-medium">Discarded</span>
-          <span className="text-text-muted">
-            {total} photo{total === 1 ? '' : 's'}
-          </span>
-        </div>
-
-        <div className="flex items-center gap-2">
-          {selected > 0 && (
-            <>
-              <button
-                onClick={() => restoreMutation.mutate(selectedPhotos)}
-                disabled={restoreMutation.isPending}
-                className="flex items-center gap-1.5 rounded bg-surface-2 px-3 py-1 text-text hover:bg-surface-offset disabled:opacity-50"
-                title="Restore selected (U)"
-              >
-                <RotateCcw className="h-3.5 w-3.5" />
-                Restore {selected}
-              </button>
-              <button
-                onClick={() => setDeleteSelectedOpen(true)}
-                disabled={deleteSelectedMutation.isPending}
-                className="flex items-center gap-1.5 rounded bg-reject/20 px-3 py-1 text-reject hover:bg-reject/30 disabled:opacity-50"
-                title="Permanently delete selected"
-              >
-                <Trash2 className="h-3.5 w-3.5" />
-                Delete {selected}
-              </button>
-            </>
-          )}
-          <button
-            onClick={() => setConfirmOpen(true)}
-            disabled={total === 0 || emptyMutation.isPending}
-            className="flex items-center gap-1.5 rounded bg-reject/20 px-3 py-1 text-reject hover:bg-reject/30 disabled:opacity-50"
-            title="Permanently delete all discarded photos and files"
-          >
-            <Trash2 className="h-3.5 w-3.5" />
-            Empty discard pile
-          </button>
-        </div>
-      </div>
-
-      <ConfirmDialog
-        isOpen={deleteSelectedOpen}
-        title={`Delete ${selected} photo${selected === 1 ? '' : 's'}?`}
-        message={
-          <>
-            This will <strong className="text-text">permanently delete</strong>{' '}
-            {selected} photo{selected === 1 ? '' : 's'} and remove the file
-            {selected === 1 ? '' : 's'} from disk. This cannot be undone.
-          </>
-        }
-        confirmLabel="Delete"
-        destructive
-        onConfirm={() => deleteSelectedMutation.mutate(selectedPhotos)}
-        onClose={() => setDeleteSelectedOpen(false)}
-      />
-
-      <ConfirmDialog
-        isOpen={confirmOpen}
-        title="Empty discard pile?"
-        message={
-          <>
-            This will <strong className="text-text">permanently delete</strong>{' '}
-            {total} photo{total === 1 ? '' : 's'} and remove the file
-            {total === 1 ? '' : 's'} from disk. This cannot be undone.
-          </>
-        }
-        confirmLabel="Empty pile"
-        destructive
-        onConfirm={() => emptyMutation.mutate()}
-        onClose={() => setConfirmOpen(false)}
-      />
-    </>
-  )
-}

frontend/src/components/duplicates/DuplicatesView.tsx

@@ -1,433 +0,0 @@
-import { useMemo, useState, useEffect, useCallback } from 'react'
-import { Copy, Layers, Sparkles, Trash2, Loader2, Info, Crown } from 'lucide-react'
-import clsx from 'clsx'
-import { useMutation, useQueryClient } from '@tanstack/react-query'
-import {
-  useDuplicateGroupsQuery,
-  DUPLICATE_GROUPS_QUERY_KEY,
-} from '../../hooks/useDuplicateGroupsQuery'
-import {
-  photos as photosApi,
-  type DuplicateGroup,
-  type DuplicateGroupMember,
-} from '../../services/api'
-import {
-  PhotoThumbnail,
-  THUMB_BADGE_BASE,
-  THUMB_BADGE_ICON,
-  THUMB_BADGE_NEUTRAL,
-  THUMB_BADGE_PICK,
-} from '../timeline/PhotoThumbnail'
-import { usePhotoStore } from '../../store/photoStore'
-import { registerUndoable } from '../../store/undoStore'
-import { LIBRARY_STATS_QUERY_KEY } from '../../hooks/useLibraryStatsQuery'
-import { toast } from '../ToastContainer'
-import type { Photo } from '../../types/photo'
-
-/**
- * Sectioned grid view of duplicate clusters. Replaces the old flat
- * "is_duplicate=true" timeline. Each section is one cluster the
- * regroup_duplicates task identified — header on top with a count and a
- * "keep best, discard rest" button, members rendered as PhotoThumbnail
- * cards below.
- *
- * Mounted from App.tsx in place of <Timeline /> when the user is in the
- * duplicates section. Touches no filter store state.
- */
-export function DuplicatesView() {
-  const { data, isLoading, isError, error } = useDuplicateGroupsQuery()
-  const queryClient = useQueryClient()
-  const openPreview = usePhotoStore((s) => s.openPreview)
-  const selectPhoto = usePhotoStore((s) => s.selectPhoto)
-  const selectedPhotos = usePhotoStore((s) => s.selectedPhotos)
-  const activePhotoId = usePhotoStore((s) => s.activePhotoId)
-
-  // Bulk discard with the same undoable wrapper the timeline uses, so
-  // Cmd+Z restores the discarded copies. invalidate ['library', 'duplicates']
-  // so the group disappears from the view immediately.
-  const discardMutation = useMutation({
-    mutationFn: (ids: string[]) => photosApi.bulkDiscard(ids),
-    onSuccess: (_, ids) => {
-      registerUndoable(
-        `Discarded ${ids.length} duplicate${ids.length === 1 ? '' : 's'}`,
-        async () => {
-          await photosApi.bulkRestore(ids)
-          queryClient.invalidateQueries({ queryKey: ['photos'] })
-          queryClient.invalidateQueries({ queryKey: DUPLICATE_GROUPS_QUERY_KEY })
-          queryClient.invalidateQueries({ queryKey: LIBRARY_STATS_QUERY_KEY })
-        }
-      )
-      queryClient.invalidateQueries({ queryKey: ['photos'] })
-      queryClient.invalidateQueries({ queryKey: DUPLICATE_GROUPS_QUERY_KEY })
-      queryClient.invalidateQueries({ queryKey: LIBRARY_STATS_QUERY_KEY })
-    },
-    onError: (e: any) =>
-      toast.error('Discard failed', e?.message || 'Unknown error'),
-  })
-
-  // Hooks below this point must run on every render — rules of hooks
-  // forbid early returns above any useState/useEffect/useMemo. The early
-  // loading/error/empty branches sit AFTER the hook block.
-  const groups = data?.groups ?? []
-
-  // Flat sequence of member ids in visual order. Drives both preview
-  // navigation and the in-grid keyboard walker. useMemo so the keyboard
-  // effect doesn't tear down on every render.
-  const allMemberIds = useMemo(
-    () => groups.flatMap((g) => g.members.map((m) => m.id)),
-    [groups]
-  )
-
-  // Track the rendered column count of the duplicates grid so ↑/↓ can
-  // skip a row instead of jumping a single cell. The grid uses
-  // `repeat(auto-fill, minmax(180px, 1fr))` so columns = floor(width/180).
-  // We measure the FIRST section's grid container — every section uses
-  // the same auto-fill rule so any one is representative.
-  const [columns, setColumns] = useState(4)
-  const sampleGridRef = useCallback((el: HTMLDivElement | null) => {
-    if (!el) return
-    const measure = () => {
-      const cols = Math.max(1, Math.floor(el.clientWidth / 180))
-      setColumns(cols)
-    }
-    measure()
-    const ro = new ResizeObserver(measure)
-    ro.observe(el)
-    // Caller doesn't get the cleanup hook but ResizeObserver disconnects
-    // when the element unmounts, which is fine for our lifecycle.
-  }, [])
-
-  // Window-level keyboard nav. Mirrors Timeline's handler but walks
-  // `allMemberIds` directly — duplicate groups don't have a uniform row
-  // grid so we approximate ↑/↓ via the measured `columns` count and
-  // wrap ←/→ across group boundaries.
-  useEffect(() => {
-    if (allMemberIds.length === 0) return
-
-    const onKeyDown = (e: KeyboardEvent) => {
-      const target = e.target as HTMLElement | null
-      if (target && (target.tagName === 'INPUT' || target.tagName === 'TEXTAREA')) {
-        return
-      }
-      const key = e.key
-      if (
-        key !== 'ArrowLeft' &&
-        key !== 'ArrowRight' &&
-        key !== 'ArrowUp' &&
-        key !== 'ArrowDown'
-      ) {
-        return
-      }
-      e.preventDefault()
-      const currentIdx = activePhotoId ? allMemberIds.indexOf(activePhotoId) : -1
-      const startIdx = currentIdx >= 0 ? currentIdx : 0
-      let nextIdx = startIdx
-      if (key === 'ArrowLeft') nextIdx = startIdx - 1
-      else if (key === 'ArrowRight') nextIdx = startIdx + 1
-      else if (key === 'ArrowUp') nextIdx = startIdx - columns
-      else if (key === 'ArrowDown') nextIdx = startIdx + columns
-      // Clamp to bounds — we don't wrap on out-of-range vertical moves
-      // since the grid is partitioned into groups and a "wrap" would
-      // skip across visually unrelated content.
-      nextIdx = Math.max(0, Math.min(allMemberIds.length - 1, nextIdx))
-      const nextId = allMemberIds[nextIdx]
-      if (!nextId) return
-      selectPhoto(nextId)
-      // Scroll the now-active cell into view if it's off-screen. The
-      // PhotoThumbnail wrapper carries data-dup-id so we can find it
-      // without threading refs through every cell.
-      const el = document.querySelector<HTMLElement>(
-        `[data-dup-id="${nextId}"]`
-      )
-      el?.scrollIntoView({ block: 'nearest', inline: 'nearest' })
-    }
-
-    window.addEventListener('keydown', onKeyDown)
-    return () => window.removeEventListener('keydown', onKeyDown)
-  }, [allMemberIds, activePhotoId, columns, selectPhoto])
-
-  if (isLoading) {
-    return (
-      <div className="flex h-full items-center justify-center text-text-muted">
-        <Loader2 className="mr-2 h-4 w-4 animate-spin" />
-        Loading duplicate groups…
-      </div>
-    )
-  }
-
-  if (isError) {
-    return (
-      <div className="flex h-full items-center justify-center text-text-muted">
-        Could not load duplicate groups: {(error as any)?.message ?? 'unknown error'}
-      </div>
-    )
-  }
-
-  if (groups.length === 0) {
-    return (
-      <div className="flex h-full flex-col items-center justify-center gap-2 px-6 text-center text-text-muted">
-        <Sparkles className="h-8 w-8" />
-        <div className="text-sm font-medium text-text">No duplicates found</div>
-        <p className="max-w-sm text-xs">
-          Nothing in your library matches another photo at the perceptual-hash
-          level. If you've just added new photos, give the worker a minute and
-          re-run "Re-detect duplicates" from Settings.
-        </p>
-      </div>
-    )
-  }
-
-  return (
-    <div className="h-full overflow-auto bg-bg p-4">
-      <div className="mb-4 flex items-center gap-2 text-xs text-text-muted">
-        <Info className="h-3.5 w-3.5" />
-        <span>
-          {data?.total_groups} group{data?.total_groups === 1 ? '' : 's'} ·{' '}
-          {data?.total_members} photo{data?.total_members === 1 ? '' : 's'}.
-          Click "Keep best" to auto-discard all but the highest-resolution
-          copy of each group. Cmd+Z to undo.
-        </span>
-      </div>
-
-      <div className="space-y-6">
-        {groups.map((group, idx) => (
-          <DuplicateGroupSection
-            key={group.group_id}
-            group={group}
-            onKeepBest={(discardIds) => discardMutation.mutate(discardIds)}
-            onPreviewMember={(memberId) => openPreview(memberId, allMemberIds)}
-            onSelectMember={(memberId) => selectPhoto(memberId)}
-            selectedPhotos={selectedPhotos}
-            isPending={discardMutation.isPending}
-            // Hand the column-measurement ref to the first section only
-            // — every section's grid uses the same auto-fill rule so any
-            // one is representative of the rendered column count.
-            gridRef={idx === 0 ? sampleGridRef : undefined}
-          />
-        ))}
-      </div>
-    </div>
-  )
-}
-
-interface DuplicateGroupSectionProps {
-  group: DuplicateGroup
-  onKeepBest: (discardIds: string[]) => void
-  onPreviewMember: (memberId: string) => void
-  onSelectMember: (memberId: string) => void
-  selectedPhotos: string[]
-  isPending: boolean
-  /** Optional callback ref attached to this section's grid container.
-   *  Used by DuplicatesView to measure the rendered column count for
-   *  ↑/↓ keyboard navigation. Only the first section gets one. */
-  gridRef?: (el: HTMLDivElement | null) => void
-}
-
-function DuplicateGroupSection({
-  group,
-  onKeepBest,
-  onPreviewMember,
-  onSelectMember,
-  selectedPhotos,
-  isPending,
-  gridRef,
-}: DuplicateGroupSectionProps) {
-  // Auto-pick "best" copy: highest pixel count, ties broken by file_size,
-  // then earliest taken_at, then id for determinism. This is just the
-  // default — the user can override it by clicking the crown button on
-  // any other thumbnail (see `manualBestId`).
-  const autoBest = useMemo(() => pickBestMember(group.members), [group.members])
-  // When the user clicks "make this the best" on a non-default thumb,
-  // we override the auto-pick. Local to the section so different groups
-  // remember independent overrides; resets if the group itself changes.
-  const [manualBestId, setManualBestId] = useState<string | null>(null)
-  const bestId =
-    manualBestId && group.members.some((m) => m.id === manualBestId)
-      ? manualBestId
-      : autoBest.id
-  const best = group.members.find((m) => m.id === bestId) ?? autoBest
-  const discardCount = group.member_count - 1
-  const isExact = group.reason === 'exact'
-
-  return (
-    <section className="rounded-lg border border-border bg-surface">
-      <header className="flex items-center justify-between gap-3 border-b border-border px-3 py-2">
-        <div className="flex items-center gap-2 text-sm">
-          {isExact ? (
-            <Copy className="h-4 w-4 text-text-muted" />
-          ) : (
-            <Layers className="h-4 w-4 text-text-muted" />
-          )}
-          <span className="font-medium text-text">
-            {group.member_count} {isExact ? 'exact' : 'similar'} photos
-          </span>
-          <span className="text-xs text-text-faint">
-            keeping: {formatDimensions(best)}
-            {best.file_size != null && ` · ${formatBytes(best.file_size)}`}
-            {manualBestId && manualBestId !== autoBest.id && (
-              <span className="ml-1 text-text-muted">(manual)</span>
-            )}
-          </span>
-        </div>
-        <button
-          onClick={() => {
-            const discardIds = group.members
-              .filter((m) => m.id !== best.id)
-              .map((m) => m.id)
-            if (discardIds.length === 0) return
-            onKeepBest(discardIds)
-          }}
-          disabled={isPending}
-          className={clsx(
-            'flex items-center gap-1.5 rounded border border-border px-2 py-1 text-xs font-medium transition-colors',
-            'hover:border-reject/50 hover:bg-reject/10 hover:text-reject',
-            isPending && 'cursor-not-allowed opacity-50'
-          )}
-          title="Keep the highest-resolution copy and discard the rest"
-        >
-          <Trash2 className="h-3 w-3" />
-          Keep best, discard {discardCount}
-        </button>
-      </header>
-
-      <div
-        ref={gridRef}
-        className="grid gap-1 p-2"
-        style={{
-          gridTemplateColumns:
-            'repeat(auto-fill, minmax(180px, 1fr))',
-        }}
-      >
-        {group.members.map((member) => {
-          const isBest = member.id === best.id
-          return (
-            <div
-              key={member.id}
-              data-dup-id={member.id}
-              className="group/dup relative"
-            >
-              <PhotoThumbnail
-                photo={memberToPhoto(member)}
-                size={180}
-                fill
-                isSelected={selectedPhotos.includes(member.id)}
-                onClick={() => onSelectMember(member.id)}
-                onDoubleClick={() => onPreviewMember(member.id)}
-              />
-              {/* BEST pill — top-right, pick-coloured. Composes the same
-               *  THUMB_BADGE_* family used by PhotoThumbnail so the full
-               *  set of ornaments (selection, rating, flags, BEST) reads
-               *  as one consistent chip system. Inset 1.5 (6px) rather
-               *  than 1 (4px) because these are SIBLINGS of the thumbnail,
-               *  not inside its overflow-hidden box, so they need
-               *  clearance from PhotoThumbnail's outer selection ring. */}
-              {isBest && (
-                <span
-                  className={clsx(
-                    'pointer-events-none absolute right-1.5 top-1.5 z-10 uppercase',
-                    THUMB_BADGE_BASE,
-                    THUMB_BADGE_PICK
-                  )}
-                >
-                  <Crown className={THUMB_BADGE_ICON} />
-                  Best
-                </span>
-              )}
-              {/* "Keep this" — shown on hover for non-best thumbnails.
-               *  Mirrors BEST's placement so the eye doesn't retarget
-               *  while scanning. Starts neutral and shifts to pick on
-               *  hover as a preview of the state it'll set. */}
-              {!isBest && (
-                <button
-                  onClick={(e) => {
-                    e.stopPropagation()
-                    setManualBestId(member.id)
-                  }}
-                  className={clsx(
-                    'absolute right-1.5 top-1.5 z-10 hidden uppercase transition hover:bg-pick group-hover/dup:inline-flex',
-                    THUMB_BADGE_BASE,
-                    THUMB_BADGE_NEUTRAL
-                  )}
-                  title="Keep this one instead"
-                >
-                  <Crown className={THUMB_BADGE_ICON} />
-                  Keep this
-                </button>
-              )}
-              {/* Dimensions chip — bottom-LEFT. Neutral metadata variant
-               *  matches the family. Rare collision with a manual rating
-               *  (also bottom-left) is tolerated: rated duplicates are
-               *  uncommon in practice. */}
-              <div
-                className={clsx(
-                  'pointer-events-none absolute bottom-1 left-1 z-10 font-mono',
-                  THUMB_BADGE_BASE,
-                  THUMB_BADGE_NEUTRAL
-                )}
-              >
-                {formatDimensions(member)}
-              </div>
-            </div>
-          )
-        })}
-      </div>
-    </section>
-  )
-}
-
-// ── Helpers ──────────────────────────────────────────────────────────────
-
-/** Score a member by (pixels, file_size, -taken_at) and return the winner.
- *  Larger pixel count wins; ties broken by file_size; final tie by earliest
- *  taken_at (more likely the original capture). */
-function pickBestMember(members: DuplicateGroupMember[]): DuplicateGroupMember {
-  return members.reduce((best, m) => {
-    const bestPixels = (best.width ?? 0) * (best.height ?? 0)
-    const mPixels = (m.width ?? 0) * (m.height ?? 0)
-    if (mPixels !== bestPixels) return mPixels > bestPixels ? m : best
-    const bestSize = best.file_size ?? 0
-    const mSize = m.file_size ?? 0
-    if (mSize !== bestSize) return mSize > bestSize ? m : best
-    // Earliest taken_at wins (treat null as far-future).
-    const bestTaken = best.taken_at ?? '9999'
-    const mTaken = m.taken_at ?? '9999'
-    if (mTaken !== bestTaken) return mTaken < bestTaken ? m : best
-    return best
-  })
-}
-
-function formatDimensions(m: DuplicateGroupMember): string {
-  if (!m.width || !m.height) return '?'
-  const mp = (m.width * m.height) / 1_000_000
-  if (mp >= 1) return `${mp.toFixed(1)}MP`
-  return `${m.width}×${m.height}`
-}
-
-function formatBytes(n: number): string {
-  if (n >= 1024 * 1024) return `${(n / (1024 * 1024)).toFixed(1)}MB`
-  if (n >= 1024) return `${(n / 1024).toFixed(0)}KB`
-  return `${n}B`
-}
-
-/** Adapt a DuplicateGroupMember (the slim API shape) to a Photo, which
- *  is what PhotoThumbnail expects. We deliberately set is_duplicate=false
- *  on the synthetic Photo so the duplicate badge isn't drawn on every
- *  cell — the entire view is duplicates, the badge would be redundant. */
-function memberToPhoto(m: DuplicateGroupMember): Photo {
-  return {
-    id: m.id,
-    filepath: m.filename, // good enough for the RAW/video extension regex
-    filename: m.filename,
-    media_type: m.media_type,
-    width: m.width,
-    height: m.height,
-    taken_at: m.taken_at,
-    rating: 0,
-    is_discarded: false,
-    is_duplicate: false,
-    file_hash: m.file_hash ?? '',
-    folder_id: m.folder_id,
-    added_at: null,
-    thumb_small: m.thumb_small ?? undefined,
-  }
-}

frontend/src/components/filter/FilterBar.tsx

@@ -1,409 +0,0 @@
-import { useEffect, useRef, useState } from 'react'
-import { Star, X, ArrowDown, ArrowUp, Search } from 'lucide-react'
-import clsx from 'clsx'
-import {
-  useFilterStore,
-  hasActiveFilters,
-  type MediaType,
-  type SortField,
-} from '../../store/filterStore'
-import { useTagsQuery } from '../../hooks/useTagsQuery'
-import { FilterPill } from './FilterPill'
-import { COLOR_LABEL_OPTIONS } from '../../constants/colorLabels'
-
-const SEARCH_DEBOUNCE_MS = 300
-
-const MEDIA_TYPES: { value: MediaType; label: string }[] = [
-  { value: 'photo', label: 'Photo' },
-  { value: 'video', label: 'Video' },
-  { value: 'raw', label: 'RAW' },
-  { value: 'heic', label: 'HEIC' },
-]
-
-const SORT_OPTIONS: { value: SortField; label: string }[] = [
-  { value: 'taken_at', label: 'Date taken' },
-  { value: 'added_at', label: 'Date added' },
-  { value: 'filename', label: 'Filename' },
-  { value: 'file_size', label: 'File size' },
-  { value: 'rating', label: 'Rating' },
-]
-
-/**
- * Compact, always-visible filter toolbar built out of FilterPill primitives.
- * Each pill represents a filter category, opens a popover with the
- * underlying control, and shows a short value summary inline when active.
- * Replaces the old expandable FilterBar + ActiveFilterChips combo.
- */
-export function FilterBar() {
-  const filterState = useFilterStore()
-  const dateFrom = useFilterStore((s) => s.dateFrom)
-  const dateTo = useFilterStore((s) => s.dateTo)
-  const mediaTypes = useFilterStore((s) => s.mediaTypes)
-  const ratingMin = useFilterStore((s) => s.ratingMin)
-  const colorLabel = useFilterStore((s) => s.colorLabel)
-  const flag = useFilterStore((s) => s.flag)
-  const sortBy = useFilterStore((s) => s.sortBy)
-  const sortOrder = useFilterStore((s) => s.sortOrder)
-  const tagIds = useFilterStore((s) => s.tagIds)
-  const currentSection = useFilterStore((s) => s.currentSection)
-
-  // Only the Flag pill is hidden inside the Discarded section. Flag has
-  // exactly two values and the section locks one of them, so the pill
-  // would only ever toggle the section off — useless. Rating + Tags
-  // pills stay visible in their sections because the user can refine
-  // them further (ratingMin >= 3, restrict to specific tag ids).
-  const hideFlagPill = currentSection === 'discarded'
-
-  const setDateFrom = useFilterStore((s) => s.setDateFrom)
-  const setDateTo = useFilterStore((s) => s.setDateTo)
-  const toggleMediaType = useFilterStore((s) => s.toggleMediaType)
-  const setRatingMin = useFilterStore((s) => s.setRatingMin)
-  const setColorLabel = useFilterStore((s) => s.setColorLabel)
-  const setFlag = useFilterStore((s) => s.setFlag)
-  const setTagIds = useFilterStore((s) => s.setTagIds)
-  const toggleTagId = useFilterStore((s) => s.toggleTagId)
-  const setSortBy = useFilterStore((s) => s.setSortBy)
-  const toggleSortOrder = useFilterStore((s) => s.toggleSortOrder)
-  const clearAll = useFilterStore((s) => s.clearAll)
-
-  const { data: allTags = [] } = useTagsQuery()
-
-  // Search box. Local state mirrors the store so typing stays responsive
-  // while we debounce store writes (each store write triggers a re-fetch).
-  const storeQ = useFilterStore((s) => s.q)
-  const setStoreQ = useFilterStore((s) => s.setQ)
-  const [searchQuery, setSearchQuery] = useState(storeQ)
-  useEffect(() => {
-    setSearchQuery(storeQ)
-  }, [storeQ])
-  const debounceRef = useRef<number | null>(null)
-  useEffect(() => {
-    if (searchQuery === storeQ) return
-    if (debounceRef.current) window.clearTimeout(debounceRef.current)
-    debounceRef.current = window.setTimeout(() => {
-      setStoreQ(searchQuery)
-    }, SEARCH_DEBOUNCE_MS)
-    return () => {
-      if (debounceRef.current) window.clearTimeout(debounceRef.current)
-    }
-  }, [searchQuery, storeQ, setStoreQ])
-
-  // Pre-compute pill values + active flags so the JSX stays terse.
-  const dateActive = dateFrom !== null || dateTo !== null
-  const dateValue = dateActive
-    ? `${dateFrom ?? '…'} → ${dateTo ?? '…'}`
-    : null
-
-  const typeActive = mediaTypes.length > 0
-  const typeValue = typeActive
-    ? mediaTypes.map((t) => t.toUpperCase()).join(', ')
-    : null
-
-  const ratingActive = ratingMin > 0
-  const ratingValue = ratingActive ? `≥ ${ratingMin}★` : null
-
-  const colorActive = colorLabel !== null
-  const colorValue = colorActive ? colorLabel : null
-
-  const flagActive = flag !== 'any'
-  const flagValue = flagActive ? flag : null
-
-  const tagActive = tagIds.length > 0
-  const activeTagNames = allTags
-    .filter((t) => tagIds.includes(t.id))
-    .map((t) => t.name)
-  const tagValue = tagActive
-    ? activeTagNames.length <= 2
-      ? activeTagNames.join(', ')
-      : `${activeTagNames.slice(0, 2).join(', ')} +${activeTagNames.length - 2}`
-    : null
-
-  const sortLabel = SORT_OPTIONS.find((o) => o.value === sortBy)?.label ?? sortBy
-  const sortValue = `${sortLabel} ${sortOrder === 'desc' ? '↓' : '↑'}`
-
-  const anyActive = hasActiveFilters(filterState)
-
-  return (
-    // Fixed bar height + py-0 so neither the active filter pills nor the
-    // clear-all button can stretch the bar vertically. The fixed h-11
-    // matches the h-7 pills + 8px symmetric vertical padding.
-    <div className="flex h-11 items-center gap-3 border-b border-border bg-surface px-3 py-0">
-      {/* Pills — left side, scroll horizontally if they overflow. */}
-      <div className="flex min-w-0 flex-1 items-center gap-1.5 overflow-x-auto">
-      {/* Date */}
-      <FilterPill
-        label="Date"
-        value={dateValue}
-        isActive={dateActive}
-        onClear={() => {
-          setDateFrom(null)
-          setDateTo(null)
-        }}
-      >
-        <div className="space-y-2">
-          <div>
-            <label className="mb-1 block text-[11px] text-text-muted">From</label>
-            <input
-              type="date"
-              value={dateFrom ?? ''}
-              onChange={(e) => setDateFrom(e.target.value || null)}
-              className="w-full rounded border border-border bg-bg px-2 py-1 text-xs text-text"
-            />
-          </div>
-          <div>
-            <label className="mb-1 block text-[11px] text-text-muted">To</label>
-            <input
-              type="date"
-              value={dateTo ?? ''}
-              onChange={(e) => setDateTo(e.target.value || null)}
-              className="w-full rounded border border-border bg-bg px-2 py-1 text-xs text-text"
-            />
-          </div>
-        </div>
-      </FilterPill>
-
-      {/* Type */}
-      <FilterPill
-        label="Type"
-        value={typeValue}
-        isActive={typeActive}
-        onClear={() => mediaTypes.forEach((t) => toggleMediaType(t))}
-      >
-        <div className="flex flex-wrap gap-1">
-          {MEDIA_TYPES.map(({ value, label }) => {
-            const active = mediaTypes.includes(value)
-            return (
-              <button
-                key={value}
-                onClick={() => toggleMediaType(value)}
-                className={clsx(
-                  'rounded px-2 py-1 text-xs transition-colors',
-                  active
-                    ? 'bg-primary text-white'
-                    : 'bg-surface-2 text-text-muted hover:bg-surface-offset hover:text-text'
-                )}
-              >
-                {label}
-              </button>
-            )
-          })}
-        </div>
-      </FilterPill>
-
-      {/* Rating */}
-      <FilterPill
-        label="Rating"
-        value={ratingValue}
-        isActive={ratingActive}
-        onClear={() => setRatingMin(0)}
-      >
-        <div>
-          <p className="mb-1 text-[11px] text-text-muted">Minimum</p>
-          <div className="flex gap-1">
-            {[1, 2, 3, 4, 5].map((n) => (
-              <button
-                key={n}
-                onClick={() => setRatingMin(ratingMin === n ? 0 : n)}
-                className="p-0.5"
-                title={`At least ${n} star${n > 1 ? 's' : ''}`}
-              >
-                <Star
-                  className={clsx(
-                    'h-5 w-5 transition-colors',
-                    n <= ratingMin
-                      ? 'fill-star text-star'
-                      : 'text-text-muted hover:text-star'
-                  )}
-                />
-              </button>
-            ))}
-          </div>
-        </div>
-      </FilterPill>
-
-      {/* Color */}
-      <FilterPill
-        label="Color"
-        value={colorValue}
-        isActive={colorActive}
-        onClear={() => setColorLabel(null)}
-      >
-        <div className="flex items-center gap-1.5">
-          {COLOR_LABEL_OPTIONS.map(({ value, className }) => {
-            const active = colorLabel === value
-            return (
-              <button
-                key={value}
-                onClick={() => setColorLabel(active ? null : value)}
-                className={clsx(
-                  'h-5 w-5 rounded-full ring-offset-2 ring-offset-surface transition-all',
-                  className,
-                  active ? 'ring-2 ring-primary' : 'opacity-60 hover:opacity-100'
-                )}
-                title={value}
-              />
-            )
-          })}
-          {colorLabel && (
-            <button
-              onClick={() => setColorLabel(null)}
-              className="ml-1 rounded p-0.5 text-text-muted hover:bg-surface-2 hover:text-text"
-              title="Clear color"
-            >
-              <X className="h-3 w-3" />
-            </button>
-          )}
-        </div>
-      </FilterPill>
-
-      {/* Flag — hidden in the Discarded section, where the flag is
-       *  pinned to "discarded" by the section preset. */}
-      {!hideFlagPill && (
-        <FilterPill
-          label="Flag"
-          value={flagValue}
-          isActive={flagActive}
-          onClear={() => setFlag('any')}
-        >
-          <div className="flex flex-col gap-1">
-            <button
-              onClick={() => setFlag('any')}
-              className={clsx(
-                'rounded px-2 py-1 text-left text-xs transition-colors',
-                flag === 'any'
-                  ? 'bg-primary text-white'
-                  : 'bg-surface-2 text-text-muted hover:bg-surface-offset hover:text-text'
-              )}
-            >
-              Any
-            </button>
-            <button
-              onClick={() => setFlag('discarded')}
-              className={clsx(
-                'rounded px-2 py-1 text-left text-xs transition-colors',
-                flag === 'discarded'
-                  ? 'bg-primary text-white'
-                  : 'bg-surface-2 text-text-muted hover:bg-surface-offset hover:text-text'
-              )}
-            >
-              Discarded
-            </button>
-          </div>
-        </FilterPill>
-      )}
-
-      {/* Tags */}
-      {allTags.length > 0 && (
-        <FilterPill
-          label="Tags"
-          value={tagValue}
-          isActive={tagActive}
-          onClear={() => setTagIds([])}
-        >
-          <div className="flex max-h-60 flex-wrap gap-1 overflow-y-auto">
-            {allTags.map((tag) => {
-              const active = tagIds.includes(tag.id)
-              return (
-                <button
-                  key={tag.id}
-                  onClick={() => toggleTagId(tag.id)}
-                  className={clsx(
-                    'rounded px-2 py-1 text-xs transition-colors',
-                    active
-                      ? 'bg-primary text-white'
-                      : 'bg-surface-2 text-text-muted hover:bg-surface-offset hover:text-text'
-                  )}
-                >
-                  {tag.name}
-                </button>
-              )
-            })}
-          </div>
-        </FilterPill>
-      )}
-
-      {/* Sort — always present, never "active/inactive" since there's
-          always a value. */}
-      <FilterPill label="Sort" value={sortValue} isActive>
-        <div className="space-y-2">
-          <select
-            value={sortBy}
-            onChange={(e) => setSortBy(e.target.value as SortField)}
-            className="w-full rounded border border-border bg-bg px-2 py-1 text-xs text-text focus:border-primary focus:outline-none"
-          >
-            {SORT_OPTIONS.map((opt) => (
-              <option key={opt.value} value={opt.value}>
-                {opt.label}
-              </option>
-            ))}
-          </select>
-          <button
-            onClick={toggleSortOrder}
-            className="flex w-full items-center justify-center gap-1 rounded bg-surface-2 px-2 py-1 text-xs text-text-muted hover:bg-surface-offset hover:text-text"
-          >
-            {sortOrder === 'desc' ? (
-              <>
-                <ArrowDown className="h-3.5 w-3.5" />
-                Descending
-              </>
-            ) : (
-              <>
-                <ArrowUp className="h-3.5 w-3.5" />
-                Ascending
-              </>
-            )}
-          </button>
-        </div>
-      </FilterPill>
-
-      {/* Clear-all — borderless text affordance pinned next to the pill
-       *  cluster on the right. Lives inside the pills container so it
-       *  shares the same flex group and gap and reads as "another
-       *  pill". Only renders when any filter is active. */}
-      {anyActive && (
-        <button
-          onClick={clearAll}
-          className="ml-1 flex h-7 flex-shrink-0 items-center whitespace-nowrap px-1 text-xs text-text-muted underline-offset-2 hover:text-text hover:underline"
-          title="Clear all filters in this section"
-        >
-          Clear all
-        </button>
-      )}
-      </div>
-
-      {/* Search — pinned to the right edge of the bar. Same id as before
-       *  so the global "/" focus shortcut still finds it. */}
-      <div className="relative w-56 flex-shrink-0">
-        <Search className="pointer-events-none absolute left-2.5 top-1/2 h-3.5 w-3.5 -translate-y-1/2 text-text-muted" />
-        <input
-          id="topbar-search"
-          type="text"
-          value={searchQuery}
-          onChange={(e) => setSearchQuery(e.target.value)}
-          onKeyDown={(e) => {
-            if (e.key === 'Escape') {
-              setSearchQuery('')
-              setStoreQ('')
-              e.currentTarget.blur()
-            }
-          }}
-          placeholder="Search photos…"
-          className="h-7 w-full rounded-full border border-border bg-surface-2 pl-8 pr-7 text-xs text-text placeholder-text-muted focus:border-primary focus:outline-none"
-        />
-        {searchQuery && (
-          <button
-            onClick={() => {
-              setSearchQuery('')
-              setStoreQ('')
-            }}
-            className="absolute right-1.5 top-1/2 -translate-y-1/2 rounded-full p-0.5 text-text-muted hover:bg-surface-offset hover:text-text"
-            title="Clear search (Esc)"
-            aria-label="Clear search"
-          >
-            <X className="h-3 w-3" />
-          </button>
-        )}
-      </div>
-    </div>
-  )
-}

frontend/src/components/filter/FilterPill.tsx

@@ -1,161 +0,0 @@
-import { useEffect, useLayoutEffect, useRef, useState } from 'react'
-import { createPortal } from 'react-dom'
-import { ChevronDown, X } from 'lucide-react'
-import clsx from 'clsx'
-
-interface FilterPillProps {
-  /** Category label, always shown ("Date", "Type", etc.). */
-  label: string
-  /** Currently unused in the rendered output — the inline value display
-   *  was making active pills wider than inactive ones. Kept on the
-   *  interface so callers don't have to change. The value is still
-   *  surfaced via the title attribute for hover discovery. */
-  value?: string | null
-  isActive?: boolean
-  /** When provided + isActive, an X appears inside the pill that clears
-   *  this filter without opening the popover. */
-  onClear?: () => void
-  /** Popover contents — usually the existing control for this filter. */
-  children: React.ReactNode
-  /** Force the popover open programmatically (rare). */
-  defaultOpen?: boolean
-}
-
-/**
- * A toolbar pill that hosts a filter category. Click the pill to open a
- * small popover with the actual control; the popover closes on outside
- * click or Escape. Active filters tint the pill primary and show their
- * current value inline.
- */
-export function FilterPill({
-  label,
-  value,
-  isActive = false,
-  onClear,
-  children,
-  defaultOpen = false,
-}: FilterPillProps) {
-  const [open, setOpen] = useState(defaultOpen)
-  const buttonRef = useRef<HTMLButtonElement>(null)
-  const popoverRef = useRef<HTMLDivElement>(null)
-  const [popoverPos, setPopoverPos] = useState<{ top: number; left: number } | null>(null)
-
-  // Compute the popover's screen position from the trigger button. Done
-  // imperatively (not via CSS absolute) so the popover can live in a portal
-  // and escape the FilterBar's overflow-x-auto clipping. Re-computed on
-  // open, scroll, and resize.
-  useLayoutEffect(() => {
-    if (!open) return
-    const update = () => {
-      const btn = buttonRef.current
-      if (!btn) return
-      const rect = btn.getBoundingClientRect()
-      // Default left-align under the trigger; clamp to viewport so the
-      // last pill on the right doesn't overflow.
-      const popWidth = popoverRef.current?.offsetWidth ?? 240
-      const margin = 8
-      let left = rect.left
-      if (left + popWidth + margin > window.innerWidth) {
-        left = Math.max(margin, window.innerWidth - popWidth - margin)
-      }
-      setPopoverPos({ top: rect.bottom + 4, left })
-    }
-    update()
-    window.addEventListener('resize', update)
-    window.addEventListener('scroll', update, true)
-    return () => {
-      window.removeEventListener('resize', update)
-      window.removeEventListener('scroll', update, true)
-    }
-  }, [open])
-
-  // Close on outside click + Escape. Outside means neither the trigger
-  // button nor the (portaled) popover.
-  useEffect(() => {
-    if (!open) return
-    const onDocMouseDown = (e: MouseEvent) => {
-      const target = e.target as Node
-      if (buttonRef.current?.contains(target)) return
-      if (popoverRef.current?.contains(target)) return
-      setOpen(false)
-    }
-    const onKey = (e: KeyboardEvent) => {
-      if (e.key === 'Escape') setOpen(false)
-    }
-    document.addEventListener('mousedown', onDocMouseDown)
-    document.addEventListener('keydown', onKey)
-    return () => {
-      document.removeEventListener('mousedown', onDocMouseDown)
-      document.removeEventListener('keydown', onKey)
-    }
-  }, [open])
-
-  return (
-    <>
-      <button
-        ref={buttonRef}
-        onClick={() => setOpen((v) => !v)}
-        // Hover to see the active value as a tooltip — keeps the pill at
-        // a constant width regardless of state. The popover is the
-        // canonical place to read/edit the filter value.
-        title={isActive && value ? `${label}: ${value}` : label}
-        className={clsx(
-          // Fixed height + py-0 so neither the X clear icon nor the
-          // chevron can stretch the pill vertically when the active
-          // state swaps them in.
-          'flex h-7 items-center gap-1 rounded-full border px-2.5 py-0 text-xs transition-colors',
-          isActive
-            ? 'border-primary/40 bg-primary/15 text-primary'
-            : 'border-border bg-surface-2 text-text-muted hover:bg-surface-offset hover:text-text'
-        )}
-      >
-        <span className={clsx(isActive && 'font-medium')}>{label}</span>
-        {isActive && onClear ? (
-          <span
-            role="button"
-            tabIndex={0}
-            onClick={(e) => {
-              e.stopPropagation()
-              onClear()
-            }}
-            onKeyDown={(e) => {
-              if (e.key === 'Enter' || e.key === ' ') {
-                e.preventDefault()
-                e.stopPropagation()
-                onClear()
-              }
-            }}
-            // Same h-4 w-4 as the chevron slot below so swapping the
-            // two doesn't change the pill's footprint.
-            className="ml-0.5 inline-flex h-4 w-4 cursor-pointer items-center justify-center rounded-full hover:bg-primary/30"
-            title={`Clear ${label}`}
-            aria-label={`Clear ${label}`}
-          >
-            <X className="h-3 w-3" />
-          </span>
-        ) : (
-          <span className="inline-flex h-4 w-4 items-center justify-center">
-            <ChevronDown className="h-3 w-3 opacity-60" />
-          </span>
-        )}
-      </button>
-
-      {open &&
-        createPortal(
-          <div
-            ref={popoverRef}
-            style={{
-              position: 'fixed',
-              top: popoverPos?.top ?? -9999,
-              left: popoverPos?.left ?? -9999,
-              visibility: popoverPos ? 'visible' : 'hidden',
-            }}
-            className="z-50 min-w-[220px] rounded-lg border border-border bg-surface p-3 shadow-xl"
-          >
-            {children}
-          </div>,
-          document.body
-        )}
-    </>
-  )
-}

frontend/src/components/heaps/ActiveHeapCard.tsx

@@ -1,169 +0,0 @@
-import { useQuery } from '@tanstack/react-query'
-import { motion, AnimatePresence } from 'framer-motion'
-import { ShoppingBasket } from 'lucide-react'
-import { useActiveHeapMembers } from '../../hooks/useActiveHeapMembersQuery'
-import { useFilterStore } from '../../store/filterStore'
-import { photos as photosApi, heaps as heapsApi } from '../../services/api'
-import cardBg from '../../assets/card.png'
-
-/** How many thumbnails fan out across the stack at once. The newest is
- *  drawn last (top), older ones fan back-left and back-right. */
-const STACK_SIZE = 5
-
-/**
- * Pinned card at the bottom of the LeftSidebar showing the currently
- * active heap. Renders nothing when no heap is active — the parent
- * layout collapses around it cleanly.
- *
- * The card is a fast nav shortcut + a satisfying landing spot for the P
- * pick action: every new pick optimistically updates the
- * ['heap-photo-ids', heapId] cache that the existing pick mutation
- * already maintains, so we just subscribe to the same query and let
- * framer-motion's AnimatePresence handle the entrance/exit animation
- * when ids appear or disappear.
- */
-export function ActiveHeapCard() {
-  const { activeHeap } = useActiveHeapMembers()
-  const navigateToSection = useFilterStore((s) => s.navigateToSection)
-
-  // Subscribes to the same cache key the pick mutation optimistically
-  // updates. The data is already fetched (and kept fresh) by
-  // useActiveHeapMembers above; this useQuery just gives us a render-
-  // dependency on the array contents and stable insertion order.
-  const { data: orderedIds = [] } = useQuery<string[]>({
-    queryKey: ['heap-photo-ids', activeHeap?.id],
-    queryFn: () => heapsApi.photoIds(activeHeap!.id),
-    enabled: !!activeHeap,
-    staleTime: 30_000,
-  })
-
-  if (!activeHeap) return null
-
-  // Show the latest STACK_SIZE photos. The backend returns ids in
-  // insertion order so the last one in the array is the most recently
-  // picked — that's the one we want at the front of the stack.
-  const visible = orderedIds.slice(-STACK_SIZE)
-  // We render newest LAST so it draws on top via z-index. Reverse so
-  // index 0 is the back card and index N-1 is the front.
-  const stack = visible.map((id, i) => ({
-    id,
-    // Symmetric fan: front card has rotate=0, x=0; cards behind it
-    // alternate left/right as you walk back through the stack.
-    rotate: stackRotate(i, visible.length),
-    x: stackOffsetX(i, visible.length),
-    y: stackOffsetY(i, visible.length),
-    z: i,
-  }))
-
-  return (
-    <div className="m-1.5 rounded-md border border-border bg-surface-2 shadow-sm">
-      {/* Header — clickable, navigates to the heap section. */}
-      <button
-        onClick={() =>
-          navigateToSection(`heap-${activeHeap.id}`, { heapId: activeHeap.id })
-        }
-        className="flex w-full items-center gap-1.5 rounded-t-md px-2 py-1.5 text-left hover:bg-surface-offset"
-        title={`Open "${activeHeap.name}"`}
-      >
-        <ShoppingBasket className="h-3.5 w-3.5 flex-shrink-0 text-pick" />
-        <span className="min-w-0 flex-1 truncate text-[12px] font-semibold text-text">
-          {activeHeap.name}
-        </span>
-        <span className="flex h-4 min-w-[20px] items-center justify-center rounded bg-surface px-1 text-[10px] font-medium text-text-muted">
-          {orderedIds.length}
-        </span>
-      </button>
-
-      {/* Stack row. Re-keyed on activeHeap.id so switching heaps tears
-       *  the animation context down cleanly instead of trying to
-       *  crossfade unrelated photos. The desert scene sits behind the
-       *  fanned thumbnails — `cover` + `bottom` keeps the dunes anchored
-       *  so the cacti frame the photos rather than the (transparent) sky. */}
-      <div
-        key={activeHeap.id}
-        className="relative h-20 overflow-hidden rounded-b-md px-2 pb-2"
-        style={{
-          backgroundImage: `url(${cardBg})`,
-          backgroundSize: 'cover',
-          backgroundPosition: 'center bottom',
-          backgroundRepeat: 'no-repeat',
-          imageRendering: 'pixelated',
-          opacity: 0.7,
-        }}
-      >
-        {visible.length === 0 ? (
-          <div className="flex h-full items-center justify-center px-2 text-center text-[11px] text-text-faint">
-            Pick photos with P to fill the heap
-          </div>
-        ) : (
-          <div className="relative h-full">
-            <AnimatePresence initial={false}>
-              {stack.map((item) => (
-                <motion.img
-                  key={item.id}
-                  src={photosApi.getThumbnailUrl(item.id, 'small')}
-                  alt=""
-                  initial={{ x: 80, y: 0, scale: 0.6, rotate: 0, opacity: 0 }}
-                  animate={{
-                    x: item.x,
-                    y: item.y,
-                    scale: 1,
-                    rotate: item.rotate,
-                    opacity: 1,
-                  }}
-                  exit={{ x: -60, scale: 0.6, opacity: 0 }}
-                  transition={{ type: 'spring', stiffness: 360, damping: 28 }}
-                  style={{
-                    zIndex: item.z,
-                    position: 'absolute',
-                    left: '50%',
-                    top: '50%',
-                    marginLeft: -26, // half of w-13
-                    marginTop: -26,  // half of h-13
-                  }}
-                  className="h-[52px] w-[52px] rounded object-cover shadow-[0_4px_10px_rgba(0,0,0,0.65),0_2px_4px_rgba(0,0,0,0.5)] ring-1 ring-black/60"
-                />
-              ))}
-            </AnimatePresence>
-          </div>
-        )}
-      </div>
-    </div>
-  )
-}
-
-// ── Stack geometry ───────────────────────────────────────────────────────
-//
-// `i` is the position in the visible array (0 = oldest, last = newest).
-// We want the newest card at center (rotate 0, x 0) and earlier cards
-// fanning symmetrically outward — so we score each card by how far it
-// is from the front, alternating sign.
-
-const X_STEP = 18  // pixels per fan step
-const Y_STEP = 2   // tiny vertical lift so the back cards peek above
-const ROTATE_STEP = 6  // degrees per fan step
-
-function stackRotate(i: number, len: number): number {
-  // Distance from the front (newest). Front card → 0, then alternating
-  // -1, +1, -2, +2 ... to spread cards outward.
-  const fromFront = len - 1 - i
-  if (fromFront === 0) return 0
-  const sign = fromFront % 2 === 1 ? -1 : 1
-  const magnitude = Math.ceil(fromFront / 2)
-  return sign * magnitude * ROTATE_STEP
-}
-
-function stackOffsetX(i: number, len: number): number {
-  const fromFront = len - 1 - i
-  if (fromFront === 0) return 0
-  const sign = fromFront % 2 === 1 ? -1 : 1
-  const magnitude = Math.ceil(fromFront / 2)
-  return sign * magnitude * X_STEP
-}
-
-function stackOffsetY(i: number, len: number): number {
-  // Back cards lift up a couple pixels so they're visible above the
-  // front card's top edge — gives the stack its sense of depth.
-  const fromFront = len - 1 - i
-  return fromFront * -Y_STEP
-}

frontend/src/components/heaps/HeapConvertDialog.tsx

@@ -1,247 +0,0 @@
-import { useState, useEffect, useMemo } from 'react'
-import { useMutation, useQueryClient } from '@tanstack/react-query'
-import { X, Folder, AlertCircle } from 'lucide-react'
-import clsx from 'clsx'
-import {
-  heaps as heapsApi,
-  type Heap,
-  type FolderTreeNode,
-} from '../../services/api'
-import { HEAPS_QUERY_KEY } from '../../hooks/useHeapsQuery'
-import { useFolderTreeQuery } from '../../hooks/useFolderTreeQuery'
-import { toast } from '../ToastContainer'
-
-interface FlatFolder {
-  id: string
-  name: string
-  path: string
-  depth: number
-}
-
-/** Walk the folder tree depth-first into a flat list with depth info so
- *  the picker can render every node — including nested subfolders — as
- *  one indented option. */
-function flattenTree(nodes: FolderTreeNode[], depth = 0): FlatFolder[] {
-  const out: FlatFolder[] = []
-  for (const n of nodes) {
-    out.push({ id: n.id, name: n.name, path: n.path, depth })
-    if (n.children.length > 0) {
-      out.push(...flattenTree(n.children, depth + 1))
-    }
-  }
-  return out
-}
-
-interface HeapConvertDialogProps {
-  heap: Heap | null
-  onClose: () => void
-}
-
-/**
- * Modal that converts a heap into a folder. The user picks a target folder
- * (any source root, today — sub-folder picking is a follow-up), chooses
- * move vs copy semantics, and optionally has the heap deleted on success.
- */
-export function HeapConvertDialog({ heap, onClose }: HeapConvertDialogProps) {
-  const queryClient = useQueryClient()
-  const [targetId, setTargetId] = useState('')
-  const [mode, setMode] = useState<'move' | 'copy'>('move')
-  const [deleteHeap, setDeleteHeap] = useState(false)
-  const [subfolderName, setSubfolderName] = useState('')
-
-  // Use the recursive folder tree, not the flat source-root list, so the
-  // user can pick a sub-folder at any depth as the target.
-  const { data: tree = [] } = useFolderTreeQuery()
-  const folders = useMemo<FlatFolder[]>(() => flattenTree(tree), [tree])
-
-  // Default to the first folder when the dialog opens or folders load.
-  useEffect(() => {
-    if (!targetId && folders.length > 0) {
-      setTargetId(folders[0].id)
-    }
-  }, [folders, targetId])
-
-  // Reset state on close, prefill subfolder name when opened.
-  useEffect(() => {
-    if (heap) {
-      setSubfolderName(heap.name)
-    } else {
-      setTargetId('')
-      setMode('move')
-      setDeleteHeap(false)
-      setSubfolderName('')
-    }
-  }, [heap])
-
-  const convertMutation = useMutation({
-    mutationFn: () =>
-      heapsApi.convert(heap!.id, {
-        target_id: targetId,
-        mode,
-        delete_heap: deleteHeap,
-        // Empty subfolder = drop directly into the parent. Trim and only
-        // send if the user kept it populated.
-        subfolder_name: subfolderName.trim() || null,
-      }),
-    onSuccess: (data) => {
-      const total = (data.moved ?? 0) + (data.copied ?? 0)
-      const verb = data.mode === 'move' ? 'Moved' : 'Copied'
-      toast.success(
-        `${verb} ${total} photo${total === 1 ? '' : 's'}`,
-        data.heap_deleted ? `Heap "${heap?.name}" deleted` : undefined
-      )
-      queryClient.invalidateQueries({ queryKey: HEAPS_QUERY_KEY })
-      queryClient.invalidateQueries({ queryKey: ['photos'] })
-      queryClient.invalidateQueries({ queryKey: ['folders'] })
-      onClose()
-    },
-    onError: (e: any) =>
-      toast.error('Convert failed', e?.response?.data?.detail || e.message),
-  })
-
-  if (!heap) return null
-
-  const targetFolder = folders.find((f) => f.id === targetId)
-
-  return (
-    <div className="fixed inset-0 z-50 flex items-center justify-center">
-      <div className="absolute inset-0 bg-black/60 backdrop-blur-sm" onClick={onClose} />
-
-      <div className="relative z-10 w-full max-w-md rounded-lg border border-border bg-surface p-6 shadow-xl">
-        <div className="mb-4 flex items-center justify-between">
-          <h2 className="text-lg font-semibold text-text">
-            Convert "{heap.name}" to folder
-          </h2>
-          <button
-            onClick={onClose}
-            disabled={convertMutation.isPending}
-            className="rounded p-1 text-text-muted hover:bg-surface-2 hover:text-text"
-          >
-            <X className="h-5 w-5" />
-          </button>
-        </div>
-
-        {/* Target picker */}
-        <div className="mb-4">
-          <label className="mb-1 block text-xs text-text-muted">Target folder</label>
-          {folders.length === 0 ? (
-            <div className="rounded border border-border bg-bg px-3 py-2 text-xs text-text-muted">
-              No folders available
-            </div>
-          ) : (
-            <select
-              value={targetId}
-              onChange={(e) => setTargetId(e.target.value)}
-              className="w-full rounded border border-border bg-bg px-2 py-1.5 text-sm text-text focus:border-primary focus:outline-none"
-            >
-              {folders.map((f) => (
-                <option key={f.id} value={f.id}>
-                  {/* Two non-breaking spaces per depth so nested
-                   *  subfolders read as a tree in the native dropdown. */}
-                  {'\u00A0\u00A0'.repeat(f.depth) + f.name}
-                </option>
-              ))}
-            </select>
-          )}
-          {targetFolder && (
-            <p className="mt-1 flex items-center gap-1 text-xs text-text-faint">
-              <Folder className="h-3 w-3" />
-              {targetFolder.path}
-            </p>
-          )}
-        </div>
-
-        {/* Subfolder name */}
-        <div className="mb-4">
-          <label className="mb-1 block text-xs text-text-muted">
-            Subfolder name
-          </label>
-          <input
-            type="text"
-            value={subfolderName}
-            onChange={(e) => setSubfolderName(e.target.value)}
-            placeholder="(none — use parent directly)"
-            className="w-full rounded border border-border bg-bg px-2 py-1.5 text-sm text-text placeholder-text-faint focus:border-primary focus:outline-none"
-          />
-          <p className="mt-1 text-xs text-text-faint">
-            {subfolderName.trim() && targetFolder
-              ? `Will create ${targetFolder.path}/${subfolderName.trim()} if missing.`
-              : 'Photos go directly into the parent folder.'}
-          </p>
-        </div>
-
-        {/* Mode toggle */}
-        <div className="mb-4">
-          <label className="mb-1 block text-xs text-text-muted">Mode</label>
-          <div className="flex gap-2">
-            <button
-              onClick={() => setMode('move')}
-              className={clsx(
-                'flex-1 rounded px-3 py-1.5 text-sm transition-colors',
-                mode === 'move'
-                  ? 'bg-primary text-white'
-                  : 'bg-surface-2 text-text-muted hover:bg-surface-offset hover:text-text'
-              )}
-            >
-              Move
-            </button>
-            <button
-              onClick={() => setMode('copy')}
-              className={clsx(
-                'flex-1 rounded px-3 py-1.5 text-sm transition-colors',
-                mode === 'copy'
-                  ? 'bg-primary text-white'
-                  : 'bg-surface-2 text-text-muted hover:bg-surface-offset hover:text-text'
-              )}
-            >
-              Copy
-            </button>
-          </div>
-          <p className="mt-1 text-xs text-text-faint">
-            {mode === 'move'
-              ? 'Files are moved on disk; original photos update their folder.'
-              : 'Files are copied on disk; new photo records are created.'}
-          </p>
-        </div>
-
-        {/* Delete heap toggle */}
-        <div className="mb-4 flex items-center gap-2">
-          <input
-            id="delete-heap"
-            type="checkbox"
-            checked={deleteHeap}
-            onChange={(e) => setDeleteHeap(e.target.checked)}
-            className="h-4 w-4 rounded border-border bg-bg text-primary focus:ring-2 focus:ring-primary focus:ring-offset-0"
-          />
-          <label htmlFor="delete-heap" className="text-sm text-text">
-            Delete heap after conversion
-          </label>
-        </div>
-
-        {convertMutation.isError && (
-          <div className="mb-3 flex items-center gap-2 rounded bg-reject/10 p-3 text-sm text-reject">
-            <AlertCircle className="h-4 w-4 flex-shrink-0" />
-            <span>{(convertMutation.error as any)?.message || 'Conversion failed'}</span>
-          </div>
-        )}
-
-        <div className="flex justify-end gap-2">
-          <button
-            onClick={onClose}
-            disabled={convertMutation.isPending}
-            className="rounded bg-surface-2 px-4 py-2 text-sm text-text hover:bg-surface-offset disabled:opacity-50"
-          >
-            Cancel
-          </button>
-          <button
-            onClick={() => convertMutation.mutate()}
-            disabled={!targetId || convertMutation.isPending}
-            className="rounded bg-primary px-4 py-2 text-sm font-medium text-white hover:bg-primary/90 disabled:opacity-50"
-          >
-            {convertMutation.isPending ? 'Converting…' : 'Convert'}
-          </button>
-        </div>
-      </div>
-    </div>
-  )
-}

frontend/src/components/heaps/HeapsPanel.tsx

@@ -1,497 +0,0 @@
-import { useEffect, useRef, useState } from 'react'
-import {
-  ShoppingBasket,
-  Plus,
-  Target,
-  ChevronDown,
-  ChevronRight,
-  FolderOutput,
-  MoreHorizontal,
-  Pencil,
-  Copy,
-  Trash2,
-} from 'lucide-react'
-import clsx from 'clsx'
-import { useMutation, useQueryClient } from '@tanstack/react-query'
-import { useHeapsQuery, HEAPS_QUERY_KEY } from '../../hooks/useHeapsQuery'
-import { heaps as heapsApi, type Heap } from '../../services/api'
-import { useFilterStore } from '../../store/filterStore'
-import { toast } from '../ToastContainer'
-import { PHOTO_DRAG_MIME } from '../timeline/PhotoThumbnail'
-import { HeapConvertDialog } from './HeapConvertDialog'
-
-/**
- * Heaps panel for the left sidebar. Renders the list of heaps with the
- * basket icon, lets the user create a new heap, click one to filter the
- * timeline to its contents, set one as the "active" target for the T
- * shortcut, and delete heaps.
- *
- * Heap state:
- *  - filter heapId: which heap is currently filtered to (visual)
- *  - heap.is_active: which heap T adds to (server-side, single per row)
- */
-export function HeapsPanel() {
-  const { data: heaps = [] } = useHeapsQuery()
-  const navigateToSection = useFilterStore((s) => s.navigateToSection)
-  const currentSection = useFilterStore((s) => s.currentSection)
-  const queryClient = useQueryClient()
-
-  const [expanded, setExpanded] = useState(true)
-  const [creating, setCreating] = useState(false)
-  const [newName, setNewName] = useState('')
-  // Which heap row is currently being hovered with a drag — used to render
-  // the drop highlight ring. Only one heap can be the target at a time.
-  const [dropTargetId, setDropTargetId] = useState<string | null>(null)
-  const [convertingHeap, setConvertingHeap] = useState<Heap | null>(null)
-  // Inline rename state for heap rows: stores the heap id being edited and
-  // the draft name. Mirrors the folder rename pattern in LeftSidebar.
-  const [renamingId, setRenamingId] = useState<string | null>(null)
-  const [renameDraft, setRenameDraft] = useState('')
-  // Which heap's burger menu is currently open. null when no menu is open.
-  // The popover closes on outside click and Escape via the effect below.
-  const [openMenuId, setOpenMenuId] = useState<string | null>(null)
-  const menuRef = useRef<HTMLDivElement>(null)
-
-  useEffect(() => {
-    if (!openMenuId) return
-    const onDown = (e: MouseEvent) => {
-      if (menuRef.current && !menuRef.current.contains(e.target as Node)) {
-        setOpenMenuId(null)
-      }
-    }
-    const onKey = (e: KeyboardEvent) => {
-      if (e.key === 'Escape') setOpenMenuId(null)
-    }
-    document.addEventListener('mousedown', onDown)
-    document.addEventListener('keydown', onKey)
-    return () => {
-      document.removeEventListener('mousedown', onDown)
-      document.removeEventListener('keydown', onKey)
-    }
-  }, [openMenuId])
-
-  const invalidate = () => {
-    queryClient.invalidateQueries({ queryKey: HEAPS_QUERY_KEY })
-  }
-
-  const createMutation = useMutation({
-    mutationFn: (name: string) => heapsApi.create(name),
-    onSuccess: () => {
-      invalidate()
-      setNewName('')
-      setCreating(false)
-    },
-    onError: (e: any) =>
-      toast.error('Failed to create heap', e.message || 'Unknown error'),
-  })
-
-  const setActiveMutation = useMutation({
-    mutationFn: (heapId: string) =>
-      heapsApi.update(heapId, { is_active: true }),
-    onSuccess: (heap) => {
-      invalidate()
-      toast.success('Active heap', `Now adding to "${heap.name}" with T`)
-    },
-    onError: (e: any) =>
-      toast.error('Failed to set active', e.message || 'Unknown error'),
-  })
-
-  const deleteMutation = useMutation({
-    mutationFn: (heapId: string) => heapsApi.delete(heapId),
-    onSuccess: (_, heapId) => {
-      invalidate()
-      // If we were viewing this heap, snap back to all-photos.
-      if (currentSection === `heap-${heapId}`) {
-        navigateToSection('all-photos', {})
-      }
-    },
-    onError: (e: any) =>
-      toast.error('Failed to delete heap', e.message || 'Unknown error'),
-  })
-
-  const renameMutation = useMutation({
-    mutationFn: ({ heapId, name }: { heapId: string; name: string }) =>
-      heapsApi.update(heapId, { name }),
-    onSuccess: () => invalidate(),
-    onError: (e: any) =>
-      toast.error('Failed to rename heap', e.message || 'Unknown error'),
-  })
-
-  const duplicateMutation = useMutation({
-    mutationFn: (heapId: string) => heapsApi.duplicate(heapId),
-    onSuccess: (heap) => {
-      invalidate()
-      toast.success('Heap duplicated', heap.name)
-    },
-    onError: (e: any) =>
-      toast.error('Failed to duplicate heap', e.message || 'Unknown error'),
-  })
-
-  // Drop handler: add the dragged photos to the target heap. Optimistically
-  // updates the membership cache so the basket affordance flips immediately,
-  // mirroring the keyboard P-toggle pattern.
-  const dropMutation = useMutation({
-    mutationFn: ({ heapId, photoIds }: { heapId: string; photoIds: string[] }) =>
-      heapsApi.addPhotos(heapId, photoIds),
-    onMutate: ({ heapId, photoIds }) => {
-      const key = ['heap-photo-ids', heapId] as const
-      const previous = queryClient.getQueryData<string[]>(key)
-      const set = new Set(previous ?? [])
-      photoIds.forEach((id) => set.add(id))
-      queryClient.setQueryData<string[]>(key, Array.from(set))
-      return { previous }
-    },
-    onError: (e: any, vars, ctx) => {
-      if (ctx?.previous) {
-        queryClient.setQueryData(['heap-photo-ids', vars.heapId], ctx.previous)
-      }
-      toast.error('Failed to add to heap', e.message || 'Unknown error')
-    },
-    onSuccess: (data, vars) => {
-      const heap = heaps.find((h) => h.id === vars.heapId)
-      const heapName = heap?.name ?? 'heap'
-      const added = data?.added ?? 0
-      const already = data?.already_present ?? 0
-      if (added > 0) {
-        toast.success(
-          `Added to ${heapName}`,
-          `${added} photo${added > 1 ? 's' : ''}${already > 0 ? ` (${already} already present)` : ''}`
-        )
-      } else if (already > 0) {
-        toast.info(`Already in ${heapName}`, `${already} photo${already > 1 ? 's' : ''}`)
-      }
-    },
-    onSettled: (_d, _e, vars) => {
-      queryClient.invalidateQueries({ queryKey: HEAPS_QUERY_KEY })
-      queryClient.invalidateQueries({ queryKey: ['heap-photo-ids', vars.heapId] })
-      queryClient.invalidateQueries({ queryKey: ['photos'] })
-    },
-  })
-
-  const handleCreate = () => {
-    const name = newName.trim()
-    if (!name) return
-    createMutation.mutate(name)
-  }
-
-  return (
-    <div>
-      {/* Section header — eyebrow style to match the LeftSidebar
-       *  library/folders headers. */}
-      <div
-        className="group mt-2 flex cursor-pointer items-center gap-1 px-3 py-1 text-[10px] font-semibold uppercase tracking-[0.14em] text-text-muted hover:text-text"
-        onClick={() => setExpanded((v) => !v)}
-      >
-        <button className="rounded p-0.5 hover:bg-surface-offset">
-          {expanded ? (
-            <ChevronDown className="h-3 w-3" />
-          ) : (
-            <ChevronRight className="h-3 w-3" />
-          )}
-        </button>
-        <span className="flex-1 truncate">Heaps</span>
-        <button
-          onClick={(e) => {
-            e.stopPropagation()
-            setCreating(true)
-            setExpanded(true)
-          }}
-          className="invisible rounded p-0.5 hover:bg-surface-offset hover:text-text group-hover:visible"
-          title="New heap"
-        >
-          <Plus className="h-3 w-3" />
-        </button>
-      </div>
-
-      {expanded && (
-        <div>
-          {/* Inline create form */}
-          {creating && (
-            <div
-              className="flex items-center gap-1 px-2 py-0.5"
-              style={{ paddingLeft: '20px' }}
-            >
-              <input
-                autoFocus
-                type="text"
-                value={newName}
-                onChange={(e) => setNewName(e.target.value)}
-                onKeyDown={(e) => {
-                  if (e.key === 'Enter') handleCreate()
-                  if (e.key === 'Escape') {
-                    setCreating(false)
-                    setNewName('')
-                  }
-                }}
-                placeholder="Heap name"
-                className="flex-1 rounded border border-border bg-bg px-2 py-0.5 text-[11px] text-text focus:border-primary focus:outline-none"
-              />
-              <button
-                onClick={handleCreate}
-                disabled={!newName.trim() || createMutation.isPending}
-                className="rounded bg-primary px-2 py-0.5 text-[11px] text-white hover:bg-primary/80 disabled:opacity-50"
-              >
-                Add
-              </button>
-            </div>
-          )}
-
-          {heaps.length === 0 && !creating && (
-            <div
-              className="px-2 py-0.5 text-[11px] text-text-faint"
-              style={{ paddingLeft: '20px' }}
-            >
-              No heaps yet
-            </div>
-          )}
-
-          {heaps.map((heap) => {
-            const isFiltered = currentSection === `heap-${heap.id}`
-            const isActive = heap.is_active
-            const isDropTarget = dropTargetId === heap.id
-            const isRenaming = renamingId === heap.id
-            const isMenuOpen = openMenuId === heap.id
-
-            const commitRename = () => {
-              const next = renameDraft.trim()
-              if (next && next !== heap.name) {
-                renameMutation.mutate({ heapId: heap.id, name: next })
-              }
-              setRenamingId(null)
-            }
-
-            return (
-              <div
-                key={heap.id}
-                className={clsx(
-                  'group relative flex h-[24px] cursor-pointer items-center gap-1 rounded px-2 text-[12px] leading-none',
-                  isFiltered ? 'bg-primary/20 text-primary' : 'text-text hover:bg-surface-2',
-                  // Active-heap row gets a soft primary wash so the
-                  // user always knows where Pick / T will land, even
-                  // when viewing a different section.
-                  isActive && !isFiltered && 'bg-primary/8 text-text',
-                  isDropTarget && 'ring-2 ring-primary bg-primary/10'
-                )}
-                style={{ paddingLeft: '20px' }}
-                onClick={() => {
-                  if (isRenaming) return
-                  navigateToSection(`heap-${heap.id}`, { heapId: heap.id })
-                }}
-                onDoubleClick={(e) => {
-                  e.stopPropagation()
-                  setRenamingId(heap.id)
-                  setRenameDraft(heap.name)
-                }}
-                onDragOver={(e) => {
-                  if (e.dataTransfer.types.includes(PHOTO_DRAG_MIME)) {
-                    e.preventDefault()
-                    e.dataTransfer.dropEffect = 'copy'
-                    if (dropTargetId !== heap.id) setDropTargetId(heap.id)
-                  }
-                }}
-                onDragLeave={(e) => {
-                  if (!e.currentTarget.contains(e.relatedTarget as Node)) {
-                    if (dropTargetId === heap.id) setDropTargetId(null)
-                  }
-                }}
-                onDrop={(e) => {
-                  e.preventDefault()
-                  setDropTargetId(null)
-                  const raw = e.dataTransfer.getData(PHOTO_DRAG_MIME)
-                  if (!raw) return
-                  try {
-                    const ids = JSON.parse(raw) as string[]
-                    if (Array.isArray(ids) && ids.length > 0) {
-                      dropMutation.mutate({ heapId: heap.id, photoIds: ids })
-                    }
-                  } catch {
-                    // Bad payload — ignore.
-                  }
-                }}
-              >
-                <ShoppingBasket
-                  className={clsx(
-                    'h-3.5 w-3.5 flex-shrink-0',
-                    isActive || isFiltered ? 'text-primary' : 'text-text-muted'
-                  )}
-                />
-
-                {isRenaming ? (
-                  <input
-                    autoFocus
-                    type="text"
-                    value={renameDraft}
-                    onChange={(e) => setRenameDraft(e.target.value)}
-                    onClick={(e) => e.stopPropagation()}
-                    onBlur={commitRename}
-                    onKeyDown={(e) => {
-                      if (e.key === 'Enter') {
-                        e.currentTarget.blur()
-                      } else if (e.key === 'Escape') {
-                        setRenamingId(null)
-                      }
-                    }}
-                    className="flex-1 rounded border border-border bg-bg px-1 py-0 text-[13px] text-text focus:border-primary focus:outline-none"
-                  />
-                ) : (
-                  <>
-                    <span
-                      className={clsx('truncate', isActive && 'font-semibold')}
-                      title={heap.name}
-                    >
-                      {heap.name}
-                    </span>
-                    {isActive && (
-                      <span
-                        className="ml-1 flex-shrink-0 rounded-full bg-primary/25 px-1.5 py-0.5 text-[9px] font-semibold uppercase tracking-wide text-primary"
-                        title="Active heap — Pick (P) and the basket badge on photos point here"
-                      >
-                        Active
-                      </span>
-                    )}
-                    <span className="flex-1" />
-                  </>
-                )}
-
-                {/* Right cluster. Count is the rightmost element in the
-                 *  resting state — set-active and kebab use display:none
-                 *  (not invisible) so they reserve no width until hover,
-                 *  keeping the count column aligned with the rest of the
-                 *  sidebar. The active heap is signaled by font-semibold
-                 *  on the name above; the standalone Target indicator
-                 *  was making heap counts sit left of the others. */}
-                {heap.photo_count > 0 ? (
-                  <span className="flex h-4 min-w-[20px] flex-shrink-0 items-center justify-center rounded bg-surface-offset px-1 text-[10px] tabular-nums text-text-muted">
-                    {heap.photo_count}
-                  </span>
-                ) : (
-                  <span className="h-4 min-w-[20px] flex-shrink-0" aria-hidden="true" />
-                )}
-                {!isActive && (
-                  <button
-                    onClick={(e) => {
-                      e.stopPropagation()
-                      setActiveMutation.mutate(heap.id)
-                    }}
-                    className="hidden flex-shrink-0 rounded p-0.5 text-text-muted hover:bg-surface-offset hover:text-text group-hover:block"
-                    title="Set as active heap (T target)"
-                    aria-label="Set as active heap"
-                  >
-                    <Target className="h-3 w-3" />
-                  </button>
-                )}
-
-                {/* Kebab menu — collects rename / duplicate / convert /
-                 *  delete so the row stays compact. */}
-                <div
-                  className={clsx(
-                    'relative flex-shrink-0',
-                    isMenuOpen ? 'block' : 'hidden group-hover:block'
-                  )}
-                >
-                  <button
-                    onClick={(e) => {
-                      e.stopPropagation()
-                      setOpenMenuId(isMenuOpen ? null : heap.id)
-                    }}
-                    className="rounded p-0.5 text-text-muted hover:bg-surface-offset hover:text-text"
-                    title="More actions"
-                    aria-label="More heap actions"
-                    aria-haspopup="menu"
-                    aria-expanded={isMenuOpen}
-                  >
-                    <MoreHorizontal className="h-3.5 w-3.5" />
-                  </button>
-
-                  {isMenuOpen && (
-                    <div
-                      ref={menuRef}
-                      role="menu"
-                      className="absolute right-0 top-full z-30 mt-1 min-w-[160px] overflow-hidden rounded-lg border border-border bg-surface py-1 text-sm shadow-xl"
-                      onClick={(e) => e.stopPropagation()}
-                    >
-                      <MenuItem
-                        icon={<Pencil className="h-3.5 w-3.5" />}
-                        label="Rename"
-                        onClick={() => {
-                          setOpenMenuId(null)
-                          setRenamingId(heap.id)
-                          setRenameDraft(heap.name)
-                        }}
-                      />
-                      <MenuItem
-                        icon={<Copy className="h-3.5 w-3.5" />}
-                        label="Duplicate"
-                        onClick={() => {
-                          setOpenMenuId(null)
-                          duplicateMutation.mutate(heap.id)
-                        }}
-                      />
-                      <MenuItem
-                        icon={<FolderOutput className="h-3.5 w-3.5" />}
-                        label="Move to folder…"
-                        onClick={() => {
-                          setOpenMenuId(null)
-                          setConvertingHeap(heap)
-                        }}
-                      />
-                      <div className="my-1 h-px bg-border" />
-                      <MenuItem
-                        icon={<Trash2 className="h-3.5 w-3.5" />}
-                        label="Delete"
-                        destructive
-                        onClick={() => {
-                          setOpenMenuId(null)
-                          if (
-                            confirm(
-                              `Delete heap "${heap.name}"? Photos are not affected.`
-                            )
-                          ) {
-                            deleteMutation.mutate(heap.id)
-                          }
-                        }}
-                      />
-                    </div>
-                  )}
-                </div>
-              </div>
-            )
-          })}
-        </div>
-      )}
-
-      <HeapConvertDialog
-        heap={convertingHeap}
-        onClose={() => setConvertingHeap(null)}
-      />
-    </div>
-  )
-}
-
-function MenuItem({
-  icon,
-  label,
-  onClick,
-  destructive = false,
-}: {
-  icon: React.ReactNode
-  label: string
-  onClick: () => void
-  destructive?: boolean
-}) {
-  return (
-    <button
-      role="menuitem"
-      onClick={onClick}
-      className={clsx(
-        'flex w-full items-center gap-2 px-3 py-1.5 text-left text-xs transition-colors',
-        destructive
-          ? 'text-reject hover:bg-reject/10'
-          : 'text-text hover:bg-surface-2'
-      )}
-    >
-      <span className="text-text-muted">{icon}</span>
-      {label}
-    </button>
-  )
-}

frontend/src/components/layout/LeftSidebar.tsx

@@ -1,762 +0,0 @@
-import { useEffect, useRef, useState } from 'react'
-import {
-  ChevronRight,
-  ChevronDown,
-  Folder,
-  FolderPlus,
-  Image,
-  Star,
-  Trash2,
-  HardDrive,
-  Copy,
-  Tag as TagIcon,
-  Layers2,
-  MoreHorizontal,
-  Pencil,
-  PanelLeftClose,
-  Settings,
-} from 'lucide-react'
-import clsx from 'clsx'
-import { sourceFolders, photos as photosApi, type FolderTreeNode } from '../../services/api'
-import { useMutation, useQueryClient } from '@tanstack/react-query'
-import { toast } from '../ToastContainer'
-import { useFilterStore } from '../../store/filterStore'
-import { HeapsPanel } from '../heaps/HeapsPanel'
-import { ActiveHeapCard } from '../heaps/ActiveHeapCard'
-import { PHOTO_DRAG_MIME } from '../timeline/PhotoThumbnail'
-import { useFolderTreeQuery } from '../../hooks/useFolderTreeQuery'
-import { useTagsQuery } from '../../hooks/useTagsQuery'
-import {
-  useLibraryStatsQuery,
-  LIBRARY_STATS_QUERY_KEY,
-} from '../../hooks/useLibraryStatsQuery'
-import { registerUndoable } from '../../store/undoStore'
-import type { Photo } from '../../types/photo'
-import { DeleteFolderDialog } from '../dialogs/DeleteFolderDialog'
-
-interface TreeItem {
-  id: string
-  label: string
-  icon?: React.ReactNode
-  count?: number
-  children?: TreeItem[]
-  type?: 'folder' | 'heap' | 'special'
-}
-
-interface LeftSidebarProps {
-  onCollapse: () => void
-  onOpenSettings: () => void
-}
-
-export function LeftSidebar({ onCollapse, onOpenSettings }: LeftSidebarProps) {
-  const [expandedItems, setExpandedItems] = useState<Set<string>>(new Set(['library', 'folders', 'heaps']))
-  // Inline rename state for source-root rows. Stores the id being edited
-  // and the draft name. Double-click a folder row to start.
-  const [renamingId, setRenamingId] = useState<string | null>(null)
-  const [renameDraft, setRenameDraft] = useState('')
-
-  const queryClient = useQueryClient()
-  const navigateToSection = useFilterStore((s) => s.navigateToSection)
-  const currentSection = useFilterStore((s) => s.currentSection)
-  const { data: allTags = [] } = useTagsQuery()
-  const { data: stats } = useLibraryStatsQuery()
-  const [dropTargetId, setDropTargetId] = useState<string | null>(null)
-
-  // Per-folder kebab menu open state. Stores the tree-item id ("folder-..."
-  // or "folders" for the section header). Outside-click + Escape close.
-  const [openMenuId, setOpenMenuId] = useState<string | null>(null)
-  const menuRef = useRef<HTMLDivElement>(null)
-  useEffect(() => {
-    if (!openMenuId) return
-    const onDown = (e: MouseEvent) => {
-      if (menuRef.current && !menuRef.current.contains(e.target as Node)) {
-        setOpenMenuId(null)
-      }
-    }
-    const onKey = (e: KeyboardEvent) => {
-      if (e.key === 'Escape') setOpenMenuId(null)
-    }
-    document.addEventListener('mousedown', onDown)
-    document.addEventListener('keydown', onKey)
-    return () => {
-      document.removeEventListener('mousedown', onDown)
-      document.removeEventListener('keydown', onKey)
-    }
-  }, [openMenuId])
-
-  // "Create new folder under {parent}" inline state. parentId is the
-  // Folder.id (no "folder-" prefix).
-  const [creatingUnder, setCreatingUnder] = useState<string | null>(null)
-  const [createDraft, setCreateDraft] = useState('')
-
-  // Folder being deleted, drives the DeleteFolderDialog mounted below.
-  const [deletingFolder, setDeletingFolder] = useState<{
-    id: string
-    name: string
-    photoCount?: number
-  } | null>(null)
-
-  // Bulk discard mutation for the drag-onto-Discarded interaction.
-  const discardDropMutation = useMutation({
-    mutationFn: (photoIds: string[]) => photosApi.bulkDiscard(photoIds),
-    onSuccess: (_data, photoIds) => {
-      registerUndoable(
-        `Discarded ${photoIds.length} photo${photoIds.length === 1 ? '' : 's'}`,
-        async () => {
-          await photosApi.bulkRestore(photoIds)
-          queryClient.invalidateQueries({ queryKey: ['photos'] })
-          queryClient.invalidateQueries({ queryKey: LIBRARY_STATS_QUERY_KEY })
-        }
-      )
-      queryClient.invalidateQueries({ queryKey: ['photos'] })
-      queryClient.invalidateQueries({ queryKey: LIBRARY_STATS_QUERY_KEY })
-    },
-    onError: (e: any) =>
-      toast.error('Discard failed', e?.message || 'Unknown error'),
-  })
-
-  // Bulk move mutation for the drag-onto-folder interaction. The mutation
-  // captures each photo's source folder before issuing the move so the
-  // undo path can put them back exactly where they came from (different
-  // sources end up in different undo subgroups).
-  const moveDropMutation = useMutation({
-    mutationFn: async ({
-      targetId,
-      photoIds,
-    }: {
-      targetId: string
-      photoIds: string[]
-    }) => {
-      // Snapshot per-photo source folder ids from the photos cache. We
-      // walk every cached ['photos', ...] entry because the user could
-      // be in any section / filter combination, and we don't know the
-      // exact key offhand.
-      const sourceMap = new Map<string, string>()
-      const photoCaches = queryClient.getQueriesData<Photo[]>({ queryKey: ['photos'] })
-      for (const [, list] of photoCaches) {
-        if (!list) continue
-        for (const p of list) {
-          if (photoIds.includes(p.id) && p.folder_id && !sourceMap.has(p.id)) {
-            sourceMap.set(p.id, p.folder_id)
-          }
-        }
-      }
-      const result = await photosApi.move(photoIds, targetId)
-      return { result, sourceMap }
-    },
-    onSuccess: ({ result, sourceMap }) => {
-      const moved = result?.moved ?? 0
-      const errCount = result?.errors?.length ?? 0
-      if (moved > 0) {
-        // Group photos by their source folder so we can issue one move
-        // call per group when undoing. Photos whose source folder we
-        // couldn't recover get dropped from the undo (they'll just stay
-        // where the move put them).
-        const groups = new Map<string, string[]>()
-        for (const [photoId, src] of sourceMap.entries()) {
-          const arr = groups.get(src) ?? []
-          arr.push(photoId)
-          groups.set(src, arr)
-        }
-        if (groups.size > 0) {
-          registerUndoable(
-            `Moved ${moved} photo${moved === 1 ? '' : 's'}`,
-            async () => {
-              for (const [src, ids] of groups.entries()) {
-                await photosApi.move(ids, src)
-              }
-              queryClient.invalidateQueries({ queryKey: ['photos'] })
-              queryClient.invalidateQueries({ queryKey: ['folders'] })
-            }
-          )
-        } else {
-          toast.success(
-            'Moved',
-            `${moved} photo${moved > 1 ? 's' : ''}${errCount ? ` (${errCount} skipped)` : ''}`
-          )
-        }
-      } else if (errCount > 0) {
-        toast.error(
-          'Move failed',
-          `${errCount} file${errCount > 1 ? 's' : ''} could not be moved`
-        )
-      }
-      queryClient.invalidateQueries({ queryKey: ['photos'] })
-      queryClient.invalidateQueries({ queryKey: ['folders'] })
-    },
-    onError: (e: any) =>
-      toast.error('Move failed', e?.response?.data?.detail || e.message || 'Unknown error'),
-  })
-
-  // Bulk copy mutation — Alt-drag uses this instead of move.
-  const copyDropMutation = useMutation({
-    mutationFn: ({ targetId, photoIds }: { targetId: string; photoIds: string[] }) =>
-      photosApi.copy(photoIds, targetId),
-    onSuccess: (data) => {
-      const copied = data?.copied ?? 0
-      const errCount = data?.errors?.length ?? 0
-      if (copied > 0) {
-        toast.success(
-          'Copied',
-          `${copied} photo${copied > 1 ? 's' : ''}${errCount ? ` (${errCount} skipped)` : ''}`
-        )
-      } else if (errCount > 0) {
-        toast.error('Copy failed', `${errCount} file${errCount > 1 ? 's' : ''} could not be copied`)
-      }
-      queryClient.invalidateQueries({ queryKey: ['photos'] })
-      queryClient.invalidateQueries({ queryKey: ['folders'] })
-    },
-    onError: (e: any) =>
-      toast.error('Copy failed', e?.response?.data?.detail || e.message || 'Unknown error'),
-  })
-
-  // Reads the dragged ids out of a drop event payload.
-  const readDragIds = (e: React.DragEvent): string[] | null => {
-    const raw = e.dataTransfer.getData(PHOTO_DRAG_MIME)
-    if (!raw) return null
-    try {
-      const parsed = JSON.parse(raw) as string[]
-      return Array.isArray(parsed) && parsed.length > 0 ? parsed : null
-    } catch {
-      return null
-    }
-  }
-
-  // Map a library tree id to a section navigation. Each "virtual node" in
-  // the library tree is its own section, with its own remembered filter
-  // state. The preset is the section's intrinsic filter (the thing that
-  // makes it that section); user-added filters from the FilterBar layer
-  // on top and are saved when the user navigates away.
-  const applyLibraryNode = (id: string) => {
-    switch (id) {
-      case 'all-photos':
-        navigateToSection('all-photos', {})
-        break
-      case 'rated':
-        navigateToSection('rated', { ratingMin: 1, groupBy: 'rating' })
-        break
-      case 'discarded':
-        navigateToSection('discarded', { flag: 'discarded' })
-        break
-      case 'duplicates':
-        navigateToSection('duplicates', { duplicates: true })
-        break
-      case 'tags':
-        navigateToSection('tags', { groupBy: 'tag' })
-        break
-      default:
-        if (id.startsWith('folder-')) {
-          const folderId = id.slice('folder-'.length)
-          navigateToSection(`folder-${folderId}`, { folderId })
-        }
-    }
-  }
-
-  // Fetch the recursive folder tree (one root per active source root).
-  const { data: folderTree = [] } = useFolderTreeQuery()
-
-  const renameMutation = useMutation({
-    mutationFn: ({ id, name }: { id: string; name: string }) =>
-      sourceFolders.rename(id, name),
-    onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ['folders'] })
-      queryClient.invalidateQueries({ queryKey: ['folders', 'tree'] })
-      queryClient.invalidateQueries({ queryKey: ['photos'] })
-    },
-    onError: (e: any) =>
-      toast.error('Rename failed', e?.response?.data?.detail || e.message || 'Unknown error'),
-  })
-
-  const createFolderMutation = useMutation({
-    mutationFn: ({ parentId, name }: { parentId: string; name: string }) =>
-      sourceFolders.create(parentId, name),
-    onSuccess: (data) => {
-      toast.success('Folder created', data.name)
-      queryClient.invalidateQueries({ queryKey: ['folders'] })
-      queryClient.invalidateQueries({ queryKey: ['folders', 'tree'] })
-      setCreatingUnder(null)
-      setCreateDraft('')
-    },
-    onError: (e: any) =>
-      toast.error('Create failed', e?.response?.data?.detail || e.message || 'Unknown error'),
-  })
-
-  const deleteFolderMutation = useMutation({
-    mutationFn: ({ id, mode }: { id: string; mode: 'discard' | 'permanent' }) =>
-      sourceFolders.delete(id, mode),
-    onSuccess: (data) => {
-      if (data.mode === 'discard') {
-        toast.success(
-          'Folder photos discarded',
-          `${data.discarded ?? 0} moved to discard pile`
-        )
-      } else {
-        toast.success(
-          'Folder deleted',
-          `${data.deleted_photos ?? 0} photos removed from disk`
-        )
-      }
-      queryClient.invalidateQueries({ queryKey: ['folders'] })
-      queryClient.invalidateQueries({ queryKey: ['folders', 'tree'] })
-      queryClient.invalidateQueries({ queryKey: ['photos'] })
-      queryClient.invalidateQueries({ queryKey: LIBRARY_STATS_QUERY_KEY })
-      // If we were viewing the deleted folder, snap back to all-photos.
-      if (deletingFolder && currentSection === `folder-${deletingFolder.id}`) {
-        navigateToSection('all-photos', {})
-      }
-      setDeletingFolder(null)
-    },
-    onError: (e: any) =>
-      toast.error('Delete failed', e?.response?.data?.detail || e.message || 'Unknown error'),
-  })
-
-  const toggleExpanded = (id: string) => {
-    const newExpanded = new Set(expandedItems)
-    if (newExpanded.has(id)) {
-      newExpanded.delete(id)
-    } else {
-      newExpanded.add(id)
-    }
-    setExpandedItems(newExpanded)
-  }
-
-  // Recursively map a backend FolderTreeNode into our generic TreeItem.
-  const folderNodeToTreeItem = (node: FolderTreeNode): TreeItem => ({
-    id: `folder-${node.id}`,
-    label: node.name,
-    icon: <Folder className="h-4 w-4" />,
-    count: node.photo_count,
-    type: 'folder',
-    children: node.children.length > 0
-      ? node.children.map(folderNodeToTreeItem)
-      : undefined,
-  })
-
-  // Total tag count for the badge on the Tags entry.
-  const tagsTotalCount = allTags.reduce((sum, t) => sum + (t.photo_count || 0), 0)
-
-  const libraryTree: TreeItem[] = [
-    {
-      id: 'library',
-      label: 'Views',
-      icon: <Layers2 className="h-4 w-4" />,
-      children: [
-        { id: 'all-photos', label: 'All Photos', icon: <Image className="h-4 w-4" />, count: stats?.all_photos ?? 0 },
-        { id: 'rated', label: 'Rated', icon: <Star className="h-4 w-4" />, count: stats?.rated ?? 0 },
-        { id: 'tags', label: 'Tags', icon: <TagIcon className="h-4 w-4" />, count: tagsTotalCount },
-        { id: 'duplicates', label: 'Duplicates', icon: <Copy className="h-4 w-4" />, count: stats?.duplicates ?? 0 },
-        { id: 'discarded', label: 'Discarded', icon: <Trash2 className="h-4 w-4" />, count: stats?.discarded ?? 0 },
-      ],
-    },
-    {
-      id: 'folders',
-      label: 'Folders',
-      icon: <HardDrive className="h-4 w-4" />,
-      children: folderTree.map(folderNodeToTreeItem),
-    },
-  ]
-
-  // Derive whether a tree item is currently the "active" filter target.
-  // Folder rows are selected when the filter store's folderId matches; the
-  // library "All Photos" virtual node is selected when no folder/heap filter
-  // is set.
-  // Active highlight is now driven entirely by currentSection. Each
-  // library node and folder row maps 1:1 to a section id.
-  const isItemActive = (id: string): boolean => {
-    if (id.startsWith('folder-')) {
-      return currentSection === id
-    }
-    return currentSection === id
-  }
-
-  // Which tree items accept photo drops, and what each does on drop.
-  const isDropTarget = (id: string): boolean => {
-    return id === 'discarded' || id.startsWith('folder-')
-  }
-
-  const handleDrop = (id: string, ids: string[], copy: boolean) => {
-    if (id === 'discarded') {
-      discardDropMutation.mutate(ids)
-      return
-    }
-    if (id.startsWith('folder-')) {
-      const targetId = id.slice('folder-'.length)
-      if (copy) {
-        copyDropMutation.mutate({ targetId, photoIds: ids })
-      } else {
-        moveDropMutation.mutate({ targetId, photoIds: ids })
-      }
-    }
-  }
-
-  const renderTreeItem = (item: TreeItem, depth: number = 0) => {
-    const hasChildren = item.children && item.children.length > 0
-    const isExpanded = expandedItems.has(item.id)
-    const isSelected = isItemActive(item.id)
-    const acceptsDrop = isDropTarget(item.id)
-    const isDropHover = dropTargetId === item.id
-    // Top-level entries (Views, Folders) render as small uppercase
-    // section eyebrows rather than another tree row, so the panel reads
-    // as distinct sections with the actual items beneath them.
-    const isSectionHeader = depth === 0
-
-    return (
-      <div key={item.id}>
-        <div
-          className={clsx(
-            'group flex cursor-pointer items-center gap-1',
-            isSectionHeader
-              ? 'mt-2 px-3 py-1 text-[10px] font-semibold uppercase tracking-[0.14em] text-text-muted hover:text-text'
-              : clsx(
-                  // Fixed h-[24px] (not min-h) locks the row height so the
-                  // hover-only kebab button can't grow the row vertically.
-                  'h-[24px] rounded px-2 text-[12px] leading-none',
-                  isSelected ? 'bg-primary/20 text-primary' : 'text-text hover:bg-surface-2'
-                ),
-            isDropHover && (item.id === 'discarded'
-              ? 'ring-2 ring-reject bg-reject/10'
-              : 'ring-2 ring-primary bg-primary/10')
-          )}
-          style={
-            isSectionHeader
-              ? undefined
-              : { paddingLeft: `${8 + (depth - 1) * 12}px` }
-          }
-          onClick={() => {
-            if (renamingId === item.id) return
-            // Folder rows are always filterable, parent or leaf — clicking
-            // anywhere on the row applies the filter and the chevron
-            // (separate button below) handles expansion. Other group
-            // headers (Library, Folders) just toggle expansion since
-            // they have no associated section.
-            if (item.id.startsWith('folder-')) {
-              applyLibraryNode(item.id)
-            } else if (hasChildren) {
-              toggleExpanded(item.id)
-            } else {
-              applyLibraryNode(item.id)
-            }
-          }}
-          onDoubleClick={
-            item.id.startsWith('folder-')
-              ? (e) => {
-                e.stopPropagation()
-                setRenamingId(item.id)
-                setRenameDraft(item.label)
-              }
-              : undefined
-          }
-          onDragOver={acceptsDrop ? (e) => {
-            if (e.dataTransfer.types.includes(PHOTO_DRAG_MIME)) {
-              e.preventDefault()
-              // Alt held → copy (only meaningful for folder targets;
-              // discarding doesn't copy).
-              const wantCopy = e.altKey && item.id.startsWith('folder-')
-              e.dataTransfer.dropEffect = wantCopy ? 'copy' : 'move'
-              if (dropTargetId !== item.id) setDropTargetId(item.id)
-            }
-          } : undefined}
-          onDragLeave={acceptsDrop ? (e) => {
-            if (!e.currentTarget.contains(e.relatedTarget as Node)) {
-              if (dropTargetId === item.id) setDropTargetId(null)
-            }
-          } : undefined}
-          onDrop={acceptsDrop ? (e) => {
-            e.preventDefault()
-            setDropTargetId(null)
-            const ids = readDragIds(e)
-            if (ids) handleDrop(item.id, ids, e.altKey)
-          } : undefined}
-        >
-          {/* Expand/Collapse Icon */}
-          {hasChildren ? (
-            <button
-              onClick={(e) => {
-                e.stopPropagation()
-                toggleExpanded(item.id)
-              }}
-              className="rounded p-0.5 hover:bg-surface-offset"
-            >
-              {isExpanded ? (
-                <ChevronDown className="h-3 w-3" />
-              ) : (
-                <ChevronRight className="h-3 w-3" />
-              )}
-            </button>
-          ) : (
-            !isSectionHeader && <div className="w-3" />
-          )}
-
-          {/* Item Icon — section headers drop their icon in favor of the
-           *  uppercase eyebrow label. */}
-          {item.icon && !isSectionHeader && (
-            <span
-              className={clsx(
-                'flex-shrink-0',
-                isSelected ? 'text-primary' : 'text-text-muted'
-              )}
-            >
-              <span className="[&>svg]:h-3.5 [&>svg]:w-3.5">{item.icon}</span>
-            </span>
-          )}
-
-          {/* Label (or inline rename input for folder rows) */}
-          {renamingId === item.id ? (
-            <input
-              autoFocus
-              type="text"
-              value={renameDraft}
-              onChange={(e) => setRenameDraft(e.target.value)}
-              onClick={(e) => e.stopPropagation()}
-              onBlur={() => {
-                const next = renameDraft.trim()
-                const id = item.id.slice('folder-'.length)
-                if (next && next !== item.label) {
-                  renameMutation.mutate({ id, name: next })
-                }
-                setRenamingId(null)
-              }}
-              onKeyDown={(e) => {
-                if (e.key === 'Enter') {
-                  e.currentTarget.blur()
-                } else if (e.key === 'Escape') {
-                  setRenamingId(null)
-                }
-              }}
-              className="flex-1 rounded border border-border bg-bg px-1 py-0 text-[13px] text-text focus:border-primary focus:outline-none"
-            />
-          ) : (
-            <span className="flex-1 truncate">{item.label}</span>
-          )}
-
-          {/* Count Badge — fixed-width slot so counts line up in a column
-           *  across rows regardless of digit count. Section headers skip
-           *  the badge entirely (they're labels, not navigable rows). */}
-          {!isSectionHeader && (
-            item.count !== undefined && item.count > 0 ? (
-              <span className="flex h-4 min-w-[20px] flex-shrink-0 items-center justify-center rounded bg-surface-offset px-1 text-[10px] tabular-nums text-text-muted">
-                {item.count}
-              </span>
-            ) : (
-              <span className="h-4 min-w-[20px] flex-shrink-0" aria-hidden="true" />
-            )
-          )}
-
-          {/* Folder kebab menu — only on folder rows. Hidden (display:none)
-           *  until hover so it reserves NO width in the resting state and
-           *  the count column stays aligned across folder + non-folder
-           *  rows. On hover it appears to the right, pushing the count
-           *  left to make room. */}
-          {item.id.startsWith('folder-') &&
-            (() => {
-              const folderId = item.id.slice('folder-'.length)
-              const isMenuOpen = openMenuId === item.id
-              return (
-                <div
-                  className={clsx(
-                    'relative flex-shrink-0',
-                    isMenuOpen ? 'block' : 'hidden group-hover:block'
-                  )}
-                >
-                  <button
-                    onClick={(e) => {
-                      e.stopPropagation()
-                      setOpenMenuId(isMenuOpen ? null : item.id)
-                    }}
-                    className="rounded p-0.5 text-text-muted hover:bg-surface-offset hover:text-text"
-                    title="More actions"
-                    aria-label="More folder actions"
-                    aria-haspopup="menu"
-                    aria-expanded={isMenuOpen}
-                  >
-                    <MoreHorizontal className="h-3.5 w-3.5" />
-                  </button>
-
-                  {isMenuOpen && (
-                    <div
-                      ref={menuRef}
-                      role="menu"
-                      onClick={(e) => e.stopPropagation()}
-                      className="absolute right-0 top-full z-30 mt-1 min-w-[180px] overflow-hidden rounded-lg border border-border bg-surface py-1 text-sm shadow-xl"
-                    >
-                      <FolderMenuItem
-                        icon={<FolderPlus className="h-3.5 w-3.5" />}
-                        label="New sub-folder"
-                        onClick={() => {
-                          setOpenMenuId(null)
-                          setCreatingUnder(folderId)
-                          setCreateDraft('')
-                          // Make sure the parent is expanded so the new
-                          // input is visible.
-                          if (!expandedItems.has(item.id)) {
-                            toggleExpanded(item.id)
-                          }
-                        }}
-                      />
-                      <FolderMenuItem
-                        icon={<Pencil className="h-3.5 w-3.5" />}
-                        label="Rename"
-                        onClick={() => {
-                          setOpenMenuId(null)
-                          setRenamingId(item.id)
-                          setRenameDraft(item.label)
-                        }}
-                      />
-                      <div className="my-1 h-px bg-border" />
-                      <FolderMenuItem
-                        icon={<Trash2 className="h-3.5 w-3.5" />}
-                        label="Delete folder…"
-                        destructive
-                        onClick={() => {
-                          setOpenMenuId(null)
-                          setDeletingFolder({
-                            id: folderId,
-                            name: item.label,
-                            photoCount: item.count,
-                          })
-                        }}
-                      />
-                    </div>
-                  )}
-                </div>
-              )
-            })()}
-
-        </div>
-
-        {/* Inline "create new sub-folder" input. Renders just below the
-         *  parent row when its create state is active. */}
-        {item.id.startsWith('folder-') &&
-          creatingUnder === item.id.slice('folder-'.length) && (
-            <div
-              className="flex items-center gap-1 px-2 py-1"
-              style={{ paddingLeft: `${8 + (depth + 1) * 16 + 4}px` }}
-            >
-              <FolderPlus className="h-3 w-3 flex-shrink-0 text-text-muted" />
-              <input
-                autoFocus
-                type="text"
-                value={createDraft}
-                placeholder="New folder name"
-                onChange={(e) => setCreateDraft(e.target.value)}
-                onClick={(e) => e.stopPropagation()}
-                onKeyDown={(e) => {
-                  if (e.key === 'Enter') {
-                    const name = createDraft.trim()
-                    if (name) {
-                      createFolderMutation.mutate({
-                        parentId: item.id.slice('folder-'.length),
-                        name,
-                      })
-                    }
-                  } else if (e.key === 'Escape') {
-                    setCreatingUnder(null)
-                    setCreateDraft('')
-                  }
-                }}
-                onBlur={() => {
-                  // Don't auto-commit on blur — empty/escaped renames
-                  // close the input but don't fire the request.
-                  if (!createFolderMutation.isPending) {
-                    setCreatingUnder(null)
-                    setCreateDraft('')
-                  }
-                }}
-                className="flex-1 rounded border border-border bg-bg px-1 py-0 text-[13px] text-text focus:border-primary focus:outline-none"
-              />
-            </div>
-          )}
-
-        {/* Render Children */}
-        {hasChildren && isExpanded && (
-          <div>
-            {item.children!.map((child) => renderTreeItem(child, depth + 1))}
-          </div>
-        )}
-      </div>
-    )
-  }
-
-  return (
-    <div className="flex h-full flex-col bg-surface">
-      {/* Header with collapse button. Matches the right sidebar header
-       *  so both panels have symmetric affordances. */}
-      <div className="flex h-9 flex-shrink-0 items-center justify-between border-b border-border px-3">
-        <h2 className="text-[11px] font-semibold uppercase tracking-[0.14em] text-text-muted">
-          Library
-        </h2>
-        <button
-          onClick={onCollapse}
-          className="rounded p-0.5 text-text-muted hover:bg-surface-2 hover:text-text"
-          title="Collapse panel (Tab)"
-          aria-label="Collapse panel"
-        >
-          <PanelLeftClose className="h-3.5 w-3.5" />
-        </button>
-      </div>
-      {/* Active heap card — pinned just below the Library header so
-       *  toasts (bottom-left fixed) can't cover it. Returns null when
-       *  no heap is active, so the layout collapses cleanly. */}
-      <ActiveHeapCard />
-
-      {/* Tree View */}
-      <div className="flex-1 overflow-y-auto pb-2">
-        {libraryTree.map((item) => renderTreeItem(item))}
-        <HeapsPanel />
-      </div>
-
-      {/* Settings entry point — pinned to the bottom of the panel so it
-       *  sits out of the way of the library tree but is always reachable. */}
-      <div className="border-t border-border p-1.5">
-        <button
-          onClick={onOpenSettings}
-          className="flex w-full items-center gap-2 rounded px-2 py-1 text-[12px] text-text-muted hover:bg-surface-2 hover:text-text"
-          title="Settings"
-        >
-          <Settings className="h-3.5 w-3.5" />
-          Settings
-        </button>
-      </div>
-
-      <DeleteFolderDialog
-        isOpen={!!deletingFolder}
-        folderName={deletingFolder?.name ?? ''}
-        photoCount={deletingFolder?.photoCount}
-        onClose={() => setDeletingFolder(null)}
-        onConfirm={(mode) => {
-          if (deletingFolder) {
-            deleteFolderMutation.mutate({ id: deletingFolder.id, mode })
-          }
-        }}
-      />
-    </div>
-  )
-}
-
-function FolderMenuItem({
-  icon,
-  label,
-  onClick,
-  destructive = false,
-}: {
-  icon: React.ReactNode
-  label: string
-  onClick: () => void
-  destructive?: boolean
-}) {
-  return (
-    <button
-      role="menuitem"
-      onClick={onClick}
-      className={clsx(
-        'flex w-full items-center gap-2 px-3 py-1.5 text-left text-xs transition-colors',
-        destructive
-          ? 'text-reject hover:bg-reject/10'
-          : 'text-text hover:bg-surface-2'
-      )}
-    >
-      <span className="text-text-muted">{icon}</span>
-      {label}
-    </button>
-  )
-}

frontend/src/components/layout/RightSidebar.tsx

@@ -1,459 +0,0 @@
-import { useState } from 'react'
-import { X, Star, Info, ShoppingBasket, Trash2, Plus, PanelRightClose } from 'lucide-react'
-import clsx from 'clsx'
-import { useMutation, useQueryClient } from '@tanstack/react-query'
-import { usePhotoStore } from '../../store/photoStore'
-import {
-  photos as photosApi,
-  heaps as heapsApi,
-  tags as tagsApi,
-} from '../../services/api'
-import { useActiveHeapMembers } from '../../hooks/useActiveHeapMembersQuery'
-import { HEAPS_QUERY_KEY } from '../../hooks/useHeapsQuery'
-import { useTagsQuery, TAGS_QUERY_KEY } from '../../hooks/useTagsQuery'
-import { toast } from '../ToastContainer'
-import { PhotoInfoPanel } from '../sidebar/PhotoInfoPanel'
-import { COLOR_LABEL_OPTIONS } from '../../constants/colorLabels'
-
-/**
- * Right-hand details panel.
- *  - 1 photo selected → delegates to PhotoInfoPanel for the full editor.
- *  - 2+ photos selected → renders a slim bulk-action panel that fans out
- *    rating / color / discard / pick across the entire selection.
- */
-interface RightSidebarProps {
-  onCollapse: () => void
-}
-
-export function RightSidebar({ onCollapse }: RightSidebarProps) {
-  const { selectedPhotos, activePhotoId, clearSelection } = usePhotoStore()
-  const queryClient = useQueryClient()
-
-  const invalidatePhotoQueries = () => {
-    queryClient.invalidateQueries({ queryKey: ['photo'] })
-    queryClient.invalidateQueries({ queryKey: ['photos'] })
-  }
-
-  const bulkRatingMutation = useMutation({
-    mutationFn: ({ ids, rating }: { ids: string[]; rating: number }) =>
-      photosApi.bulkSetRating(ids, rating),
-    onSuccess: invalidatePhotoQueries,
-  })
-  const bulkColorMutation = useMutation({
-    mutationFn: ({ ids, color }: { ids: string[]; color: string | null }) =>
-      photosApi.bulkSetColor(ids, color),
-    onSuccess: invalidatePhotoQueries,
-  })
-  const bulkDiscardMutation = useMutation({
-    mutationFn: (ids: string[]) => photosApi.bulkDiscard(ids),
-    onSuccess: invalidatePhotoQueries,
-  })
-
-  // Bulk tag mutations. Tag mutations also need to invalidate the tags
-  // query so the FilterBar / sidebar tag counts stay fresh.
-  const invalidateTagsAndPhotos = () => {
-    invalidatePhotoQueries()
-    queryClient.invalidateQueries({ queryKey: TAGS_QUERY_KEY })
-  }
-  const bulkAddTagsMutation = useMutation({
-    mutationFn: ({ ids, tagIds }: { ids: string[]; tagIds: string[] }) =>
-      photosApi.bulkAddTags(ids, tagIds),
-    onSuccess: (data) => {
-      const added = data?.added ?? 0
-      toast.success(
-        'Tags added',
-        `${added} new link${added === 1 ? '' : 's'}`
-      )
-      invalidateTagsAndPhotos()
-    },
-    onError: (e: any) =>
-      toast.error('Add tags failed', e?.message || 'Unknown error'),
-  })
-  const bulkRemoveTagsMutation = useMutation({
-    mutationFn: ({ ids, tagIds }: { ids: string[]; tagIds: string[] }) =>
-      photosApi.bulkRemoveTags(ids, tagIds),
-    onSuccess: (data) => {
-      const removed = data?.removed ?? 0
-      toast.success(
-        'Tags removed',
-        `${removed} link${removed === 1 ? '' : 's'} removed`
-      )
-      invalidateTagsAndPhotos()
-    },
-    onError: (e: any) =>
-      toast.error('Remove tags failed', e?.message || 'Unknown error'),
-  })
-
-  // Idempotent create-and-attach: lets the user type a brand-new tag
-  // name and apply it to the whole selection in one click.
-  const createAndAttachMutation = useMutation({
-    mutationFn: async ({ name, ids }: { name: string; ids: string[] }) => {
-      const created = await tagsApi.create(name)
-      return photosApi.bulkAddTags(ids, [created.id])
-    },
-    onSuccess: () => {
-      toast.success('Tag created and applied')
-      invalidateTagsAndPhotos()
-    },
-    onError: (e: any) =>
-      toast.error('Create tag failed', e?.message || 'Unknown error'),
-  })
-
-  const { data: allTags = [] } = useTagsQuery()
-  const [tagInput, setTagInput] = useState('')
-
-  // Active heap membership for the bulk Pick toggle.
-  const { activeHeap, memberIds: activeHeapMembers } = useActiveHeapMembers()
-
-  const heapMutation = useMutation({
-    mutationFn: ({ ids, remove }: { ids: string[]; remove: boolean }) => {
-      if (!activeHeap || ids.length === 0) return Promise.resolve(null)
-      return remove
-        ? heapsApi.removePhotos(activeHeap.id, ids)
-        : heapsApi.addPhotos(activeHeap.id, ids)
-    },
-    onMutate: ({ ids, remove }) => {
-      if (!activeHeap || ids.length === 0) return { previous: undefined }
-      const key = ['heap-photo-ids', activeHeap.id] as const
-      const previous = queryClient.getQueryData<string[]>(key)
-      const set = new Set(previous ?? [])
-      if (remove) ids.forEach((id) => set.delete(id))
-      else ids.forEach((id) => set.add(id))
-      queryClient.setQueryData<string[]>(key, Array.from(set))
-      return { previous }
-    },
-    onError: (e: any, _vars, ctx) => {
-      if (activeHeap && ctx?.previous) {
-        queryClient.setQueryData(['heap-photo-ids', activeHeap.id], ctx.previous)
-      }
-      toast.error('Heap update failed', e?.message || 'Unknown error')
-    },
-    onSettled: () => {
-      queryClient.invalidateQueries({ queryKey: HEAPS_QUERY_KEY })
-      if (activeHeap) {
-        queryClient.invalidateQueries({
-          queryKey: ['heap-photo-ids', activeHeap.id],
-        })
-      }
-    },
-  })
-
-  // Unified header rendered in every branch so the collapse button is
-  // always reachable regardless of selection state. Title and the
-  // clear-selection X adapt to what's selected.
-  const headerTitle =
-    selectedPhotos.length === 0
-      ? 'Metadata'
-      : selectedPhotos.length === 1
-        ? 'Metadata'
-        : `${selectedPhotos.length} Photos Selected`
-
-  const Header = () => (
-    <div className="flex h-9 flex-shrink-0 items-center justify-between border-b border-border px-3">
-      <h2 className="text-[11px] font-semibold uppercase tracking-[0.14em] text-text-muted">
-        {headerTitle}
-      </h2>
-      <div className="flex items-center gap-0.5">
-        {selectedPhotos.length > 0 && (
-          <button
-            onClick={clearSelection}
-            className="rounded p-0.5 text-text-muted hover:bg-surface-2 hover:text-text"
-            title="Clear selection (Esc)"
-            aria-label="Clear selection"
-          >
-            <X className="h-3.5 w-3.5" />
-          </button>
-        )}
-        <button
-          onClick={onCollapse}
-          className="rounded p-0.5 text-text-muted hover:bg-surface-2 hover:text-text"
-          title="Collapse panel (I)"
-          aria-label="Collapse panel"
-        >
-          <PanelRightClose className="h-3.5 w-3.5" />
-        </button>
-      </div>
-    </div>
-  )
-
-  if (selectedPhotos.length === 0) {
-    return (
-      <div className="flex h-full flex-col bg-surface">
-        <Header />
-        <div className="flex flex-1 items-center justify-center p-4 text-center">
-          <div className="text-text-muted">
-            <Info className="mx-auto mb-2 h-8 w-8" />
-            <p className="text-sm">Select photos to view details</p>
-          </div>
-        </div>
-      </div>
-    )
-  }
-
-  // ── Single-photo: full editor via PhotoInfoPanel ────────────────────
-  if (selectedPhotos.length === 1) {
-    const id = activePhotoId ?? selectedPhotos[0]
-    return (
-      <div className="flex h-full flex-col bg-surface">
-        <Header />
-        <PhotoInfoPanel photoId={id} />
-      </div>
-    )
-  }
-
-  // ── Multi-photo: bulk action panel ──────────────────────────────────
-  const allMembers = selectedPhotos.every((id) => activeHeapMembers.has(id))
-
-  return (
-    <div className="flex h-full flex-col bg-surface">
-      <Header />
-
-      <div className="space-y-2.5 border-b border-border p-3">
-        <p className="text-[11px] text-text-muted">
-          Rating, color, and flag apply to all {selectedPhotos.length} selected.
-        </p>
-
-        {/* Bulk rating */}
-        <div>
-          <label className="mb-1 block text-xs text-text-muted">Rating</label>
-          <div className="flex gap-1">
-            {[1, 2, 3, 4, 5].map((value) => (
-              <button
-                key={value}
-                onClick={() =>
-                  bulkRatingMutation.mutate({ ids: selectedPhotos, rating: value })
-                }
-                className="p-0.5"
-                title={`Set rating to ${value}`}
-              >
-                <Star className="h-5 w-5 text-text-muted hover:text-star" />
-              </button>
-            ))}
-            <button
-              onClick={() =>
-                bulkRatingMutation.mutate({ ids: selectedPhotos, rating: 0 })
-              }
-              className="ml-1 rounded px-1 text-xs text-text-muted hover:text-text"
-              title="Clear rating"
-            >
-              clear
-            </button>
-          </div>
-        </div>
-
-        {/* Bulk color */}
-        <div>
-          <label className="mb-1 block text-xs text-text-muted">Color label</label>
-          <div className="flex items-center gap-1.5">
-            {COLOR_LABEL_OPTIONS.map(({ value, className }) => (
-              <button
-                key={value}
-                onClick={() =>
-                  bulkColorMutation.mutate({ ids: selectedPhotos, color: value })
-                }
-                className={clsx(
-                  'h-5 w-5 rounded-full opacity-80 ring-offset-2 ring-offset-surface transition-all hover:opacity-100',
-                  className
-                )}
-                title={value}
-              />
-            ))}
-            <button
-              onClick={() =>
-                bulkColorMutation.mutate({ ids: selectedPhotos, color: null })
-              }
-              className="ml-1 rounded p-0.5 text-text-muted hover:bg-surface-2 hover:text-text"
-              title="Clear color label"
-            >
-              <X className="h-3 w-3" />
-            </button>
-          </div>
-        </div>
-
-        {/* Bulk flag */}
-        <div>
-          <label className="mb-1 block text-xs text-text-muted">Flag</label>
-          <div className="flex gap-2">
-            <button
-              onClick={() => {
-                if (!activeHeap) return
-                heapMutation.mutate({ ids: selectedPhotos, remove: allMembers })
-              }}
-              disabled={!activeHeap || heapMutation.isPending}
-              className={clsx(
-                'flex items-center gap-1 rounded px-2 py-1 text-sm transition-colors disabled:cursor-not-allowed disabled:opacity-50',
-                allMembers
-                  ? 'bg-pick/20 text-pick'
-                  : 'bg-surface-2 text-text-muted hover:bg-surface-offset'
-              )}
-              title={
-                activeHeap
-                  ? allMembers
-                    ? `Remove all from "${activeHeap.name}"`
-                    : `Add all to "${activeHeap.name}"`
-                  : 'Set an active heap first'
-              }
-            >
-              <ShoppingBasket className="h-3 w-3" />
-              {allMembers ? 'Picked' : 'Pick'}
-            </button>
-            <button
-              onClick={() => bulkDiscardMutation.mutate(selectedPhotos)}
-              className="flex items-center gap-1 rounded bg-surface-2 px-2 py-1 text-sm text-text-muted transition-colors hover:bg-surface-offset"
-            >
-              <Trash2 className="h-3 w-3" />
-              Discard
-            </button>
-          </div>
-        </div>
-
-        {/* Bulk tags. Click an existing tag chip to apply it to the
-         *  whole selection; long-press / X icon to remove. The text
-         *  input adds an existing tag if it matches a name, or creates
-         *  a new tag and applies it. */}
-        <div>
-          <label className="mb-1 block text-xs text-text-muted">Tags</label>
-          <BulkTagsEditor
-            allTags={allTags}
-            tagInput={tagInput}
-            onTagInputChange={setTagInput}
-            disabled={
-              bulkAddTagsMutation.isPending ||
-              bulkRemoveTagsMutation.isPending ||
-              createAndAttachMutation.isPending
-            }
-            onApply={(tagId) =>
-              bulkAddTagsMutation.mutate({ ids: selectedPhotos, tagIds: [tagId] })
-            }
-            onRemove={(tagId) =>
-              bulkRemoveTagsMutation.mutate({
-                ids: selectedPhotos,
-                tagIds: [tagId],
-              })
-            }
-            onCreate={(name) => {
-              createAndAttachMutation.mutate({ name, ids: selectedPhotos })
-              setTagInput('')
-            }}
-          />
-        </div>
-      </div>
-    </div>
-  )
-}
-
-interface BulkTagsEditorProps {
-  allTags: { id: string; name: string; color: string | null }[]
-  tagInput: string
-  onTagInputChange: (value: string) => void
-  disabled: boolean
-  onApply: (tagId: string) => void
-  onRemove: (tagId: string) => void
-  onCreate: (name: string) => void
-}
-
-/**
- * Compact bulk tag editor for the multi-select right sidebar. Unlike the
- * single-photo TagsEditor we don't show "current tags" — there's no clean
- * single-photo notion of that across an arbitrary selection. Instead the
- * user picks an existing tag (apply to all) or types a new one (create
- * and apply to all).
- */
-function BulkTagsEditor({
-  allTags,
-  tagInput,
-  onTagInputChange,
-  disabled,
-  onApply,
-  onRemove,
-  onCreate,
-}: BulkTagsEditorProps) {
-  const trimmed = tagInput.trim()
-  const lower = trimmed.toLowerCase()
-
-  const filtered = trimmed
-    ? allTags.filter((t) => t.name.toLowerCase().includes(lower))
-    : allTags
-
-  const exactMatch = trimmed
-    ? allTags.find((t) => t.name.toLowerCase() === lower)
-    : null
-
-  const handleSubmit = () => {
-    if (!trimmed || disabled) return
-    if (exactMatch) {
-      onApply(exactMatch.id)
-      onTagInputChange('')
-    } else {
-      onCreate(trimmed)
-    }
-  }
-
-  return (
-    <div className="space-y-2">
-      <input
-        type="text"
-        value={tagInput}
-        onChange={(e) => onTagInputChange(e.target.value)}
-        onKeyDown={(e) => {
-          if (e.key === 'Enter') {
-            e.preventDefault()
-            handleSubmit()
-          } else if (e.key === 'Escape') {
-            onTagInputChange('')
-          }
-        }}
-        placeholder="Filter or create…"
-        disabled={disabled}
-        className="w-full rounded border border-border bg-bg px-2 py-1 text-xs text-text placeholder-text-faint focus:border-primary focus:outline-none disabled:opacity-50"
-      />
-
-      {trimmed && !exactMatch && (
-        <button
-          onClick={handleSubmit}
-          disabled={disabled}
-          className="flex w-full items-center justify-center gap-1 rounded border border-dashed border-primary/50 px-2 py-1 text-xs text-primary hover:bg-primary/10 disabled:opacity-50"
-        >
-          <Plus className="h-3 w-3" />
-          Create "{trimmed}" and apply
-        </button>
-      )}
-
-      {filtered.length > 0 ? (
-        <div className="flex max-h-40 flex-wrap gap-1 overflow-y-auto">
-          {filtered.map((tag) => (
-            <span
-              key={tag.id}
-              className="flex items-center gap-1 rounded bg-surface-2 px-2 py-0.5 text-xs text-text"
-              style={
-                tag.color
-                  ? { backgroundColor: `${tag.color}33`, color: tag.color }
-                  : undefined
-              }
-            >
-              <button
-                onClick={() => onApply(tag.id)}
-                disabled={disabled}
-                className="hover:underline disabled:opacity-50"
-                title={`Apply "${tag.name}" to selection`}
-              >
-                {tag.name}
-              </button>
-              <button
-                onClick={() => onRemove(tag.id)}
-                disabled={disabled}
-                className="rounded p-0.5 opacity-60 hover:bg-surface-offset hover:opacity-100 disabled:opacity-30"
-                title={`Remove "${tag.name}" from selection`}
-                aria-label={`Remove ${tag.name} from selection`}
-              >
-                <X className="h-3 w-3" />
-              </button>
-            </span>
-          ))}
-        </div>
-      ) : (
-        <div className="text-xs text-text-faint">No tags match</div>
-      )}
-    </div>
-  )
-}

frontend/src/components/layout/TopBar.tsx

@@ -1,119 +0,0 @@
-import { PanelLeftOpen, PanelRightOpen } from 'lucide-react'
-import desertBg from '../../assets/desert.png'
-import muleSprites from '../../assets/mule-sprites.png'
-
-interface TopBarProps {
-  leftSidebarOpen: boolean
-  rightSidebarOpen: boolean
-  onExpandLeft: () => void
-  onExpandRight: () => void
-}
-
-// Block-character ASCII rendering of "Mulimago" — sits on a black plate
-// in place of the old text title.
-const MULIMAGO_ASCII = `▖  ▖  ▜ ▘
-▛▖▞▌▌▌▐ ▌▛▛▌▀▌▛▌█▌
-▌▝ ▌▙▌▐▖▌▌▌▌█▌▙▌▙▖`
-
-const ROMAN_PAIRS: [number, string][] = [
-  [1000, 'M'], [900, 'CM'], [500, 'D'], [400, 'CD'],
-  [100, 'C'], [90, 'XC'], [50, 'L'], [40, 'XL'],
-  [10, 'X'], [9, 'IX'], [5, 'V'], [4, 'IV'], [1, 'I'],
-]
-
-function toRoman(n: number): string {
-  let result = ''
-  for (const [value, symbol] of ROMAN_PAIRS) {
-    while (n >= value) {
-      result += symbol
-      n -= value
-    }
-  }
-  return result
-}
-
-/**
- * Slim top bar — animated walking mule on the left over a tiled desert
- * backdrop, settings gear on the right. The active heap badge moved into
- * the Heaps panel in the left sidebar (where it actually relates to the
- * heap rows the user navigates to).
- *
- * Also hosts the "expand sidebar" affordances: when a side panel is
- * collapsed, a small panel-open icon appears on the corresponding edge
- * so the user has a way to bring it back without hunting for the
- * keyboard shortcut. When the panel is open, the button hides — its
- * collapse twin lives in the panel's own header.
- */
-export function TopBar({
-  leftSidebarOpen,
-  rightSidebarOpen,
-  onExpandLeft,
-  onExpandRight,
-}: TopBarProps) {
-  return (
-    <header
-      className="relative flex h-16 items-center justify-between overflow-hidden border-b border-border px-4"
-      style={{
-        // Two layers: desert tile on top (scrolls right→left), dusk-sky
-        // gradient underneath (static). Tile width is fixed at 200px so
-        // the `desert-scroll` keyframe can move by exactly one tile and
-        // loop seamlessly.
-        backgroundImage: `url(${desertBg}), linear-gradient(to bottom, #2b3a5c 0%, #6b6b8a 35%, #d68a5c 75%, #f0c188 100%)`,
-        backgroundRepeat: 'repeat-x, no-repeat',
-        backgroundSize: '200px 100%, 100% 100%',
-        backgroundPosition: '0 bottom, 0 0',
-        imageRendering: 'pixelated',
-        animation: 'desert-scroll 24s linear infinite',
-      }}
-    >
-      <div className="relative flex items-center gap-3">
-        {!leftSidebarOpen && (
-          <button
-            onClick={onExpandLeft}
-            className="rounded bg-black/30 p-1.5 text-text-muted backdrop-blur-sm transition-colors hover:bg-black/50 hover:text-text"
-            title="Expand panel (Tab)"
-            aria-label="Expand left panel"
-          >
-            <PanelLeftOpen className="h-4 w-4" />
-          </button>
-        )}
-        <div
-          aria-label="Mulimago"
-          className="h-12 w-14"
-          style={{
-            backgroundImage: `url(${muleSprites})`,
-            backgroundSize: '300% 200%',
-            backgroundRepeat: 'no-repeat',
-            imageRendering: 'pixelated',
-            animation: 'mule-walk 0.6s steps(1) infinite',
-          }}
-        />
-        <pre
-          aria-label="Mulimago"
-          className="rounded bg-black px-2 py-1 font-mono text-[8px] leading-[1.05] text-text"
-          style={{ letterSpacing: 0 }}
-        >
-          {MULIMAGO_ASCII}
-        </pre>
-      </div>
-      <div className="flex h-full items-end gap-2 self-stretch pb-1">
-        {!rightSidebarOpen && (
-          <button
-            onClick={onExpandRight}
-            className="self-center rounded bg-black/30 p-1.5 text-text-muted backdrop-blur-sm transition-colors hover:bg-black/50 hover:text-text"
-            title="Expand panel (I)"
-            aria-label="Expand right panel"
-          >
-            <PanelRightOpen className="h-4 w-4" />
-          </button>
-        )}
-        <span
-          className="text-[10px] text-black/50"
-          style={{ textShadow: '0 1px 2px rgba(0,0,0,0.7)' }}
-        >
-          Built with hubris • {toRoman(new Date().getFullYear())}
-        </span>
-      </div>
-    </header>
-  )
-}

frontend/src/components/preview/PreviewFilmstrip.tsx

@@ -1,55 +0,0 @@
-import { useEffect, useRef } from 'react'
-import clsx from 'clsx'
-import type { Photo } from '../../types/photo'
-import { photos as photosApi } from '../../services/api'
-
-interface PreviewFilmstripProps {
-  photos: Photo[]
-  currentIndex: number
-  onSelect: (id: string) => void
-}
-
-const CELL_SIZE = 72
-
-export function PreviewFilmstrip({ photos, currentIndex, onSelect }: PreviewFilmstripProps) {
-  const activeRef = useRef<HTMLButtonElement>(null)
-
-  useEffect(() => {
-    activeRef.current?.scrollIntoView({
-      block: 'nearest',
-      inline: 'center',
-      behavior: 'smooth',
-    })
-  }, [currentIndex])
-
-  return (
-    <div className="flex h-24 shrink-0 items-center gap-1 overflow-x-auto border-t border-border bg-surface px-2 py-2">
-      {photos.map((photo, index) => {
-        const isActive = index === currentIndex
-        return (
-          <button
-            key={photo.id}
-            ref={isActive ? activeRef : null}
-            onClick={() => onSelect(photo.id)}
-            className={clsx(
-              'shrink-0 overflow-hidden rounded-sm transition-all',
-              'hover:opacity-100',
-              isActive
-                ? 'ring-2 ring-primary opacity-100'
-                : 'opacity-60'
-            )}
-            style={{ width: CELL_SIZE, height: CELL_SIZE }}
-            title={photo.filename}
-          >
-            <img
-              src={photosApi.getThumbnailUrl(photo.id, 'small')}
-              alt={photo.filename}
-              loading="lazy"
-              className="h-full w-full object-cover"
-            />
-          </button>
-        )
-      })}
-    </div>
-  )
-}

frontend/src/components/preview/PreviewImage.tsx

@@ -1,178 +0,0 @@
-import { useState, useEffect, useRef, useCallback } from 'react'
-import { useHotkeys } from 'react-hotkeys-hook'
-import type { Photo } from '../../types/photo'
-import {
-  getPreviewImageSrc,
-  getPreviewFallbackSrc,
-  getVideoSrc,
-  isVideo,
-} from './previewSrc'
-
-interface PreviewImageProps {
-  photo: Photo
-}
-
-const MIN_SCALE = 1
-const MAX_SCALE = 8
-const WHEEL_STEP = 1.15
-
-export function PreviewImage({ photo }: PreviewImageProps) {
-  if (isVideo(photo)) {
-    return <PreviewVideo photo={photo} />
-  }
-  return <PreviewStillImage photo={photo} />
-}
-
-function PreviewVideo({ photo }: { photo: Photo }) {
-  return (
-    <div className="flex flex-1 items-center justify-center bg-black">
-      <video
-        key={photo.id}
-        src={getVideoSrc(photo)}
-        controls
-        autoPlay
-        muted
-        className="max-h-full max-w-full"
-      />
-    </div>
-  )
-}
-
-function PreviewStillImage({ photo }: { photo: Photo }) {
-  const [loaded, setLoaded] = useState(false)
-  const [usingFallback, setUsingFallback] = useState(false)
-
-  // scale=1 means "fit to viewport". Anything >1 zooms in; we don't allow <1
-  // because the fit size already fills the viewport.
-  const [scale, setScale] = useState(1)
-  const [offset, setOffset] = useState({ x: 0, y: 0 })
-  const dragStateRef = useRef<{ x: number; y: number; ox: number; oy: number } | null>(null)
-  const imgRef = useRef<HTMLImageElement>(null)
-
-  // Reset everything when the photo changes.
-  useEffect(() => {
-    setLoaded(false)
-    setUsingFallback(false)
-    setScale(1)
-    setOffset({ x: 0, y: 0 })
-  }, [photo.id])
-
-  const primarySrc = getPreviewImageSrc(photo)
-  const fallbackSrc = getPreviewFallbackSrc(photo)
-  const src = usingFallback ? fallbackSrc : primarySrc
-
-  const handleError = () => {
-    if (!usingFallback && primarySrc !== fallbackSrc) {
-      setUsingFallback(true)
-    }
-  }
-
-  // Z key: toggle between fit (scale=1) and actual size (natural/displayed).
-  // If we're already zoomed (manual wheel zoom), Z snaps back to fit.
-  const toggleZoom = useCallback(() => {
-    if (scale !== 1) {
-      setScale(1)
-      setOffset({ x: 0, y: 0 })
-      return
-    }
-    const img = imgRef.current
-    if (!img) return
-    const ratio = img.naturalWidth / img.clientWidth
-    if (!isFinite(ratio) || ratio <= 1) return
-    setScale(Math.min(ratio, MAX_SCALE))
-  }, [scale])
-
-  useHotkeys(
-    'z',
-    (e) => {
-      e.preventDefault()
-      toggleZoom()
-    },
-    { preventDefault: true },
-    [toggleZoom]
-  )
-
-  const handleWheel = (e: React.WheelEvent) => {
-    e.preventDefault()
-    const delta = e.deltaY < 0 ? WHEEL_STEP : 1 / WHEEL_STEP
-    setScale((prev) => {
-      const next = Math.min(MAX_SCALE, Math.max(MIN_SCALE, prev * delta))
-      // Snapping back to 1 also resets pan offset.
-      if (next === 1) setOffset({ x: 0, y: 0 })
-      return next
-    })
-  }
-
-  const handleMouseDown = (e: React.MouseEvent) => {
-    if (scale === 1) return
-    e.preventDefault()
-    dragStateRef.current = {
-      x: e.clientX,
-      y: e.clientY,
-      ox: offset.x,
-      oy: offset.y,
-    }
-  }
-
-  const handleMouseMove = (e: React.MouseEvent) => {
-    const drag = dragStateRef.current
-    if (!drag) return
-    setOffset({
-      x: drag.ox + (e.clientX - drag.x),
-      y: drag.oy + (e.clientY - drag.y),
-    })
-  }
-
-  const endDrag = () => {
-    dragStateRef.current = null
-  }
-
-  const isZoomed = scale > 1
-  const cursor = isZoomed
-    ? dragStateRef.current
-      ? 'grabbing'
-      : 'grab'
-    : 'zoom-in'
-
-  return (
-    <div
-      className="relative flex flex-1 select-none items-center justify-center overflow-hidden bg-black"
-      onWheel={handleWheel}
-      onMouseDown={handleMouseDown}
-      onMouseMove={handleMouseMove}
-      onMouseUp={endDrag}
-      onMouseLeave={endDrag}
-      style={{ cursor }}
-    >
-      <img
-        ref={imgRef}
-        key={`${photo.id}-${usingFallback}`}
-        src={src}
-        alt={photo.filename}
-        loading="eager"
-        decoding="async"
-        draggable={false}
-        onLoad={() => setLoaded(true)}
-        onError={handleError}
-        className="max-h-full max-w-full object-contain"
-        style={{
-          transform: `translate(${offset.x}px, ${offset.y}px) scale(${scale})`,
-          transformOrigin: 'center center',
-          willChange: 'transform',
-        }}
-      />
-      {!loaded && (
-        <div className="pointer-events-none absolute inset-0 flex items-center justify-center text-text-muted">
-          <div className="h-10 w-10 animate-spin rounded-full border-2 border-primary/30 border-t-primary" />
-        </div>
-      )}
-
-      {/* Zoom indicator */}
-      {isZoomed && (
-        <div className="pointer-events-none absolute bottom-3 left-1/2 -translate-x-1/2 rounded bg-black/60 px-2 py-1 text-xs font-mono text-white">
-          {Math.round(scale * 100)}%
-        </div>
-      )}
-    </div>
-  )
-}

frontend/src/components/preview/PreviewView.tsx

@@ -1,215 +0,0 @@
-import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
-import { useHotkeys } from 'react-hotkeys-hook'
-import { X, Info } from 'lucide-react'
-import { usePhotoStore } from '../../store/photoStore'
-import { usePhotosQuery } from '../../hooks/usePhotosQuery'
-import type { Photo } from '../../types/photo'
-import { PreviewImage } from './PreviewImage'
-import { PreviewFilmstrip } from './PreviewFilmstrip'
-import { getPreviewImageSrc, isVideo } from './previewSrc'
-import { PhotoInfoPanel } from '../sidebar/PhotoInfoPanel'
-
-export function PreviewView() {
-  const activePhotoId = usePhotoStore((s) => s.activePhotoId)
-  const setActivePhoto = usePhotoStore((s) => s.setActivePhoto)
-  const closePreview = usePhotoStore((s) => s.closePreview)
-  const visiblePhotoIds = usePhotoStore((s) => s.visiblePhotoIds)
-
-  const containerRef = useRef<HTMLDivElement>(null)
-  const previouslyFocusedRef = useRef<HTMLElement | null>(null)
-  const [infoPanelOpen, setInfoPanelOpen] = useState(false)
-
-  // Same hook Timeline uses, so we share one cache entry rather than looking
-  // it up by key (which broke when the key gained the filter params).
-  const { data: rawPhotos = [] } = usePhotosQuery()
-
-  // Walk the timeline's visible-order sequence (published by Timeline
-  // into the photo store), which respects tag-grouping and any other
-  // grid-layout rearrangement. Falls back to the raw photos list when
-  // the sequence isn't populated yet — relevant on a fresh page load
-  // where the user opened preview before the timeline mounted.
-  const photos: Photo[] = useMemo(() => {
-    if (visiblePhotoIds.length === 0) return rawPhotos
-    const byId = new Map(rawPhotos.map((p) => [p.id, p]))
-    const out: Photo[] = []
-    for (const id of visiblePhotoIds) {
-      const p = byId.get(id)
-      if (p) out.push(p)
-    }
-    return out
-  }, [visiblePhotoIds, rawPhotos])
-
-  const currentIndex = activePhotoId
-    ? photos.findIndex((p) => p.id === activePhotoId)
-    : 0
-  const safeIndex = currentIndex < 0 ? 0 : currentIndex
-  const currentPhoto: Photo | undefined = photos[safeIndex]
-
-  // Keep the latest photos array + active id in a ref so the keyboard
-  // handlers ALWAYS read the freshest state. Without this, react-hotkeys-
-  // hook can fire a closure that captured an older photos array (e.g.
-  // the empty initial render before visiblePhotoIds was applied) and
-  // arrow nav lands on the wrong photo or no-ops.
-  const navRef = useRef({ photos, activePhotoId })
-  navRef.current = { photos, activePhotoId }
-
-  const goPrev = useCallback(() => {
-    const { photos: ps, activePhotoId: aid } = navRef.current
-    if (ps.length === 0) return
-    const idx = aid ? ps.findIndex((p) => p.id === aid) : 0
-    const safe = idx < 0 ? 0 : idx
-    const next = Math.max(0, safe - 1)
-    setActivePhoto(ps[next].id)
-  }, [setActivePhoto])
-
-  const goNext = useCallback(() => {
-    const { photos: ps, activePhotoId: aid } = navRef.current
-    if (ps.length === 0) return
-    const idx = aid ? ps.findIndex((p) => p.id === aid) : 0
-    const safe = idx < 0 ? 0 : idx
-    const next = Math.min(ps.length - 1, safe + 1)
-    setActivePhoto(ps[next].id)
-  }, [setActivePhoto])
-
-  // Preview-scoped hotkeys: only mounted while PreviewView is rendered.
-  // The handlers themselves are stable (refs internally) so the deps
-  // array stays empty — useHotkeys won't have to re-bind on every render.
-  useHotkeys('escape', closePreview, { preventDefault: true })
-  useHotkeys('left', goPrev, { preventDefault: true })
-  useHotkeys('right', goNext, { preventDefault: true })
-  useHotkeys('i', () => setInfoPanelOpen((v) => !v), { preventDefault: true })
-
-  // Preload the immediate neighbors so arrow nav feels instant. Skip videos
-  // (browsers can't preload them via Image()) and skip when at the edges.
-  useEffect(() => {
-    const neighbors: Photo[] = []
-    if (safeIndex > 0) neighbors.push(photos[safeIndex - 1])
-    if (safeIndex < photos.length - 1) neighbors.push(photos[safeIndex + 1])
-    for (const p of neighbors) {
-      if (isVideo(p)) continue
-      const img = new Image()
-      img.src = getPreviewImageSrc(p)
-    }
-  }, [safeIndex, photos])
-
-  // Focus trap: focus the preview container on mount, restore focus on
-  // unmount. The container is keyboard-focusable (tabIndex=-1) so screen
-  // readers and tab navigation stay scoped here.
-  useEffect(() => {
-    previouslyFocusedRef.current = document.activeElement as HTMLElement | null
-    containerRef.current?.focus()
-    return () => {
-      previouslyFocusedRef.current?.focus?.()
-    }
-  }, [])
-
-  // Trap Tab inside the dialog so users can't accidentally tab into the
-  // hidden grid behind. Simple cycle implementation.
-  const handleKeyDown = (e: React.KeyboardEvent) => {
-    if (e.key !== 'Tab') return
-    const root = containerRef.current
-    if (!root) return
-    const focusable = root.querySelectorAll<HTMLElement>(
-      'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
-    )
-    if (focusable.length === 0) {
-      e.preventDefault()
-      root.focus()
-      return
-    }
-    const first = focusable[0]
-    const last = focusable[focusable.length - 1]
-    const active = document.activeElement as HTMLElement | null
-    if (e.shiftKey && active === first) {
-      e.preventDefault()
-      last.focus()
-    } else if (!e.shiftKey && active === last) {
-      e.preventDefault()
-      first.focus()
-    }
-  }
-
-  if (!currentPhoto) {
-    return (
-      <div
-        ref={containerRef}
-        role="dialog"
-        aria-modal="true"
-        aria-label="Photo preview"
-        tabIndex={-1}
-        className="fixed inset-0 z-40 flex flex-col items-center justify-center bg-black text-text-muted outline-none"
-      >
-        <div>No photo to display</div>
-        <button
-          onClick={closePreview}
-          className="mt-4 rounded border border-border px-3 py-1 text-sm hover:bg-surface"
-        >
-          Close
-        </button>
-      </div>
-    )
-  }
-
-  return (
-    <div
-      ref={containerRef}
-      role="dialog"
-      aria-modal="true"
-      aria-label={`Photo preview: ${currentPhoto.filename}`}
-      tabIndex={-1}
-      onKeyDown={handleKeyDown}
-      className="fixed inset-0 z-40 flex bg-black outline-none"
-    >
-      {/* Main column — image + filmstrip */}
-      <div className="relative flex min-w-0 flex-1 flex-col">
-        {/* Filename + counter */}
-        <div className="absolute left-3 top-3 z-10 rounded bg-black/60 px-3 py-1.5 text-xs text-white">
-          <div className="font-mono">{currentPhoto.filename}</div>
-          <div className="text-text-muted">
-            {safeIndex + 1} / {photos.length}
-          </div>
-        </div>
-
-        {/* Top-right action buttons */}
-        <div className="absolute right-3 top-3 z-10 flex items-center gap-2">
-          <button
-            onClick={() => setInfoPanelOpen((v) => !v)}
-            className={
-              'flex h-9 w-9 items-center justify-center rounded-full bg-black/60 text-white transition hover:bg-black/80 ' +
-              (infoPanelOpen ? 'ring-2 ring-primary' : '')
-            }
-            title="Toggle info panel (I)"
-            aria-label="Toggle info panel"
-            aria-pressed={infoPanelOpen}
-          >
-            <Info className="h-5 w-5" />
-          </button>
-          <button
-            onClick={closePreview}
-            className="flex h-9 w-9 items-center justify-center rounded-full bg-black/60 text-white transition hover:bg-black/80"
-            title="Close (Esc)"
-            aria-label="Close preview"
-          >
-            <X className="h-5 w-5" />
-          </button>
-        </div>
-
-        <PreviewImage photo={currentPhoto} />
-
-        <PreviewFilmstrip
-          photos={photos}
-          currentIndex={safeIndex}
-          onSelect={setActivePhoto}
-        />
-      </div>
-
-      {/* Right info panel — slides in/out, mirrors the grid right sidebar
-       *  but lives inside the preview overlay so it isn't covered by it. */}
-      {infoPanelOpen && (
-        <aside className="w-80 shrink-0 overflow-hidden border-l border-border bg-surface">
-          <PhotoInfoPanel photoId={currentPhoto.id} />
-        </aside>
-      )}
-    </div>
-  )
-}

frontend/src/components/preview/previewSrc.ts

@@ -1,33 +0,0 @@
-import { photos as photosApi } from '../../services/api'
-import type { Photo } from '../../types/photo'
-
-const VIDEO_EXTENSIONS = ['.mp4', '.mov', '.webm', '.mkv', '.m4v']
-
-export function isVideo(photo: Photo): boolean {
-  if (photo.media_type === 'video') return true
-  const lower = photo.filepath.toLowerCase()
-  return VIDEO_EXTENSIONS.some((ext) => lower.endsWith(ext))
-}
-
-/**
- * Pick the best display URL for a still photo in the preview view.
- *
- * Always uses the /proxy endpoint, which the backend resolves to:
- *   - the original file for web-safe formats (JPEG/PNG/WebP/GIF)
- *   - a transcoded full-res WebP for RAW/HEIC/TIFF (cached on first hit)
- *
- * Videos go through `getVideoSrc` instead and use /original directly.
- */
-export function getPreviewImageSrc(photo: Photo): string {
-  return photosApi.getProxyUrl(photo.id)
-}
-
-/** Fallback used when the proxy endpoint fails or 404s — shows the 1280px
- *  large thumbnail so the user still sees something. */
-export function getPreviewFallbackSrc(photo: Photo): string {
-  return photosApi.getThumbnailUrl(photo.id, 'large')
-}
-
-export function getVideoSrc(photo: Photo): string {
-  return photosApi.getOriginalUrl(photo.id)
-}

frontend/src/components/sidebar/PhotoInfoPanel.tsx

@@ -1,741 +0,0 @@
-import { useEffect, useMemo, useState } from 'react'
-import {
-  X,
-  Star,
-  MapPin,
-  Camera,
-  Aperture,
-  ChevronDown,
-  ChevronRight,
-  ShoppingBasket,
-  Trash2,
-} from 'lucide-react'
-import clsx from 'clsx'
-import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
-import { format } from 'date-fns'
-import {
-  photos as photosApi,
-  heaps as heapsApi,
-  tags as tagsApi,
-  type Tag,
-} from '../../services/api'
-import { useActiveHeapMembers } from '../../hooks/useActiveHeapMembersQuery'
-import { HEAPS_QUERY_KEY } from '../../hooks/useHeapsQuery'
-import { useTagsQuery, TAGS_QUERY_KEY } from '../../hooks/useTagsQuery'
-import { toast } from '../ToastContainer'
-import {
-  COLOR_LABEL_OPTIONS,
-  type ColorLabel,
-} from '../../constants/colorLabels'
-
-interface PhotoTagSummary {
-  id: string
-  name: string
-  color: string | null
-}
-
-interface PhotoDetails {
-  id: string
-  filename: string
-  filepath: string
-  width: number | null
-  height: number | null
-  file_size: number | null
-  taken_at: string | null
-  rating: number
-  is_discarded: boolean
-  user_title: string | null
-  user_notes: string | null
-  color_label: string | null
-  exif_json: string | null
-  tags?: PhotoTagSummary[]
-}
-
-interface ExifData {
-  Make?: string
-  Model?: string
-  LensModel?: string
-  Lens?: string
-  ISO?: number | string
-  FNumber?: number | string
-  ApertureValue?: number | string
-  ExposureTime?: string
-  ShutterSpeedValue?: string
-  FocalLength?: string
-  FocalLengthIn35mmFormat?: string
-  GPSLatitude?: number | string
-  GPSLongitude?: number | string
-  [key: string]: unknown
-}
-
-function formatFileSize(bytes: number | null): string {
-  if (bytes == null) return '—'
-  if (bytes < 1024) return `${bytes} B`
-  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`
-  if (bytes < 1024 * 1024 * 1024) return `${(bytes / 1024 / 1024).toFixed(1)} MB`
-  return `${(bytes / 1024 / 1024 / 1024).toFixed(2)} GB`
-}
-
-function formatExifValue(v: unknown): string {
-  if (v == null || v === '') return '—'
-  return String(v)
-}
-
-function pickFirst(exif: ExifData, ...keys: string[]): string {
-  for (const k of keys) {
-    const v = exif[k]
-    if (v != null && v !== '') return String(v)
-  }
-  return '—'
-}
-
-function parseExif(json: string | null): ExifData {
-  if (!json) return {}
-  try {
-    const parsed = JSON.parse(json)
-    return typeof parsed === 'object' && parsed !== null ? (parsed as ExifData) : {}
-  } catch {
-    return {}
-  }
-}
-
-interface PhotoInfoPanelProps {
-  /** The photo to show metadata for. Drives an on-demand detail fetch. */
-  photoId: string
-  /** When true, the editable text fields (filename, title, notes) render
-   *  with a darker theme to read against a black preview backdrop. */
-  darkTheme?: boolean
-}
-
-/**
- * Reusable single-photo metadata + edit panel. Used by both the grid
- * RightSidebar (when one photo is selected) and the PreviewView's optional
- * info overlay. Self-contained — owns its own queries and mutations.
- */
-export function PhotoInfoPanel({ photoId, darkTheme = false }: PhotoInfoPanelProps) {
-  const queryClient = useQueryClient()
-
-  const [expandedSections, setExpandedSections] = useState<Set<string>>(
-    new Set(['basic', 'camera', 'location', 'tags'])
-  )
-  const toggleSection = (section: string) => {
-    const next = new Set(expandedSections)
-    if (next.has(section)) next.delete(section)
-    else next.add(section)
-    setExpandedSections(next)
-  }
-
-  // Fetch the photo's full record (with EXIF) on demand.
-  const { data: photo } = useQuery<PhotoDetails>({
-    queryKey: ['photo', photoId],
-    queryFn: () => photosApi.get(photoId),
-    enabled: !!photoId,
-    staleTime: 60_000,
-  })
-
-  // Mutation for any patchable field. Invalidates both the photo detail
-  // cache and the timeline list so the grid reflects the change too.
-  const updateMutation = useMutation({
-    mutationFn: (data: {
-      filename?: string
-      rating?: number
-      is_discarded?: boolean
-      user_title?: string | null
-      user_notes?: string | null
-      color_label?: string | null
-    }) => photosApi.update(photoId, data),
-    onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ['photo', photoId] })
-      queryClient.invalidateQueries({ queryKey: ['photos'] })
-    },
-  })
-
-  // Active heap membership for the Pick toggle button.
-  const { activeHeap, memberIds: activeHeapMembers } = useActiveHeapMembers()
-  const isInActiveHeap = activeHeapMembers.has(photoId)
-
-  const heapMutation = useMutation({
-    mutationFn: ({ remove }: { remove: boolean }) => {
-      if (!activeHeap) return Promise.resolve(null)
-      return remove
-        ? heapsApi.removePhotos(activeHeap.id, [photoId])
-        : heapsApi.addPhotos(activeHeap.id, [photoId])
-    },
-    onMutate: ({ remove }) => {
-      if (!activeHeap) return { previous: undefined }
-      const key = ['heap-photo-ids', activeHeap.id] as const
-      const previous = queryClient.getQueryData<string[]>(key)
-      const set = new Set(previous ?? [])
-      if (remove) set.delete(photoId)
-      else set.add(photoId)
-      queryClient.setQueryData<string[]>(key, Array.from(set))
-      return { previous }
-    },
-    onError: (_e, _vars, ctx) => {
-      if (activeHeap && ctx?.previous) {
-        queryClient.setQueryData(['heap-photo-ids', activeHeap.id], ctx.previous)
-      }
-    },
-    onSettled: () => {
-      queryClient.invalidateQueries({ queryKey: HEAPS_QUERY_KEY })
-      if (activeHeap) {
-        queryClient.invalidateQueries({
-          queryKey: ['heap-photo-ids', activeHeap.id],
-        })
-      }
-    },
-  })
-
-  // ── Tags state + mutations ──────────────────────────────────────────
-  const { data: allTags = [] } = useTagsQuery()
-  const [tagInput, setTagInput] = useState('')
-
-  const invalidateTagsAndPhoto = () => {
-    queryClient.invalidateQueries({ queryKey: TAGS_QUERY_KEY })
-    queryClient.invalidateQueries({ queryKey: ['photo', photoId] })
-    queryClient.invalidateQueries({ queryKey: ['photos'] })
-  }
-
-  const addTagMutation = useMutation({
-    mutationFn: async (name: string) => {
-      const created = await tagsApi.create(name)
-      await tagsApi.addToPhoto(photoId, [created.id])
-      return created
-    },
-    onSuccess: () => invalidateTagsAndPhoto(),
-    onError: (e: any) =>
-      toast.error('Add tag failed', e?.message || 'Unknown error'),
-  })
-
-  const attachExistingTagMutation = useMutation({
-    mutationFn: (tagId: string) => tagsApi.addToPhoto(photoId, [tagId]),
-    onSuccess: () => invalidateTagsAndPhoto(),
-    onError: (e: any) =>
-      toast.error('Add tag failed', e?.message || 'Unknown error'),
-  })
-
-  const removeTagMutation = useMutation({
-    mutationFn: (tagId: string) => tagsApi.removeFromPhoto(photoId, tagId),
-    onSuccess: () => invalidateTagsAndPhoto(),
-    onError: (e: any) =>
-      toast.error('Remove tag failed', e?.message || 'Unknown error'),
-  })
-
-  // Local drafts for the text fields. Mirror the server value but stay
-  // independent while typing so we don't fight focus or clobber edits.
-  const [filenameDraft, setFilenameDraft] = useState('')
-  const [titleDraft, setTitleDraft] = useState('')
-  const [notesDraft, setNotesDraft] = useState('')
-
-  useEffect(() => {
-    setFilenameDraft(photo?.filename ?? '')
-    setTitleDraft(photo?.user_title ?? '')
-    setNotesDraft(photo?.user_notes ?? '')
-  }, [photo?.id, photo?.filename, photo?.user_title, photo?.user_notes])
-
-  const commitFilename = () => {
-    const next = filenameDraft.trim()
-    const current = photo?.filename ?? ''
-    if (!next || next === current) {
-      setFilenameDraft(current)
-      return
-    }
-    if (next.includes('/') || next.includes('\\') || next === '.' || next === '..') {
-      toast.error('Invalid filename', 'No path separators allowed')
-      setFilenameDraft(current)
-      return
-    }
-    updateMutation.mutate(
-      { filename: next },
-      {
-        onError: (e: any) => {
-          toast.error(
-            'Rename failed',
-            e?.response?.data?.detail || e.message || 'Unknown error'
-          )
-          setFilenameDraft(current)
-        },
-      }
-    )
-  }
-
-  const commitTitle = () => {
-    const next = titleDraft.trim()
-    const current = photo?.user_title ?? ''
-    if (next === current) return
-    updateMutation.mutate({ user_title: next || null })
-  }
-
-  const commitNotes = () => {
-    const next = notesDraft
-    const current = photo?.user_notes ?? ''
-    if (next === current) return
-    updateMutation.mutate({ user_notes: next || null })
-  }
-
-  const exif = useMemo(() => parseExif(photo?.exif_json ?? null), [photo?.exif_json])
-
-  if (!photo) {
-    return <div className="p-4 text-xs text-text-muted">Loading…</div>
-  }
-
-  const rating = photo.rating ?? 0
-  const isDiscarded = photo.is_discarded ?? false
-  const colorLabel = (photo.color_label ?? null) as ColorLabel | null
-
-  // Single themable input class so the same component reads against either
-  // the surface (grid sidebar) or a darker preview overlay.
-  const inputClass = clsx(
-    'w-full rounded border px-2 py-1 text-sm focus:outline-none',
-    darkTheme
-      ? 'border-white/15 bg-black/40 text-white placeholder-white/40 focus:border-primary'
-      : 'border-border bg-bg text-text placeholder-text-faint focus:border-primary'
-  )
-  const monoInputClass = clsx(
-    'w-full rounded border px-2 py-1 font-mono text-xs focus:outline-none',
-    darkTheme
-      ? 'border-white/15 bg-black/40 text-white placeholder-white/40 focus:border-primary'
-      : 'border-border bg-bg text-text placeholder-text-faint focus:border-primary'
-  )
-
-  return (
-    <div className="flex h-full flex-col">
-      {/* Edit fields */}
-      <div className="space-y-2.5 border-b border-border p-3">
-        <div>
-          <label className="mb-1 block text-xs text-text-muted">Filename</label>
-          <input
-            type="text"
-            value={filenameDraft}
-            onChange={(e) => setFilenameDraft(e.target.value)}
-            onBlur={commitFilename}
-            onKeyDown={(e) => {
-              if (e.key === 'Enter') {
-                e.currentTarget.blur()
-              } else if (e.key === 'Escape') {
-                setFilenameDraft(photo.filename ?? '')
-                e.currentTarget.blur()
-              }
-            }}
-            className={monoInputClass}
-          />
-        </div>
-
-        <div>
-          <label className="mb-1 block text-xs text-text-muted">Title</label>
-          <input
-            type="text"
-            value={titleDraft}
-            onChange={(e) => setTitleDraft(e.target.value)}
-            onBlur={commitTitle}
-            onKeyDown={(e) => {
-              if (e.key === 'Enter') {
-                e.currentTarget.blur()
-              } else if (e.key === 'Escape') {
-                setTitleDraft(photo.user_title ?? '')
-                e.currentTarget.blur()
-              }
-            }}
-            placeholder="No title"
-            className={inputClass}
-          />
-        </div>
-
-        <div>
-          <label className="mb-1 block text-xs text-text-muted">Notes</label>
-          <textarea
-            value={notesDraft}
-            onChange={(e) => setNotesDraft(e.target.value)}
-            onBlur={commitNotes}
-            placeholder="Add notes…"
-            rows={3}
-            className={clsx(inputClass, 'resize-none')}
-          />
-        </div>
-
-        {/* Rating */}
-        <div>
-          <label className="mb-1 block text-xs text-text-muted">Rating</label>
-          <div className="flex gap-1">
-            {[1, 2, 3, 4, 5].map((value) => (
-              <button
-                key={value}
-                onClick={() =>
-                  updateMutation.mutate({ rating: rating === value ? 0 : value })
-                }
-                className="p-0.5"
-                title={`Set rating to ${value}`}
-              >
-                <Star
-                  className={clsx(
-                    'h-5 w-5 transition-colors',
-                    value <= rating
-                      ? 'fill-star text-star'
-                      : 'text-text-muted hover:text-star'
-                  )}
-                />
-              </button>
-            ))}
-          </div>
-        </div>
-
-        {/* Color label */}
-        <div>
-          <label className="mb-1 block text-xs text-text-muted">Color label</label>
-          <div className="flex items-center gap-1.5">
-            {COLOR_LABEL_OPTIONS.map(({ value, className }) => {
-              const active = colorLabel === value
-              return (
-                <button
-                  key={value}
-                  onClick={() =>
-                    updateMutation.mutate({ color_label: active ? null : value })
-                  }
-                  className={clsx(
-                    'h-5 w-5 rounded-full ring-offset-2 ring-offset-surface transition-all',
-                    className,
-                    active ? 'ring-2 ring-primary' : 'opacity-60 hover:opacity-100'
-                  )}
-                  title={value}
-                />
-              )
-            })}
-            {colorLabel && (
-              <button
-                onClick={() => updateMutation.mutate({ color_label: null })}
-                className="ml-1 rounded p-0.5 text-text-muted hover:bg-surface-2 hover:text-text"
-                title="Clear color label"
-              >
-                <X className="h-3 w-3" />
-              </button>
-            )}
-          </div>
-        </div>
-
-        {/* Flag — Pick + Discard */}
-        <div>
-          <label className="mb-1 block text-xs text-text-muted">Flag</label>
-          <div className="flex gap-2">
-            <button
-              onClick={() => {
-                if (!activeHeap) return
-                heapMutation.mutate({ remove: isInActiveHeap })
-              }}
-              disabled={!activeHeap || heapMutation.isPending}
-              className={clsx(
-                'flex items-center gap-1 rounded px-2 py-1 text-sm transition-colors disabled:cursor-not-allowed disabled:opacity-50',
-                isInActiveHeap
-                  ? 'bg-pick/20 text-pick'
-                  : 'bg-surface-2 text-text-muted hover:bg-surface-offset'
-              )}
-              title={
-                activeHeap
-                  ? isInActiveHeap
-                    ? `Remove from "${activeHeap.name}"`
-                    : `Add to "${activeHeap.name}"`
-                  : 'Set an active heap first'
-              }
-            >
-              <ShoppingBasket className="h-3 w-3" />
-              {isInActiveHeap ? 'Picked' : 'Pick'}
-            </button>
-            <button
-              onClick={() => updateMutation.mutate({ is_discarded: !isDiscarded })}
-              className={clsx(
-                'flex items-center gap-1 rounded px-2 py-1 text-sm transition-colors',
-                isDiscarded
-                  ? 'bg-reject/20 text-reject'
-                  : 'bg-surface-2 text-text-muted hover:bg-surface-offset'
-              )}
-            >
-              <Trash2 className="h-3 w-3" />
-              Discard
-            </button>
-          </div>
-        </div>
-      </div>
-
-      {/* Read-only metadata sections */}
-      <div className="flex-1 overflow-y-auto">
-        <Section
-          title="Basic Info"
-          expanded={expandedSections.has('basic')}
-          onToggle={() => toggleSection('basic')}
-        >
-          <div className="grid grid-cols-2 gap-2 text-xs">
-            <Field label="Size" value={formatFileSize(photo.file_size)} />
-            <Field
-              label="Dimensions"
-              value={
-                photo.width && photo.height
-                  ? `${photo.width} × ${photo.height}`
-                  : '—'
-              }
-            />
-            <Field
-              label="Date Taken"
-              value={
-                photo.taken_at
-                  ? format(new Date(photo.taken_at), 'MMM d, yyyy HH:mm')
-                  : '—'
-              }
-            />
-          </div>
-          {/* Filepath spans the full sidebar width — most paths are long
-           *  enough that the two-column grid above wraps them painfully.
-           *  Mono so each character lines up under the next, break-all
-           *  so we never overflow horizontally on a long basename. */}
-          <div className="mt-2 text-xs">
-            <span className="text-text-muted">Path:</span>
-            <p className="mt-0.5 break-all font-mono text-[11px] text-text" title={photo.filepath}>
-              {photo.filepath || '—'}
-            </p>
-          </div>
-        </Section>
-
-        <Section
-          title="Camera"
-          expanded={expandedSections.has('camera')}
-          onToggle={() => toggleSection('camera')}
-        >
-          <div className="space-y-1 text-xs">
-            <div className="flex items-center gap-2">
-              <Camera className="h-3 w-3 text-text-muted" />
-              <span className="text-text">
-                {pickFirst(exif, 'Make', 'Model') === '—'
-                  ? '—'
-                  : `${formatExifValue(exif.Make)} ${formatExifValue(exif.Model)}`.trim()}
-              </span>
-            </div>
-            <div className="flex items-center gap-2">
-              <Aperture className="h-3 w-3 text-text-muted" />
-              <span className="text-text">
-                {pickFirst(exif, 'LensModel', 'Lens')}
-              </span>
-            </div>
-            <div className="mt-2 grid grid-cols-2 gap-2">
-              <Field label="ISO" value={formatExifValue(exif.ISO)} />
-              <Field
-                label="Aperture"
-                value={
-                  exif.FNumber
-                    ? `f/${exif.FNumber}`
-                    : pickFirst(exif, 'ApertureValue')
-                }
-              />
-              <Field
-                label="Shutter"
-                value={pickFirst(exif, 'ExposureTime', 'ShutterSpeedValue')}
-              />
-              <Field
-                label="Focal"
-                value={pickFirst(
-                  exif,
-                  'FocalLength',
-                  'FocalLengthIn35mmFormat'
-                )}
-              />
-            </div>
-          </div>
-        </Section>
-
-        <Section
-          title="Location"
-          expanded={expandedSections.has('location')}
-          onToggle={() => toggleSection('location')}
-        >
-          {exif.GPSLatitude && exif.GPSLongitude ? (
-            <div className="flex items-center gap-2 text-xs">
-              <MapPin className="h-3 w-3 text-text-muted" />
-              <span className="font-mono text-text">
-                {String(exif.GPSLatitude)}, {String(exif.GPSLongitude)}
-              </span>
-            </div>
-          ) : (
-            <div className="text-xs text-text-muted">No GPS data</div>
-          )}
-        </Section>
-
-        <Section
-          title="Tags"
-          expanded={expandedSections.has('tags')}
-          onToggle={() => toggleSection('tags')}
-        >
-          <TagsEditor
-            photoTags={photo.tags ?? []}
-            allTags={allTags}
-            tagInput={tagInput}
-            onTagInputChange={setTagInput}
-            onAttachExisting={(id) => attachExistingTagMutation.mutate(id)}
-            onCreateAndAttach={(name) => {
-              addTagMutation.mutate(name)
-              setTagInput('')
-            }}
-            onRemove={(id) => removeTagMutation.mutate(id)}
-          />
-        </Section>
-      </div>
-    </div>
-  )
-}
-
-function Section({
-  title,
-  expanded,
-  onToggle,
-  children,
-}: {
-  title: string
-  expanded: boolean
-  onToggle: () => void
-  children: React.ReactNode
-}) {
-  return (
-    <div className="border-b border-border">
-      <button
-        onClick={onToggle}
-        className="flex w-full items-center justify-between px-3 py-1.5 text-[10px] font-semibold uppercase tracking-[0.14em] text-text-muted hover:bg-surface-2 hover:text-text"
-      >
-        <span>{title}</span>
-        {expanded ? (
-          <ChevronDown className="h-3 w-3" />
-        ) : (
-          <ChevronRight className="h-3 w-3" />
-        )}
-      </button>
-      {expanded && <div className="px-3 pb-2.5">{children}</div>}
-    </div>
-  )
-}
-
-interface TagsEditorProps {
-  photoTags: PhotoTagSummary[]
-  allTags: Tag[]
-  tagInput: string
-  onTagInputChange: (value: string) => void
-  onAttachExisting: (id: string) => void
-  onCreateAndAttach: (name: string) => void
-  onRemove: (id: string) => void
-}
-
-function TagsEditor({
-  photoTags,
-  allTags,
-  tagInput,
-  onTagInputChange,
-  onAttachExisting,
-  onCreateAndAttach,
-  onRemove,
-}: TagsEditorProps) {
-  const trimmed = tagInput.trim()
-  const lowerTrimmed = trimmed.toLowerCase()
-  const photoTagIds = new Set(photoTags.map((t) => t.id))
-
-  const suggestions = trimmed
-    ? allTags
-        .filter(
-          (t) =>
-            !photoTagIds.has(t.id) &&
-            t.name.toLowerCase().includes(lowerTrimmed)
-        )
-        .slice(0, 6)
-    : []
-
-  const exactMatch = trimmed
-    ? allTags.find((t) => t.name.toLowerCase() === lowerTrimmed)
-    : null
-
-  const handleSubmit = () => {
-    if (!trimmed) return
-    if (exactMatch) {
-      if (!photoTagIds.has(exactMatch.id)) {
-        onAttachExisting(exactMatch.id)
-      }
-      onTagInputChange('')
-    } else {
-      onCreateAndAttach(trimmed)
-    }
-  }
-
-  return (
-    <div className="space-y-2">
-      {photoTags.length > 0 ? (
-        <div className="flex flex-wrap gap-1">
-          {photoTags.map((tag) => (
-            <span
-              key={tag.id}
-              className="flex items-center gap-1 rounded bg-surface-2 px-2 py-0.5 text-xs text-text"
-              style={
-                tag.color
-                  ? { backgroundColor: `${tag.color}33`, color: tag.color }
-                  : undefined
-              }
-            >
-              {tag.name}
-              <button
-                onClick={() => onRemove(tag.id)}
-                className="rounded p-0.5 opacity-60 hover:bg-surface-offset hover:opacity-100"
-                title="Remove tag"
-              >
-                <X className="h-3 w-3" />
-              </button>
-            </span>
-          ))}
-        </div>
-      ) : (
-        <div className="text-xs text-text-faint">No tags</div>
-      )}
-
-      <div className="relative">
-        <input
-          type="text"
-          value={tagInput}
-          onChange={(e) => onTagInputChange(e.target.value)}
-          onKeyDown={(e) => {
-            if (e.key === 'Enter') {
-              e.preventDefault()
-              handleSubmit()
-            } else if (e.key === 'Escape') {
-              onTagInputChange('')
-            }
-          }}
-          placeholder="Add tag…"
-          className="w-full rounded border border-border bg-bg px-2 py-1 text-xs text-text placeholder-text-faint focus:border-primary focus:outline-none"
-        />
-        {suggestions.length > 0 && (
-          <div className="mt-1 rounded border border-border bg-bg shadow-md">
-            {suggestions.map((s) => (
-              <button
-                key={s.id}
-                onClick={() => {
-                  onAttachExisting(s.id)
-                  onTagInputChange('')
-                }}
-                className="block w-full px-2 py-1 text-left text-xs text-text hover:bg-surface-2"
-              >
-                {s.name}
-              </button>
-            ))}
-          </div>
-        )}
-        {trimmed && !exactMatch && (
-          <button
-            onClick={handleSubmit}
-            className="mt-1 w-full rounded border border-dashed border-primary/50 px-2 py-1 text-left text-xs text-primary hover:bg-primary/10"
-          >
-            + Create "{trimmed}"
-          </button>
-        )}
-      </div>
-    </div>
-  )
-}
-
-function Field({ label, value }: { label: string; value: string }) {
-  return (
-    <div>
-      <span className="text-text-muted">{label}:</span>
-      <p className="break-words text-text">{value}</p>
-    </div>
-  )
-}

frontend/src/components/timeline/PhotoThumbnail.tsx

@@ -1,315 +0,0 @@
-import { useState, useEffect, useCallback, useRef } from 'react'
-import { Star, ShoppingBasket, Trash2, RefreshCw, Check, Copy } from 'lucide-react'
-import clsx from 'clsx'
-import { photos as photosApi } from '../../services/api'
-import type { Photo } from '../../types/photo'
-import { usePhotoStore } from '../../store/photoStore'
-
-/** Custom MIME used by HeapsPanel to recognise our drag payload. */
-export const PHOTO_DRAG_MIME = 'application/x-mulita-photos'
-
-// ── Thumbnail badge family ───────────────────────────────────────────────
-// Every ornament that overlays a thumbnail — here and in other views that
-// wrap PhotoThumbnail (e.g. DuplicatesView) — must compose these classes so
-// the set reads as one coherent system. Shape, height, typography are
-// fixed; variants set the fill + chiseled-pixel frame:
-//   PRIMARY  → user-affirmed state (selection, rating, active-heap)
-//   NEUTRAL  → informational metadata (duplicate flag, discard, file type, dims)
-//   PICK     → auto-suggested "best" in duplicate groups
-//
-// Frame is a single box-shadow stack rather than a Tailwind `ring` so the
-// 1px outline, the subtle inset top highlight, and the drop shadow all
-// live in one paint, and variants can tint the inset highlight to suit
-// their fill. Corners are `rounded-sm` (2px) to echo the pixel-art theme
-// used in the TopBar and ActiveHeapCard.
-export const THUMB_BADGE_BASE =
-  'inline-flex h-5 items-center gap-1 rounded-sm px-1.5 text-[10px] font-semibold leading-none text-white'
-/** Square icon-only variant — compose alongside THUMB_BADGE_BASE. */
-export const THUMB_BADGE_SQUARE = 'w-5 justify-center !px-0'
-/** Standard icon size for any lucide glyph inside a badge. */
-export const THUMB_BADGE_ICON = 'h-3 w-3'
-export const THUMB_BADGE_PRIMARY =
-  'bg-primary shadow-[0_0_0_1px_rgba(0,0,0,0.55),inset_0_1px_0_rgba(255,255,255,0.28),0_1px_2px_rgba(0,0,0,0.5)]'
-export const THUMB_BADGE_NEUTRAL =
-  'bg-black/75 backdrop-blur-sm shadow-[0_0_0_1px_rgba(255,255,255,0.12),inset_0_1px_0_rgba(255,255,255,0.08),0_1px_2px_rgba(0,0,0,0.55)]'
-export const THUMB_BADGE_PICK =
-  'bg-pick shadow-[0_0_0_1px_rgba(0,0,0,0.55),inset_0_1px_0_rgba(255,255,255,0.28),0_1px_2px_rgba(0,0,0,0.5)]'
-
-// Auto-retry schedule (ms). Backend generates thumbs on-demand via Celery, so
-// the first hit on a freshly-scanned library returns 404 "not ready" until
-// the worker catches up. RAW postprocess can take several seconds per file
-// when the queue is deep, so the tail of the schedule is generous.
-const AUTO_RETRY_DELAYS = [1500, 3500, 7000, 12000, 20000]
-
-interface PhotoThumbnailProps {
-  photo: Photo
-  size: number
-  /** When true, the cell stretches to fill its parent (100% width +
-   *  100% height) and ignores `size` for the box dimensions. Used by
-   *  the Timeline grid where the parent is a CSS grid track of 1fr —
-   *  this is what guarantees the row fills the container without any
-   *  rounding gap on the right. The heap sidebar leaves this off so
-   *  thumbnails stay at the explicit `size`. */
-  fill?: boolean
-  isSelected: boolean
-  /** True when the photo belongs to the currently active heap. */
-  isInActiveHeap?: boolean
-  /** Name of the active heap. When set + isInActiveHeap, the basket
-   *  badge expands into a name chip so the user knows which heap. */
-  activeHeapName?: string | null
-  onClick: (e: React.MouseEvent) => void
-  onDoubleClick?: (e: React.MouseEvent) => void
-}
-
-export function PhotoThumbnail({
-  photo,
-  size,
-  fill = false,
-  isSelected,
-  isInActiveHeap = false,
-  activeHeapName = null,
-  onClick,
-  onDoubleClick,
-}: PhotoThumbnailProps) {
-  const [imageError, setImageError] = useState(false)
-  const [imageLoaded, setImageLoaded] = useState(false)
-  const [retryCount, setRetryCount] = useState(0)
-  const [isRetrying, setIsRetrying] = useState(false)
-  const retryTimerRef = useRef<number | null>(null)
-
-  // Cache-bust on retry so the browser actually re-requests instead of
-  // serving the cached 404.
-  const baseUrl = photosApi.getThumbnailUrl(photo.id, 'medium')
-  const thumbnailUrl = retryCount > 0 ? `${baseUrl}?retry=${retryCount}` : baseUrl
-
-  // Square cells (Lightroom-style grid). Variable-aspect cells previously
-  // overflowed their row because TanStack Virtual estimates row height as a
-  // single fixed value — portraits in a landscape row would overlap the row
-  // below. With object-cover the image still fills the cell, just cropped.
-  //
-  // The cell stretches to whatever width the parent grid track gives it
-  // (via width:100% + aspect-ratio:1) so the timeline's CSS grid can hand
-  // out 1fr columns and we never leave horizontal space unused. `size`
-  // remains the *minimum* track width and the fallback when there's no
-  // parent grid (e.g. heap thumbnails).
-  const displayHeight = size
-
-  const clearRetryTimer = () => {
-    if (retryTimerRef.current !== null) {
-      window.clearTimeout(retryTimerRef.current)
-      retryTimerRef.current = null
-    }
-  }
-
-  const handleImageLoad = () => {
-    setImageLoaded(true)
-    setIsRetrying(false)
-  }
-
-  const handleImageError = () => {
-    // Schedule next auto-retry if attempts remain.
-    const nextDelay = AUTO_RETRY_DELAYS[retryCount]
-    if (nextDelay !== undefined) {
-      setIsRetrying(true)
-      clearRetryTimer()
-      retryTimerRef.current = window.setTimeout(() => {
-        retryTimerRef.current = null
-        setRetryCount(prev => prev + 1)
-      }, nextDelay)
-    } else {
-      setImageError(true)
-      setIsRetrying(false)
-    }
-  }
-
-  const handleManualRetry = useCallback((e: React.MouseEvent) => {
-    e.stopPropagation() // Prevent selection when clicking retry
-    clearRetryTimer()
-    setRetryCount(prev => prev + 1)
-    setImageError(false)
-    setImageLoaded(false)
-    setIsRetrying(true)
-  }, [])
-
-  // Reset state when photo changes (component is reused across rows when virtualized)
-  useEffect(() => {
-    clearRetryTimer()
-    setImageError(false)
-    setImageLoaded(false)
-    setRetryCount(0)
-    setIsRetrying(false)
-  }, [photo.id])
-
-  // Clear pending timer on unmount to avoid setState-after-unmount.
-  useEffect(() => {
-    return () => clearRetryTimer()
-  }, [])
-
-  // Build the drag payload at fire time so multi-selection drags carry the
-  // current selection. If the dragged photo isn't part of the selection,
-  // drag just that one photo (matches Finder semantics).
-  const handleDragStart = (e: React.DragEvent<HTMLDivElement>) => {
-    const state = usePhotoStore.getState()
-    const ids =
-      state.selectedPhotos.includes(photo.id) && state.selectedPhotos.length > 0
-        ? state.selectedPhotos
-        : [photo.id]
-    e.dataTransfer.effectAllowed = 'copy'
-    e.dataTransfer.setData(PHOTO_DRAG_MIME, JSON.stringify(ids))
-    // A plain text fallback so the OS shows something sensible if the user
-    // drops outside the app.
-    e.dataTransfer.setData('text/plain', `${ids.length} photo${ids.length > 1 ? 's' : ''}`)
-  }
-
-  return (
-    <div
-      className={clsx(
-        'group relative cursor-pointer overflow-hidden rounded-sm transition-all duration-200',
-        // Two-tone hover ring: bright primary inner + dark offset so it
-        // pops on light AND dark photos.
-        'hover:ring-2 hover:ring-primary/60 hover:ring-offset-1 hover:ring-offset-bg',
-        isSelected &&
-        'ring-2 ring-primary ring-offset-2 ring-offset-bg shadow-lg',
-        !imageLoaded && 'bg-surface animate-pulse'
-      )}
-      style={
-        fill
-          ? { width: '100%', height: '100%' }
-          : { width: size, height: displayHeight }
-      }
-      onClick={onClick}
-      onDoubleClick={onDoubleClick}
-      draggable
-      onDragStart={handleDragStart}
-      title="Click to select • Double-click to open • Shift+Click for range • Ctrl+Click to add • Drag onto a heap to add"
-    >
-      {/* Thumbnail Image */}
-      {!imageError ? (
-        <>
-          <img
-            src={thumbnailUrl}
-            alt={photo.filename}
-            className={clsx(
-              'h-full w-full object-cover transition-opacity duration-200',
-              imageLoaded ? 'opacity-100' : 'opacity-0',
-              // Discarded photos fade out + desaturate so the trash section
-              // reads as a trash section, not just another grid view.
-              photo.is_discarded && 'opacity-50 grayscale'
-            )}
-            onLoad={handleImageLoad}
-            onError={handleImageError}
-            loading="lazy"
-          />
-          {/* Loading indicator */}
-          {!imageLoaded && (
-            <div className="absolute inset-0 flex items-center justify-center bg-surface">
-              <div className="text-text-muted">
-                {isRetrying ? (
-                  <div className="text-center">
-                    <RefreshCw className="h-5 w-5 animate-spin mx-auto mb-1" />
-                    <div className="text-xs">Retrying...</div>
-                  </div>
-                ) : (
-                  <div className="h-8 w-8 border-2 border-primary/30 border-t-primary rounded-full animate-spin" />
-                )}
-              </div>
-            </div>
-          )}
-        </>
-      ) : (
-        <div className="flex h-full w-full items-center justify-center bg-surface text-text-muted">
-          <div className="text-center text-xs">
-            <button
-              onClick={handleManualRetry}
-              className="p-2 hover:bg-surface-light rounded transition-colors"
-              title="Retry loading thumbnail"
-            >
-              <RefreshCw className="h-5 w-5 mb-1" />
-            </button>
-            <div>Unable to load</div>
-            <div className="mt-1 font-mono text-[10px] px-2 break-all">{photo.filename}</div>
-          </div>
-        </div>
-      )}
-
-      {/* ── Ornaments ────────────────────────────────────────────────────
-       *  All overlays compose the THUMB_BADGE_* classes so they share one
-       *  shape/size/ring family. Colour signals semantics:
-       *    PRIMARY → user-affirmed state     (selection, rating, heap)
-       *    NEUTRAL → informational metadata  (duplicate, discard, file type)
-       *  Corner ownership is fixed: TL=selection, TR=file-type,
-       *  BL=rating, BR=flags. This keeps badges from stacking or colliding. */}
-
-      {/* TL — selection */}
-      {isSelected && (
-        <div
-          className={clsx(
-            'absolute left-1 top-1',
-            THUMB_BADGE_BASE,
-            THUMB_BADGE_SQUARE,
-            THUMB_BADGE_PRIMARY
-          )}
-        >
-          <Check className={THUMB_BADGE_ICON} strokeWidth={3} />
-        </div>
-      )}
-
-      {/* BL — rating */}
-      {photo.rating > 0 && (
-        <div
-          className={clsx(
-            'absolute bottom-1 left-1 gap-0.5',
-            THUMB_BADGE_BASE,
-            THUMB_BADGE_PRIMARY
-          )}
-        >
-          {Array.from({ length: photo.rating }).map((_, i) => (
-            <Star key={i} className={clsx(THUMB_BADGE_ICON, 'fill-white')} />
-          ))}
-        </div>
-      )}
-
-      {/* BR — flags stack: heap (primary) · duplicate / discard (neutral).
-       *  Heap is the only user-state flag here so it gets primary; the
-       *  rest are metadata about the file, so they're neutral-dark. */}
-      <div className="absolute bottom-1 right-1 flex items-center gap-1">
-        {isInActiveHeap && (
-          <div
-            className={clsx(THUMB_BADGE_BASE, THUMB_BADGE_PRIMARY, 'max-w-[120px]')}
-            title={activeHeapName ? `In heap: ${activeHeapName}` : 'In active heap'}
-          >
-            <ShoppingBasket
-              className={clsx(THUMB_BADGE_ICON, 'flex-shrink-0')}
-              strokeWidth={2.5}
-            />
-            {activeHeapName && <span className="truncate">{activeHeapName}</span>}
-          </div>
-        )}
-        {photo.is_duplicate && (
-          <div
-            className={clsx(THUMB_BADGE_BASE, THUMB_BADGE_SQUARE, THUMB_BADGE_NEUTRAL)}
-            title="Duplicate (matches another photo's hash)"
-          >
-            <Copy className={THUMB_BADGE_ICON} strokeWidth={2.5} />
-          </div>
-        )}
-        {photo.is_discarded && (
-          <div
-            className={clsx(THUMB_BADGE_BASE, THUMB_BADGE_SQUARE, THUMB_BADGE_NEUTRAL)}
-            title="Discarded"
-          >
-            <Trash2 className={THUMB_BADGE_ICON} strokeWidth={2.5} />
-          </div>
-        )}
-      </div>
-
-      {/* TR — file-type metadata (RAW / VIDEO) */}
-      {(photo.filepath.toLowerCase().match(/\.(raw|arw|cr2|cr3|nef|orf|rw2|dng)$/i) ||
-        photo.filepath.toLowerCase().match(/\.(mov|mp4|avi|mkv)$/i)) && (
-          <div className={clsx('absolute right-1 top-1', THUMB_BADGE_BASE, THUMB_BADGE_NEUTRAL)}>
-            {photo.filepath.toLowerCase().match(/\.(mov|mp4|avi|mkv)$/i) ? 'VIDEO' : 'RAW'}
-          </div>
-        )}
-    </div>
-  )
-}

frontend/src/components/timeline/Timeline.tsx

@@ -1,723 +0,0 @@
-import { useRef, useEffect, useMemo, useState, useCallback } from 'react'
-import { useVirtualizer } from '@tanstack/react-virtual'
-import { format, parseISO } from 'date-fns'
-import { usePhotoStore } from '../../store/photoStore'
-import { useFilterStore } from '../../store/filterStore'
-import { PhotoThumbnail } from './PhotoThumbnail'
-import { usePhotosQuery } from '../../hooks/usePhotosQuery'
-import { useActiveHeapMembers } from '../../hooks/useActiveHeapMembersQuery'
-import type { Photo } from '../../types/photo'
-
-// Layout constants for the grid + grouped headers.
-const THUMBNAIL_SIZE = 200
-const GAP = 4
-const PADDING = 16
-const HEADER_HEIGHT = 36
-
-interface PhotoCell {
-  photo: Photo
-  globalIndex: number
-}
-
-type TimelineItem =
-  | { type: 'header'; key: string; label: string; height: number }
-  | { type: 'row'; key: string; cells: PhotoCell[]; height: number }
-
-/**
- * Build the flat header|row item array the virtualizer renders.
- *
- * Four modes:
- *  - groupBy='tag': one bucket per unique tag (plus an "Untagged" bucket
- *    for photos with no tags). A photo with N tags appears in N buckets.
- *  - groupBy='rating': one bucket per star rating 5..1 (plus "Unrated"
- *    for rating 0). Each photo lands in exactly one bucket.
- *  - groupBy='date' AND sortBy is a date field: month buckets (existing).
- *  - otherwise: one un-headered stream.
- */
-function buildItems(
-  photos: Photo[],
-  columns: number,
-  rowHeight: number,
-  sortBy: string,
-  groupBy: 'date' | 'tag' | 'rating'
-): TimelineItem[] {
-  if (photos.length === 0) return []
-
-  const items: TimelineItem[] = []
-
-  // Helper: split a flat array of cells into rows of `columns` cells.
-  const pushRowsForGroup = (groupKey: string, cells: PhotoCell[]) => {
-    for (let i = 0; i < cells.length; i += columns) {
-      const slice = cells.slice(i, i + columns)
-      items.push({
-        type: 'row',
-        key: `${groupKey}::row::${i}`,
-        cells: slice,
-        height: rowHeight + GAP,
-      })
-    }
-  }
-
-  // ── Tag grouping ──────────────────────────────────────────────────────
-  if (groupBy === 'tag') {
-    // Bucket by tag name. A photo with multiple tags lands in multiple
-    // buckets. Photos with no tags go into "Untagged".
-    const tagBuckets = new Map<string, PhotoCell[]>()
-    const untagged: PhotoCell[] = []
-
-    photos.forEach((photo, globalIndex) => {
-      const cell: PhotoCell = { photo, globalIndex }
-      const tags = photo.tags ?? []
-      if (tags.length === 0) {
-        untagged.push(cell)
-      } else {
-        for (const t of tags) {
-          const arr = tagBuckets.get(t.name) ?? []
-          arr.push(cell)
-          tagBuckets.set(t.name, arr)
-        }
-      }
-    })
-
-    // Sort tag groups alphabetically; Untagged goes at the end.
-    const sortedTagNames = Array.from(tagBuckets.keys()).sort((a, b) =>
-      a.localeCompare(b)
-    )
-
-    let bucketIndex = 0
-    for (const name of sortedTagNames) {
-      items.push({
-        type: 'header',
-        key: `tag::${bucketIndex}::${name}`,
-        label: name,
-        height: HEADER_HEIGHT,
-      })
-      pushRowsForGroup(`tag::${bucketIndex}::${name}`, tagBuckets.get(name)!)
-      bucketIndex++
-    }
-    if (untagged.length > 0) {
-      items.push({
-        type: 'header',
-        key: `tag::${bucketIndex}::__untagged`,
-        label: 'Untagged',
-        height: HEADER_HEIGHT,
-      })
-      pushRowsForGroup(`tag::${bucketIndex}::untagged`, untagged)
-    }
-    return items
-  }
-
-  // ── Rating grouping ───────────────────────────────────────────────────
-  if (groupBy === 'rating') {
-    // Bucket by star rating. Each photo lands in exactly one bucket;
-    // rating 0 goes into "Unrated".
-    const ratingBuckets = new Map<number, PhotoCell[]>()
-    const unrated: PhotoCell[] = []
-
-    photos.forEach((photo, globalIndex) => {
-      const cell: PhotoCell = { photo, globalIndex }
-      if (photo.rating > 0) {
-        const arr = ratingBuckets.get(photo.rating) ?? []
-        arr.push(cell)
-        ratingBuckets.set(photo.rating, arr)
-      } else {
-        unrated.push(cell)
-      }
-    })
-
-    // Highest rating first; Unrated goes at the end.
-    const sortedRatings = Array.from(ratingBuckets.keys()).sort((a, b) => b - a)
-
-    let bucketIndex = 0
-    for (const rating of sortedRatings) {
-      items.push({
-        type: 'header',
-        key: `rating::${bucketIndex}::${rating}`,
-        label: '★'.repeat(rating),
-        height: HEADER_HEIGHT,
-      })
-      pushRowsForGroup(
-        `rating::${bucketIndex}::${rating}`,
-        ratingBuckets.get(rating)!
-      )
-      bucketIndex++
-    }
-    if (unrated.length > 0) {
-      items.push({
-        type: 'header',
-        key: `rating::${bucketIndex}::__unrated`,
-        label: 'Unrated',
-        height: HEADER_HEIGHT,
-      })
-      pushRowsForGroup(`rating::${bucketIndex}::unrated`, unrated)
-    }
-    return items
-  }
-
-  // ── Date grouping (existing) ──────────────────────────────────────────
-  const isDateSort = sortBy === 'taken_at' || sortBy === 'added_at'
-
-  if (!isDateSort) {
-    // No grouping — one row stream.
-    const cells: PhotoCell[] = photos.map((photo, globalIndex) => ({
-      photo,
-      globalIndex,
-    }))
-    pushRowsForGroup('all', cells)
-    return items
-  }
-
-  // Walk photos in order, breaking into groups whenever the month label changes.
-  let currentLabel: string | null = null
-  let bucket: PhotoCell[] = []
-  let bucketIndex = 0
-
-  const flushBucket = () => {
-    if (bucket.length === 0 || currentLabel === null) return
-    items.push({
-      type: 'header',
-      key: `header::${bucketIndex}::${currentLabel}`,
-      label: currentLabel,
-      height: HEADER_HEIGHT,
-    })
-    pushRowsForGroup(`${bucketIndex}::${currentLabel}`, bucket)
-    bucketIndex++
-    bucket = []
-  }
-
-  photos.forEach((photo, globalIndex) => {
-    const dateStr =
-      sortBy === 'taken_at' ? photo.taken_at : photo.added_at ?? photo.taken_at
-    let label: string
-    if (dateStr) {
-      try {
-        label = format(parseISO(dateStr), 'MMMM yyyy')
-      } catch {
-        label = 'Unknown date'
-      }
-    } else {
-      label = 'Unknown date'
-    }
-    if (label !== currentLabel) {
-      flushBucket()
-      currentLabel = label
-    }
-    bucket.push({ photo, globalIndex })
-  })
-  flushBucket()
-
-  return items
-}
-
-export function Timeline() {
-  const parentRef = useRef<HTMLDivElement>(null)
-  // Sentinel placed inside the inner virtualizer wrapper at the exact
-  // position rows will render. We measure THIS instead of parentRef,
-  // because parentRef has padding and we'd otherwise have to subtract
-  // it (and account for any scrollbar) — easy to get wrong by a pixel
-  // and end up with a column count off by one.
-  const [containerWidth, setContainerWidth] = useState(0)
-
-  const {
-    selectedPhotos,
-    activePhotoId,
-    selectPhoto,
-    togglePhotoSelection,
-    selectRange,
-    clearSelection,
-    openPreview,
-  } = usePhotoStore()
-  // Pulled via a focused selector so the publisher subscription doesn't
-  // re-render Timeline on every unrelated photo store change.
-  const setVisiblePhotoIds = usePhotoStore((s) => s.setVisiblePhotoIds)
-
-  const sortBy = useFilterStore((s) => s.sortBy)
-  const groupBy = useFilterStore((s) => s.groupBy)
-  const currentSection = useFilterStore((s) => s.currentSection)
-  const viewMode = usePhotoStore((s) => s.viewMode)
-
-  // Calculate number of columns + actual cell size based on container
-  // width. Treat THUMBNAIL_SIZE as a *minimum* and let cells grow to
-  // fill the remaining space, so we never leave a horizontal gap on
-  // the right side of the grid.
-  //
-  // Column math: with N columns there are N-1 inter-cell gaps, so the
-  // width needed is N*T + (N-1)*G. Solving for the largest N that fits
-  // in the available width gives N = floor((available + G) / (T + G)).
-  // The previous formula floor((available) / (T + G)) was off-by-one
-  // and lost a whole column whenever the remainder almost fit.
-  const { columns, cellSize } = useMemo(() => {
-    if (containerWidth === 0) {
-      return { columns: 4, cellSize: THUMBNAIL_SIZE }
-    }
-    // containerWidth here is the sentinel's actual rendered width — no
-    // padding subtraction needed, the sentinel already lives inside the
-    // padded scroll container.
-    const available = containerWidth
-    const cols = Math.max(
-      1,
-      Math.floor((available + GAP) / (THUMBNAIL_SIZE + GAP))
-    )
-    // Exact float — no floor. cellSize × cols + (cols-1) × gap == available
-    // by construction, so the row fills edge-to-edge without any
-    // sub-pixel rounding gap.
-    const cell = (available - (cols - 1) * GAP) / cols
-    return { columns: cols, cellSize: cell }
-  }, [containerWidth])
-
-  // Shared photos query — both Timeline and PreviewView use the same hook so
-  // they share one cache entry, regardless of filter state.
-  const { data: photos = [], isLoading } = usePhotosQuery()
-
-  // Auto-focus the first photo on initial grid load so arrow-key nav
-  // works immediately without a pre-click. Only fires when there's no
-  // current active photo — we never clobber the user's selection or
-  // the one they restored by navigating back from preview.
-  useEffect(() => {
-    if (viewMode !== 'grid') return
-    if (activePhotoId) return
-    if (photos.length === 0) return
-    selectPhoto(photos[0].id)
-  }, [viewMode, activePhotoId, photos, selectPhoto])
-
-  // Membership in the active heap (for the basket affordance). Subscribed
-  // once at this level so we don't have hundreds of thumbnails each
-  // subscribing to the same query.
-  const { memberIds: activeHeapMembers, activeHeap } = useActiveHeapMembers()
-  const activeHeapName = activeHeap?.name ?? null
-
-  // Build the flat virtualizer items: a mix of group headers and rows of
-  // photos. Date headers appear when sorted by a date field; tag headers
-  // appear when groupBy === 'tag' (overrides date grouping).
-  const items = useMemo(
-    () => buildItems(photos, columns, cellSize, sortBy, groupBy),
-    [photos, columns, cellSize, sortBy, groupBy]
-  )
-
-  // Pre-computed offset of every header in the virtualizer's coordinate
-  // space, used to drive the sticky-header overlay below.
-  const headerOffsets = useMemo(() => {
-    const result: { offset: number; label: string }[] = []
-    let cumulative = 0
-    for (const item of items) {
-      if (item.type === 'header') {
-        result.push({ offset: cumulative, label: item.label })
-      }
-      cumulative += item.height
-    }
-    return result
-  }, [items])
-
-  // Virtual scrolling setup with per-item heights.
-  const virtualizer = useVirtualizer({
-    count: items.length,
-    getScrollElement: () => parentRef.current,
-    estimateSize: (index) => items[index]?.height ?? cellSize,
-    overscan: 5,
-  })
-
-  // Re-measure when items change (column count, group structure).
-  useEffect(() => {
-    virtualizer.measure()
-  }, [items, virtualizer])
-
-  // Track scroll position so we can show the current group label as a
-  // pinned overlay at the top of the scroll container. The virtualizer's
-  // items use transform translateY (so CSS position: sticky doesn't work
-  // on the inline headers); the overlay sidesteps that by living outside
-  // the virtualizer's positioned children.
-  const [scrollTop, setScrollTop] = useState(0)
-  useEffect(() => {
-    const el = parentRef.current
-    if (!el) return
-    const onScroll = () => setScrollTop(el.scrollTop)
-    el.addEventListener('scroll', onScroll, { passive: true })
-    return () => el.removeEventListener('scroll', onScroll)
-  }, [])
-
-  // Find the latest header whose BOTTOM is above the viewport top. That's
-  // the group whose natural in-grid header has scrolled out of view —
-  // exactly the case where we want to pin the label as a sticky overlay.
-  // If the natural header is still visible (scrolled but not yet past),
-  // we return null and let the in-grid label do the work, avoiding the
-  // duplicate-label flash.
-  const stickyLabel = useMemo(() => {
-    if (headerOffsets.length === 0) return null
-    let current: string | null = null
-    for (const h of headerOffsets) {
-      if (h.offset + HEADER_HEIGHT <= scrollTop) current = h.label
-      else break
-    }
-    return current
-  }, [headerOffsets, scrollTop])
-
-  // Measure the sentinel's actual rendered width on mount, window
-  // resize, and any layout change driven by the sidebar collapse /
-  // right panel toggle. ResizeObserver picks up everything window
-  // resize misses (sidebar collapse doesn't fire window resize).
-  //
-  // Uses a callback ref (not useRef + useEffect) because Timeline
-  // early-returns a loading/empty state before the sentinel exists,
-  // so a mount-only effect would see a null ref and never install
-  // the observer. The callback ref fires whenever the sentinel
-  // actually attaches, which is the moment we can measure it.
-  const roRef = useRef<ResizeObserver | null>(null)
-  const measureElRef = useRef<HTMLDivElement | null>(null)
-  const widthSentinelRef = useCallback((el: HTMLDivElement | null) => {
-    roRef.current?.disconnect()
-    roRef.current = null
-    measureElRef.current = el
-    if (!el) return
-    const measure = () => setContainerWidth(el.clientWidth)
-    measure()
-    const ro = new ResizeObserver(measure)
-    ro.observe(el)
-    roRef.current = ro
-  }, [])
-  useEffect(() => {
-    const onResize = () => {
-      const el = measureElRef.current
-      if (el) setContainerWidth(el.clientWidth)
-    }
-    window.addEventListener('resize', onResize)
-    return () => {
-      window.removeEventListener('resize', onResize)
-      roRef.current?.disconnect()
-      roRef.current = null
-    }
-  }, [])
-
-  // Photo rows in visual order — drops the header items so navigation
-  // walks the grid as the user sees it. Each row has cells of length
-  // [1..columns], the last row of a group can be short, and a single
-  // photo with multiple tags will appear in multiple rows.
-  const photoRows = useMemo(
-    () => items.filter((it): it is Extract<TimelineItem, { type: 'row' }> => it.type === 'row'),
-    [items]
-  )
-
-  // Parallel array: photoRows[i] corresponds to items[photoRowItemIndex[i]].
-  // Lets keyboard nav jump the virtualizer to the destination row even when
-  // it hasn't been rendered yet (beyond the overscan window).
-  const photoRowItemIndex = useMemo(() => {
-    const map: number[] = []
-    items.forEach((it, idx) => {
-      if (it.type === 'row') map.push(idx)
-    })
-    return map
-  }, [items])
-
-  // Flat visible-order id sequence — exactly the order the user reads
-  // off the grid (top-to-bottom, left-to-right within each row).
-  // Includes duplicates from tag-grouping; landing on the same photo's
-  // "second" appearance in the next tag bucket is the right behavior
-  // in tag mode.
-  const visibleSequence = useMemo(() => {
-    const ids: string[] = []
-    for (const row of photoRows) {
-      for (const cell of row.cells) {
-        ids.push(cell.photo.id)
-      }
-    }
-    return ids
-  }, [photoRows])
-
-  // Publish to the photo store so PreviewView's arrow nav and filmstrip
-  // can walk the same order even when opened from a non-click path
-  // (e.g. the global Space hotkey).
-  useEffect(() => {
-    setVisiblePhotoIds(visibleSequence)
-  }, [visibleSequence, setVisiblePhotoIds])
-
-  // Locate the active photo in the visual grid. Returns the FIRST
-  // (rowIndex, colIndex) where its id appears, since a tag-grouped view
-  // can repeat a photo across groups. Returns null when there's no
-  // active photo or it isn't currently rendered.
-  const findActiveCell = (): { row: number; col: number } | null => {
-    if (!activePhotoId) return null
-    for (let r = 0; r < photoRows.length; r++) {
-      const row = photoRows[r]
-      const c = row.cells.findIndex((cell) => cell.photo.id === activePhotoId)
-      if (c >= 0) return { row: r, col: c }
-    }
-    return null
-  }
-
-  // Handle keyboard shortcuts for photo navigation. Operates on the
-  // grouped grid the user sees, so a half-full last row of a group
-  // doesn't make ArrowDown skip into the wrong place.
-  //
-  // Inert in preview mode — PreviewView mounts its own arrow handlers,
-  // and a window-level grid handler firing alongside them used to race
-  // against PreviewView's setActivePhoto, landing the user on the wrong
-  // photo. The grid handler stays attached so it can re-engage the
-  // moment the user closes preview.
-  useEffect(() => {
-    if (viewMode !== 'grid') return
-    // The duplicates section mounts its own grouped view (DuplicatesView)
-    // with its own keyboard nav — bail out so we don't double-handle
-    // arrow keys and try to navigate against a photoRows snapshot that
-    // doesn't match what the user actually sees on screen.
-    if (currentSection === 'duplicates') return
-    const handleKeyDown = (e: KeyboardEvent) => {
-      if (photoRows.length === 0) return
-      const target = e.target as HTMLElement | null
-      if (target && (target.tagName === 'INPUT' || target.tagName === 'TEXTAREA')) {
-        return
-      }
-
-      const move = (dr: number, dc: number) => {
-        const current = findActiveCell() ?? { row: 0, col: -1 }
-        let nextRow = current.row
-        let nextCol = current.col + dc
-
-        if (dc !== 0) {
-          // Wrap left/right across row boundaries.
-          while (nextCol < 0 && nextRow > 0) {
-            nextRow -= 1
-            nextCol = photoRows[nextRow].cells.length - 1
-          }
-          while (
-            nextRow < photoRows.length &&
-            nextCol >= photoRows[nextRow].cells.length
-          ) {
-            if (nextRow === photoRows.length - 1) {
-              nextCol = photoRows[nextRow].cells.length - 1
-              break
-            }
-            nextRow += 1
-            nextCol = 0
-          }
-          if (nextCol < 0) nextCol = 0
-        }
-
-        if (dr !== 0) {
-          nextRow += dr
-          if (nextRow < 0) nextRow = 0
-          if (nextRow >= photoRows.length) nextRow = photoRows.length - 1
-          // Clamp the column to the destination row's actual width so
-          // moving down into a half-full row lands on its last cell
-          // instead of nothing.
-          const rowLen = photoRows[nextRow].cells.length
-          if (nextCol >= rowLen) nextCol = rowLen - 1
-          if (nextCol < 0) nextCol = 0
-        }
-
-        const dest = photoRows[nextRow]?.cells[nextCol]
-        if (!dest) return
-        if (e.shiftKey) {
-          selectRange(dest.photo.id)
-        } else {
-          selectPhoto(dest.photo.id)
-        }
-        // Bring the destination row into view if it's off-screen, leaving
-        // a "peek" margin so the next row above/below stays partly visible
-        // — cues the user that there's more content in the scroll direction.
-        // In-viewport moves are a no-op, so same-row arrow presses don't
-        // jitter the scroll position.
-        const itemIdx = photoRowItemIndex[nextRow]
-        const scrollEl = parentRef.current
-        if (itemIdx !== undefined && scrollEl) {
-          // Sum item heights up to itemIdx to get this row's offset in the
-          // virtualizer's coordinate space. Cheap enough at O(items) and
-          // avoids reaching into virtualizer.measurementsCache internals.
-          let rowTop = 0
-          for (let i = 0; i < itemIdx; i++) rowTop += items[i].height
-          const rowHeight = items[itemIdx].height
-          const peek = Math.round(cellSize * 0.35)
-          const viewTop = scrollEl.scrollTop
-          const viewBottom = viewTop + scrollEl.clientHeight
-          if (rowTop - peek < viewTop) {
-            // Destination is above (or flush with) the viewport top. Leave
-            // `peek` pixels of the previous row visible above it.
-            scrollEl.scrollTo({ top: Math.max(0, rowTop - peek) })
-          } else if (rowTop + rowHeight + peek > viewBottom) {
-            // Destination is below the viewport bottom. Leave `peek` pixels
-            // of the next row visible below it.
-            scrollEl.scrollTo({
-              top: rowTop + rowHeight + peek - scrollEl.clientHeight,
-            })
-          }
-        }
-      }
-
-      switch (e.key) {
-        case 'ArrowUp':
-          e.preventDefault()
-          move(-1, 0)
-          break
-        case 'ArrowDown':
-          e.preventDefault()
-          move(1, 0)
-          break
-        case 'ArrowLeft':
-          e.preventDefault()
-          move(0, -1)
-          break
-        case 'ArrowRight':
-          e.preventDefault()
-          move(0, 1)
-          break
-        case 'a':
-          if (e.ctrlKey || e.metaKey) {
-            e.preventDefault()
-            photos.forEach((photo) => {
-              if (!selectedPhotos.includes(photo.id)) {
-                togglePhotoSelection(photo.id)
-              }
-            })
-          }
-          break
-        case 'Escape':
-          e.preventDefault()
-          clearSelection()
-          break
-      }
-    }
-
-    window.addEventListener('keydown', handleKeyDown)
-    return () => window.removeEventListener('keydown', handleKeyDown)
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [viewMode, photoRows, photos, selectedPhotos, activePhotoId, photoRowItemIndex, items, cellSize, currentSection])
-
-  if (isLoading) {
-    return (
-      <div className="flex items-center justify-center h-full">
-        <div className="text-text-muted">Loading photos...</div>
-      </div>
-    )
-  }
-
-  if (photos.length === 0) {
-    return (
-      <div className="flex items-center justify-center h-full">
-        <div className="text-text-muted">(╯°□°）╯︵ ┻━┻</div>
-      </div>
-    )
-  }
-
-  return (
-    <div className="relative h-full">
-      {/* Sticky group-header overlay. Lives outside the virtualizer's
-       *  positioned children so it isn't affected by translateY transforms.
-       *  Updates as the user scrolls past month boundaries. */}
-      {stickyLabel && (
-        <div className="pointer-events-none absolute left-0 right-0 top-0 z-20 border-b-2 border-border bg-bg/95 px-4 py-1.5 shadow-sm backdrop-blur">
-          <h3 className="text-sm font-semibold uppercase tracking-wide text-text">
-            {stickyLabel}
-          </h3>
-        </div>
-      )}
-
-      <div
-        ref={parentRef}
-        className="h-full overflow-auto bg-bg"
-        style={{ padding: `${PADDING}px` }}
-      >
-        <div
-          style={{
-            height: `${virtualizer.getTotalSize()}px`,
-            width: '100%',
-            position: 'relative',
-          }}
-        >
-          {/* Width sentinel — a 1px-tall normal-flow div that takes the
-           *  full width of the inner virtualizer wrapper, which is the
-           *  exact width rows render at. clientWidth on this is what we
-           *  base the column count on, sidestepping any padding /
-           *  scrollbar mismatch the parentRef-based measurement is
-           *  vulnerable to. ResizeObserver doesn't reliably fire on
-           *  zero-area absolute elements, so 1px tall + relative flow. */}
-          <div
-            ref={widthSentinelRef}
-            aria-hidden="true"
-            style={{
-              width: '100%',
-              height: 1,
-              marginBottom: -1,
-              pointerEvents: 'none',
-            }}
-          />
-          {virtualizer.getVirtualItems().map((virtualItem) => {
-            const item = items[virtualItem.index]
-            if (!item) return null
-
-            if (item.type === 'header') {
-              return (
-                <div
-                  key={virtualItem.key}
-                  style={{
-                    position: 'absolute',
-                    top: 0,
-                    left: 0,
-                    width: '100%',
-                    height: `${virtualItem.size}px`,
-                    transform: `translateY(${virtualItem.start}px)`,
-                  }}
-                  className="flex items-end pb-1"
-                >
-                  <h3 className="text-sm font-semibold uppercase tracking-wide text-text">
-                    {item.label}
-                  </h3>
-                </div>
-              )
-            }
-
-            // row
-            return (
-              <div
-                key={virtualItem.key}
-                style={{
-                  position: 'absolute',
-                  top: 0,
-                  left: 0,
-                  width: '100%',
-                  height: `${virtualItem.size}px`,
-                  transform: `translateY(${virtualItem.start}px)`,
-                }}
-              >
-                <div
-                  style={{
-                    // Fixed-size grid: every track is exactly cellSize
-                    // wide and the row is exactly cellSize tall, so
-                    // cells are guaranteed square no matter what CSS
-                    // the cell contents bring along. cellSize was
-                    // already computed from `available / cols` so the
-                    // sum cols*cellSize + (cols-1)*gap equals the
-                    // container width to within sub-pixel rounding.
-                    display: 'grid',
-                    gridTemplateColumns: `repeat(${columns}, ${cellSize}px)`,
-                    gridAutoRows: `${cellSize}px`,
-                    gap: `${GAP}px`,
-                  }}
-                >
-                  {item.cells.map(({ photo }) => (
-                    <PhotoThumbnail
-                      key={photo.id}
-                      photo={photo}
-                      size={cellSize}
-                      fill
-                      isSelected={selectedPhotos.includes(photo.id)}
-                      isInActiveHeap={activeHeapMembers.has(photo.id)}
-                      activeHeapName={activeHeapName}
-                      onClick={(e) => {
-                        if (e.shiftKey) {
-                          selectRange(photo.id)
-                        } else if (e.ctrlKey || e.metaKey) {
-                          togglePhotoSelection(photo.id)
-                        } else {
-                          selectPhoto(photo.id)
-                        }
-                      }}
-                      onDoubleClick={() => openPreview(photo.id, visibleSequence)}
-                    />
-                  ))}
-                </div>
-              </div>
-            )
-          })}
-        </div>
-      </div>
-    </div>
-  )
-}

frontend/src/constants/colorLabels.ts

@@ -1,22 +0,0 @@
-/**
- * Single source of truth for the six Lightroom-style color labels.
- * Both filter UIs and edit UIs (FilterBar, PhotoInfoPanel, RightSidebar)
- * read from this list so dot colors and ordering stay consistent.
- */
-
-export type ColorLabel =
-  | 'red'
-  | 'orange'
-  | 'yellow'
-  | 'green'
-  | 'blue'
-  | 'purple'
-
-export const COLOR_LABEL_OPTIONS: { value: ColorLabel; className: string }[] = [
-  { value: 'red', className: 'bg-red-500' },
-  { value: 'orange', className: 'bg-orange-500' },
-  { value: 'yellow', className: 'bg-yellow-400' },
-  { value: 'green', className: 'bg-green-500' },
-  { value: 'blue', className: 'bg-blue-500' },
-  { value: 'purple', className: 'bg-purple-500' },
-]

frontend/src/hooks/useActiveHeapMembersQuery.ts

@@ -1,39 +0,0 @@
-import { useMemo } from 'react'
-import { useQuery } from '@tanstack/react-query'
-import { useHeapsQuery } from './useHeapsQuery'
-import { heaps as heapsApi } from '../services/api'
-
-const EMPTY_SET: ReadonlySet<string> = new Set()
-
-/**
- * Returns the photo ids that belong to the active heap as a Set, plus the
- * active heap itself. Used by PhotoThumbnail to render the basket affordance
- * and by the P shortcut to decide between add vs remove.
- *
- * If no heap is active, the Set is empty (and shared across renders).
- */
-export function useActiveHeapMembers(): {
-  activeHeap: ReturnType<typeof useHeapsQuery>['data'] extends (infer T)[] | undefined
-    ? T | null
-    : never
-  memberIds: ReadonlySet<string>
-} {
-  const { data: heaps } = useHeapsQuery()
-  const activeHeap = heaps?.find((h) => h.is_active) ?? null
-
-  const { data: ids } = useQuery({
-    queryKey: ['heap-photo-ids', activeHeap?.id],
-    queryFn: () => heapsApi.photoIds(activeHeap!.id),
-    enabled: !!activeHeap,
-    staleTime: 30_000,
-  })
-
-  const memberIds = useMemo(
-    () => (ids ? new Set(ids) : EMPTY_SET),
-    [ids]
-  )
-
-  return { activeHeap: activeHeap as any, memberIds }
-}
-
-export const ACTIVE_HEAP_MEMBERS_QUERY_KEY_PREFIX = ['heap-photo-ids'] as const

frontend/src/hooks/useDuplicateGroupsQuery.ts

@@ -1,17 +0,0 @@
-import { useQuery } from '@tanstack/react-query'
-import { library, type DuplicateGroupsResponse } from '../services/api'
-
-export const DUPLICATE_GROUPS_QUERY_KEY = ['library', 'duplicates'] as const
-
-/**
- * Duplicate groups computed by the backend regroup_duplicates task. The
- * cache is shared between DuplicatesView and the Settings panel stats so
- * the user only ever pays for one fetch per refresh.
- */
-export function useDuplicateGroupsQuery() {
-  return useQuery<DuplicateGroupsResponse>({
-    queryKey: DUPLICATE_GROUPS_QUERY_KEY,
-    queryFn: library.duplicates.groups,
-    staleTime: 30_000,
-  })
-}

frontend/src/hooks/useFilterUrlSync.ts

@@ -1,156 +0,0 @@
-import { useEffect, useRef } from 'react'
-import {
-  useFilterStore,
-  type FilterState,
-  type MediaType,
-  type ColorLabel,
-  type FlagFilter,
-  type SortField,
-  type SortOrder,
-} from '../store/filterStore'
-
-const ALLOWED_MEDIA: MediaType[] = ['photo', 'video', 'raw', 'heic']
-const ALLOWED_COLORS: ColorLabel[] = [
-  'red',
-  'orange',
-  'yellow',
-  'green',
-  'blue',
-  'purple',
-]
-const ALLOWED_FLAGS: FlagFilter[] = ['any', 'discarded']
-const ALLOWED_SORT_FIELDS: SortField[] = [
-  'taken_at',
-  'added_at',
-  'filename',
-  'file_size',
-  'rating',
-]
-const ALLOWED_SORT_ORDERS: SortOrder[] = ['asc', 'desc']
-
-// What parseUrl returns: a partial filter state, plus the optional
-// section id (which lives on the store but isn't part of FilterState
-// itself). The hydrate action accepts this exact shape.
-type HydratePayload = Partial<FilterState> & { currentSection?: string }
-
-function parseUrl(): HydratePayload {
-  const sp = new URLSearchParams(window.location.search)
-  const out: HydratePayload = {}
-
-  const q = sp.get('q')
-  if (q) out.q = q
-
-  const df = sp.get('date_from')
-  if (df) out.dateFrom = df
-
-  const dt = sp.get('date_to')
-  if (dt) out.dateTo = dt
-
-  const mt = sp.get('media_type')
-  if (mt) {
-    const types = mt
-      .split(',')
-      .filter((t): t is MediaType => ALLOWED_MEDIA.includes(t as MediaType))
-    if (types.length > 0) out.mediaTypes = types
-  }
-
-  const rm = sp.get('rating_min')
-  if (rm) {
-    const n = parseInt(rm, 10)
-    if (Number.isFinite(n) && n >= 0 && n <= 5) out.ratingMin = n
-  }
-
-  const cl = sp.get('color_label')
-  if (cl && ALLOWED_COLORS.includes(cl as ColorLabel)) {
-    out.colorLabel = cl as ColorLabel
-  }
-
-  const flag = sp.get('flag')
-  if (flag && ALLOWED_FLAGS.includes(flag as FlagFilter)) {
-    out.flag = flag as FlagFilter
-  }
-
-  const heapId = sp.get('heap_id')
-  if (heapId) out.heapId = heapId
-
-  const folderId = sp.get('folder_id')
-  if (folderId) out.folderId = folderId
-
-  const tagIds = sp.get('tag_ids')
-  if (tagIds) {
-    const ids = tagIds.split(',').map((t) => t.trim()).filter(Boolean)
-    if (ids.length > 0) out.tagIds = ids
-  }
-
-  if (sp.get('duplicates') === 'true') out.duplicates = true
-
-  const groupBy = sp.get('group')
-  if (groupBy === 'date' || groupBy === 'tag') out.groupBy = groupBy
-
-  const section = sp.get('section')
-  if (section) out.currentSection = section
-
-  const sortBy = sp.get('sort')
-  if (sortBy && ALLOWED_SORT_FIELDS.includes(sortBy as SortField)) {
-    out.sortBy = sortBy as SortField
-  }
-
-  const sortOrder = sp.get('order')
-  if (sortOrder && ALLOWED_SORT_ORDERS.includes(sortOrder as SortOrder)) {
-    out.sortOrder = sortOrder as SortOrder
-  }
-
-  return out
-}
-
-function writeUrl(f: FilterState & { currentSection?: string }) {
-  const sp = new URLSearchParams()
-  if (f.q.trim()) sp.set('q', f.q.trim())
-  if (f.dateFrom) sp.set('date_from', f.dateFrom)
-  if (f.dateTo) sp.set('date_to', f.dateTo)
-  if (f.mediaTypes.length > 0) sp.set('media_type', f.mediaTypes.join(','))
-  if (f.ratingMin > 0) sp.set('rating_min', String(f.ratingMin))
-  if (f.colorLabel) sp.set('color_label', f.colorLabel)
-  if (f.flag !== 'any') sp.set('flag', f.flag)
-  if (f.heapId) sp.set('heap_id', f.heapId)
-  if (f.folderId) sp.set('folder_id', f.folderId)
-  if (f.tagIds.length > 0) sp.set('tag_ids', f.tagIds.join(','))
-  if (f.duplicates) sp.set('duplicates', 'true')
-  if (f.groupBy !== 'date') sp.set('group', f.groupBy)
-  if (f.currentSection && f.currentSection !== 'all-photos')
-    sp.set('section', f.currentSection)
-  if (f.sortBy !== 'taken_at') sp.set('sort', f.sortBy)
-  if (f.sortOrder !== 'desc') sp.set('order', f.sortOrder)
-
-  const search = sp.toString()
-  const next = search ? `?${search}` : window.location.pathname
-  if (next !== window.location.search && next !== window.location.pathname + window.location.search) {
-    window.history.replaceState(null, '', next)
-  }
-}
-
-/**
- * Bidirectional URL <-> filterStore sync. Hydrates the store from the URL on
- * mount, then writes any subsequent store changes back to the URL via
- * history.replaceState (no navigation).
- */
-export function useFilterUrlSync() {
-  const hydrated = useRef(false)
-
-  // Hydrate once on mount.
-  useEffect(() => {
-    const fromUrl = parseUrl()
-    if (Object.keys(fromUrl).length > 0) {
-      useFilterStore.getState().hydrate(fromUrl)
-    }
-    hydrated.current = true
-  }, [])
-
-  // Mirror store -> URL on every change (after hydration).
-  useEffect(() => {
-    return useFilterStore.subscribe((state) => {
-      if (!hydrated.current) return
-      writeUrl(state)
-    })
-  }, [])
-}

frontend/src/hooks/useFolderTreeQuery.ts

@@ -1,26 +0,0 @@
-import { useQuery } from '@tanstack/react-query'
-import { sourceFolders, type FolderTreeNode } from '../services/api'
-
-export const FOLDER_TREE_QUERY_KEY = ['folders', 'tree'] as const
-
-export function useFolderTreeQuery() {
-  return useQuery<FolderTreeNode[]>({
-    queryKey: FOLDER_TREE_QUERY_KEY,
-    queryFn: sourceFolders.tree,
-    staleTime: 30_000,
-  })
-}
-
-/** Walk the tree to find a node by id. Used for chip name lookups. */
-export function findFolderInTree(
-  tree: FolderTreeNode[] | undefined,
-  id: string
-): FolderTreeNode | null {
-  if (!tree) return null
-  for (const node of tree) {
-    if (node.id === id) return node
-    const child = findFolderInTree(node.children, id)
-    if (child) return child
-  }
-  return null
-}

frontend/src/hooks/useHeapsQuery.ts

@@ -1,12 +0,0 @@
-import { useQuery } from '@tanstack/react-query'
-import { heaps as heapsApi, type Heap } from '../services/api'
-
-export const HEAPS_QUERY_KEY = ['heaps'] as const
-
-export function useHeapsQuery() {
-  return useQuery<Heap[]>({
-    queryKey: HEAPS_QUERY_KEY,
-    queryFn: heapsApi.list,
-    staleTime: 30_000,
-  })
-}

frontend/src/hooks/useKeyboardShortcuts.ts

@@ -1,352 +0,0 @@
-import { useHotkeys } from 'react-hotkeys-hook'
-import { useMutation, useQueryClient } from '@tanstack/react-query'
-import { usePhotoStore } from '../store/photoStore'
-import { photos as photosApi, heaps as heapsApi, type Heap } from '../services/api'
-import { HEAPS_QUERY_KEY } from './useHeapsQuery'
-import { toast } from '../components/ToastContainer'
-import { registerUndoable, useUndoStore } from '../store/undoStore'
-import { LIBRARY_STATS_QUERY_KEY } from './useLibraryStatsQuery'
-
-interface KeyboardShortcutsProps {
-  onToggleLeftSidebar: () => void
-  onToggleRightSidebar: () => void
-  /** Returns the first photo id in the current timeline, or null if empty. */
-  getFirstPhotoId?: () => string | null
-}
-
-interface PhotoUpdate {
-  rating?: number
-  is_discarded?: boolean
-  color_label?: string | null
-}
-
-// Spec §6.4 number-key color labels.
-const COLOR_LABELS: Record<string, string> = {
-  '6': 'red',
-  '7': 'orange',
-  '8': 'yellow',
-  '9': 'green',
-}
-
-// Default options shared by every shortcut: preventDefault stops the browser
-// from claiming the event (Firefox quick-find on letter keys, Cmd+F search,
-// `/` quick-find, Tab focus traversal). enableOnFormTags is left default-off
-// so typing in inputs doesn't fire culling shortcuts.
-const HK_OPTS = { preventDefault: true } as const
-
-export function useKeyboardShortcuts(props: KeyboardShortcutsProps) {
-  const { onToggleLeftSidebar, onToggleRightSidebar, getFirstPhotoId } = props
-
-  const viewMode = usePhotoStore((s) => s.viewMode)
-  const openPreview = usePhotoStore((s) => s.openPreview)
-  const closePreview = usePhotoStore((s) => s.closePreview)
-
-  const isPreview = viewMode === 'preview'
-
-  // Photo mutation shared by every culling shortcut. Reads the active photo
-  // id from the store at fire time so the closure stays fresh without forcing
-  // hotkey re-binding on every selection change.
-  const queryClient = useQueryClient()
-  const updateMutation = useMutation({
-    mutationFn: ({ id, data }: { id: string; data: PhotoUpdate }) =>
-      photosApi.update(id, data),
-    onSuccess: (_data, vars) => {
-      queryClient.invalidateQueries({ queryKey: ['photo', vars.id] })
-      queryClient.invalidateQueries({ queryKey: ['photos'] })
-    },
-  })
-
-  const invalidatePhotoQueries = () => {
-    queryClient.invalidateQueries({ queryKey: ['photo'] })
-    queryClient.invalidateQueries({ queryKey: ['photos'] })
-    queryClient.invalidateQueries({ queryKey: LIBRARY_STATS_QUERY_KEY })
-  }
-
-  const bulkRatingMutation = useMutation({
-    mutationFn: ({ ids, rating }: { ids: string[]; rating: number }) =>
-      photosApi.bulkSetRating(ids, rating),
-    onSuccess: invalidatePhotoQueries,
-    onError: (e: any) => toast.error('Bulk rating failed', e.message || 'Unknown error'),
-  })
-
-  const bulkColorMutation = useMutation({
-    mutationFn: ({ ids, color }: { ids: string[]; color: string | null }) =>
-      photosApi.bulkSetColor(ids, color),
-    onSuccess: invalidatePhotoQueries,
-    onError: (e: any) => toast.error('Bulk color failed', e.message || 'Unknown error'),
-  })
-
-  const bulkDiscardMutation = useMutation({
-    mutationFn: (ids: string[]) => photosApi.bulkDiscard(ids),
-    onSuccess: invalidatePhotoQueries,
-    onError: (e: any) => toast.error('Bulk discard failed', e.message || 'Unknown error'),
-  })
-
-  const bulkRestoreMutation = useMutation({
-    mutationFn: (ids: string[]) => photosApi.bulkRestore(ids),
-    onSuccess: invalidatePhotoQueries,
-    onError: (e: any) => toast.error('Bulk restore failed', e.message || 'Unknown error'),
-  })
-
-  /** The set of photo ids the next culling action should apply to.
-   *  - Multi-selection → all selected photos
-   *  - Single selection → that one photo
-   *  - No selection but an activePhotoId set (last clicked) → that one
-   *  - Otherwise → empty
-   */
-  const cullTargets = (): string[] => {
-    const state = usePhotoStore.getState()
-    if (state.selectedPhotos.length > 0) return state.selectedPhotos
-    if (state.activePhotoId) return [state.activePhotoId]
-    return []
-  }
-
-  /** Apply a partial PhotoUpdate to the cull targets. Picks the right
-   *  bulk endpoint when there are 2+ photos so a single API call covers
-   *  the whole selection. */
-  const updateActive = (data: PhotoUpdate) => {
-    const ids = cullTargets()
-    if (ids.length === 0) return
-
-    if (ids.length === 1) {
-      const id = ids[0]
-      updateMutation.mutate(
-        { id, data },
-        {
-          onSuccess: () => {
-            // Only the discard/restore subset of single-photo updates is
-            // undoable today — rating and color round-trip cleanly enough
-            // that the manual fix is faster than maintaining per-photo
-            // previous-value snapshots.
-            if (data.is_discarded === true) {
-              registerUndoable('Discarded 1 photo', async () => {
-                await photosApi.bulkRestore([id])
-                invalidatePhotoQueries()
-              })
-            } else if (data.is_discarded === false) {
-              registerUndoable('Restored 1 photo', async () => {
-                await photosApi.bulkDiscard([id])
-                invalidatePhotoQueries()
-              })
-            }
-          },
-        }
-      )
-      return
-    }
-
-    // Multi-selection — fan out to the right bulk endpoint per field.
-    if (data.rating !== undefined) {
-      bulkRatingMutation.mutate({ ids, rating: data.rating })
-    }
-    if (data.color_label !== undefined) {
-      bulkColorMutation.mutate({ ids, color: data.color_label })
-    }
-    if (data.is_discarded === true) {
-      bulkDiscardMutation.mutate(ids, {
-        onSuccess: () => {
-          registerUndoable(
-            `Discarded ${ids.length} photo${ids.length === 1 ? '' : 's'}`,
-            async () => {
-              await photosApi.bulkRestore(ids)
-              invalidatePhotoQueries()
-            }
-          )
-        },
-      })
-    } else if (data.is_discarded === false) {
-      bulkRestoreMutation.mutate(ids, {
-        onSuccess: () => {
-          registerUndoable(
-            `Restored ${ids.length} photo${ids.length === 1 ? '' : 's'}`,
-            async () => {
-              await photosApi.bulkDiscard(ids)
-              invalidatePhotoQueries()
-            }
-          )
-        },
-      })
-    }
-  }
-
-  // P key (Pick): toggle the current selection's membership in the active
-  // heap. If every selected photo is already a member, remove them; otherwise
-  // add the missing ones. No active heap → toast hint.
-  const heapMutation = useMutation({
-    mutationFn: ({
-      heapId,
-      photoIds,
-      remove,
-    }: {
-      heapId: string
-      photoIds: string[]
-      remove: boolean
-    }) =>
-      remove
-        ? heapsApi.removePhotos(heapId, photoIds)
-        : heapsApi.addPhotos(heapId, photoIds),
-    // Optimistically flip the membership cache so the basket affordance
-    // updates instantly and a quick second P press reads the new state
-    // (otherwise invalidate-then-refetch leaves a brief stale window).
-    onMutate: ({ heapId, photoIds, remove }) => {
-      const key = ['heap-photo-ids', heapId] as const
-      const previous = queryClient.getQueryData<string[]>(key)
-      const set = new Set(previous ?? [])
-      if (remove) photoIds.forEach((id) => set.delete(id))
-      else photoIds.forEach((id) => set.add(id))
-      queryClient.setQueryData<string[]>(key, Array.from(set))
-      return { previous }
-    },
-    onError: (e: any, _vars, ctx) => {
-      // Roll back the optimistic update on failure.
-      if (ctx?.previous) {
-        queryClient.setQueryData(['heap-photo-ids', _vars.heapId], ctx.previous)
-      }
-      toast.error('Heap update failed', e.message || 'Unknown error')
-    },
-    onSuccess: (data, vars) => {
-      const heap = (queryClient.getQueryData<Heap[]>(HEAPS_QUERY_KEY) ?? []).find(
-        (h) => h.id === vars.heapId
-      )
-      const heapName = heap?.name ?? 'heap'
-      if (vars.remove) {
-        const removed = data?.removed ?? 0
-        toast.success(`Removed from ${heapName}`, `${removed} photo${removed === 1 ? '' : 's'}`)
-      } else {
-        const added = data?.added ?? 0
-        const already = data?.already_present ?? 0
-        if (added > 0) {
-          toast.success(
-            `Added to ${heapName}`,
-            `${added} photo${added > 1 ? 's' : ''}${already > 0 ? ` (${already} already present)` : ''}`
-          )
-        }
-      }
-    },
-    onSettled: (_data, _err, vars) => {
-      // Re-sync with server truth (heap counts in particular need this).
-      queryClient.invalidateQueries({ queryKey: HEAPS_QUERY_KEY })
-      queryClient.invalidateQueries({ queryKey: ['heap-photo-ids', vars.heapId] })
-    },
-  })
-
-  const togglePickOnSelection = () => {
-    const state = usePhotoStore.getState()
-    const ids =
-      state.selectedPhotos.length > 0
-        ? state.selectedPhotos
-        : state.activePhotoId
-          ? [state.activePhotoId]
-          : []
-    if (ids.length === 0) {
-      toast.info('Nothing selected', 'Select photos first, then press P')
-      return
-    }
-    const heapsList = queryClient.getQueryData<Heap[]>(HEAPS_QUERY_KEY) ?? []
-    const active = heapsList.find((h) => h.is_active)
-    if (!active) {
-      toast.info('No active heap', 'Set an active heap (target icon next to a heap)')
-      return
-    }
-    // Determine direction: if every selected photo is already a member, this
-    // press REMOVES them; otherwise it ADDS the missing ones. Mirrors how
-    // Lightroom's flag-toggle works.
-    const memberIds =
-      queryClient.getQueryData<string[]>(['heap-photo-ids', active.id]) ?? []
-    const memberSet = new Set(memberIds)
-    const allMembers = ids.every((id) => memberSet.has(id))
-    heapMutation.mutate({
-      heapId: active.id,
-      photoIds: ids,
-      remove: allMembers,
-    })
-  }
-
-  // Toggle sidebars. The right sidebar `i` shortcut is grid-only — in
-  // preview mode the PreviewView mounts its own `i` handler for the
-  // overlay info panel, and we don't want both to fire.
-  useHotkeys('tab', onToggleLeftSidebar, HK_OPTS)
-  useHotkeys('i', onToggleRightSidebar, { ...HK_OPTS, enabled: !isPreview })
-
-  // Cmd/Ctrl+Z → pop the most recent undoable action and reverse it.
-  // Bound at the global level so it works in both grid and preview modes.
-  useHotkeys(
-    'mod+z',
-    async () => {
-      const entry = useUndoStore.getState().pop()
-      if (!entry) {
-        toast.info('Nothing to undo')
-        return
-      }
-      try {
-        await entry.undo()
-      } catch (e: any) {
-        useUndoStore.getState().push({ label: entry.label, undo: entry.undo })
-        toast.error('Undo failed', e?.message || 'Unknown error')
-      }
-    },
-    HK_OPTS
-  )
-
-  // Search focus (/ or Cmd/Ctrl+F).
-  const focusSearch = () => {
-    const el = document.getElementById('topbar-search') as HTMLInputElement | null
-    el?.focus()
-    el?.select()
-  }
-  useHotkeys('/', focusSearch, HK_OPTS)
-  useHotkeys('mod+f', focusSearch, HK_OPTS)
-
-  // Space toggles the preview view (open from grid, close from preview).
-  // Double-click on a thumbnail does the same.
-  const openPreviewFromGrid = () => {
-    const state = usePhotoStore.getState()
-    const id = state.activePhotoId ?? getFirstPhotoId?.() ?? null
-    if (!id) return
-    // Pass the current visible sequence explicitly so preview navigation
-    // walks the order the user actually sees, even if the active photo
-    // was selected before the publisher caught up.
-    openPreview(id, state.visiblePhotoIds)
-  }
-
-  const togglePreview = () => {
-    if (isPreview) closePreview()
-    else openPreviewFromGrid()
-  }
-
-  useHotkeys('space', togglePreview, HK_OPTS, [isPreview, getFirstPhotoId])
-
-  // ── Culling shortcuts (work in both grid and preview) ────────────────────
-
-  // Star rating: 1-5 set, 0 clears.
-  useHotkeys(
-    '1,2,3,4,5',
-    (_e, handler) => {
-      const rating = parseInt(handler.keys![0])
-      if (Number.isFinite(rating)) updateActive({ rating })
-    },
-    HK_OPTS
-  )
-
-  useHotkeys('0', () => updateActive({ rating: 0 }), HK_OPTS)
-
-  // P (Pick) is unified with "add to active heap" — Pick a photo and you're
-  // adding it to the heap you set as active. Toggling on already-picked
-  // photos removes them from the heap.
-  useHotkeys('p', togglePickOnSelection, HK_OPTS)
-
-  useHotkeys('x', () => updateActive({ is_discarded: true }), HK_OPTS)
-
-  useHotkeys('u', () => updateActive({ is_discarded: false }), HK_OPTS)
-
-  // Color labels 6-9 (red/orange/yellow/green per spec §6.4).
-  useHotkeys(
-    '6,7,8,9',
-    (_e, handler) => {
-      const label = COLOR_LABELS[handler.keys![0]]
-      if (label) updateActive({ color_label: label })
-    },
-    HK_OPTS
-  )
-
-}

frontend/src/hooks/useLibraryStatsQuery.ts

@@ -1,18 +0,0 @@
-import { useQuery } from '@tanstack/react-query'
-import { library, type LibraryStats } from '../services/api'
-
-export const LIBRARY_STATS_QUERY_KEY = ['library', 'stats'] as const
-
-/**
- * Per-section counts for the LeftSidebar badges (All Photos, Rated,
- * Duplicates, Discarded). Cached briefly so navigating around doesn't
- * re-fetch on every click; invalidated on photo mutations through the
- * standard ['photos'] invalidation in the mutation onSuccess paths.
- */
-export function useLibraryStatsQuery() {
-  return useQuery<LibraryStats>({
-    queryKey: LIBRARY_STATS_QUERY_KEY,
-    queryFn: library.stats,
-    staleTime: 30_000,
-  })
-}

frontend/src/hooks/usePhotosQuery.ts

@@ -1,86 +0,0 @@
-import { useMemo } from 'react'
-import { useQuery } from '@tanstack/react-query'
-import { useFilterStore, filtersToParams } from '../store/filterStore'
-import api from '../services/api'
-import type { Photo } from '../types/photo'
-
-/**
- * Single source of truth for the timeline photos query. Both Timeline and
- * PreviewView call this so they share one cache entry — previously
- * PreviewView looked the cache up by key directly, which broke the moment
- * Timeline's key gained the filter params.
- */
-export function usePhotosQuery() {
-  const q = useFilterStore((s) => s.q)
-  const dateFrom = useFilterStore((s) => s.dateFrom)
-  const dateTo = useFilterStore((s) => s.dateTo)
-  const mediaTypes = useFilterStore((s) => s.mediaTypes)
-  const ratingMin = useFilterStore((s) => s.ratingMin)
-  const colorLabel = useFilterStore((s) => s.colorLabel)
-  const flag = useFilterStore((s) => s.flag)
-  const heapId = useFilterStore((s) => s.heapId)
-  const folderId = useFilterStore((s) => s.folderId)
-  const tagIds = useFilterStore((s) => s.tagIds)
-  const duplicates = useFilterStore((s) => s.duplicates)
-  const groupBy = useFilterStore((s) => s.groupBy)
-  const sortBy = useFilterStore((s) => s.sortBy)
-  const sortOrder = useFilterStore((s) => s.sortOrder)
-
-  const filterParams = useMemo(
-    () =>
-      filtersToParams({
-        q,
-        dateFrom,
-        dateTo,
-        mediaTypes,
-        ratingMin,
-        colorLabel,
-        flag,
-        heapId,
-        folderId,
-        tagIds,
-        duplicates,
-        groupBy,
-        sortBy,
-        sortOrder,
-      }),
-    [q, dateFrom, dateTo, mediaTypes, ratingMin, colorLabel, flag, heapId, folderId, tagIds, duplicates, groupBy, sortBy, sortOrder]
-  )
-
-  return useQuery({
-    queryKey: ['photos', filterParams],
-    queryFn: async () => {
-      // Goes through the shared axios instance so it inherits the
-      // relative /api/v1 baseURL — same-origin behind the nginx / vite
-      // proxy, no CORS dance required from another machine.
-      //
-      // The Timeline and grid views virtualize, so we load every match
-      // up-front rather than paginating in the UI. Backend caps per_page
-      // at 500, so for libraries / folders with more matches we walk
-      // pages until we have everything. Capped at 200 pages (= 100k
-      // photos) as a sanity bound.
-      const PER_PAGE = 500
-      const MAX_PAGES = 200
-      const all: Photo[] = []
-      for (let page = 1; page <= MAX_PAGES; page++) {
-        const response = await api.get<{
-          photos: Photo[]
-          total: number
-          pages: number
-        }>('/photos', {
-          params: {
-            page,
-            per_page: PER_PAGE,
-            ...filterParams,
-          },
-        })
-        const photos = response.data.photos || []
-        all.push(...photos)
-        const totalPages = response.data.pages ?? 1
-        if (page >= totalPages || photos.length < PER_PAGE) break
-      }
-      return all
-    },
-    staleTime: 30_000,
-  })
-}

frontend/src/hooks/useTagsQuery.ts

@@ -1,12 +0,0 @@
-import { useQuery } from '@tanstack/react-query'
-import { tags as tagsApi, type Tag } from '../services/api'
-
-export const TAGS_QUERY_KEY = ['tags'] as const
-
-export function useTagsQuery() {
-  return useQuery<Tag[]>({
-    queryKey: TAGS_QUERY_KEY,
-    queryFn: tagsApi.list,
-    staleTime: 30_000,
-  })
-}

frontend/src/index.css

@@ -1,83 +0,0 @@
-@tailwind base;
-@tailwind components;
-@tailwind utilities;
-
-@layer base {
-  :root {
-    --color-bg: #1a1424;
-    --color-surface: #221c2f;
-    --color-surface-2: #2a2339;
-    --color-surface-offset: #352c46;
-    --color-border: rgba(240, 193, 136, 0.10);
-    --color-text: #f0e6d2;
-    --color-text-muted: #a8997d;
-    --color-text-faint: #5e5448;
-    --color-primary: #e8965a;
-    --color-pick: #8aaa5a;
-    --color-reject: #d06464;
-    --color-star: #f0c188;
-  }
-
-  body {
-    @apply bg-bg text-text;
-    font-family: 'Geist', system-ui, sans-serif;
-  }
-}
-
-/* Compact themed scrollbars. Track is fully transparent so the bar
-   floats over the panel surface, and the thumb is a slim translucent
-   pill that tints toward the primary on hover. Firefox uses the
-   `scrollbar-*` properties below; Chromium / WebKit uses the
-   `::-webkit-scrollbar*` rules. */
-* {
-  scrollbar-width: thin;
-  scrollbar-color: rgba(240, 230, 210, 0.18) transparent;
-}
-
-::-webkit-scrollbar {
-  width: 6px;
-  height: 6px;
-}
-
-::-webkit-scrollbar-track,
-::-webkit-scrollbar-corner {
-  background: transparent;
-}
-
-::-webkit-scrollbar-thumb {
-  background-color: rgba(240, 230, 210, 0.18);
-  border-radius: 9999px;
-  /* Inset border keeps the thumb visually slimmer than the track gutter
-     so it reads as a pill rather than a bar. */
-  border: 1px solid transparent;
-  background-clip: padding-box;
-}
-
-::-webkit-scrollbar-thumb:hover {
-  background-color: rgba(232, 150, 90, 0.55); /* primary, soft */
-}
-
-::-webkit-scrollbar-thumb:active {
-  background-color: rgba(232, 150, 90, 0.85);
-}
-
-/* Mule walk cycle — 3x2 sprite sheet (6 frames). Each keyframe holds
-   for one step thanks to `steps(1)` so the background snaps frame-to-frame
-   instead of interpolating. */
-@keyframes mule-walk {
-  0%     { background-position: 0% 0%; }
-  16.66% { background-position: 50% 0%; }
-  33.33% { background-position: 100% 0%; }
-  50%    { background-position: 0% 100%; }
-  66.66% { background-position: 50% 100%; }
-  83.33% { background-position: 100% 100%; }
-  100%   { background-position: 0% 0%; }
-}
-
-/* Parallax desert scroll — moves the desert layer right→left by exactly
-   one tile width so the loop is seamless. The tile width is fixed in
-   CSS (see TopBar.tsx) so the keyframe end value matches. */
-@keyframes desert-scroll {
-  from { background-position-x: 0px, 0px; }
-  to   { background-position-x: -200px, 0px; }
-}

frontend/src/main.tsx

@@ -1,24 +0,0 @@
-import React from 'react'
-import ReactDOM from 'react-dom/client'
-import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
-import { ReactQueryDevtools } from '@tanstack/react-query-devtools'
-import App from './App'
-import './index.css'
-
-const queryClient = new QueryClient({
-  defaultOptions: {
-    queries: {
-      staleTime: 5 * 60 * 1000, // 5 minutes
-      retry: 2,
-    },
-  },
-})
-
-ReactDOM.createRoot(document.getElementById('root')!).render(
-  <React.StrictMode>
-    <QueryClientProvider client={queryClient}>
-      <App />
-      <ReactQueryDevtools initialIsOpen={false} />
-    </QueryClientProvider>
-  </React.StrictMode>,
-)

frontend/src/services/api.ts

@@ -1,575 +0,0 @@
-import axios from 'axios'
-
-// Relative API base. In production the nginx in front of the SPA proxies
-// /api/ to the backend container; in dev the vite server has the same
-// proxy in vite.config.ts. Using a relative URL means requests are
-// always same-origin, so the app works whether you hit it from
-// localhost, a LAN IP, or a reverse proxy without any CORS dance.
-const API_BASE_URL = '/api/v1'
-
-const api = axios.create({
-  baseURL: API_BASE_URL,
-  headers: {
-    'Content-Type': 'application/json',
-  },
-})
-
-// Source Folders API. Source roots are config-driven now (PHOTO_DIRS in
-// .env → bootstrap on backend startup), so the UI only reads them and
-// optionally renames the display label.
-export interface FolderTreeNode {
-  id: string
-  name: string
-  path: string
-  photo_count: number
-  children: FolderTreeNode[]
-}
-
-export const sourceFolders = {
-  list: async () => {
-    const response = await api.get('/folders')
-    return response.data
-  },
-
-  /** Recursive folder tree, one root per active source root. */
-  tree: async (): Promise<FolderTreeNode[]> => {
-    const response = await api.get('/folders/tree')
-    return response.data
-  },
-
-  scan: async (folderId: string) => {
-    const response = await api.post(`/folders/${folderId}/scan`)
-    return response.data
-  },
-
-  /** Rename a folder. SourceRoot ids only update the display label;
-   *  Folder ids actually move the directory on disk and update every
-   *  descendant photo's filepath. */
-  rename: async (folderId: string, name: string) => {
-    const response = await api.patch(`/folders/${folderId}`, { name })
-    return response.data
-  },
-
-  /** Create a new sub-folder under an existing Folder. parent_id MUST
-   *  be a Folder row id (not a SourceRoot id). */
-  create: async (parentId: string, name: string) => {
-    const response = await api.post('/folders', {
-      name,
-      parent_id: parentId,
-    })
-    return response.data as { id: string; name: string; path: string; parent_id: string }
-  },
-
-  /** Delete a folder. mode=discard moves all photos under it to the
-   *  discard pile (recoverable) and leaves the folder + on-disk dir
-   *  alone. mode=permanent unlinks files, removes folder rows, and
-   *  rmtrees the directory — irreversible. */
-  delete: async (folderId: string, mode: 'discard' | 'permanent') => {
-    const response = await api.delete(`/folders/${folderId}`, {
-      params: { mode },
-    })
-    return response.data as {
-      status: string
-      mode: string
-      discarded?: number
-      deleted_photos?: number
-      file_errors?: number
-    }
-  },
-}
-
-// Photos API
-export const photos = {
-  list: async (params?: {
-    limit?: number
-    offset?: number
-    folder_id?: string
-    heap_id?: string
-    rating?: number
-    flag?: string
-  }) => {
-    const response = await api.get('/photos', { params })
-    return response.data
-  },
-
-  get: async (photoId: string) => {
-    const response = await api.get(`/photos/${photoId}`)
-    return response.data
-  },
-
-  update: async (photoId: string, data: {
-    filename?: string
-    rating?: number
-    user_title?: string | null
-    user_notes?: string | null
-    color_label?: string | null
-    is_picked?: boolean
-    is_discarded?: boolean
-    taken_at?: string
-  }) => {
-    const response = await api.patch(`/photos/${photoId}`, data)
-    return response.data
-  },
-
-  /** Bulk discard — matches the backend BulkAction schema. */
-  bulkDiscard: async (photoIds: string[]) => {
-    const response = await api.post('/photos/bulk', {
-      ids: photoIds,
-      action: 'discard',
-    })
-    return response.data
-  },
-
-  /** Bulk restore from discarded. */
-  bulkRestore: async (photoIds: string[]) => {
-    const response = await api.post('/photos/bulk', {
-      ids: photoIds,
-      action: 'restore',
-    })
-    return response.data
-  },
-
-  /** Bulk set rating (0-5). */
-  bulkSetRating: async (photoIds: string[], rating: number) => {
-    const response = await api.post('/photos/bulk', {
-      ids: photoIds,
-      action: 'set_rating',
-      value: rating,
-    })
-    return response.data
-  },
-
-  /** Bulk set color label (or null to clear). */
-  bulkSetColor: async (photoIds: string[], color: string | null) => {
-    const response = await api.post('/photos/bulk', {
-      ids: photoIds,
-      action: 'set_color',
-      value: color,
-    })
-    return response.data
-  },
-
-  /** Add the listed tags to every listed photo. Idempotent — re-adding
-   *  an existing (photo, tag) pair is a no-op. Returns { added: N }. */
-  bulkAddTags: async (photoIds: string[], tagIds: string[]) => {
-    const response = await api.post('/photos/bulk', {
-      ids: photoIds,
-      action: 'add_tags',
-      value: tagIds,
-    })
-    return response.data as { status: string; added: number }
-  },
-
-  /** Remove the listed tags from every listed photo. Removing a
-   *  non-member is a no-op. Returns { removed: N }. */
-  bulkRemoveTags: async (photoIds: string[], tagIds: string[]) => {
-    const response = await api.post('/photos/bulk', {
-      ids: photoIds,
-      action: 'remove_tags',
-      value: tagIds,
-    })
-    return response.data as { status: string; removed: number }
-  },
-
-  /** Move photos into a target folder (or source root). Returns
-   *  { moved, errors[] }. */
-  move: async (photoIds: string[], targetId: string) => {
-    const response = await api.post('/photos/move', {
-      photo_ids: photoIds,
-      target_id: targetId,
-    })
-    return response.data as { status: string; moved: number; errors: Array<{ id: string; error: string }> }
-  },
-
-  /** Copy photos into a target folder. Originals are unaffected; new
-   *  rows are created with is_duplicate=true. */
-  copy: async (photoIds: string[], targetId: string) => {
-    const response = await api.post('/photos/copy', {
-      photo_ids: photoIds,
-      target_id: targetId,
-    })
-    return response.data as { status: string; copied: number; errors: Array<{ id: string; error: string }> }
-  },
-
-  getThumbnailUrl: (photoId: string, size: 'small' | 'medium' | 'large' = 'medium') => {
-    return `${API_BASE_URL}/photos/${photoId}/thumb/${size}`
-  },
-
-  getOriginalUrl: (photoId: string) => {
-    return `${API_BASE_URL}/photos/${photoId}/original`
-  },
-
-  /** Full-resolution display URL. Backend serves the original for web-safe
-   *  formats and a transcoded WebP for RAW/HEIC/TIFF. */
-  getProxyUrl: (photoId: string) => {
-    return `${API_BASE_URL}/photos/${photoId}/proxy`
-  },
-}
-
-// Library API
-export type MediaType = 'photo' | 'raw' | 'heic' | 'video'
-
-export interface ThumbnailStats {
-  total: number
-  pending: number
-  processing: number
-  completed: number
-  failed: number
-  by_media_type: Record<string, number>
-}
-
-export interface RegenerateResult {
-  status: string
-  matched: number
-  queued: number
-  cleared_dirs: number
-  file_errors: number
-  filters: {
-    media_types: MediaType[] | null
-    only_failed: boolean
-  }
-}
-
-export interface MissingStats {
-  would_delete?: number
-  deleted?: number
-  would_delete_folders?: number
-  deleted_folders?: number
-  skipped_unmounted: number
-  dry_run: boolean
-}
-
-export interface PruneResult extends MissingStats {
-  status?: string
-  message?: string
-}
-
-export interface WorkerInfo {
-  name: string
-  status: 'online' | 'unreachable'
-  active: number
-  reserved: number
-  scheduled: number
-  concurrency: number | null
-  processed: Record<string, number>
-  queues: string[]
-  active_tasks: Array<{
-    id: string
-    name: string
-    args: unknown
-    time_start: number | null
-  }>
-}
-
-export interface WorkerFailure {
-  photo_id: string
-  filename: string
-  media_type: string
-  error: string
-  updated_at: string | null
-}
-
-export interface WorkerStatus {
-  broker_ok: boolean
-  broker_error: string | null
-  inspect_error: string | null
-  workers: WorkerInfo[]
-  worker_count: number
-  queues: Record<string, number>
-  failures: {
-    total: number
-    recent: WorkerFailure[]
-  }
-  scan_errors: string[]
-}
-
-export const library = {
-  scan: async () => {
-    const response = await api.post('/library/scan')
-    return response.data
-  },
-
-  scanStatus: async () => {
-    const response = await api.get('/library/scan/status')
-    return response.data
-  },
-
-  stats: async (): Promise<LibraryStats> => {
-    const response = await api.get('/library/stats')
-    return response.data
-  },
-
-  /** Maintenance / admin actions surfaced via the Settings panel. */
-  maintenance: {
-    thumbnailStats: async (): Promise<ThumbnailStats> => {
-      const response = await api.get('/library/maintenance/thumbnail-stats')
-      return response.data
-    },
-
-    /** Reset on-disk thumbs and re-queue Celery generation. With no
-     *  filters, every photo in the library is re-queued. */
-    regenerateThumbnails: async (
-      body: {
-        media_types?: MediaType[]
-        only_failed?: boolean
-        only_pending?: boolean
-      } = {}
-    ): Promise<RegenerateResult> => {
-      const response = await api.post(
-        '/library/maintenance/regenerate-thumbnails',
-        body
-      )
-      return response.data
-    },
-
-    /** Celery worker fleet diagnostics + recent task failures. Surfaced
-     *  in the Settings panel so users can debug stuck queues without
-     *  tailing container logs. */
-    workerStatus: async (): Promise<WorkerStatus> => {
-      const response = await api.get('/library/maintenance/worker-status')
-      return response.data
-    },
-
-    /** Dry-run count of photo rows whose files are no longer on disk
-     *  (under a mounted source root). */
-    missingStats: async (): Promise<MissingStats> => {
-      const response = await api.get('/library/maintenance/missing-stats')
-      return response.data
-    },
-
-    /** Actually delete the orphaned photo rows. */
-    pruneMissing: async (): Promise<PruneResult> => {
-      const response = await api.post('/library/maintenance/prune-missing')
-      return response.data
-    },
-
-    /** Re-run the source-roots / folders / photos integrity cleanup that
-     *  normally runs on backend startup. */
-    cleanup: async (): Promise<{ status: string; message?: string }> => {
-      const response = await api.post('/library/maintenance/cleanup')
-      return response.data
-    },
-
-    /** Recompute duplicate groups from current perceptual hashes.
-     *  Idempotent — safe to fire repeatedly. */
-    regroupDuplicates: async (): Promise<{ status: string; message?: string }> => {
-      const response = await api.post('/library/maintenance/regroup-duplicates')
-      return response.data
-    },
-
-    /** Compute pHash for every photo currently missing one. One-shot
-     *  recovery path for libraries that existed before the phash column
-     *  was added. */
-    backfillPhashes: async (): Promise<{ status: string; message?: string }> => {
-      const response = await api.post('/library/maintenance/backfill-phashes')
-      return response.data
-    },
-  },
-
-  /** Duplicate groups computed by app.services.duplicates.regroup_duplicates.
-   *  Drives the grouped grid view in the Duplicates section. */
-  duplicates: {
-    groups: async (): Promise<DuplicateGroupsResponse> => {
-      const response = await api.get('/library/duplicates/groups')
-      return response.data
-    },
-  },
-}
-
-// ── Duplicate groups ─────────────────────────────────────────────────────
-
-export interface DuplicateGroupMember {
-  id: string
-  filename: string
-  taken_at: string | null
-  file_size: number | null
-  width: number | null
-  height: number | null
-  thumb_small: string | null
-  file_hash: string | null
-  folder_id: string | null
-  media_type: string
-}
-
-export interface DuplicateGroup {
-  group_id: string
-  member_count: number
-  /** "exact" iff every member shares the same SHA-256 (true byte
-   *  duplicates that pHash also caught). "similar" otherwise. */
-  reason: 'exact' | 'similar'
-  members: DuplicateGroupMember[]
-}
-
-export interface DuplicateGroupsResponse {
-  groups: DuplicateGroup[]
-  total_groups: number
-  total_members: number
-}
-
-export interface LibraryStats {
-  all_photos: number
-  rated: number
-  duplicates: number
-  discarded: number
-  total_photos: number
-  total_videos: number
-  total_size: number
-  total_size_gb: number
-}
-
-// Heaps API
-export interface Heap {
-  id: string
-  name: string
-  is_active: boolean
-  created_at: string
-  updated_at: string | null
-  photo_count: number
-}
-
-export const heaps = {
-  list: async (): Promise<Heap[]> => {
-    const response = await api.get('/heaps')
-    return response.data
-  },
-
-  create: async (name: string): Promise<Heap> => {
-    const response = await api.post('/heaps', { name })
-    return response.data
-  },
-
-  update: async (
-    heapId: string,
-    data: { name?: string; is_active?: boolean }
-  ): Promise<Heap> => {
-    const response = await api.patch(`/heaps/${heapId}`, data)
-    return response.data
-  },
-
-  delete: async (heapId: string): Promise<void> => {
-    await api.delete(`/heaps/${heapId}`)
-  },
-
-  /** Duplicate a heap, copying its membership but never marking the new
-   *  one as active. The new heap is named "{name} (copy)". */
-  duplicate: async (heapId: string): Promise<Heap> => {
-    const response = await api.post(`/heaps/${heapId}/duplicate`)
-    return response.data
-  },
-
-  /** Lightweight: just the photo ids in a heap, for client-side membership
-   *  lookups (the basket affordance on thumbnails). */
-  photoIds: async (heapId: string): Promise<string[]> => {
-    const response = await api.get(`/heaps/${heapId}/photo_ids`)
-    return response.data
-  },
-
-  addPhotos: async (heapId: string, photoIds: string[]) => {
-    const response = await api.post(`/heaps/${heapId}/photos`, {
-      photo_ids: photoIds,
-    })
-    return response.data
-  },
-
-  removePhotos: async (heapId: string, photoIds: string[]) => {
-    const response = await api.delete(`/heaps/${heapId}/photos`, {
-      data: { photo_ids: photoIds },
-    })
-    return response.data
-  },
-
-  /** Convert a heap into a folder by moving (or copying) every member
-   *  photo into the target directory. Optionally creates a subfolder
-   *  inside the target by name. */
-  convert: async (
-    heapId: string,
-    body: {
-      target_id: string
-      mode: 'move' | 'copy'
-      delete_heap: boolean
-      subfolder_name?: string | null
-    }
-  ) => {
-    const response = await api.post(`/heaps/${heapId}/convert`, body)
-    return response.data as {
-      status: string
-      mode: 'move' | 'copy'
-      moved: number
-      copied: number
-      errors: Array<{ id: string; error: string }>
-      heap_deleted: boolean
-    }
-  },
-}
-
-// Tags API
-export interface Tag {
-  id: string
-  name: string
-  color: string | null
-  photo_count: number
-}
-
-export const tags = {
-  list: async (): Promise<Tag[]> => {
-    const response = await api.get('/tags')
-    return response.data
-  },
-
-  create: async (name: string, color?: string): Promise<Tag> => {
-    const response = await api.post('/tags', { name, color })
-    return response.data
-  },
-
-  update: async (tagId: string, data: { name?: string; color?: string }): Promise<Tag> => {
-    const response = await api.patch(`/tags/${tagId}`, data)
-    return response.data
-  },
-
-  delete: async (tagId: string): Promise<void> => {
-    await api.delete(`/tags/${tagId}`)
-  },
-
-  /** Add one or more tags to a photo. */
-  addToPhoto: async (photoId: string, tagIds: string[]) => {
-    const response = await api.post(`/photos/${photoId}/tags`, { tag_ids: tagIds })
-    return response.data
-  },
-
-  /** Remove a tag from a photo. */
-  removeFromPhoto: async (photoId: string, tagId: string): Promise<void> => {
-    await api.delete(`/photos/${photoId}/tags/${tagId}`)
-  },
-}
-
-// Discard API
-export const discard = {
-  list: async () => {
-    const response = await api.get('/discard')
-    return response.data
-  },
-
-  restore: async (photoIds: string[]) => {
-    const response = await api.post('/discard/restore', {
-      photo_ids: photoIds,
-    })
-    return response.data
-  },
-
-  empty: async () => {
-    const response = await api.delete('/discard/empty')
-    return response.data
-  },
-
-  /** Permanently delete a specific subset of discarded photos. The backend
-   *  silently skips ids that aren't in the pile, so this can never bypass
-   *  the soft-delete safety net. */
-  deletePermanent: async (photoIds: string[]) => {
-    const response = await api.delete('/discard', {
-      data: { photo_ids: photoIds },
-    })
-    return response.data
-  },
-}
-
-export default api

frontend/src/store/filterStore.ts

@@ -1,234 +0,0 @@
-import { create } from 'zustand'
-import type { ColorLabel } from '../constants/colorLabels'
-
-export type MediaType = 'photo' | 'video' | 'raw' | 'heic'
-export type { ColorLabel }
-export type FlagFilter = 'any' | 'discarded'
-export type SortField =
-  | 'taken_at'
-  | 'added_at'
-  | 'filename'
-  | 'file_size'
-  | 'rating'
-export type SortOrder = 'asc' | 'desc'
-export type GroupBy = 'date' | 'tag' | 'rating'
-
-export interface FilterState {
-  q: string
-  dateFrom: string | null // ISO yyyy-mm-dd
-  dateTo: string | null
-  mediaTypes: MediaType[]
-  ratingMin: number // 0-5; 0 means no filter
-  colorLabel: ColorLabel | null
-  flag: FlagFilter
-  /** When set, restrict to photos in this heap. Independent of `activeHeapId`
-   *  on the heap store — that's the target for the T shortcut. */
-  heapId: string | null
-  /** When set, restrict to photos in this folder. */
-  folderId: string | null
-  /** Restrict to photos that have ALL of these tag ids (AND semantics). */
-  tagIds: string[]
-  /** When true, restrict to photos flagged as duplicates by the scanner. */
-  duplicates: boolean
-  /** Visual grouping mode. 'date' groups by month when sortBy is a date
-   *  field; 'tag' groups by photo tag membership. Independent of filters. */
-  groupBy: GroupBy
-  sortBy: SortField
-  sortOrder: SortOrder
-}
-
-/** Identifies which "section" of the app the user is currently viewing.
- *  Sections each carry their own filter state — switching to one restores
- *  whatever filters were active there last time, switching away saves the
- *  current state under the section being left. */
-export const ALL_PHOTOS_SECTION = 'all-photos'
-
-interface FilterStore extends FilterState {
-  /** The active section id. Changes via navigateToSection. */
-  currentSection: string
-  /** Per-section snapshot of filter state, in-memory. Restored on return. */
-  sectionFilters: Record<string, FilterState>
-  /** Per-section "intrinsic" filters — the preset that defines what makes
-   *  a section that section (e.g. flag=discarded for the discarded
-   *  section). Used by clearAll to reset within a section without
-   *  navigating away. */
-  sectionPresets: Record<string, Partial<FilterState>>
-
-  setQ: (q: string) => void
-  setDateFrom: (date: string | null) => void
-  setDateTo: (date: string | null) => void
-  toggleMediaType: (t: MediaType) => void
-  setRatingMin: (rating: number) => void
-  setColorLabel: (label: ColorLabel | null) => void
-  setFlag: (flag: FlagFilter) => void
-  setHeapId: (id: string | null) => void
-  setFolderId: (id: string | null) => void
-  setTagIds: (ids: string[]) => void
-  toggleTagId: (id: string) => void
-  setDuplicates: (v: boolean) => void
-  setGroupBy: (mode: GroupBy) => void
-  setSortBy: (field: SortField) => void
-  setSortOrder: (order: SortOrder) => void
-  toggleSortOrder: () => void
-
-  /** Navigate to a section. Saves the current section's filter state into
-   *  the in-memory map under the OLD section id, then loads the saved
-   *  state for the destination — or, if none exists, applies the preset
-   *  overrides on top of INITIAL_FILTERS. The preset is also stored so
-   *  clearAll inside the section resets correctly. */
-  navigateToSection: (
-    sectionId: string,
-    presetOverrides?: Partial<FilterState>
-  ) => void
-
-  hydrate: (partial: Partial<FilterState> & { currentSection?: string }) => void
-  /** Reset filters within the CURRENT section back to its preset. Doesn't
-   *  navigate. For an explicit "go to all photos" use navigateToSection. */
-  clearAll: () => void
-}
-
-export const INITIAL_FILTERS: FilterState = {
-  q: '',
-  dateFrom: null,
-  dateTo: null,
-  mediaTypes: [],
-  ratingMin: 0,
-  colorLabel: null,
-  flag: 'any',
-  heapId: null,
-  folderId: null,
-  tagIds: [],
-  duplicates: false,
-  groupBy: 'date',
-  sortBy: 'taken_at',
-  sortOrder: 'desc',
-}
-
-/** Pull the FilterState slice out of the full store, dropping the
- *  control fields. Used when snapshotting current filters into the
- *  per-section map. */
-function snapshotFilters(s: FilterState): FilterState {
-  return {
-    q: s.q,
-    dateFrom: s.dateFrom,
-    dateTo: s.dateTo,
-    mediaTypes: [...s.mediaTypes],
-    ratingMin: s.ratingMin,
-    colorLabel: s.colorLabel,
-    flag: s.flag,
-    heapId: s.heapId,
-    folderId: s.folderId,
-    tagIds: [...s.tagIds],
-    duplicates: s.duplicates,
-    groupBy: s.groupBy,
-    sortBy: s.sortBy,
-    sortOrder: s.sortOrder,
-  }
-}
-
-export const useFilterStore = create<FilterStore>((set) => ({
-  ...INITIAL_FILTERS,
-  currentSection: ALL_PHOTOS_SECTION,
-  sectionFilters: {},
-  sectionPresets: { [ALL_PHOTOS_SECTION]: {} },
-
-  setQ: (q) => set({ q }),
-  setDateFrom: (dateFrom) => set({ dateFrom }),
-  setDateTo: (dateTo) => set({ dateTo }),
-  toggleMediaType: (t) =>
-    set((s) => ({
-      mediaTypes: s.mediaTypes.includes(t)
-        ? s.mediaTypes.filter((x) => x !== t)
-        : [...s.mediaTypes, t],
-    })),
-  setRatingMin: (ratingMin) => set({ ratingMin }),
-  setColorLabel: (colorLabel) => set({ colorLabel }),
-  setFlag: (flag) => set({ flag }),
-  setHeapId: (heapId) => set({ heapId }),
-  setFolderId: (folderId) => set({ folderId }),
-  setTagIds: (tagIds) => set({ tagIds }),
-  toggleTagId: (id) =>
-    set((s) => ({
-      tagIds: s.tagIds.includes(id)
-        ? s.tagIds.filter((t) => t !== id)
-        : [...s.tagIds, id],
-    })),
-  setDuplicates: (duplicates) => set({ duplicates }),
-  setGroupBy: (groupBy) => set({ groupBy }),
-  setSortBy: (sortBy) => set({ sortBy }),
-  setSortOrder: (sortOrder) => set({ sortOrder }),
-  toggleSortOrder: () =>
-    set((s) => ({ sortOrder: s.sortOrder === 'desc' ? 'asc' : 'desc' })),
-
-  navigateToSection: (sectionId, presetOverrides = {}) =>
-    set((s) => {
-      // Snapshot the current section's filters before switching.
-      const updatedSectionFilters = {
-        ...s.sectionFilters,
-        [s.currentSection]: snapshotFilters(s),
-      }
-      // Remember this section's intrinsic preset (last write wins, which
-      // is fine — sections are uniquely identified by id).
-      const updatedSectionPresets = {
-        ...s.sectionPresets,
-        [sectionId]: presetOverrides,
-      }
-      // Restore the destination section's saved state, or apply the
-      // preset on top of fresh defaults if it's never been visited.
-      const saved = updatedSectionFilters[sectionId]
-      const next: FilterState = saved
-        ? saved
-        : { ...INITIAL_FILTERS, ...presetOverrides }
-
-      return {
-        ...next,
-        currentSection: sectionId,
-        sectionFilters: updatedSectionFilters,
-        sectionPresets: updatedSectionPresets,
-      }
-    }),
-
-  hydrate: (partial) => set(partial),
-  clearAll: () =>
-    set((s) => {
-      const preset = s.sectionPresets[s.currentSection] ?? {}
-      return { ...INITIAL_FILTERS, ...preset }
-    }),
-}))
-
-/** Convert filter state to the query params the backend list endpoint expects.
- *  Empty / default values are omitted so the cache key is stable. */
-export function filtersToParams(f: FilterState): Record<string, string | number> {
-  const params: Record<string, string | number> = {}
-  if (f.q.trim()) params.q = f.q.trim()
-  if (f.dateFrom) params.date_from = f.dateFrom
-  if (f.dateTo) params.date_to = f.dateTo
-  if (f.mediaTypes.length > 0) params.media_type = f.mediaTypes.join(',')
-  if (f.ratingMin > 0) params.rating_min = f.ratingMin
-  if (f.colorLabel) params.color_label = f.colorLabel
-  if (f.flag === 'discarded') params.is_discarded = 'true'
-  if (f.heapId) params.heap_id = f.heapId
-  if (f.folderId) params.folder_id = f.folderId
-  if (f.tagIds.length > 0) params.tag_ids = f.tagIds.join(',')
-  if (f.duplicates) params.is_duplicate = 'true'
-  params.sort = f.sortBy
-  params.order = f.sortOrder
-  return params
-}
-
-/** True if any filter (other than the search box) is active. */
-export function hasActiveFilters(f: FilterState): boolean {
-  return (
-    f.q.trim() !== '' ||
-    f.dateFrom !== null ||
-    f.dateTo !== null ||
-    f.mediaTypes.length > 0 ||
-    f.ratingMin > 0 ||
-    f.colorLabel !== null ||
-    f.flag !== 'any' ||
-    f.heapId !== null ||
-    f.folderId !== null ||
-    f.tagIds.length > 0 ||
-    f.duplicates
-  )
-}

frontend/src/store/photoStore.ts

@@ -1,161 +0,0 @@
-import { create } from 'zustand'
-import type { Photo } from '../types/photo'
-
-type ViewMode = 'grid' | 'preview'
-
-interface PhotoStore {
-  photos: Photo[]
-  selectedPhotos: string[]
-  activePhotoId: string | null
-  /** The id of the photo where the current range-selection anchor lives.
-   *  Set when the user clicks (without modifiers) or arrow-navigates,
-   *  read by selectRange to figure out the start of a Shift+Click /
-   *  Shift+Arrow range. Tracked as an id (not an index) so it survives
-   *  filter changes and works correctly in tag-grouped mode where
-   *  visual indices != API indices. */
-  rangeStartId: string | null
-  viewMode: ViewMode
-  /** Flat sequence of photo ids in the order they currently appear in
-   *  the timeline grid (including duplicates from tag-grouping). Used
-   *  for both preview navigation order and range selection. Owned by
-   *  the Timeline component. */
-  visiblePhotoIds: string[]
-
-  setPhotos: (photos: Photo[]) => void
-  selectPhoto: (id: string) => void
-  togglePhotoSelection: (id: string) => void
-  /** Replace the selection with every photo between the current
-   *  rangeStartId and the supplied endId, walking visiblePhotoIds in
-   *  visual order. If there's no anchor yet, anchors at endId. */
-  selectRange: (endId: string) => void
-  deselectPhoto: (id: string) => void
-  clearSelection: () => void
-  setActivePhoto: (id: string | null) => void
-  setViewMode: (mode: ViewMode) => void
-  setVisiblePhotoIds: (ids: string[]) => void
-  /** Open preview on a specific photo. The visibleSequence (optional)
-   *  is the ordered list of photo ids the user currently sees in the
-   *  timeline; passing it from the click site avoids a race where the
-   *  passive Timeline publisher hasn't updated yet. */
-  openPreview: (id: string, visibleSequence?: string[]) => void
-  closePreview: () => void
-}
-
-export const usePhotoStore = create<PhotoStore>((set) => ({
-  photos: [],
-  selectedPhotos: [],
-  activePhotoId: null,
-  rangeStartId: null,
-  viewMode: 'grid',
-  visiblePhotoIds: [],
-
-  setPhotos: (photos) => set({ photos }),
-
-  selectPhoto: (id) => set({
-    selectedPhotos: [id],
-    activePhotoId: id,
-    rangeStartId: id,
-  }),
-
-  togglePhotoSelection: (id) => set((state) => {
-    const isSelected = state.selectedPhotos.includes(id)
-    return {
-      selectedPhotos: isSelected
-        ? state.selectedPhotos.filter((photoId) => photoId !== id)
-        : [...state.selectedPhotos, id],
-      // A toggle-add anchors the range here so a subsequent Shift+click
-      // extends from this id. A toggle-remove leaves the anchor alone.
-      rangeStartId: isSelected ? state.rangeStartId : id,
-      activePhotoId: id,
-    }
-  }),
-
-  selectRange: (endId) =>
-    set((state) => {
-      const ids = state.visiblePhotoIds
-      // No published sequence yet → just behave like a single-pick.
-      if (ids.length === 0) {
-        return {
-          selectedPhotos: [endId],
-          activePhotoId: endId,
-          rangeStartId: endId,
-        }
-      }
-      const anchorId = state.rangeStartId ?? state.activePhotoId ?? endId
-      const startIdx = ids.indexOf(anchorId)
-      const endIdx = ids.indexOf(endId)
-      if (startIdx < 0 || endIdx < 0) {
-        return {
-          selectedPhotos: [endId],
-          activePhotoId: endId,
-          rangeStartId: endId,
-        }
-      }
-      const min = Math.min(startIdx, endIdx)
-      const max = Math.max(startIdx, endIdx)
-      // De-dupe because the visible sequence can repeat photos in
-      // tag-grouped mode.
-      const seen = new Set<string>()
-      const next: string[] = []
-      for (let i = min; i <= max; i++) {
-        const id = ids[i]
-        if (!seen.has(id)) {
-          seen.add(id)
-          next.push(id)
-        }
-      }
-      return {
-        selectedPhotos: next,
-        activePhotoId: endId,
-        // Anchor stays put — the user can keep extending from the
-        // original click point, matching Lightroom / Finder behavior.
-      }
-    }),
-
-  deselectPhoto: (id) => set((state) => ({
-    selectedPhotos: state.selectedPhotos.filter(photoId => photoId !== id)
-  })),
-
-  clearSelection: () => set({
-    selectedPhotos: [],
-    rangeStartId: null,
-  }),
-  
-  setActivePhoto: (id) => set({ activePhotoId: id }),
-
-  setViewMode: (mode) => set({ viewMode: mode }),
-
-  // No-op when the content is identical so callers can fire from an
-  // effect without risking a re-render loop.
-  setVisiblePhotoIds: (visiblePhotoIds) =>
-    set((s) => {
-      const prev = s.visiblePhotoIds
-      if (prev.length === visiblePhotoIds.length) {
-        let same = true
-        for (let i = 0; i < prev.length; i++) {
-          if (prev[i] !== visiblePhotoIds[i]) {
-            same = false
-            break
-          }
-        }
-        if (same) return s
-      }
-      return { visiblePhotoIds }
-    }),
-
-  openPreview: (id, visibleSequence) =>
-    set((s) => ({
-      viewMode: 'preview',
-      activePhotoId: id,
-      // Adopt the caller-provided sequence when they pass one. Falls
-      // back to whatever Timeline most recently published, which is
-      // correct for paths like the global Space hotkey that don't have
-      // a click site to compute the sequence from.
-      visiblePhotoIds:
-        visibleSequence && visibleSequence.length > 0
-          ? visibleSequence
-          : s.visiblePhotoIds,
-    })),
-
-  closePreview: () => set({ viewMode: 'grid' }),
-}))

frontend/src/store/undoStore.ts

@@ -1,71 +0,0 @@
-import { create } from 'zustand'
-import { toast } from '../components/ToastContainer'
-
-const MAX_STACK = 20
-
-export interface UndoEntry {
-  id: string
-  /** Short description of what happened, e.g. "Discarded 12 photos". */
-  label: string
-  /** Function that reverses the action. May be async; errors should be
-   *  surfaced via toast.error from inside the function. */
-  undo: () => void | Promise<void>
-}
-
-interface UndoStore {
-  stack: UndoEntry[]
-  /** Push a new entry. Caps the stack at MAX_STACK by dropping the oldest. */
-  push: (entry: Omit<UndoEntry, 'id'>) => void
-  /** Pop the most recent entry. Returns null when the stack is empty. */
-  pop: () => UndoEntry | null
-  clear: () => void
-}
-
-export const useUndoStore = create<UndoStore>((set, get) => ({
-  stack: [],
-
-  push: (entry) => {
-    const id = Date.now().toString() + Math.random().toString(36).slice(2, 6)
-    set((s) => {
-      const next = [...s.stack, { ...entry, id }]
-      if (next.length > MAX_STACK) next.shift()
-      return { stack: next }
-    })
-  },
-
-  pop: () => {
-    const stack = get().stack
-    if (stack.length === 0) return null
-    const last = stack[stack.length - 1]
-    set({ stack: stack.slice(0, -1) })
-    return last
-  },
-
-  clear: () => set({ stack: [] }),
-}))
-
-/**
- * Convenience: register an undoable action AND show the user a success
- * toast with an inline Undo button. The toast and Cmd+Z hotkey both pop
- * from the same stack so either path works.
- */
-export function registerUndoable(label: string, undo: () => void | Promise<void>) {
-  useUndoStore.getState().push({ label, undo })
-  toast.success(label, 'Press ⌘Z to undo', {
-    label: 'Undo',
-    onClick: async () => {
-      // Pop the entry we just pushed (or whatever is now on top, if the
-      // user fired multiple actions in quick succession — Undo always
-      // reverses the most recent thing).
-      const entry = useUndoStore.getState().pop()
-      if (!entry) return
-      try {
-        await entry.undo()
-      } catch (e) {
-        // Re-push so the user can try again, and surface the failure.
-        useUndoStore.getState().push({ label: entry.label, undo: entry.undo })
-        toast.error('Undo failed', e instanceof Error ? e.message : String(e))
-      }
-    },
-  })
-}

frontend/src/types/images.d.ts

@@ -1,29 +0,0 @@
-declare module '*.png' {
-  const value: string;
-  export default value;
-}
-
-declare module '*.jpg' {
-  const value: string;
-  export default value;
-}
-
-declare module '*.jpeg' {
-  const value: string;
-  export default value;
-}
-
-declare module '*.gif' {
-  const value: string;
-  export default value;
-}
-
-declare module '*.svg' {
-  const value: string;
-  export default value;
-}
-
-declare module '*.webp' {
-  const value: string;
-  export default value;
-}

frontend/src/types/photo.ts

@@ -1,25 +0,0 @@
-export interface PhotoTagSummary {
-  id: string
-  name: string
-  color: string | null
-}
-
-export interface Photo {
-  id: string
-  filepath: string
-  filename: string
-  media_type: string
-  width: number | null
-  height: number | null
-  taken_at: string | null
-  rating: number
-  is_discarded: boolean
-  is_duplicate: boolean
-  file_hash: string
-  folder_id: string | null
-  added_at: string | null
-  thumb_small?: string
-  thumb_medium?: string
-  thumb_large?: string
-  tags?: PhotoTagSummary[]
-}

frontend/tailwind.config.js

@@ -1,54 +0,0 @@
-/** @type {import('tailwindcss').Config} */
-export default {
-  content: [
-    "./index.html",
-    "./src/**/*.{js,ts,jsx,tsx}",
-  ],
-  darkMode: 'class',
-  theme: {
-    extend: {
-      colors: {
-        // Desert dusk palette — warm, slightly indigo darks pulled from
-        // the TopBar sunset gradient. Dark enough that photo content
-        // stays the visual focus, but no longer the cool neutral greys
-        // we started with.
-        bg: '#1a1424',           // deep dusk indigo (was near-black)
-        surface: '#221c2f',       // panel base
-        'surface-2': '#2a2339',   // raised panels / hover
-        'surface-offset': '#352c46', // chips, inputs
-        border: 'rgba(240, 193, 136, 0.10)', // warm sand tint, low alpha
-        text: '#f0e6d2',          // warm cream
-        'text-muted': '#a8997d',  // sandy beige
-        'text-faint': '#5e5448',  // dark sand
-        primary: '#e8965a',       // sunset orange — pulled from horizon
-        pick: '#8aaa5a',          // sage / cactus green
-        reject: '#d06464',        // warmer red
-        star: '#f0c188',          // pale amber matching horizon
-      },
-      fontFamily: {
-        sans: ['Geist', 'system-ui', 'sans-serif'],
-        mono: ['Geist Mono', 'monospace'],
-      },
-      animation: {
-        'fade-in': 'fadeIn 0.2s ease-in-out',
-        'slide-up': 'slideUp 0.3s ease-out',
-        'shimmer': 'shimmer 2s infinite linear',
-      },
-      keyframes: {
-        fadeIn: {
-          '0%': { opacity: '0' },
-          '100%': { opacity: '1' },
-        },
-        slideUp: {
-          '0%': { transform: 'translateY(20px)', opacity: '0' },
-          '100%': { transform: 'translateY(0)', opacity: '1' },
-        },
-        shimmer: {
-          '0%': { backgroundPosition: '-200% 0' },
-          '100%': { backgroundPosition: '200% 0' },
-        },
-      },
-    },
-  },
-  plugins: [],
-}

frontend/tsconfig.json

@@ -1,31 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2020",
-    "useDefineForClassFields": true,
-    "lib": ["ES2020", "DOM", "DOM.Iterable"],
-    "module": "ESNext",
-    "skipLibCheck": true,
-
-    /* Bundler mode */
-    "moduleResolution": "bundler",
-    "allowImportingTsExtensions": true,
-    "resolveJsonModule": true,
-    "isolatedModules": true,
-    "noEmit": true,
-    "jsx": "react-jsx",
-
-    /* Linting */
-    "strict": true,
-    "noUnusedLocals": true,
-    "noUnusedParameters": true,
-    "noFallthroughCasesInSwitch": true,
-
-    /* Path mapping */
-    "baseUrl": ".",
-    "paths": {
-      "@/*": ["src/*"]
-    }
-  },
-  "include": ["src"],
-  "references": [{ "path": "./tsconfig.node.json" }]
-}

frontend/tsconfig.node.json

@@ -1,10 +0,0 @@
-{
-  "compilerOptions": {
-    "composite": true,
-    "skipLibCheck": true,
-    "module": "ESNext",
-    "moduleResolution": "bundler",
-    "allowSyntheticDefaultImports": true
-  },
-  "include": ["vite.config.ts"]
-}

frontend/vite.config.ts

@@ -1,22 +0,0 @@
-import { defineConfig } from 'vite'
-import react from '@vitejs/plugin-react'
-import path from 'path'
-
-// https://vitejs.dev/config/
-export default defineConfig({
-  plugins: [react()],
-  resolve: {
-    alias: {
-      '@': path.resolve(__dirname, './src'),
-    },
-  },
-  server: {
-    port: 5173,
-    proxy: {
-      '/api': {
-        target: 'http://localhost:8000',
-        changeOrigin: true,
-      },
-    },
-  },
-})

mariadb/init/01-sidecar.sql

@@ -0,0 +1,25 @@
+-- Bootstraps the `mule_sidecar` database + user used by the Go sidecar
+-- service (per-user heap sharing + folder mutations, stood up in M4).
+--
+-- MariaDB runs every .sql in /docker-entrypoint-initdb.d ONCE, on first
+-- boot of a fresh data volume. Subsequent boots are no-ops.
+--
+-- The sidecar's MariaDB user is intentionally scoped to `mule_sidecar.*`
+-- only — it never has access to PhotoPrism's schema.
+
+CREATE DATABASE IF NOT EXISTS mule_sidecar
+  CHARACTER SET utf8mb4
+  COLLATE utf8mb4_unicode_ci;
+
+-- The password here is substituted at compose build time via envsubst,
+-- but MariaDB's init script doesn't expand vars in .sql files. So we use
+-- a literal placeholder that the user replaces locally — or, simpler,
+-- we let the M4 sidecar bring-up script create the user via SQL with the
+-- env-var password. Keeping a placeholder here makes the schema visible
+-- in source control without leaking creds.
+--
+-- TODO (M4): replace this block with an entrypoint that templates the
+-- password from $SIDECAR_DB_PASSWORD before MariaDB reads the file.
+CREATE USER IF NOT EXISTS 'sidecar'@'%' IDENTIFIED BY 'replace-at-m4-bringup';
+GRANT ALL PRIVILEGES ON mule_sidecar.* TO 'sidecar'@'%';
+FLUSH PRIVILEGES;

mulita.yml

@@ -1,24 +0,0 @@
-# Mulita configuration file
-#
-# Source roots and discard handling are owned by the database — manage them
-# from the UI (left sidebar → "+ Add Source Folder") or via the API. Only
-# operational tuning lives here.
-
-thumbnails:
-  small: 240      # px, longest edge
-  medium: 640
-  large: 1280
-  quality: 85     # JPEG/WebP quality
-  format: webp    # output format for thumbs
-
-scanner:
-  watch: true     # use watchfiles inotify
-  initial_scan_on_start: true
-  batch_size: 100
-  concurrent_workers: 4
-
-performance:
-  max_concurrent_thumbnails: 10
-  cache_ttl: 3600
-  db_pool_size: 20
-  db_pool_recycle: 3600

photovault-app-prompt.md

@@ -1,753 +0,0 @@
-# PhotoVault — Full Application Spec Prompt
-
-> A self-hosted, Docker-deployed photo management application inspired by Lightroom's workflow.
-> Use this document as the complete specification to build the app from scratch.
-
----
-
-## 1. Project Overview
-
-Build **PhotoVault**, a self-hosted photo & video management web application optimized for a single-user homelab deployment. The user mounts one or more host folders containing photos/videos; the app indexes them, generates thumbnails, and provides a fast keyboard-driven interface to browse, organize, tag, and manage the library. The architecture must be forward-compatible with AI photo recognition features (face detection, scene classification, CLIP embeddings) to be added in a later phase.
-
----
-
-## 2. Stack & Deployment
-
-### 2.1 Docker Compose (single `docker-compose.yml`)
-
-```
-services:
-  frontend   — React SPA (Nginx)
-  backend    — Python FastAPI
-  db         — SQLite (file-based, volume-mounted)
-  worker     — Celery + Redis for background thumbnail/indexing tasks
-  redis      — Redis (Celery broker)
-```
-
-All services declared in one `docker-compose.yml`. Use named volumes for:
-- `/data/thumbs` — generated thumbnails (persistent)
-- `/data/db` — SQLite database file
-- `/data/trash` — files moved to trash
-
-Photo source folders are mounted as **read-write** bind mounts via an environment variable:
-
-```yaml
-volumes:
-  - ${PHOTO_DIRS}:/photos:rw
-```
-
-`PHOTO_DIRS` supports multiple paths via a config file (`photovault.yml`) described in §4.
-
-### 2.2 Frontend
-
-- **React 18** + **Vite**
-- **Tailwind CSS v4**
-- **shadcn/ui** component library
-- **TanStack Query** (React Query) for data fetching & cache
-- **TanStack Virtual** for virtualized scrolling (critical for performance with thousands of photos)
-- **Zustand** for global UI state (selection, active photo, heap, filters)
-- **Framer Motion** for transitions
-
-### 2.3 Backend
-
-- **Python 3.12 + FastAPI**
-- **SQLite** via **SQLAlchemy 2.0** (async) + **Alembic** for migrations
-- **Celery + Redis** for background tasks (thumbnail generation, folder scanning, metadata extraction)
-- **pyvips** (libvips) for fast thumbnail generation — preferred over Pillow for speed at scale
-- **rawpy** for RAW format decoding (CR2, CR3, NEF, ARW, RAF, DNG, ORF, RW2, etc.)
-- **pillow-heif** for HEIC/HEIF (iPhone photos)
-- **ffmpeg** (via `ffmpeg-python`) for video thumbnail extraction and metadata
-- **pyexiftool** (wraps ExifTool binary) for deep metadata extraction from all formats
-- **Watchfiles** for inotify-based folder watching (auto-detect new/deleted files)
-
-> **AI-readiness note**: The backend worker architecture is designed to add a `clip_embed` task later (using `open-clip-torch`) that stores 512-dim CLIP embeddings per photo in the DB. Reserve a `embeddings` table with a `photo_id` FK and a `BLOB` column for the vector. No AI code yet — just the schema placeholder.
-
----
-
-## 3. Data Model (SQLite via SQLAlchemy)
-
-```sql
--- Core tables
-
-photos (
-  id            TEXT PRIMARY KEY,   -- UUID
-  filepath      TEXT UNIQUE NOT NULL,
-  filename      TEXT NOT NULL,
-  folder_id     TEXT REFERENCES folders(id),
-  media_type    TEXT NOT NULL,      -- 'photo' | 'video' | 'raw' | 'heic'
-  original_format TEXT,            -- 'CR3', 'NEF', 'HEIC', 'MP4', 'JPEG', etc.
-  width         INTEGER,
-  height        INTEGER,
-  file_size     INTEGER,
-  taken_at      DATETIME,          -- from EXIF DateTimeOriginal, fallback to file mtime
-  taken_at_source TEXT,            -- 'exif' | 'filesystem' | 'manual'
-  added_at      DATETIME DEFAULT CURRENT_TIMESTAMP,
-  updated_at    DATETIME,
-  is_trashed    BOOLEAN DEFAULT 0,
-  trashed_at    DATETIME,
-  thumb_small   TEXT,              -- path to 240px thumb
-  thumb_medium  TEXT,              -- path to 640px thumb
-  thumb_large   TEXT,              -- path to 1280px thumb
-  exif_json     TEXT,              -- full EXIF/XMP blob as JSON
-  user_title    TEXT,              -- user-edited title
-  user_notes    TEXT,
-  rating        INTEGER DEFAULT 0, -- 0-5 stars
-  color_label   TEXT,              -- 'red'|'orange'|'yellow'|'green'|'blue'|'purple'|NULL
-  is_picked     BOOLEAN DEFAULT 0,
-  is_rejected   BOOLEAN DEFAULT 0
-)
-
-folders (
-  id            TEXT PRIMARY KEY,
-  name          TEXT NOT NULL,
-  path          TEXT UNIQUE NOT NULL,
-  parent_id     TEXT REFERENCES folders(id),
-  source_root_id TEXT REFERENCES source_roots(id),
-  photo_count   INTEGER DEFAULT 0,
-  last_scanned  DATETIME
-)
-
-source_roots (
-  id            TEXT PRIMARY KEY,
-  name          TEXT NOT NULL,
-  path          TEXT UNIQUE NOT NULL,
-  is_active     BOOLEAN DEFAULT 1,
-  added_at      DATETIME DEFAULT CURRENT_TIMESTAMP
-)
-
-tags (
-  id            TEXT PRIMARY KEY,
-  name          TEXT UNIQUE NOT NULL,
-  color         TEXT
-)
-
-photo_tags (
-  photo_id      TEXT REFERENCES photos(id) ON DELETE CASCADE,
-  tag_id        TEXT REFERENCES tags(id) ON DELETE CASCADE,
-  PRIMARY KEY (photo_id, tag_id)
-)
-
-heaps (
-  id            TEXT PRIMARY KEY,
-  name          TEXT NOT NULL,
-  created_at    DATETIME DEFAULT CURRENT_TIMESTAMP,
-  updated_at    DATETIME
-)
-
-heap_photos (
-  heap_id       TEXT REFERENCES heaps(id) ON DELETE CASCADE,
-  photo_id      TEXT REFERENCES photos(id) ON DELETE CASCADE,
-  added_at      DATETIME DEFAULT CURRENT_TIMESTAMP,
-  sort_order    INTEGER DEFAULT 0,
-  PRIMARY KEY (heap_id, photo_id)
-)
-
--- AI-readiness placeholder (no implementation yet)
-embeddings (
-  photo_id      TEXT PRIMARY KEY REFERENCES photos(id) ON DELETE CASCADE,
-  model         TEXT,              -- e.g. 'clip-vit-b32'
-  vector        BLOB               -- raw float32 bytes
-)
-```
-
-**Indexes**: Create indexes on `photos.taken_at`, `photos.folder_id`, `photos.is_trashed`, `photos.rating`, `photos.color_label`, `photo_tags.tag_id`.
-
----
-
-## 4. Configuration
-
-App is configured via a `photovault.yml` file mounted into the backend container:
-
-```yaml
-source_roots:
-  - name: "Main Library"
-    path: /photos/main
-  - name: "iPhone Imports"
-    path: /photos/iphone
-
-thumbnails:
-  small: 240      # px, longest edge
-  medium: 640
-  large: 1280
-  quality: 85     # JPEG quality
-  format: webp    # output format for thumbs
-
-scanner:
-  watch: true     # use watchfiles inotify
-  initial_scan_on_start: true
-
-trash:
-  path: /data/trash
-```
-
----
-
-## 5. Backend API (FastAPI)
-
-All routes under `/api/v1/`. Authentication: none (single-user, homelab). Use async SQLAlchemy sessions.
-
-### 5.1 Photos
-
-```
-GET    /photos                   List photos (pagination + filters — see §5.5)
-GET    /photos/{id}              Get single photo with full EXIF + tags
-GET    /photos/{id}/thumb/{size} Serve thumbnail (small|medium|large) — use X-Accel-Redirect for Nginx
-GET    /photos/{id}/original     Serve original file (download)
-PATCH  /photos/{id}             Update: user_title, user_notes, rating, color_label, is_picked, is_rejected, taken_at (manual override)
-DELETE /photos/{id}             Move to trash (sets is_trashed=1, moves file to /data/trash)
-POST   /photos/bulk             Bulk actions: { ids: [], action: 'trash'|'restore'|'delete_permanent'|'move'|'copy'|'add_tag'|'remove_tag'|'set_rating'|'set_color'|'pick'|'reject' }
-POST   /photos/bulk/move        Move files to a target folder_id
-POST   /photos/bulk/copy        Copy files to a target folder_id
-```
-
-### 5.2 Folders
-
-```
-GET    /folders                  Folder tree (nested, with photo_count)
-GET    /folders/{id}/photos      Photos in folder (supports same filters as /photos)
-POST   /folders                  Create folder (creates directory on disk)
-PATCH  /folders/{id}             Rename folder (renames directory on disk)
-DELETE /folders/{id}             Delete folder — requires folder to be empty
-POST   /folders/{id}/scan        Trigger manual re-scan of folder
-```
-
-### 5.3 Heaps
-
-```
-GET    /heaps                    List all heaps
-POST   /heaps                    Create heap { name }
-GET    /heaps/{id}               Get heap with photos
-PATCH  /heaps/{id}               Rename heap
-DELETE /heaps/{id}               Delete heap (does NOT delete photos)
-POST   /heaps/{id}/photos        Add photos { photo_ids: [] }
-DELETE /heaps/{id}/photos        Remove photos { photo_ids: [] }
-POST   /heaps/{id}/convert       Convert heap to folder on disk: { target_path, move: bool }
-```
-
-### 5.4 Tags
-
-```
-GET    /tags                     List all tags with usage counts
-POST   /tags                     Create tag
-PATCH  /tags/{id}                Rename / recolor tag
-DELETE /tags/{id}                Delete tag (removes from all photos)
-GET    /tags/{id}/photos         Photos with this tag
-```
-
-### 5.5 Filters & Search
-
-All list endpoints support these query parameters:
-
-```
-q              Full-text search (filename, user_title, user_notes, EXIF JSON)
-date_from      ISO8601 datetime
-date_to        ISO8601 datetime
-folder_id      Filter by folder (recursive if include_subfolders=true)
-tag_ids        Comma-separated tag IDs (AND logic by default; mode=or for OR)
-media_type     photo|video|raw|heic (comma-separated for multiple)
-rating_min     0-5
-rating_max     0-5
-color_label    red|orange|yellow|green|blue|purple|none
-is_picked      true|false
-is_rejected    true|false
-is_trashed     true|false (default false)
-heap_id        Filter to photos in a specific heap
-sort           taken_at|added_at|filename|file_size|rating (default taken_at)
-order          asc|desc (default desc)
-page           integer (default 1)
-per_page       integer (default 100, max 500)
-```
-
-Full-text search uses SQLite FTS5. Create a virtual FTS table:
-```sql
-CREATE VIRTUAL TABLE photos_fts USING fts5(
-  photo_id UNINDEXED,
-  filename,
-  user_title,
-  user_notes,
-  exif_text  -- denormalized key EXIF fields as plain text (camera make/model, GPS, lens, etc.)
-);
-```
-
-### 5.6 Trash
-
-```
-GET    /trash                    List trashed photos (same filters)
-POST   /trash/restore            Restore { photo_ids: [] } — moves files back to original folder
-DELETE /trash/empty              Permanently delete all trashed photos + files
-DELETE /trash/{id}               Permanently delete single photo + file
-```
-
-### 5.7 Library Stats & Scanning
-
-```
-GET    /library/stats            { total_photos, total_videos, total_size, last_scan }
-POST   /library/scan             Trigger full re-scan (Celery task)
-GET    /library/scan/status      { status, progress, current_folder, queued, done }
-```
-
-### 5.8 Background Tasks (Celery)
-
-- `scan_folder(folder_path)` — Walk directory tree, insert/update photos, detect deletions
-- `generate_thumbs(photo_id)` — Generate small/medium/large WebP thumbnails via pyvips/rawpy/ffmpeg
-- `extract_metadata(photo_id)` — Run ExifTool, parse EXIF/XMP/IPTC, update DB
-- `watch_folders()` — Long-running Watchfiles task, dispatches scan_folder on changes
-- `embed_photo(photo_id)` *(placeholder, no-op)* — Reserved for CLIP embeddings
-
-**Priority queues**: Thumbnail generation for visible photos should be on a `high` queue; full library scans on a `low` queue.
-
----
-
-## 6. Frontend Architecture
-
-### 6.1 Layout
-
-Three-pane layout (similar to Lightroom Library module):
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│  TOP BAR  [Logo] [Search] [Filters bar] [View mode] [Heap]  │
-├──────────┬──────────────────────────────────┬───────────────┤
-│          │                                  │               │
-│  LEFT    │        MAIN TIMELINE             │  RIGHT        │
-│  SIDEBAR │     (continuous scroll,          │  SIDEBAR      │
-│          │      sticky date headers,        │  (metadata    │
-│  Folder  │      virtualized thumbnail       │   panel for   │
-│  tree    │      grid)                       │   selected    │
-│          │                                  │   photo)      │
-│  Heaps   │                                  │               │
-│  list    │                                  │               │
-│          │                                  │               │
-│  Tags    │                                  │               │
-└──────────┴──────────────────────────────────┴───────────────┘
-```
-
-- Left sidebar: resizable, collapsible (shortcut: `Tab`)
-- Right sidebar: collapsible (shortcut: `I`), shows when ≥1 photo selected
-- Main area: full virtualized scroll, single scroll region
-
-### 6.2 Views
-
-| View | Shortcut | Description |
-|------|----------|-------------|
-| Grid (Library) | `G` | Default timeline thumbnail grid |
-| Loupe (Fullscreen) | `E` | Single photo full-viewport view |
-| Compare | `C` | Side-by-side compare of 2 selected photos |
-
-### 6.3 Timeline View (Grid)
-
-- **Continuous vertical scroll** with **sticky date headers** that label each date group (Year / Month / Day — configurable via a "Group by" dropdown: Year, Month, Day, Week, Folder)
-- Thumbnails rendered via **TanStack Virtual** — only DOM nodes in/near viewport are rendered
-- Thumbnail grid is **responsive** — uses CSS grid with `auto-fill` and configurable thumbnail size (slider or `+/-` keys)
-- Thumbnails show: image, hover overlay with filename, EXIF date, optional rating stars
-- **Lazy thumbnail loading**: request `thumb_small` initially; upgrade to `thumb_medium` on hover/selection
-- On initial scan, show a shimmer skeleton for photos without thumbnails yet; poll backend for thumb completion
-
-### 6.4 Keyboard Shortcuts (Lightroom-style)
-
-#### Navigation (Grid mode)
-| Key | Action |
-|-----|--------|
-| `←` `→` `↑` `↓` | Move cursor one photo in direction |
-| `Shift+←/→/↑/↓` | Extend selection |
-| `Cmd/Ctrl+A` | Select all |
-| `Cmd/Ctrl+Shift+A` | Deselect all |
-| `Space` | Quick preview (fullscreen loupe, hold) |
-| `Enter` | Open loupe view |
-| `Esc` | Deselect / close loupe |
-| `Home` / `End` | Jump to first / last photo |
-| `Page Up/Down` | Scroll by screen height |
-
-#### Navigation (Loupe mode)
-| Key | Action |
-|-----|--------|
-| `←` `→` | Previous / next photo |
-| `Esc` | Return to grid |
-| `Z` | Toggle zoom (fit ↔ 100%) |
-| `+` / `-` | Zoom in / out |
-
-#### Flagging & Rating
-| Key | Action |
-|-----|--------|
-| `P` | Pick (flag) |
-| `X` | Reject |
-| `U` | Unflag |
-| `1–5` | Set star rating |
-| `0` | Remove star rating |
-| `6` | Red label |
-| `7` | Orange label |
-| `8` | Yellow label |
-| `9` | Green label |
-
-#### Actions
-| Key | Action |
-|-----|--------|
-| `G` | Go to grid view |
-| `E` | Go to loupe view |
-| `C` | Compare view (2 selected) |
-| `Tab` | Toggle left sidebar |
-| `I` | Toggle right metadata sidebar |
-| `\` | Toggle filter bar |
-| `F` | Toggle fullscreen |
-| `Delete` | Move selected to trash |
-| `Shift+Delete` | Permanently delete (if in trash view) |
-| `Cmd/Ctrl+Z` | Undo last action |
-| `Cmd/Ctrl+Shift+Z` | Redo |
-| `Cmd/Ctrl+C` | Copy selected to clipboard (for move/copy target) |
-| `Cmd/Ctrl+X` | Cut selected (for move) |
-| `Cmd/Ctrl+V` | Paste into current folder |
-| `T` | Add/remove from active heap |
-| `Cmd/Ctrl+F` | Focus search bar |
-| `/` | Focus search bar |
-| `?` | Show keyboard shortcut reference overlay |
-
-All shortcuts must work without modifier unless noted. Shortcuts must be suppressed when focus is inside an input/textarea.
-
-### 6.5 Bulk Selection
-
-- **Click** — select single photo (deselects others)
-- **Shift+Click** — range select from last selected to clicked
-- **Cmd/Ctrl+Click** — toggle individual photo in selection
-- **Cmd/Ctrl+A** — select all visible
-- A **selection bar** appears at the top of the main area when ≥2 photos selected, showing count and bulk action buttons: Rate, Color Label, Tag, Add to Heap, Move, Copy, Trash, Export
-- Bulk actions call `POST /api/v1/photos/bulk`
-
-### 6.6 Metadata Sidebar (Right Panel)
-
-When a photo is selected, the right sidebar shows:
-
-**Section: Preview**
-- Large thumbnail (clicking opens loupe)
-- Filename (editable inline, renames file on disk)
-- User title (editable)
-- User notes (textarea)
-- Rating (5-star widget, keyboard-interactive)
-- Color label (color dot picker)
-- Flags: Picked / Rejected toggles
-
-**Section: Tags**
-- Tag chips with remove button
-- "Add tag" autocomplete input
-- Create new tag inline
-
-**Section: EXIF / Metadata**
-Collapsible groups:
-- *Camera*: Make, Model, Serial, Lens, Firmware
-- *Capture*: Date Taken (editable override), Shutter Speed, Aperture, ISO, Focal Length, EV, Flash, White Balance, Metering Mode
-- *File*: Format, Dimensions, File Size, Color Space, Bit Depth
-- *Location*: GPS lat/lon shown on a small Leaflet.js map tile if available; altitude, country, city (reverse-geocoded via nominatim.openstreetmap.org on demand)
-- *IPTC/XMP*: Copyright, Creator, Description, Keywords
-
-**Section: Histogram** (stretch goal)
-- Live RGB+Luminosity histogram rendered from a downsampled version of the photo
-
-### 6.7 Filter Bar
-
-A collapsible horizontal bar below the top bar (shortcut `\`). Contains:
-
-| Control | Type |
-|---------|------|
-| Date range | Date range picker (from/to) |
-| Media type | Multi-select chips: Photo / Video / RAW / HEIC |
-| Rating | Min/max star slider |
-| Color label | Color dot multi-select |
-| Flags | Picked / Rejected / Unflagged toggle buttons |
-| Tags | Multi-select tag dropdown (AND/OR mode toggle) |
-| Camera make | Dropdown (populated from DB) |
-| Lens | Dropdown (populated from DB) |
-
-Active filters shown as removable chips in the filter bar. "Clear all" button. Filter state persists in URL query params for shareability/bookmarks.
-
-### 6.8 Search
-
-- Magnifier icon in top bar, shortcut `/` or `Cmd+F`
-- Full-text search via FTS5 backend
-- Search covers: filename, user title, user notes, camera make/model, lens, GPS place names, tags
-- Results appear inline in the current view (no separate search results page)
-- Search combined with active filters (additive)
-
-### 6.9 Folder Tree (Left Sidebar)
-
-- Hierarchical tree view of all source roots and their subfolder structure
-- Each folder shows photo count badge
-- Right-click context menu: New Subfolder, Rename, Move Photos Here, Scan Now, Copy Path
-- Drag-and-drop folders to rearrange (moves directory on disk with confirmation)
-- "All Photos" virtual root node at top
-- "Trash" virtual node at bottom with count badge
-
-### 6.10 Heaps Panel (Left Sidebar)
-
-- List of named heaps below folder tree
-- "+ New Heap" button (creates unnamed heap, prompts for name)
-- Each heap shows photo count
-- Click heap → main area shows heap contents in grid
-- Right-click context menu: Rename, Convert to Folder (prompts for target path + move/copy choice), Delete Heap, Clear Heap
-- **Active Heap indicator**: One heap can be set as "active" (bold + icon). Pressing `T` adds/removes the selected photo(s) from the active heap.
-- A persistent "current heap" pill shown in the top bar when a heap is active
-
-### 6.11 Loupe View
-
-- Single photo, full-viewport
-- Original-quality image (served from backend, format-agnostic — backend transcodes RAW/HEIC to JPEG/WebP on the fly for web display)
-- Zoom: fit-to-window ↔ 100% (toggle `Z`), scroll wheel to zoom, drag to pan at 100%+
-- Filmstrip at bottom: horizontally scrollable strip of thumbnails (current context — same folder or heap), keyboard navigable
-- Left panel collapse, right metadata panel still accessible
-- For videos: HTML5 `<video>` player with controls, muted autoplay of preview, unmute toggle
-
-### 6.12 Trash View
-
-- Accessible via "Trash" node in sidebar
-- Same grid layout, same filters, same shortcuts
-- Extra actions in bulk selection bar: Restore, Permanently Delete
-- "Empty Trash" button at top with confirmation dialog showing count + total size
-
-### 6.13 Library Scan Progress
-
-- On first launch or manual scan trigger: a non-blocking progress bar in the top bar
-- Shows: `Scanning… 1,234 / 12,456 photos indexed`
-- Photos appear in the timeline as they are indexed (optimistic streaming via polling `GET /library/scan/status` every 2s)
-
----
-
-## 7. Media Handling
-
-### 7.1 Supported Formats
-
-| Category | Formats |
-|----------|---------|
-| JPEG | `.jpg`, `.jpeg` |
-| PNG | `.png` |
-| TIFF | `.tif`, `.tiff` |
-| WebP | `.webp` |
-| HEIC/HEIF | `.heic`, `.heif` (via pillow-heif) |
-| RAW — Canon | `.cr2`, `.cr3` |
-| RAW — Nikon | `.nef`, `.nrw` |
-| RAW — Sony | `.arw`, `.srf` |
-| RAW — Fuji | `.raf` |
-| RAW — Panasonic | `.rw2` |
-| RAW — Olympus | `.orf` |
-| RAW — Samsung | `.srw` |
-| RAW — Pentax | `.pef` |
-| RAW — Leica | `.rwl`, `.dng` |
-| RAW — DNG (universal) | `.dng` |
-| RAW — Others | via rawpy (libraw) fallback |
-| Video | `.mp4`, `.mov`, `.avi`, `.mkv`, `.mts`, `.m2ts`, `.3gp` |
-| Live Photos | `.heic` + `.mov` pair (detect by matching base filename) |
-
-### 7.2 Thumbnail Generation Pipeline
-
-For each photo during indexing:
-1. Detect format by extension + magic bytes
-2. Decode to in-memory RGB image:
-   - JPEG/PNG/TIFF/WebP → pyvips native
-   - HEIC/HEIF → pillow-heif → pyvips
-   - RAW → rawpy (half-size decode for speed) → numpy → pyvips
-   - Video → ffmpeg extract frame at 10% duration → pyvips
-3. Auto-rotate by EXIF orientation
-4. Generate 3 sizes: 240px, 640px, 1280px (longest edge, maintain AR)
-5. Save as WebP (quality 85) to `/data/thumbs/{photo_id}/{size}.webp`
-6. Update `thumb_small`, `thumb_medium`, `thumb_large` columns in DB
-
-For web display of original RAW/HEIC in loupe view: generate a full-res WebP proxy on demand (cached). Serve via `GET /photos/{id}/proxy`.
-
-### 7.3 Metadata Extraction
-
-Run ExifTool (subprocess) on every file during indexing. Parse output JSON. Store:
-- `taken_at` — prefer `DateTimeOriginal`, fallback: `CreateDate`, `MediaCreateDate`, file mtime
-- GPS coordinates if present
-- All EXIF/IPTC/XMP fields stored as JSON in `exif_json`
-- Denormalize key fields to FTS table for search
-
-For Live Photos: link the `.mov` sidecar to the `.heic` via a `live_photo_video_id` FK on the photos table.
-
----
-
-## 8. File Operations
-
-All file operations that touch disk must:
-1. Validate target path is within a known source_root (prevent path traversal)
-2. Execute atomically where possible (temp file + rename)
-3. Update DB after successful disk operation (never before)
-4. Emit a WebSocket event (or SSE) so the frontend can update optimistically
-5. Be undoable via Undo stack (store reverse operation in memory, max 50 ops)
-
-### Operations
-
-| Operation | Disk action | DB action |
-|-----------|-------------|-----------|
-| Move photos | `shutil.move` | Update `filepath`, `folder_id` |
-| Copy photos | `shutil.copy2` | Insert new photo record |
-| Rename file | `os.rename` | Update `filepath`, `filename` |
-| Rename folder | `os.rename` | Update folder `path` recursively |
-| Create folder | `os.makedirs` | Insert folder record |
-| Trash photo | Move to `/data/trash/{id}/original.{ext}` | Set `is_trashed=1`, `trashed_at` |
-| Restore from trash | Move back to original path (or new path if original gone) | Clear `is_trashed` |
-| Permanent delete | `os.unlink` | Delete photo record (cascade to tags, heaps) |
-| Convert heap to folder | `os.makedirs(target)` + move/copy each photo | Insert folder, update photo folder_id |
-
----
-
-## 9. Performance Requirements
-
-- **Initial page load**: < 2s (LCP)
-- **Timeline scroll** (10,000+ photos): 60 fps — enforced by TanStack Virtual (only ~20-30 DOM nodes rendered at any time)
-- **Thumbnail serve**: < 50ms via Nginx X-Accel-Redirect (backend sets header, Nginx serves file directly)
-- **Search**: < 200ms for FTS5 query on 100k photos
-- **Thumbnail generation**: ≥ 10 photos/sec on typical homelab CPU (pyvips is ~10x faster than Pillow)
-- **Scan throughput**: ≥ 500 files/sec metadata scan (ExifTool batch mode processes files in bulk)
-- **Celery workers**: 4 concurrent workers by default (`CELERYD_CONCURRENCY=4` env var)
-- Images not yet thumbnailed show a shimmer skeleton; thumbnails stream into view as they complete
-
----
-
-## 10. UI Design System
-
-### 10.1 Aesthetic
-
-Dark-first application (photography tools are dark-themed to preserve color perception). Light mode available via toggle.
-
-- **Dark mode primary surface**: Near-black warm dark `#111110`, not cold gray
-- **Accent**: Desaturated teal — does not compete with photo colors
-- **Typography**: `Geist` (body, UI chrome) + `Geist Mono` (metadata values, EXIF numbers)
-- Dense UI — this is a power tool, not a consumer app. Compact spacing.
-- Inspired by: Lightroom Classic, Linear, Darkroom (iOS)
-
-### 10.2 Key UI Components (shadcn/ui)
-
-Use these shadcn/ui primitives: `Button`, `ContextMenu`, `Dialog`, `DropdownMenu`, `Input`, `Label`, `Popover`, `ScrollArea`, `Separator`, `Sheet` (for mobile sidebar), `Skeleton`, `Slider`, `Switch`, `Tabs`, `Textarea`, `Toast`, `Tooltip`
-
-Build custom components:
-- `<PhotoThumbnail>` — thumbnail with selection state, pick/reject badges, rating overlay on hover
-- `<TimelineGroup>` — sticky date header + grid of thumbnails
-- `<VirtualTimeline>` — TanStack Virtual wrapper over TimelineGroups
-- `<FilmStrip>` — horizontal scrollable strip for loupe view
-- `<StarRating>` — interactive 0-5 stars
-- `<ColorLabel>` — 7-state color dot picker
-- `<MetadataRow>` — label + value pair with edit-in-place for editable fields
-- `<FolderTreeNode>` — recursive folder tree item with context menu
-- `<HeapItem>` — heap list item with active indicator
-- `<FilterChip>` — removable active filter chip
-- `<ProgressBar>` — scan progress in top bar
-- `<ShortcutReference>` — `?` overlay showing all shortcuts in a modal
-
-### 10.3 Color Scheme Variables
-
-```css
-/* Dark mode (default for photo apps) */
---color-bg:           #111110;
---color-surface:      #161615;
---color-surface-2:    #1c1c1a;
---color-surface-offset: #222220;
---color-border:       rgba(255,255,255,0.08);
---color-text:         #e8e6e0;
---color-text-muted:   #878580;
---color-text-faint:   #4a4845;
---color-primary:      #4f98a3;  /* desaturated teal */
---color-pick:         #4f9e5c;  /* green for picked */
---color-reject:       #c25a5a;  /* red for rejected */
---color-star:         #d4a340;  /* amber for stars */
-```
-
----
-
-## 11. Error States & Edge Cases
-
-- **File not found on disk** (moved externally): Show "missing file" badge on thumbnail. Offer "Locate File" action.
-- **Corrupt/unreadable file**: Log error, show broken-image placeholder, never crash the scan worker.
-- **Duplicate detection**: On scan, if a file with the same SHA-256 hash already exists in DB, mark as `is_duplicate=true` — do not create a second record. Show duplicate indicator in thumbnail.
-- **Scan in progress + user navigates**: Show partial results immediately as photos are indexed.
-- **Disk full**: Catch `OSError` on thumbnail write, log, continue scan.
-- **RAW decode failure**: Fall back to extracting the embedded JPEG preview from the RAW file (ExifTool can extract it).
-
----
-
-## 12. Stretch Goals (Phase 2 — Not in Initial Build)
-
-These must not be built now but the architecture must not block them:
-
-1. **AI Scene Classification** — CLIP embeddings per photo, semantic search ("find photos with mountains")
-2. **Face Detection & Clustering** — face_recognition lib or InsightFace, cluster by identity
-3. **Smart Albums** — saved filter presets that auto-populate (e.g., "5-star Canon shots from 2024")
-4. **Duplicate Finder** — perceptual hash (pHash) across library
-5. **Export Presets** — resize + watermark + format conversion on export
-6. **Multi-user** — add FastAPI auth (JWT), per-user libraries
-7. **Mobile PWA** — service worker, offline thumbnail caching
-
----
-
-## 13. Docker Compose File Structure
-
-```
-photovault/
-├── docker-compose.yml
-├── photovault.yml               ← user config
-├── .env                         ← PHOTO_DIRS, REDIS_URL, etc.
-├── frontend/
-│   ├── Dockerfile
-│   ├── package.json
-│   ├── vite.config.ts
-│   └── src/
-│       ├── main.tsx
-│       ├── App.tsx
-│       ├── store/               ← Zustand stores
-│       ├── components/
-│       │   ├── layout/
-│       │   ├── timeline/
-│       │   ├── loupe/
-│       │   ├── sidebar/
-│       │   ├── metadata/
-│       │   └── shared/
-│       ├── hooks/
-│       ├── api/                 ← TanStack Query hooks + axios client
-│       └── lib/
-│           └── shortcuts.ts     ← global keyboard shortcut registry
-└── backend/
-    ├── Dockerfile
-    ├── requirements.txt
-    ├── alembic/
-    ├── app/
-    │   ├── main.py              ← FastAPI app
-    │   ├── config.py            ← pydantic settings
-    │   ├── database.py          ← SQLAlchemy async engine
-    │   ├── models/              ← SQLAlchemy ORM models
-    │   ├── schemas/             ← Pydantic request/response schemas
-    │   ├── routers/             ← FastAPI routers per domain
-    │   │   ├── photos.py
-    │   │   ├── folders.py
-    │   │   ├── heaps.py
-    │   │   ├── tags.py
-    │   │   ├── trash.py
-    │   │   └── library.py
-    │   ├── services/            ← Business logic
-    │   │   ├── scanner.py
-    │   │   ├── thumbnailer.py
-    │   │   ├── metadata.py
-    │   │   └── file_ops.py
-    │   └── tasks/               ← Celery tasks
-    │       ├── celery.py
-    │       ├── scan.py
-    │       └── thumbs.py
-    └── nginx.conf               ← X-Accel-Redirect for thumb serving
-```
-
----
-
-## 14. Implementation Priorities
-
-Build in this order to get a working MVP as fast as possible:
-
-1. **Docker Compose skeleton** — all services up, health checks passing
-2. **DB schema + Alembic migration**
-3. **Folder scanner + thumbnail generator** (Celery tasks) — the core engine
-4. **`GET /photos` + `GET /photos/{id}/thumb/{size}`** — minimum API to display photos
-5. **Frontend: VirtualTimeline + PhotoThumbnail** — display the library
-6. **Frontend: keyboard navigation + selection**
-7. **Frontend: left sidebar (folder tree + heaps)**
-8. **Frontend: right sidebar (metadata panel) + EXIF display**
-9. **Filter bar + search**
-10. **Loupe view with filmstrip**
-11. **File operations: move, copy, rename, trash, restore**
-12. **Metadata editing: title, notes, rating, color label, tags**
-13. **Heaps: create, populate, convert to folder**
-14. **Trash view + permanent delete**
-15. **Polish: undo/redo, bulk actions, duplicate detection, live scan progress**

sidecar/.dockerignore

@@ -0,0 +1,13 @@
+# Files that have no business shipping into the build context.
+# Anything not listed here gets COPY'd into /src so keep this tight.
+
+# Local host-mode build output — re-built inside the image.
+mule-sidecar
+
+# Runtime state from the M3 Node prototype.
+data/
+
+# Docs + git noise.
+README.md
+.git/
+.gitignore

sidecar/Dockerfile

@@ -0,0 +1,28 @@
+# syntax=docker/dockerfile:1.6
+#
+# mule-sidecar — Go service for endpoints PhotoPrism does not expose.
+# Multi-stage build: a Go toolchain image compiles a static binary,
+# then we copy it onto a distroless base so the runtime image is ~12 MB
+# with no shell, package manager, or libc.
+
+FROM docker.io/library/golang:1.25-alpine AS build
+WORKDIR /src
+
+# Cache deps separately from source so a one-line code change doesn't
+# re-download the whole module graph.
+COPY go.mod go.sum ./
+RUN go mod download
+
+COPY . ./
+# CGO disabled → fully static binary that runs on the distroless base
+# (no libc resolution at startup). -trimpath strips local paths from
+# debug info; -s -w drop the symbol table to keep the binary small.
+RUN CGO_ENABLED=0 GOOS=linux go build \
+    -trimpath \
+    -ldflags='-s -w' \
+    -o /out/mule-sidecar .
+
+FROM gcr.io/distroless/static-debian12:latest
+COPY --from=build /out/mule-sidecar /mule-sidecar
+EXPOSE 8000
+ENTRYPOINT ["/mule-sidecar"]

sidecar/README.md

@@ -0,0 +1,116 @@
+# mule-sidecar
+
+Go + Gin + GORM service for the endpoints PhotoPrism's REST API does not
+expose. Same wire contract as the M3 Node prototype it replaces; the
+SvelteKit client at [web/](../web/) talks to it transparently through
+Vite's `/api/sidecar/*` proxy.
+
+## What it owns
+
+| Method | Path                                    | Purpose                                       |
+| ------ | --------------------------------------- | --------------------------------------------- |
+| GET    | `/api/sidecar/healthz`                  | Unauthenticated liveness probe.               |
+| GET    | `/api/sidecar/photos/marks`             | Every per-photo `{rating, color}` mark.       |
+| GET    | `/api/sidecar/photos/:uid/marks`        | One photo's mark (or `{}` if none).           |
+| PUT    | `/api/sidecar/photos/:uid/marks`        | Patch one photo's mark.                       |
+| POST   | `/api/sidecar/photos/marks/bulk`        | Stamp the same mark onto many photos.         |
+| POST   | `/api/sidecar/files/:uid/rename`        | Rename the primary file on disk + reindex.    |
+| POST   | `/api/sidecar/folders`                  | Create a folder under `${ORIGINALS_ROOT}`.    |
+| POST   | `/api/sidecar/folders/:rel/rename`      | Rename a folder (rel path URL-encoded).       |
+| DELETE | `/api/sidecar/folders/:rel`             | Delete an **empty** folder.                   |
+| POST   | `/api/sidecar/albums/:uid/convert`      | Move/copy every photo in a heap into folder X. |
+| GET    | `/api/sidecar/duplicates/scan`          | Walk originals, return same-hash groups.      |
+| POST   | `/api/sidecar/duplicates/archive`       | Move duplicate paths into `.duplicates/<ts>/`. |
+
+Auth: every endpoint except `healthz` requires the caller's
+`X-Auth-Token` header. The sidecar holds no service credentials — it
+proxies the token straight back to PhotoPrism's `/api/v1/photos?count=1`
+to confirm the session is live before doing anything destructive.
+
+Marks persist to **MariaDB** (`mule_sidecar.marks`); everything else
+operates on the filesystem under `${ORIGINALS_ROOT}` and triggers a
+PhotoPrism reindex of the affected parent in the background.
+
+## Run
+
+The sidecar is a `sidecar` service in the PhotoPrism compose stack.
+Bringing the whole stack up brings it up too:
+
+```sh
+podman-compose --env-file .env \
+  -f docker-compose.yml \
+  -f docker-compose.podman.yml \
+  up -d
+```
+
+This builds [Dockerfile](Dockerfile) (multi-stage `golang:1.25-alpine` →
+`gcr.io/distroless/static`, ~12 MB final image), starts the container,
+and binds `127.0.0.1:8000` to the service. The SvelteKit dev server
+proxies `/api/sidecar/*` to that port transparently.
+
+### Dev-iteration loop (host build)
+
+For tight iteration without rebuilding the image on every change you
+can run it as a host process — Go is already on the dev machine:
+
+```sh
+cd sidecar
+go build -o mule-sidecar .
+
+ORIGINALS_ROOT=/path/to/photoprism/originals \
+PHOTOPRISM_BASE_URL=http://localhost:2342 \
+SIDECAR_PORT=8000 \
+./mule-sidecar
+```
+
+The host build connects to `mariadb` via the loopback port the compose
+file publishes; stop `pp-sidecar` first so they don't fight for 8000.
+
+## Env
+
+| Var                   | Default                           | Notes                                                                                          |
+| --------------------- | --------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `ORIGINALS_ROOT`      | `/photoprism/originals`           | Absolute path; must match PhotoPrism's mount.                                                  |
+| `PHOTOPRISM_BASE_URL` | `http://localhost:2342`           | Where to reach PhotoPrism for session validation + reindex calls.                              |
+| `SIDECAR_PORT`        | `8000`                            | Loopback-only; reverse-proxy fronts it in production.                                          |
+| `SIDECAR_DSN`         | _(built from the vars below)_     | Set this to override the assembled MySQL DSN entirely.                                         |
+| `SIDECAR_DB_HOST`     | `127.0.0.1`                       | Host of the MariaDB the compose stack publishes on `127.0.0.1:3306`.                           |
+| `SIDECAR_DB_PORT`     | `3306`                            |                                                                                                |
+| `SIDECAR_DB_USER`     | `sidecar`                         | Provisioned by [`mariadb/init/01-sidecar.sql`](../mariadb/init/01-sidecar.sql) on first boot.  |
+| `SIDECAR_DB_PASSWORD` | `replace-at-m4-bringup`           | Literal placeholder — **rotate before any non-local deployment**.                              |
+| `SIDECAR_DB_NAME`     | `mule_sidecar`                    |                                                                                                |
+
+## Schema
+
+GORM `AutoMigrate` creates the only table the service owns:
+
+```sql
+CREATE TABLE marks (
+  photo_uid  VARCHAR(64) PRIMARY KEY,
+  rating     BIGINT NULL,
+  color      VARCHAR(16) NULL,
+  updated_at DATETIME(3)
+);
+```
+
+The M3 Node prototype kept the same data in `sidecar/data/marks.json`.
+There is no migration path — the prototype's marks file was dev-only
+state. Heap-sharing tables (M4) will land in subsequent migrations.
+
+## Layout
+
+```text
+sidecar/
+├── Dockerfile            multi-stage golang:1.25 → distroless/static
+├── main.go               entrypoint, route wiring, graceful shutdown
+├── config.go             env-driven Config
+├── db.go                 GORM open + Mark model + AutoMigrate
+├── auth.go               requireSession middleware + ctxToken
+├── fs.go                 path safety, walk, sha1
+├── pp.go                 PhotoPrism HTTP client (validateSession, reindex)
+├── handlers_rename.go
+├── handlers_folders.go
+├── handlers_marks.go
+├── handlers_heap.go
+└── handlers_dups.go
+```

sidecar/auth.go

@@ -0,0 +1,44 @@
+package main
+
+import (
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+)
+
+// requireSession is the standard auth shim every mutating handler wears.
+// We don't store a shared service credential — the caller's X-Auth-Token
+// is the only authority, and we probe PhotoPrism with it before doing any
+// destructive work. The handler reads the validated token off the context
+// via ctxToken so it can keep forwarding it to PhotoPrism for the actual
+// operation.
+func requireSession(pp *ppClient) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		token := c.GetHeader("X-Auth-Token")
+		if token == "" {
+			c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "no token"})
+			return
+		}
+		if !pp.validateSession(c.Request.Context(), token) {
+			c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "invalid session"})
+			return
+		}
+		c.Set("token", token)
+		c.Next()
+	}
+}
+
+// ctxToken returns the validated X-Auth-Token a previous requireSession
+// middleware stored on the request. Handlers MUST run behind that
+// middleware; otherwise this returns the empty string.
+func ctxToken(c *gin.Context) string {
+	v, ok := c.Get("token")
+	if !ok {
+		return ""
+	}
+	s, ok := v.(string)
+	if !ok {
+		return ""
+	}
+	return s
+}

sidecar/config.go

@@ -0,0 +1,92 @@
+package main
+
+import (
+	"os"
+	"path/filepath"
+	"strconv"
+)
+
+// Config aggregates every runtime knob the sidecar reads from the
+// environment. Held in one struct so the rest of the package can take a
+// pointer instead of poking os.Getenv at use-sites.
+type Config struct {
+	OriginalsRoot     string // absolute path to PhotoPrism's originals dir
+	PhotoprismBaseURL string // e.g. http://localhost:2342
+	ListenAddr        string // bind interface — 127.0.0.1 for host mode, 0.0.0.0 in containers
+	Port              int    // HTTP listen port
+	DSN               string // GORM/MySQL connection string for mule_sidecar
+	// PpDSN is a second DB connection string pointed at PhotoPrism's own
+	// schema (`photoprism.*`). Sidecar code that needs to mutate
+	// PhotoPrism-managed rows (e.g. auth_users.base_path) opens its own
+	// connection with these creds rather than asking for grants on the
+	// mule_sidecar user. Empty if PP_DB_PASSWORD isn't provided, in
+	// which case PP-touching features (user-basepath reconciler) stay
+	// dormant.
+	PpDSN string
+	// UserBasepaths is the parsed `USER_BASEPATHS` env. Maps PhotoPrism
+	// usernames to originals-relative base paths so OIDC-provisioned
+	// users land with the right library scope without any admin
+	// touching `photoprism users mod`.
+	UserBasepaths map[string]string
+}
+
+func loadConfig() (*Config, error) {
+	root := envOr("ORIGINALS_ROOT", "/photoprism/originals")
+	abs, err := filepath.Abs(root)
+	if err != nil {
+		return nil, err
+	}
+
+	portStr := envOr("SIDECAR_PORT", "8000")
+	port, err := strconv.Atoi(portStr)
+	if err != nil {
+		return nil, err
+	}
+
+	dsn := os.Getenv("SIDECAR_DSN")
+	if dsn == "" {
+		// Default matches the user that mariadb/init/01-sidecar.sql provisions
+		// on first boot. The literal placeholder password is intentional: the
+		// SQL ships with it and an env-templating step is left for whoever
+		// runs this in a non-local context.
+		user := envOr("SIDECAR_DB_USER", "sidecar")
+		pass := envOr("SIDECAR_DB_PASSWORD", "replace-at-m4-bringup")
+		host := envOr("SIDECAR_DB_HOST", "127.0.0.1")
+		dbPort := envOr("SIDECAR_DB_PORT", "3306")
+		name := envOr("SIDECAR_DB_NAME", "mule_sidecar")
+		dsn = user + ":" + pass + "@tcp(" + host + ":" + dbPort + ")/" + name +
+			"?charset=utf8mb4&parseTime=true&loc=Local"
+	}
+
+	// PhotoPrism schema connection — only used by the user-basepath
+	// reconciler. Stays empty if PP_DB_PASSWORD isn't set, and callers
+	// gate behaviour on that. We use PhotoPrism's own DB user rather
+	// than the sidecar's because `mule_sidecar` has no grants on
+	// `photoprism.*` (see mariadb/init/01-sidecar.sql).
+	ppDSN := ""
+	if ppPass := os.Getenv("PP_DB_PASSWORD"); ppPass != "" {
+		ppUser := envOr("PP_DB_USER", "photoprism")
+		ppHost := envOr("PP_DB_HOST", envOr("SIDECAR_DB_HOST", "mariadb"))
+		ppPort := envOr("PP_DB_PORT", envOr("SIDECAR_DB_PORT", "3306"))
+		ppName := envOr("PP_DB_NAME", "photoprism")
+		ppDSN = ppUser + ":" + ppPass + "@tcp(" + ppHost + ":" + ppPort + ")/" + ppName +
+			"?charset=utf8mb4&parseTime=true&loc=Local"
+	}
+
+	return &Config{
+		OriginalsRoot:     abs,
+		PhotoprismBaseURL: envOr("PHOTOPRISM_BASE_URL", "http://localhost:2342"),
+		ListenAddr:        envOr("SIDECAR_LISTEN_ADDR", "127.0.0.1"),
+		Port:              port,
+		DSN:               dsn,
+		PpDSN:             ppDSN,
+		UserBasepaths:     parseUserBasepaths(os.Getenv("USER_BASEPATHS")),
+	}, nil
+}
+
+func envOr(key, fallback string) string {
+	if v := os.Getenv(key); v != "" {
+		return v
+	}
+	return fallback
+}

sidecar/db.go

@@ -0,0 +1,63 @@
+package main
+
+import (
+	"time"
+
+	"gorm.io/driver/mysql"
+	"gorm.io/gorm"
+	"gorm.io/gorm/logger"
+)
+
+// Mark mirrors the per-photo extras the web client stores via the marks
+// endpoints — rating + four-colour label. PhotoUID is the row key; both
+// payload fields are nullable so the sparse "no rating / no colour" state
+// round-trips cleanly. The Node prototype kept this in a JSON file; we
+// migrate to MariaDB here so the M4 sharing work has a real table to
+// extend.
+type Mark struct {
+	PhotoUID  string    `gorm:"primaryKey;size:64;column:photo_uid" json:"-"`
+	Rating    *int      `gorm:"column:rating" json:"rating,omitempty"`
+	Color     *string   `gorm:"size:16;column:color" json:"color,omitempty"`
+	UpdatedAt time.Time `gorm:"column:updated_at" json:"updatedAt"`
+}
+
+// TableName pins the GORM-pluralised default to a name that matches the
+// other tables the M4 plan calls out (`marks`, `heap_shares`, …) so
+// nothing surprising lands in the schema.
+func (Mark) TableName() string { return "marks" }
+
+// asJSON returns the wire shape clients expect — same flat object the
+// Node prototype emitted. An empty Mark (rating=nil, color=nil) renders
+// as `{}` which the client treats as "no mark on this photo".
+func (m *Mark) asJSON() map[string]any {
+	out := map[string]any{}
+	if m == nil {
+		return out
+	}
+	if m.Rating != nil {
+		out["rating"] = *m.Rating
+	}
+	if m.Color != nil && *m.Color != "" {
+		out["color"] = *m.Color
+	}
+	if !m.UpdatedAt.IsZero() {
+		// ISO-8601 with millisecond precision, UTC — matches the Node
+		// prototype's `new Date().toISOString()` so clients written against
+		// the old endpoint stay happy.
+		out["updatedAt"] = m.UpdatedAt.UTC().Format("2006-01-02T15:04:05.000Z")
+	}
+	return out
+}
+
+func openDB(dsn string) (*gorm.DB, error) {
+	db, err := gorm.Open(mysql.Open(dsn), &gorm.Config{
+		Logger: logger.Default.LogMode(logger.Warn),
+	})
+	if err != nil {
+		return nil, err
+	}
+	if err := db.AutoMigrate(&Mark{}); err != nil {
+		return nil, err
+	}
+	return db, nil
+}

sidecar/fs.go

@@ -0,0 +1,213 @@
+package main
+
+import (
+	"crypto/sha1"
+	"encoding/hex"
+	"errors"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+)
+
+// sanitizeFilename trims a user-supplied filename and rejects anything
+// dangerous: path separators, leading dots, NUL bytes, the `.`/`..`
+// pseudo-names, anything absurdly long. PhotoPrism's indexer is happy
+// with most filename shapes; we lock down the ones a malicious or
+// careless caller might use to escape the folder.
+func sanitizeFilename(name string) (string, bool) {
+	s := strings.TrimSpace(name)
+	if s == "" || len(s) > 240 {
+		return "", false
+	}
+	if strings.HasPrefix(s, ".") {
+		return "", false
+	}
+	if s == "." || s == ".." {
+		return "", false
+	}
+	if strings.ContainsAny(s, "/\\\x00") {
+		return "", false
+	}
+	return s, true
+}
+
+// resolveUnderRoot takes a user-supplied relative path and returns its
+// absolute form, but only when the resolved location lives under the
+// configured originals root. Symlink escapes are caught by resolving the
+// parent through filepath.EvalSymlinks first.
+//
+// `mustExist=false` is for the *target* of a rename/create where the
+// terminal path isn't on disk yet; the parent still has to exist and
+// still has to be inside the root.
+func resolveUnderRoot(root, rel string, mustExist bool) (string, error) {
+	if rel == "" {
+		return "", errors.New("empty path")
+	}
+	clean := strings.TrimLeft(rel, "/")
+	if clean == "" || clean == "." {
+		return "", errors.New("empty path")
+	}
+	for _, seg := range strings.Split(clean, "/") {
+		if seg == "" || seg == ".." {
+			return "", errors.New("path traversal")
+		}
+	}
+	abs := filepath.Join(root, clean)
+	parent := filepath.Dir(abs)
+
+	parentReal, err := filepath.EvalSymlinks(parent)
+	if err != nil {
+		return "", err
+	}
+	if !sameOrUnder(parentReal, root) {
+		return "", errors.New("parent escapes originals root")
+	}
+	if mustExist {
+		if _, err := os.Stat(abs); err != nil {
+			return "", err
+		}
+	}
+	return abs, nil
+}
+
+// ensureWithinOriginals checks that an absolute path's parent resolves to
+// somewhere inside the root after symlink evaluation. Used for the
+// already-resolved-on-disk paths returned by PhotoPrism's Files[].
+func ensureWithinOriginals(root, absPath string) bool {
+	real, err := filepath.EvalSymlinks(filepath.Dir(absPath))
+	if err != nil {
+		return false
+	}
+	return sameOrUnder(real, root)
+}
+
+func sameOrUnder(p, root string) bool {
+	if p == root {
+		return true
+	}
+	return strings.HasPrefix(p, root+string(os.PathSeparator))
+}
+
+// uniqueName resolves "destDir/basename" against collisions by appending
+// `-1`, `-2`, … to the stem. Caps at 1000 attempts so a runaway loop
+// can't pin the goroutine forever.
+func uniqueName(destDir, basename string) (abs, name string, ok bool) {
+	ext := filepath.Ext(basename)
+	stem := strings.TrimSuffix(basename, ext)
+	for i := 0; i < 1000; i++ {
+		candidate := basename
+		if i > 0 {
+			candidate = stem + "-" + itoa(i) + ext
+		}
+		p := filepath.Join(destDir, candidate)
+		if _, err := os.Stat(p); errors.Is(err, os.ErrNotExist) {
+			return p, candidate, true
+		}
+	}
+	return "", "", false
+}
+
+// itoa is the tiny stdlib-free formatter we use inside hot loops.
+func itoa(n int) string {
+	if n == 0 {
+		return "0"
+	}
+	neg := n < 0
+	if neg {
+		n = -n
+	}
+	var buf [20]byte
+	i := len(buf)
+	for n > 0 {
+		i--
+		buf[i] = byte('0' + n%10)
+		n /= 10
+	}
+	if neg {
+		i--
+		buf[i] = '-'
+	}
+	return string(buf[i:])
+}
+
+// fileEntry is the per-file row walkFiles emits. relPath stays root-
+// relative so it can land in API responses unchanged.
+type fileEntry struct {
+	RelPath string
+	AbsPath string
+	Size    int64
+}
+
+// supportedExts mirrors the Node prototype's whitelist. PhotoPrism
+// itself walks the same set; we keep the list in lock-step so callers
+// don't see "duplicate" warnings about files PhotoPrism would ignore.
+var supportedExts = map[string]struct{}{
+	".jpg": {}, ".jpeg": {}, ".png": {}, ".heic": {}, ".heif": {},
+	".tiff": {}, ".tif": {}, ".gif": {}, ".bmp": {}, ".webp": {}, ".avif": {},
+	".mov": {}, ".mp4": {}, ".m4v": {}, ".avi": {}, ".mkv": {}, ".webm": {},
+	".dng": {}, ".cr2": {}, ".cr3": {}, ".nef": {}, ".arw": {},
+	".orf": {}, ".rw2": {}, ".raw": {},
+}
+
+// walkFiles enumerates every supported media file under root, skipping
+// dotfiles/dotdirs (matches PhotoPrism's indexer and our own quarantine
+// folder). Errors on individual entries are swallowed so a single
+// permission-denied dir doesn't abort the whole scan.
+func walkFiles(root string) ([]fileEntry, error) {
+	var out []fileEntry
+	err := filepath.WalkDir(root, func(p string, d os.DirEntry, err error) error {
+		if err != nil {
+			// Permission errors etc. — skip the offending subtree but
+			// keep walking. The dup-scan endpoint is best-effort.
+			if d != nil && d.IsDir() {
+				return filepath.SkipDir
+			}
+			return nil
+		}
+		name := d.Name()
+		if p != root && strings.HasPrefix(name, ".") {
+			if d.IsDir() {
+				return filepath.SkipDir
+			}
+			return nil
+		}
+		if d.IsDir() {
+			return nil
+		}
+		ext := strings.ToLower(filepath.Ext(name))
+		if _, ok := supportedExts[ext]; !ok {
+			return nil
+		}
+		info, err := d.Info()
+		if err != nil {
+			return nil
+		}
+		rel, err := filepath.Rel(root, p)
+		if err != nil {
+			return nil
+		}
+		out = append(out, fileEntry{
+			RelPath: rel,
+			AbsPath: p,
+			Size:    info.Size(),
+		})
+		return nil
+	})
+	return out, err
+}
+
+// sha1File streams the file through a SHA1 hasher so a 4GB ProRes clip
+// doesn't blow the process's RAM. Returns the hex digest.
+func sha1File(absPath string) (string, error) {
+	f, err := os.Open(absPath)
+	if err != nil {
+		return "", err
+	}
+	defer f.Close()
+	h := sha1.New()
+	if _, err := io.Copy(h, f); err != nil {
+		return "", err
+	}
+	return hex.EncodeToString(h.Sum(nil)), nil
+}

sidecar/go.mod

@@ -0,0 +1,45 @@
+module mule-sidecar
+
+go 1.25.0
+
+require (
+	github.com/gin-gonic/gin v1.12.0
+	gorm.io/driver/mysql v1.6.0
+	gorm.io/gorm v1.31.1
+)
+
+require (
+	filippo.io/edwards25519 v1.1.0 // indirect
+	github.com/bytedance/gopkg v0.1.3 // indirect
+	github.com/bytedance/sonic v1.15.0 // indirect
+	github.com/bytedance/sonic/loader v0.5.0 // indirect
+	github.com/cloudwego/base64x v0.1.6 // indirect
+	github.com/gabriel-vasile/mimetype v1.4.12 // indirect
+	github.com/gin-contrib/sse v1.1.0 // indirect
+	github.com/go-playground/locales v0.14.1 // indirect
+	github.com/go-playground/universal-translator v0.18.1 // indirect
+	github.com/go-playground/validator/v10 v10.30.1 // indirect
+	github.com/go-sql-driver/mysql v1.8.1 // indirect
+	github.com/goccy/go-json v0.10.5 // indirect
+	github.com/goccy/go-yaml v1.19.2 // indirect
+	github.com/jinzhu/inflection v1.0.0 // indirect
+	github.com/jinzhu/now v1.1.5 // indirect
+	github.com/json-iterator/go v1.1.12 // indirect
+	github.com/klauspost/cpuid/v2 v2.3.0 // indirect
+	github.com/leodido/go-urn v1.4.0 // indirect
+	github.com/mattn/go-isatty v0.0.20 // indirect
+	github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
+	github.com/modern-go/reflect2 v1.0.2 // indirect
+	github.com/pelletier/go-toml/v2 v2.2.4 // indirect
+	github.com/quic-go/qpack v0.6.0 // indirect
+	github.com/quic-go/quic-go v0.59.0 // indirect
+	github.com/twitchyliquid64/golang-asm v0.15.1 // indirect
+	github.com/ugorji/go/codec v1.3.1 // indirect
+	go.mongodb.org/mongo-driver/v2 v2.5.0 // indirect
+	golang.org/x/arch v0.22.0 // indirect
+	golang.org/x/crypto v0.48.0 // indirect
+	golang.org/x/net v0.51.0 // indirect
+	golang.org/x/sys v0.41.0 // indirect
+	golang.org/x/text v0.34.0 // indirect
+	google.golang.org/protobuf v1.36.10 // indirect
+)

sidecar/go.sum

@@ -0,0 +1,101 @@
+filippo.io/edwards25519 v1.1.0 h1:FNf4tywRC1HmFuKW5xopWpigGjJKiJSV0Cqo0cJWDaA=
+filippo.io/edwards25519 v1.1.0/go.mod h1:BxyFTGdWcka3PhytdK4V28tE5sGfRvvvRV7EaN4VDT4=
+github.com/bytedance/gopkg v0.1.3 h1:TPBSwH8RsouGCBcMBktLt1AymVo2TVsBVCY4b6TnZ/M=
+github.com/bytedance/gopkg v0.1.3/go.mod h1:576VvJ+eJgyCzdjS+c4+77QF3p7ubbtiKARP3TxducM=
+github.com/bytedance/sonic v1.15.0 h1:/PXeWFaR5ElNcVE84U0dOHjiMHQOwNIx3K4ymzh/uSE=
+github.com/bytedance/sonic v1.15.0/go.mod h1:tFkWrPz0/CUCLEF4ri4UkHekCIcdnkqXw9VduqpJh0k=
+github.com/bytedance/sonic/loader v0.5.0 h1:gXH3KVnatgY7loH5/TkeVyXPfESoqSBSBEiDd5VjlgE=
+github.com/bytedance/sonic/loader v0.5.0/go.mod h1:AR4NYCk5DdzZizZ5djGqQ92eEhCCcdf5x77udYiSJRo=
+github.com/cloudwego/base64x v0.1.6 h1:t11wG9AECkCDk5fMSoxmufanudBtJ+/HemLstXDLI2M=
+github.com/cloudwego/base64x v0.1.6/go.mod h1:OFcloc187FXDaYHvrNIjxSe8ncn0OOM8gEHfghB2IPU=
+github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/gabriel-vasile/mimetype v1.4.12 h1:e9hWvmLYvtp846tLHam2o++qitpguFiYCKbn0w9jyqw=
+github.com/gabriel-vasile/mimetype v1.4.12/go.mod h1:d+9Oxyo1wTzWdyVUPMmXFvp4F9tea18J8ufA774AB3s=
+github.com/gin-contrib/sse v1.1.0 h1:n0w2GMuUpWDVp7qSpvze6fAu9iRxJY4Hmj6AmBOU05w=
+github.com/gin-contrib/sse v1.1.0/go.mod h1:hxRZ5gVpWMT7Z0B0gSNYqqsSCNIJMjzvm6fqCz9vjwM=
+github.com/gin-gonic/gin v1.12.0 h1:b3YAbrZtnf8N//yjKeU2+MQsh2mY5htkZidOM7O0wG8=
+github.com/gin-gonic/gin v1.12.0/go.mod h1:VxccKfsSllpKshkBWgVgRniFFAzFb9csfngsqANjnLc=
+github.com/go-playground/assert/v2 v2.2.0 h1:JvknZsQTYeFEAhQwI4qEt9cyV5ONwRHC+lYKSsYSR8s=
+github.com/go-playground/assert/v2 v2.2.0/go.mod h1:VDjEfimB/XKnb+ZQfWdccd7VUvScMdVu0Titje2rxJ4=
+github.com/go-playground/locales v0.14.1 h1:EWaQ/wswjilfKLTECiXz7Rh+3BjFhfDFKv/oXslEjJA=
+github.com/go-playground/locales v0.14.1/go.mod h1:hxrqLVvrK65+Rwrd5Fc6F2O76J/NuW9t0sjnWqG1slY=
+github.com/go-playground/universal-translator v0.18.1 h1:Bcnm0ZwsGyWbCzImXv+pAJnYK9S473LQFuzCbDbfSFY=
+github.com/go-playground/universal-translator v0.18.1/go.mod h1:xekY+UJKNuX9WP91TpwSH2VMlDf28Uj24BCp08ZFTUY=
+github.com/go-playground/validator/v10 v10.30.1 h1:f3zDSN/zOma+w6+1Wswgd9fLkdwy06ntQJp0BBvFG0w=
+github.com/go-playground/validator/v10 v10.30.1/go.mod h1:oSuBIQzuJxL//3MelwSLD5hc2Tu889bF0Idm9Dg26cM=
+github.com/go-sql-driver/mysql v1.8.1 h1:LedoTUt/eveggdHS9qUFC1EFSa8bU2+1pZjSRpvNJ1Y=
+github.com/go-sql-driver/mysql v1.8.1/go.mod h1:wEBSXgmK//2ZFJyE+qWnIsVGmvmEKlqwuVSjsCm7DZg=
+github.com/goccy/go-json v0.10.5 h1:Fq85nIqj+gXn/S5ahsiTlK3TmC85qgirsdTP/+DeaC4=
+github.com/goccy/go-json v0.10.5/go.mod h1:oq7eo15ShAhp70Anwd5lgX2pLfOS3QCiwU/PULtXL6M=
+github.com/goccy/go-yaml v1.19.2 h1:PmFC1S6h8ljIz6gMRBopkjP1TVT7xuwrButHID66PoM=
+github.com/goccy/go-yaml v1.19.2/go.mod h1:XBurs7gK8ATbW4ZPGKgcbrY1Br56PdM69F7LkFRi1kA=
+github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
+github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
+github.com/google/gofuzz v1.0.0/go.mod h1:dBl0BpW6vV/+mYPU4Po3pmUjxk6FQPldtuIdl/M65Eg=
+github.com/jinzhu/inflection v1.0.0 h1:K317FqzuhWc8YvSVlFMCCUb36O/S9MCKRDI7QkRKD/E=
+github.com/jinzhu/inflection v1.0.0/go.mod h1:h+uFLlag+Qp1Va5pdKtLDYj+kHp5pxUVkryuEj+Srlc=
+github.com/jinzhu/now v1.1.5 h1:/o9tlHleP7gOFmsnYNz3RGnqzefHA47wQpKrrdTIwXQ=
+github.com/jinzhu/now v1.1.5/go.mod h1:d3SSVoowX0Lcu0IBviAWJpolVfI5UJVZZ7cO71lE/z8=
+github.com/json-iterator/go v1.1.12 h1:PV8peI4a0ysnczrg+LtxykD8LfKY9ML6u2jnxaEnrnM=
+github.com/json-iterator/go v1.1.12/go.mod h1:e30LSqwooZae/UwlEbR2852Gd8hjQvJoHmT4TnhNGBo=
+github.com/klauspost/cpuid/v2 v2.3.0 h1:S4CRMLnYUhGeDFDqkGriYKdfoFlDnMtqTiI/sFzhA9Y=
+github.com/klauspost/cpuid/v2 v2.3.0/go.mod h1:hqwkgyIinND0mEev00jJYCxPNVRVXFQeu1XKlok6oO0=
+github.com/leodido/go-urn v1.4.0 h1:WT9HwE9SGECu3lg4d/dIA+jxlljEa1/ffXKmRjqdmIQ=
+github.com/leodido/go-urn v1.4.0/go.mod h1:bvxc+MVxLKB4z00jd1z+Dvzr47oO32F/QSNjSBOlFxI=
+github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
+github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
+github.com/modern-go/concurrent v0.0.0-20180228061459-e0a39a4cb421/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
+github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd h1:TRLaZ9cD/w8PVh93nsPXa1VrQ6jlwL5oN8l14QlcNfg=
+github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
+github.com/modern-go/reflect2 v1.0.2 h1:xBagoLtFs94CBntxluKeaWgTMpvLxC4ur3nMaC9Gz0M=
+github.com/modern-go/reflect2 v1.0.2/go.mod h1:yWuevngMOJpCy52FWWMvUC8ws7m/LJsjYzDa0/r8luk=
+github.com/pelletier/go-toml/v2 v2.2.4 h1:mye9XuhQ6gvn5h28+VilKrrPoQVanw5PMw/TB0t5Ec4=
+github.com/pelletier/go-toml/v2 v2.2.4/go.mod h1:2gIqNv+qfxSVS7cM2xJQKtLSTLUE9V8t9Stt+h56mCY=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/quic-go/qpack v0.6.0 h1:g7W+BMYynC1LbYLSqRt8PBg5Tgwxn214ZZR34VIOjz8=
+github.com/quic-go/qpack v0.6.0/go.mod h1:lUpLKChi8njB4ty2bFLX2x4gzDqXwUpaO1DP9qMDZII=
+github.com/quic-go/quic-go v0.59.0 h1:OLJkp1Mlm/aS7dpKgTc6cnpynnD2Xg7C1pwL6vy/SAw=
+github.com/quic-go/quic-go v0.59.0/go.mod h1:upnsH4Ju1YkqpLXC305eW3yDZ4NfnNbmQRCMWS58IKU=
+github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
+github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw=
+github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo=
+github.com/stretchr/objx v0.5.2/go.mod h1:FRsXN1f5AsAjCGJKqEizvkpNtU+EGNCLh3NxZ/8L+MA=
+github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
+github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
+github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=
+github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
+github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
+github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
+github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
+github.com/twitchyliquid64/golang-asm v0.15.1 h1:SU5vSMR7hnwNxj24w34ZyCi/FmDZTkS4MhqMhdFk5YI=
+github.com/twitchyliquid64/golang-asm v0.15.1/go.mod h1:a1lVb/DtPvCB8fslRZhAngC2+aY1QWCk3Cedj/Gdt08=
+github.com/ugorji/go/codec v1.3.1 h1:waO7eEiFDwidsBN6agj1vJQ4AG7lh2yqXyOXqhgQuyY=
+github.com/ugorji/go/codec v1.3.1/go.mod h1:pRBVtBSKl77K30Bv8R2P+cLSGaTtex6fsA2Wjqmfxj4=
+go.mongodb.org/mongo-driver/v2 v2.5.0 h1:yXUhImUjjAInNcpTcAlPHiT7bIXhshCTL3jVBkF3xaE=
+go.mongodb.org/mongo-driver/v2 v2.5.0/go.mod h1:yOI9kBsufol30iFsl1slpdq1I0eHPzybRWdyYUs8K/0=
+go.uber.org/mock v0.6.0 h1:hyF9dfmbgIX5EfOdasqLsWD6xqpNZlXblLB/Dbnwv3Y=
+go.uber.org/mock v0.6.0/go.mod h1:KiVJ4BqZJaMj4svdfmHM0AUx4NJYO8ZNpPnZn1Z+BBU=
+golang.org/x/arch v0.22.0 h1:c/Zle32i5ttqRXjdLyyHZESLD/bB90DCU1g9l/0YBDI=
+golang.org/x/arch v0.22.0/go.mod h1:dNHoOeKiyja7GTvF9NJS1l3Z2yntpQNzgrjh1cU103A=
+golang.org/x/crypto v0.48.0 h1:/VRzVqiRSggnhY7gNRxPauEQ5Drw9haKdM0jqfcCFts=
+golang.org/x/crypto v0.48.0/go.mod h1:r0kV5h3qnFPlQnBSrULhlsRfryS2pmewsg+XfMgkVos=
+golang.org/x/net v0.51.0 h1:94R/GTO7mt3/4wIKpcR5gkGmRLOuE/2hNGeWq/GBIFo=
+golang.org/x/net v0.51.0/go.mod h1:aamm+2QF5ogm02fjy5Bb7CQ0WMt1/WVM7FtyaTLlA9Y=
+golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.41.0 h1:Ivj+2Cp/ylzLiEU89QhWblYnOE9zerudt9Ftecq2C6k=
+golang.org/x/sys v0.41.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
+golang.org/x/text v0.34.0 h1:oL/Qq0Kdaqxa1KbNeMKwQq0reLCCaFtqu2eNuSeNHbk=
+golang.org/x/text v0.34.0/go.mod h1:homfLqTYRFyVYemLBFl5GgL/DWEiH5wcsQ5gSh1yziA=
+google.golang.org/protobuf v1.36.10 h1:AYd7cD/uASjIL6Q9LiTjz8JLcrh/88q5UObnmY3aOOE=
+google.golang.org/protobuf v1.36.10/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+gorm.io/driver/mysql v1.6.0 h1:eNbLmNTpPpTOVZi8MMxCi2aaIm0ZpInbORNXDwyLGvg=
+gorm.io/driver/mysql v1.6.0/go.mod h1:D/oCC2GWK3M/dqoLxnOlaNKmXz8WNTfcS9y5ovaSqKo=
+gorm.io/gorm v1.31.1 h1:7CA8FTFz/gRfgqgpeKIBcervUn3xSyPUmr6B2WXJ7kg=
+gorm.io/gorm v1.31.1/go.mod h1:XyQVbO2k6YkOis7C2437jSit3SsDK72s7n7rsSHd+Gs=