docs(release): fill 0.2.0 installer checksums

release.yml gains a required tag input so an existing tag can be rebuilt
without re-pushing it. The tag is checked out via refs/tags/, verified
against package.json and Cargo.toml versions before any toolchain setup,
and Gitea commit statuses are posted against the tag commit rather than
GITHUB_SHA (which is the dispatched branch head on workflow_dispatch).

.gitattributes

@@ -0,0 +1,22 @@
+# Keep LF in the working copy for all text files (prettier enforces LF)
+* text=auto eol=lf
+
+# Windows scripts that genuinely need CRLF
+*.bat text eol=crlf
+*.cmd text eol=crlf
+*.ps1 text eol=crlf
+
+# Binary assets — never touch line endings
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.webp binary
+*.gif binary
+*.ico binary
+*.icns binary
+*.woff binary
+*.woff2 binary
+*.ttf binary
+*.otf binary
+*.mp4 binary
+*.onnx binary

.github/workflows/ci.yml

@@ -4,16 +4,39 @@ on:
   push:
     branches: [main]
     paths:
+      - '.github/workflows/ci.yml'
+      # CHANGELOG.md is a build input: src/changelog.ts imports it ?raw for
+      # the What's New modal, and changelog.test.ts asserts on its content.
+      - 'CHANGELOG.md'
+      - 'index.html'
+      - 'package.json'
+      - 'pnpm-lock.yaml'
+      - 'pnpm-workspace.yaml'
       - 'src/**'
       - 'src-tauri/**'
+      - 'tsconfig*.json'
+      - 'vite.config.ts'
   pull_request:
     paths:
+      - '.github/workflows/ci.yml'
+      # CHANGELOG.md is a build input: src/changelog.ts imports it ?raw for
+      # the What's New modal, and changelog.test.ts asserts on its content.
+      - 'CHANGELOG.md'
+      - 'index.html'
+      - 'package.json'
+      - 'pnpm-lock.yaml'
+      - 'pnpm-workspace.yaml'
       - 'src/**'
       - 'src-tauri/**'
+      - 'tsconfig*.json'
+      - 'vite.config.ts'
   workflow_dispatch:
 
+permissions:
+  contents: read
+
 concurrency:
-  group: ci-${{ github.ref }}
+  group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
 
 jobs:
@@ -21,7 +44,9 @@ jobs:
     # windows-latest to match the release target — the ML crates (ort, candle)
     # and the NSIS bundle only ever ship from Windows.
     runs-on: windows-latest
+    timeout-minutes: 60
     env:
+      CARGO_INCREMENTAL: 0
       GITEA_STATUS_TOKEN: ${{ secrets.GITEA_STATUS_TOKEN }}
     steps:
       - name: Report pending status to Gitea
@@ -58,10 +83,14 @@ jobs:
         with:
           node-version: 22
           cache: pnpm
+          cache-dependency-path: pnpm-lock.yaml
 
       - name: Install frontend dependencies
         run: pnpm install --frozen-lockfile
 
+      - name: Unit tests
+        run: pnpm test:unit
+
       # tsc + vite build; also produces dist/ which tauri's build script expects
       - name: Type-check and build frontend
         run: pnpm build:vite
@@ -85,6 +114,10 @@ jobs:
         working-directory: src-tauri
         run: cargo clippy --all-targets --locked --no-default-features -- -D warnings
 
+      - name: Rust tests
+        working-directory: src-tauri
+        run: cargo test --locked --no-default-features
+
       - name: Report final status to Gitea
         if: always() && github.event_name != 'pull_request' && env.GITEA_STATUS_TOKEN != ''
         continue-on-error: true

.github/workflows/release.yml

@@ -8,15 +8,59 @@ on:
     tags:
       - 'v*'
   workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Existing release tag to build, for example v0.1.1'
+        required: true
+        type: string
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event_name == 'workflow_dispatch' && inputs.tag || github.ref_name }}
+  cancel-in-progress: false
 
 jobs:
   release:
     permissions:
       contents: write
     runs-on: windows-latest
+    timeout-minutes: 120
     env:
+      CARGO_INCREMENTAL: 0
       GITEA_STATUS_TOKEN: ${{ secrets.GITEA_STATUS_TOKEN }}
+      RELEASE_TAG: ${{ github.event_name == 'workflow_dispatch' && inputs.tag || github.ref_name }}
     steps:
+      # refs/tags/ qualification: a branch with a tag-like name must never win
+      # ref resolution. Works for tag pushes too — RELEASE_TAG is the tag name.
+      - uses: actions/checkout@v4
+        with:
+          ref: refs/tags/${{ env.RELEASE_TAG }}
+
+      # On workflow_dispatch GITHUB_SHA is the dispatched branch head, not the
+      # tag's commit — resolve the real one for Gitea commit statuses.
+      - name: Resolve release commit
+        shell: pwsh
+        run: |
+          $sha = git rev-parse HEAD
+          "RELEASE_SHA=$sha" | Out-File -FilePath $env:GITHUB_ENV -Append
+
+      - name: Verify release version
+        shell: pwsh
+        run: |
+          if ($env:RELEASE_TAG -notmatch '^v\d+\.\d+\.\d+(-.+)?$') {
+            throw "Release tag '$env:RELEASE_TAG' must look like v0.1.1"
+          }
+
+          $packageVersion = (Get-Content package.json -Raw | ConvertFrom-Json).version
+          $cargoVersion = (Select-String -Path src-tauri/Cargo.toml -Pattern '^version\s*=\s*"(.+)"').Matches[0].Groups[1].Value
+
+          if ($packageVersion -ne $cargoVersion) {
+            throw "package.json version ($packageVersion) does not match Cargo.toml version ($cargoVersion)"
+          }
+
+          if ($env:RELEASE_TAG -ne "v$packageVersion") {
+            throw "Release tag '$env:RELEASE_TAG' does not match project version v$packageVersion"
+          }
+
       - name: Report pending status to Gitea
         if: env.GITEA_STATUS_TOKEN != ''
         continue-on-error: true
@@ -36,13 +80,11 @@ jobs:
           } | ConvertTo-Json
           Invoke-RestMethod `
             -Method Post `
-            -Uri "https://git.jezz.wtf/api/v1/repos/JezzWTF/phokus/statuses/$env:GITHUB_SHA" `
+            -Uri "https://git.jezz.wtf/api/v1/repos/JezzWTF/phokus/statuses/$env:RELEASE_SHA" `
             -Headers $headers `
             -ContentType "application/json" `
             -Body $body
 
-      - uses: actions/checkout@v4
-
       - uses: pnpm/action-setup@v4
         with:
           version: 11
@@ -51,6 +93,7 @@ jobs:
         with:
           node-version: 22
           cache: pnpm
+          cache-dependency-path: pnpm-lock.yaml
 
       - name: Install Rust stable
         uses: dtolnay/rust-toolchain@stable
@@ -71,7 +114,7 @@ jobs:
           TAURI_SIGNING_PRIVATE_KEY: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY }}
           TAURI_SIGNING_PRIVATE_KEY_PASSWORD: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY_PASSWORD }}
         with:
-          tagName: ${{ github.ref_name }}
+          tagName: ${{ env.RELEASE_TAG }}
           releaseName: 'Phokus v__VERSION__'
           releaseBody: 'See the assets below to download and install this version.'
           releaseDraft: true
@@ -105,9 +148,11 @@ jobs:
             description = "GitHub Actions release finished: $env:JOB_STATUS"
             target_url = $env:GITHUB_RUN_URL
           } | ConvertTo-Json
+          # RELEASE_SHA is unset if the job died before checkout; fall back.
+          $sha = if ($env:RELEASE_SHA) { $env:RELEASE_SHA } else { $env:GITHUB_SHA }
           Invoke-RestMethod `
             -Method Post `
-            -Uri "https://git.jezz.wtf/api/v1/repos/JezzWTF/phokus/statuses/$env:GITHUB_SHA" `
+            -Uri "https://git.jezz.wtf/api/v1/repos/JezzWTF/phokus/statuses/$sha" `
             -Headers $headers `
             -ContentType "application/json" `
             -Body $body

.prettierignore

@@ -0,0 +1,30 @@
+# Build outputs
+dist/
+build/
+
+# Tauri / Rust (handled by cargo fmt)
+src-tauri/
+
+# Lock files & generated
+pnpm-lock.yaml
+*.lock
+
+# Generated
+src/vite-env.d.ts
+
+# Public assets
+public/
+
+# Website subpackage (has its own config if needed)
+website/
+
+# Markdown & docs (hand-written or tool-generated, keep diffs quiet)
+*.md
+docs/
+
+# CI workflows
+.github/
+.gitea/
+
+# Tool-managed config
+.claude/

.prettierrc

@@ -0,0 +1,14 @@
+{
+  "semi": false,
+  "singleQuote": true,
+  "jsxSingleQuote": false,
+  "trailingComma": "es5",
+  "printWidth": 100,
+  "tabWidth": 2,
+  "useTabs": false,
+  "bracketSpacing": true,
+  "bracketSameLine": false,
+  "arrowParens": "always",
+  "endOfLine": "lf",
+  "plugins": ["prettier-plugin-tailwindcss"]
+}

CHANGELOG.md

@@ -5,7 +5,7 @@ All notable changes to Phokus are documented here. The format is based on
 aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
 (0.x: anything may change between minor versions).
 
-## [Unreleased]
+## [0.2.0] — 2026-07-11
 
 ### Added
 
@@ -31,9 +31,7 @@ aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
   an album can now stay inside that album, jump back to the source folder, or
   search everything.
 - **Tag manager** — Explore's Tag Cloud now has a Manage mode for renaming,
-  merging, and deleting tags across the whole library. There is also an "Open tag
-  manager" shortcut in Settings -> AI Workspace when you want to get straight to
-  the cleanup.
+  merging, and deleting tags across the whole library.
 - **Camera info in the lightbox** — the info panel now shows EXIF details like
   camera, lens, aperture, shutter speed, ISO, and focal length. Geotagged photos
   also get a browser link for their GPS coordinates, and already-indexed images
@@ -43,7 +41,13 @@ aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
 - **Choose your tagging model** — Settings -> AI Workspace now lets you pick
   between the anime-focused WD tagger and JoyTag, which is better suited to photo
   libraries and stronger on NSFW concepts (if that's your thing, we don't judge).
-  Models download only when needed, and tags remember which model created them.
+  New users get the same choice during the welcome tour, and each model keeps its
+  own confidence threshold instead of sharing one.
+- **Reset AI tags** — a new reset action in Settings -> AI Workspace and the Tag
+  manager wipes AI-generated tags for a folder or the whole library, cancelling
+  any tagging still in flight. Tag manager rows now show which tags came from the
+  AI, so you know what you are about to lose before you lose it. Manually-added
+  tags are never touched.
 - **Related tags in Explore** — Hover over a tag in the Tag Cloud to see the tags
   that most often appear with it, complete with connection lines and image counts.
   Handy for finding little clusters you did not know were there.
@@ -52,13 +56,30 @@ aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
   library but leave out of background processing for now.
 - **Editable folder path** — the folder picker now has an address bar, so you can
   paste a path directly while still using breadcrumbs for quick jumps.
+- **Slideshow mode** — turn the lightbox into a fullscreen, image-only slideshow
+  from whatever collection you are already browsing.
+- **Add to album from the right-click menu** — right-click any image in the
+  Gallery or Timeline and file it straight into an album from the new "Add to
+  Album" submenu. One image, one click, zero ceremony.
 
 ### Changed
 
+- **Settings got a spring clean** — preferences are now organised into General,
+  Media, Updates & Setup, Storage, and AI Workspace pages, so update and
+  maintenance controls no longer hide at the bottom of unrelated sections.
+- **Menus got their act together** — right-click menus (images, folders,
+  albums, the theme switcher) and every dropdown (sort, folder scope, settings,
+  sidebar) now share one style with one set of manners: they stay on screen
+  instead of wandering off the edge, all close on Escape, and right-click menus
+  can do proper submenus now. Subtle Light dresses them all the same way too,
+  instead of saving the nice outfit for one dropdown.
 - **Neater lightbox details** — image and video metadata now sits in two columns,
   so the info panel shows more at a glance with less scrolling.
 - **Faster Explore revisits** — returning to a folder's visual clusters should
   feel much faster now, even in big libraries.
+- **Calmer Tag Cloud during AI tagging** — Explore no longer keeps hammering the
+  tag list while a folder is actively being tagged, so tagging stays smoother and
+  the cloud catches up once the work settles.
 - **Faster first-time clustering** — large libraries build their first visual
   clusters much more quickly, while still keeping the groups nicely balanced.
 - **Better tag browsing** — the Tag manager now has live search, sorting
@@ -84,37 +105,48 @@ aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
 - **Explore no longer flashes the last folder** — switching folders now clears
   the old clusters/tags and shows a loading state while the new folder catches
   up.
-- **Ratings keep your search order** — rating or favoriting an image no longer
-  reshuffles similar-image, region, semantic, tag, or album results.
+- **Ratings keep your search order** — if you ever rated an image mid-search and
+  watched your results reshuffle themselves, that's over. Similar-image, region,
+  semantic, tag, and album results now stay put.
 - **Update progress comes back when you need it** — if you dismiss the update
   prompt and later start the update from the title bar or Settings, the progress
   toast now reappears instead of hiding away in Settings.
 - **Subtle Light cleanup** — fixed dark or hard-to-read surfaces, hover states,
   dialogs, updater buttons, onboarding controls, and green action buttons in the
   light theme.
-- **No more self-indexing loops** — if you add a broad folder like your user
-  profile, Phokus now skips its own app-data directory instead of indexing its
-  thumbnail cache forever.
+- **No more self-indexing loops** — adding a broad folder like your whole user
+  profile used to send Phokus off indexing its own thumbnail cache, generating
+  thumbnails of thumbnails until the end of time. It now skips its own app-data
+  directory.
 - **Background tasks show the active work first** — when one folder is paused and
   another is processing, the active folder gets the main spot in the background
   tasks bar.
-- **First launch fits smaller screens** — fresh installs now clamp the window to
-  the usable monitor area, so 1366x768-style displays do not lose part of the app
-  below the taskbar.
+- **First launch fits smaller screens** — on 1366x768-style displays, fresh
+  installs used to open with part of the app tucked below the taskbar. The window
+  now clamps itself to the usable monitor area.
 - **Explore is clearer in Subtle Light** — cluster captions, buttons, cloud
   words, hover glows, and the new connection lines now use stronger light-theme
   colours.
 - **Explore got a few sharp edges sanded down** — Cluster Cloud uses the in-app
   tooltip, singular counts now say "1 image", and the folder-scope dropdown no
   longer hides behind cluster cards.
-- **AI tagging stays responsive** — GPU tagging now works in smaller bursts with
-  brief pauses between them, so the UI keeps moving and the first batch starts
+- **AI tagging stays responsive** — starting a big tagging job used to turn the
+  rest of the app into a slideshow. GPU tagging now works in smaller bursts with
+  brief pauses between them, so the UI keeps moving and the first results land
   sooner.
+- **Lightbox AI tags wake up on time** — the lightbox's AI tags action no longer
+  stays disabled until you happen to open Settings, and it switches on as soon as
+  a model download finishes.
 - **Noisy AI tags get cleaned up** — generic low-signal tags from WD and JoyTag
   are filtered before they are saved, and matching older generated tags are
   cleaned up on startup. Your manually-added tags are left alone.
 - **Selected Folders starts empty** — choosing "Selected Folders" for AI tagging
   no longer pre-selects the first folder. You decide exactly what gets queued.
+- **A handful of tiny UI papercuts are gone** — the zoom buttons now show the
+  right tile size when you hover them, the folder picker no longer adds an odd
+  trailing slash to Windows drive breadcrumbs, the search field's clear button
+  no longer sits a few pixels too high, and menu labels no longer highlight like
+  text when you drag across them.
 
 ## [0.1.1] — 2026-06-23
 
@@ -232,5 +264,6 @@ installer with a built-in updater.
   Settings, with live size/reclaimable stats.
 - **Window state** persistence and single-instance handling.
 
+[0.2.0]: https://github.com/JezzWTF/phokus/releases/tag/v0.2.0
 [0.1.1]: https://github.com/JezzWTF/phokus/releases/tag/v0.1.1
 [0.1.0]: https://github.com/JezzWTF/phokus/releases/tag/v0.1.0

CLAUDE.md

@@ -15,6 +15,9 @@ pnpm dev:app
 # Frontend only (no Tauri window)
 pnpm dev:vite
 
+# UI Lab — browser-only frontend with mocked Tauri backend (http://127.0.0.1:1422)
+pnpm dev:ui
+
 # Production build (CPU)
 pnpm build:app:cpu
 
@@ -23,27 +26,56 @@ pnpm build:app:cuda
 
 # Type-check frontend
 pnpm build:vite
+
+# Frontend unit tests (Vitest; only picks up src/**/*.test.ts)
+pnpm test:unit
+pnpm test:unit:watch
+
+# Rust unit tests (in-memory SQLite; --no-default-features skips CUDA)
+pnpm test:rust
+
+# E2E tests (Playwright against the UI Lab; auto-starts the server)
+pnpm test:e2e
+pnpm exec playwright test tests/ui-lab.spec.ts        # single file
+pnpm exec playwright test -g "filename search"        # single test by name
+
+# Formatting (Prettier + prettier-plugin-tailwindcss; cargo fmt for Rust)
+pnpm format:all
 ```
 
 Use **pnpm** — never npm.
 
-There are no test suites configured.
+Three test layers, none of which exercise the real Tauri window:
+- **Vitest unit tests** — co-located `*.test.ts` next to the pure logic they cover (`src/store/helpers.ts`, formatters, path utils); fixture factories in `src/test/factories.ts`.
+- **Rust unit tests** — inline `#[cfg(test)]` modules; DB tests run against in-memory SQLite via the shared `db::test_support` fixture (`test_conn()` + `test_image()`), which registers sqlite-vec and applies both migrations. Reuse it for any new DB-touching tests.
+- **Playwright e2e smoke tests** in `tests/` — run against the UI Lab (browser mocks).
 
 ## Architecture
 
 ### Frontend (`src/`)
 
-- **`store.ts`** — single Zustand store (`useGalleryStore`) that owns all app state and all `invoke()` calls to the Tauri backend. Every feature (folders, images, search, similar images, tags, captions, tagger, duplicates) is implemented as store actions here. React components are thin consumers.
+- **`src/store/`** — single Zustand store (`useGalleryStore`) that owns all app state and all `invoke()` calls to the Tauri backend, split into per-feature slices combined in `index.ts` (which exports `useGalleryStore` and the `GalleryStore` type). `types.ts` holds all interfaces/type unions (including `ImageRecord`); `helpers.ts` holds pure functions and cross-slice module state (search parsing, image sort/merge, request-token guards). Slices: `librarySlice` (folders), `gallerySlice` (image paging/filters/bulk actions), `searchSlice` (search + similar-images), `exploreSlice` (visual clusters, tag cloud, tags), `albumSlice`, `duplicateSlice`, `taggerSlice`, `captionSlice`, `settingsSlice`, `appSlice` (updates, onboarding, ffmpeg, worker pauses); `events.ts` wires the Tauri event listeners (`subscribeToProgress`). Components still call `useGalleryStore(s => s.field)` against one flat state object — the slice split is internal. React components are thin consumers.
 - **`App.tsx`** — sets up Tauri event listeners (`subscribeToProgress`) and renders the top-level layout (sidebar + active view).
-- **`src/components/`** — UI components: `Gallery`, `Lightbox`, `Sidebar`, `Toolbar`, `TagCloud`, `DuplicateFinder`, `BackgroundTasks`, `SettingsModal`, `MenuBar`, `TitleBar`.
+- **`src/components/`** — UI components: `Gallery`, `Lightbox`, `Sidebar`, `Toolbar`, `Timeline`, `ExploreView`, `DuplicateFinder`, `BackgroundTasks`, `SettingsModal`, `TitleBar`.
+- **`src/components/menu/`** — shared floating-UI primitives: `useDismissable`, `MenuPanel`/`MenuItem`/`SubMenu`, the portal-based `ContextMenu`, and the app-wide `Dropdown`. Build menus, dropdowns, and popovers on these instead of hand-rolling.
 - State management: Zustand v5, no selectors library — components call `useGalleryStore(s => s.field)` directly.
 - Styling: Tailwind CSS v4 (Vite plugin, no config file).
 - Virtualized gallery grid: `@tanstack/react-virtual`.
 - Animation: `framer-motion`.
 
+### UI Lab (`src/dev/`)
+
+`pnpm dev:ui` runs the real frontend (same `App.tsx`, store, components, CSS) in a plain browser with Tauri fully mocked — no Rust backend or Tauri window. `src/main.tsx` imports `src/dev/setupMockTauri.ts` before `App` in `ui` mode; `mockBackend.ts` implements an in-memory command backend, with fixtures in `mockFixtures.ts`/`mockScenarios.ts`. Pick a seeded state via `?scenario=` (`rich` default; also `empty`, `new-user`, `just-updated`, `busy`, `duplicates`, `album`, `errors`, `huge`) and a What's New entry via `?changelog=`. `Ctrl+Shift+D` opens the demo panel. Full guide: `docs/ui-lab.md`.
+
+Rules that keep UI Lab working:
+- Components that render thumbnails/covers/posters must use `mediaSrc(...)` from `src/lib/mediaSrc.ts`, never `convertFileSrc(...)` directly.
+- New Tauri commands invoked from the frontend need a mock in `src/dev/mockBackend.ts` (unmocked commands log console errors, which fail the e2e tests).
+
+UI Lab is for visual/layout work and agent browser inspection. Native behavior (file pickers, real thumbnails, window controls, updater) must still be validated in `pnpm dev:app`.
+
 ### Search modes
 
-The search bar supports prefix syntax parsed by `parseSearchValue` in `store.ts`:
+The search bar supports prefix syntax parsed by `parseSearchValue` in `src/store/helpers.ts`:
 - No prefix / `f:` — filename search (paginated, DB-backed)
 - `/s <query>` or `s: <query>` — semantic (embedding) search
 - `/t <tag>` or `t: <tag>` — tag search
@@ -67,6 +99,8 @@ Key modules:
 | `hnsw_index.rs` | In-memory HNSW index wrapper (hnsw_rs) |
 | `tagger.rs` | WD tagger: ONNX model download, inference, CSV tag loading |
 | `captioner.rs` | AI captioning (ONNX, disabled in workers but code intact) |
+| `download.rs` | Resilient file downloads via the system `curl` (resume, stall detection) |
+| `onnx_runtime.rs` | Shared ONNX Runtime DLL provisioning + `ort` init (used by tagger and captioner; DLLs live in the caption model dir for legacy reasons) |
 | `thumbnail.rs` | Thumbnail generation (image crate + fast_image_resize, FFmpeg for video) |
 | `media.rs` | FFmpeg sidecar provisioning and probing |
 | `storage.rs` | `StorageProfile` for tuning worker counts |
@@ -87,7 +121,7 @@ Database: SQLite with WAL mode, stored in the Tauri app data directory as `galle
 
 ### Key types
 
-`ImageRecord` (mirrored in `store.ts` and `db.rs`) is the central data type. It carries embedding status, tagging status, caption data, and media metadata. The frontend type must stay in sync with the Rust struct serialization.
+`ImageRecord` (mirrored in `src/store/types.ts` and `db.rs`) is the central data type. It carries embedding status, tagging status, caption data, and media metadata. The frontend type must stay in sync with the Rust struct serialization.
 
 ## Development notes
 
@@ -95,3 +129,5 @@ Database: SQLite with WAL mode, stored in the Tauri app data directory as `galle
 - ML inference crates (`candle-*`, `ort`, `image`, `rayon`, `tokenizers`, `xxhash-rust`, `rusqlite`) use `opt-level = 3` in dev profile to keep inference performance acceptable.
 - The caption worker is intentionally disabled (`lib.rs:73`) — the backend code is intact for future re-enabling.
 - **Never use `any` type** in TypeScript — look up correct types.
+- `website/` is a separate Vite project for the marketing site (phokus.jezz.wtf): `pnpm dev:web` / `pnpm build:web`. It is not part of the app build.
+- `pnpm changelog:add -- --type fixed --message "..."` appends an entry to the `[Unreleased]` section of `CHANGELOG.md`, which also feeds the in-app What's New modal (types: added, changed, deprecated, removed, fixed, security).

docs/release-notes-0.2.0.md

@@ -0,0 +1,85 @@
+# Phokus v0.2.0
+
+> Draft for the GitHub Release body. Fill in the checksums and trim as needed.
+
+**Phokus is a local-first desktop media library for Windows** — point it at
+your image and video folders and it builds a fast, searchable gallery with
+thumbnails, semantic search, visual discovery, AI tagging, and duplicate
+cleanup. Everything is processed on your machine; nothing is uploaded.
+
+0.2.0 is the biggest update since launch: albums, gallery multi-select with
+bulk actions, colour search, a second AI tagging model (JoyTag), a full tag
+manager, camera EXIF details in the lightbox, a slideshow mode, and a large
+batch of performance and theme fixes. Updating from 0.1.x? The built-in
+updater will fetch this for you — and afterwards, a new in-app "What's New"
+tour shows you around.
+
+## Install / update
+
+- **Updating from 0.1.x:** the in-app updater will offer 0.2.0 on launch — one
+  click downloads, installs, and relaunches.
+- **Fresh install:** download `Phokus_0.2.0_x64-setup.exe` below and run it.
+  **Windows SmartScreen will warn** that the publisher is unrecognized — this
+  build is **not code-signed**. Click **More info → Run anyway**.
+- Requires **Windows 10/11**. WebView2 is fetched automatically if missing.
+
+NVIDIA users wanting GPU embedding/tagging speed can use the
+`Phokus_0.2.0_x64-cuda-setup.exe` variant instead (larger download; bundles the
+CUDA runtime DLLs). Settings → Updates now shows which build you are running.
+
+## Highlights
+
+### Added
+- **Albums** — cross-folder collections without moving files: their own
+  sidebar section with cover thumbnails, create/rename/reorder/manage, and
+  album-aware similar-image search.
+- **Gallery multi-select** — hover a thumbnail's corner to start selecting,
+  then bulk tag, rate, favorite, add to an album, or delete from a floating
+  action bar. Works in similar-image, region, and album views too.
+- **Colour search** — filter the Gallery, Timeline, or tag results by dominant
+  colour via toolbar swatches or a custom picker.
+- **Choose your tagging model** — pick between the anime-focused WD tagger and
+  **JoyTag** (better for photo libraries), each with its own confidence
+  threshold, plus a **Reset AI tags** action that never touches manual tags.
+- **Tag manager** — rename, merge, and delete tags across the library, with
+  live search and sorting; Explore's Tag Cloud also shows **related tags** on
+  hover.
+- **Camera info in the lightbox** — EXIF camera, lens, aperture, shutter
+  speed, ISO, focal length, and a map link for geotagged photos.
+- **Slideshow mode**, **What's New tour after updates**, **quick theme switch**
+  from the title bar, an editable path bar in the folder picker, persistent
+  per-folder worker pauses, and add-to-album from the right-click menu.
+
+### Changed
+- **Settings reorganised** into General, Media, Updates & Setup, Storage, and
+  AI Workspace pages.
+- **Menus unified** — all context menus and dropdowns share one style, stay on
+  screen, close on Escape, and support submenus.
+- **Faster Explore** — quicker cluster revisits, much faster first-time
+  clustering on large libraries, and a calmer Tag Cloud during active tagging.
+- **Faster CPU tagging** (multi-core with headroom) and smoother GPU tagging.
+- **Safer deletion** — deleting media now asks for confirmation and says
+  clearly that files are removed from disk.
+- Better narrow-window layouts, a real update download progress bar, and a
+  two-column lightbox info panel.
+
+### Fixed
+- **No more self-indexing loops** — Phokus now skips its own thumbnail cache
+  when you add a broad folder like your user profile.
+- **Ratings keep your search order** — rating an image mid-search no longer
+  reshuffles similar-image, region, semantic, tag, or album results.
+- **AI tagging stays responsive** — big GPU tagging jobs no longer freeze the
+  UI, and noisy low-signal tags are filtered (older ones cleaned up on
+  startup).
+- First launch now fits smaller screens, Explore no longer flashes the
+  previous folder, and a long list of Subtle Light readability fixes.
+
+See the [changelog](https://github.com/JezzWTF/phokus/blob/main/CHANGELOG.md)
+for the full list.
+
+## Checksums
+
+```
+SHA-256 (Phokus_0.2.0_x64-setup.exe)      = 9d52b485ef0d614620b0df4ba235fbdf285e0792e4a38841777e0f0a05f38770
+SHA-256 (Phokus_0.2.0_x64-cuda-setup.exe) = b3a24ea5fb9f00f64fe5b4040a69347b91341c75eb83fd7bb2409cc74c5eb052
+```

docs/ui-lab.md

@@ -22,7 +22,7 @@ http://127.0.0.1:1422
 The script runs Vite in the custom `ui` mode:
 
 ```bash
-vite --mode ui --host 127.0.0.1 --port 1422 --strictPort --open
+vite --mode ui --host 127.0.0.1 --port 1422 --strictPort
 ```
 
 The normal app development commands are unchanged:
@@ -40,7 +40,9 @@ UI Lab reads `?scenario=` from the URL. If no scenario is provided, it uses
 | URL | Purpose |
 | --- | --- |
 | `/?scenario=rich` | Default realistic library with folders, albums, ratings, favorites, tags, images, and videos |
-| `/?scenario=empty` | First-run state with no folders or media |
+| `/?scenario=empty` | Empty library with no folders or media (onboarding already completed) |
+| `/?scenario=new-user` | True first run: onboarding tour open, empty library, no tagger model downloaded |
+| `/?scenario=just-updated` | Rich library that has just been updated — the "What's new" toast fires on launch |
 | `/?scenario=busy` | Background workers with pending thumbnail, metadata, embedding, caption, and tagging jobs |
 | `/?scenario=duplicates` | Duplicate Finder opened with duplicate groups already available |
 | `/?scenario=album` | Gallery opened directly into an album |
@@ -55,6 +57,23 @@ http://127.0.0.1:1422/?scenario=errors
 http://127.0.0.1:1422/?scenario=huge
 ```
 
+## Changelog Previews
+
+The What's New modal adapts its layout to release size (compact single column
+for small releases, a two-pane section rail for large ones). UI Lab reads
+`?changelog=` to override which entry the modal shows:
+
+| URL | Purpose |
+| --- | --- |
+| `/?changelog=unreleased` | The in-progress `[Unreleased]` notes — large release, rail layout |
+| `/?changelog=small` | Synthetic hotfix-sized entry — compact single-column layout |
+| `/?changelog=0.1.1` | Any specific released version |
+
+Open the modal via the demo panel: `Ctrl+Shift+D` → Open "What's new" modal.
+
+Combine with the scenario above to walk the whole post-update greeting for the
+next release: `/?scenario=just-updated&changelog=unreleased`.
+
 ## How It Works
 
 `src/main.tsx` bootstraps the app asynchronously. In `ui` mode it imports

package.json

@@ -1,7 +1,7 @@
 {
   "name": "phokus",
   "private": true,
-  "version": "0.1.1",
+  "version": "0.2.0",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -13,13 +13,20 @@
     "clean:app": "cd src-tauri && cargo clean",
     "dev:app": "tauri dev",
     "dev:app:cpu": "tauri dev -- --no-default-features",
-    "dev:ui": "vite --mode ui --host 127.0.0.1 --port 1422 --strictPort --open",
+    "dev:ui": "vite --mode ui --host 127.0.0.1 --port 1422 --strictPort",
     "dev:vite": "vite",
     "dev:web": "cd website && pnpm dev",
-    "format:app": "cd src-tauri && cargo fmt",
-    "format:check": "cd src-tauri && cargo fmt --check",
+    "format": "prettier --write .",
+    "format:all": "pnpm format && pnpm format:rust",
+    "format:check": "prettier --check .",
+    "format:rust": "cd src-tauri && cargo fmt",
+    "format:rust:check": "cd src-tauri && cargo fmt --check",
     "preview": "vite preview",
-    "tauri": "tauri"
+    "tauri": "tauri",
+    "test:e2e": "playwright test",
+    "test:rust": "cd src-tauri && cargo test --no-default-features",
+    "test:unit": "vitest run",
+    "test:unit:watch": "vitest"
   },
   "dependencies": {
     "@tanstack/react-virtual": "^3.13.23",
@@ -45,8 +52,11 @@
     "@types/react": "^19.1.8",
     "@types/react-dom": "^19.1.6",
     "@vitejs/plugin-react": "^4.6.0",
+    "prettier": "^3.9.4",
+    "prettier-plugin-tailwindcss": "^0.8.0",
     "tailwindcss": "^4.2.2",
     "typescript": "~5.8.3",
-    "vite": "^7.0.4"
+    "vite": "^7.0.4",
+    "vitest": "^4.1.9"
   }
 }

playwright.config.ts

@@ -1,4 +1,4 @@
-import { defineConfig, devices } from '@playwright/test';
+import { defineConfig, devices } from '@playwright/test'
 
 /**
  * Read environment variables from file.
@@ -20,13 +20,13 @@ export default defineConfig({
   /* Retry on CI only */
   retries: process.env.CI ? 2 : 0,
   /* Opt out of parallel tests on CI. */
-  workers: process.env.CI ? 1 : undefined,
+  workers: process.env.CI ? 1 : 4,
   /* Reporter to use. See https://playwright.dev/docs/test-reporters */
   reporter: 'html',
   /* Shared settings for all the projects below. See https://playwright.dev/docs/api/class-testoptions. */
   use: {
     /* Base URL to use in actions like `await page.goto('')`. */
-    // baseURL: 'http://localhost:3000',
+    baseURL: 'http://127.0.0.1:1422',
 
     /* Collect trace when retrying the failed test. See https://playwright.dev/docs/trace-viewer */
     trace: 'on-first-retry',
@@ -39,11 +39,6 @@ export default defineConfig({
       use: { ...devices['Desktop Chrome'] },
     },
 
-    {
-      name: 'firefox',
-      use: { ...devices['Desktop Firefox'] },
-    },
-
     {
       name: 'webkit',
       use: { ...devices['Desktop Safari'] },
@@ -70,10 +65,11 @@ export default defineConfig({
     // },
   ],
 
-  /* Run your local dev server before starting the tests */
-  // webServer: {
-  //   command: 'npm run start',
-  //   url: 'http://localhost:3000',
-  //   reuseExistingServer: !process.env.CI,
-  // },
-});
+  /* Run the Phokus UI Lab (browser-only dev mode, see docs/ui-lab.md) before starting the tests */
+  webServer: {
+    command: 'pnpm exec vite --mode ui --host 127.0.0.1 --port 1422 --strictPort',
+    url: 'http://127.0.0.1:1422',
+    reuseExistingServer: !process.env.CI,
+    timeout: 120_000,
+  },
+})

pnpm-lock.yaml

@@ -72,6 +72,12 @@ importers:
       '@vitejs/plugin-react':
         specifier: ^4.6.0
         version: 4.7.0(vite@7.3.1(@types/node@26.0.1)(jiti@2.6.1)(lightningcss@1.32.0))
+      prettier:
+        specifier: ^3.9.4
+        version: 3.9.4
+      prettier-plugin-tailwindcss:
+        specifier: ^0.8.0
+        version: 0.8.0(prettier@3.9.4)
       tailwindcss:
         specifier: ^4.2.2
         version: 4.2.2
@@ -81,6 +87,9 @@ importers:
       vite:
         specifier: ^7.0.4
         version: 7.3.1(@types/node@26.0.1)(jiti@2.6.1)(lightningcss@1.32.0)
+      vitest:
+        specifier: ^4.1.9
+        version: 4.1.9(@types/node@26.0.1)(vite@7.3.1(@types/node@26.0.1)(jiti@2.6.1)(lightningcss@1.32.0))
 
   website:
     dependencies:
@@ -699,6 +708,9 @@ packages:
     cpu: [x64]
     os: [win32]
 
+  '@standard-schema/spec@1.1.0':
+    resolution: {integrity: sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w==}
+
   '@tailwindcss/node@4.2.2':
     resolution: {integrity: sha512-pXS+wJ2gZpVXqFaUEjojq7jzMpTGf8rU6ipJz5ovJV6PUGmlJ+jvIwGrzdHdQ80Sg+wmQxUFuoW1UAAwHNEdFA==}
 
@@ -911,9 +923,15 @@ packages:
   '@types/babel__traverse@7.28.0':
     resolution: {integrity: sha512-8PvcXf70gTDZBgt9ptxJ8elBeBjcLOAcOtoO/mPJjtji1+CdGbHgm77om1GrsPxsiE+uXIpNSK64UYaIwQXd4Q==}
 
+  '@types/chai@5.2.3':
+    resolution: {integrity: sha512-Mw558oeA9fFbv65/y4mHtXDs9bPnFMZAL/jxdPFUpOHHIXX91mcgEHbS5Lahr+pwZFR8A7GQleRWeI6cGFC2UA==}
+
   '@types/d3-force@3.0.10':
     resolution: {integrity: sha512-ZYeSaCF3p73RdOKcjj+swRlZfnYpK1EbaDiYICEEp5Q6sUiqFaFQ9qgoshp5CzIyyb/yD09kD9o2zEltCexlgw==}
 
+  '@types/deep-eql@4.0.2':
+    resolution: {integrity: sha512-c9h9dVVMigMPc4bwTvC5dxqtqJZwQPePsWjPlpSOnojbor6pGqdk541lfA7AqFQr5pB1BRdq0juY9db81BwyFw==}
+
   '@types/estree@1.0.8':
     resolution: {integrity: sha512-dWHzHa2WqEXI/O1E9OjrocMTKJl2mSrEolh1Iomrv6U+JuNwaHXsXx9bLu5gG7BUWFIN0skIQJQ/L1rIex4X6w==}
 
@@ -934,6 +952,39 @@ packages:
     peerDependencies:
       vite: ^4.2.0 || ^5.0.0 || ^6.0.0 || ^7.0.0
 
+  '@vitest/expect@4.1.9':
+    resolution: {integrity: sha512-vl/rYsUKcBr3SnQn166+XR5ZQcgMx3DQhFWdfli/cWpLnLUmbxZvyrJZotLFUryib+LtArYMSTJ5RbQ57ZqrlA==}
+
+  '@vitest/mocker@4.1.9':
+    resolution: {integrity: sha512-EVkXzBjrPGM+cK8/ANWgBrkUCfJfb38/EfTSO8h7pWvKkyPkpWxvR7BkD2MyItMF62C97zAEoqdpUixwR/e+Rw==}
+    peerDependencies:
+      msw: ^2.4.9
+      vite: ^6.0.0 || ^7.0.0 || ^8.0.0
+    peerDependenciesMeta:
+      msw:
+        optional: true
+      vite:
+        optional: true
+
+  '@vitest/pretty-format@4.1.9':
+    resolution: {integrity: sha512-s0iufns3iIFitdgm+YR7g1whCAaGtXz459VS9/PqyKDEEFgYIhsHOQmXgIgDuYCt7DeQmiZT0Qe2OA2p4ZPu5A==}
+
+  '@vitest/runner@4.1.9':
+    resolution: {integrity: sha512-KXLMDtc7oe70+3mJfGrPUWPesswH+3sTxAMAMl8DG7I8IUQT4XW718dY5ID3vPUcmlu27CcKfY4P3h3I29SLJg==}
+
+  '@vitest/snapshot@4.1.9':
+    resolution: {integrity: sha512-Jc7RKGNBo8Z28WYIm0Niej4xdSPByRf6mU58VpHQkd6Zh05rlnA+twjbK5HyeIGHxrzsc3mJgS43uM0CZKzaIA==}
+
+  '@vitest/spy@4.1.9':
+    resolution: {integrity: sha512-fHpsS6mIi+PiEW+vcRVOMkX1oSaPKne3VOclSFICPcGOmfKgXPU5iAah+wcNcj2xPrCCmfq99IDGf+EojhhvhA==}
+
+  '@vitest/utils@4.1.9':
+    resolution: {integrity: sha512-A51o8ymO5PpqlWNnBP9ZHPXDIpuMtTLlGSjN7la4US+LJzoUMyhwjA5QXlm39JexgwHKW4Xjs8Z2d3dLCXOeuA==}
+
+  assertion-error@2.0.1:
+    resolution: {integrity: sha512-Izi8RQcffqCeNVgFigKli1ssklIbpHnCYc6AknXGYoB6grJqyeby7jv12JUQgmTAnIDnbck1uxksT4dzN3PWBA==}
+    engines: {node: '>=12'}
+
   baseline-browser-mapping@2.10.14:
     resolution: {integrity: sha512-fOVLPAsFTsQfuCkvahZkzq6nf8KvGWanlYoTh0SVA0A/PIUxQGU2AOZAoD95n2gFLVDW/jP6sbGLny95nmEuHA==}
     engines: {node: '>=6.0.0'}
@@ -947,6 +998,10 @@ packages:
   caniuse-lite@1.0.30001785:
     resolution: {integrity: sha512-blhOL/WNR+Km1RI/LCVAvA73xplXA7ZbjzI4YkMK9pa6T/P3F2GxjNpEkyw5repTw9IvkyrjyHpwjnhZ5FOvYQ==}
 
+  chai@6.2.2:
+    resolution: {integrity: sha512-NUPRluOfOiTKBKvWPtSD4PhFvWCqOi0BGStNWs57X9js7XGTprSmFoz5F0tWhR4WPjNeR9jXqdC7/UpSJTnlRg==}
+    engines: {node: '>=18'}
+
   convert-source-map@2.0.0:
     resolution: {integrity: sha512-Kvp459HrV2FEJ1CAsi1Ku+MY3kasH19TFykTz2xWmMeq6bk2NU3XXvfJ+Q61m0xktWwt+1HSYf3JZsTms3aRJg==}
 
@@ -989,6 +1044,9 @@ packages:
     resolution: {integrity: sha512-Qohcme7V1inbAfvjItgw0EaxVX5q2rdVEZHRBrEQdRZTssLDGsL8Lwrznl8oQ/6kuTJONLaDcGjkNP247XEhcA==}
     engines: {node: '>=10.13.0'}
 
+  es-module-lexer@2.3.0:
+    resolution: {integrity: sha512-KLdwQm2NvGLDkQDCGvmiQrhkd0JbMzXthwQAUgWjQuQdBLFa3eiBP5arXZyA+f8x+x7OXgud6bq2rxjGtHV2tw==}
+
   esbuild@0.27.7:
     resolution: {integrity: sha512-IxpibTjyVnmrIQo5aqNpCgoACA/dTKLTlhMHihVHhdkxKyPO1uBBthumT0rdHmcsk9uMonIWS0m4FljWzILh3w==}
     engines: {node: '>=18'}
@@ -1001,6 +1059,13 @@ packages:
   estree-walker@2.0.2:
     resolution: {integrity: sha512-Rfkk/Mp/DL7JVje3u18FxFujQlTNR2q6QfMSMB7AvCBx91NGj/ba3kCfza0f6dVDbw7YlRf/nDrn7pQrCCyQ/w==}
 
+  estree-walker@3.0.3:
+    resolution: {integrity: sha512-7RUKfXgSMMkzt6ZuXmqapOurLGPPfgj6l9uRZ7lRGolvk0y2yocc35LdcxKC5PQZdn2DMqioAQ2NoWcrTKmm6g==}
+
+  expect-type@1.4.0:
+    resolution: {integrity: sha512-KfYbmpRm0VbLjEvVa9yGwCi9GI34xvi7A/HXYWQO65CSD2u3MczUJSuwXKFIxlGsgBQizV9q5J9NHj4VG0n+pA==}
+    engines: {node: '>=12.0.0'}
+
   fdir@6.5.0:
     resolution: {integrity: sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg==}
     engines: {node: '>=12.0.0'}
@@ -1159,6 +1224,13 @@ packages:
   node-releases@2.0.37:
     resolution: {integrity: sha512-1h5gKZCF+pO/o3Iqt5Jp7wc9rH3eJJ0+nh/CIoiRwjRxde/hAHyLPXYN4V3CqKAbiZPSeJFSWHmJsbkicta0Eg==}
 
+  obug@2.1.3:
+    resolution: {integrity: sha512-9miFgM2OFba7hB+pRgvtV84pYTBaoTHohvmIgiRt6dRIzbwEOIaNaP+dIlGs2fNFoB0SeISs0Jz5WFVRid6Xyg==}
+    engines: {node: '>=12.20.0'}
+
+  pathe@2.0.3:
+    resolution: {integrity: sha512-WUjGcAqP1gQacoQe+OBJsFA7Ld4DyXuUIjZ5cc75cLHvJ7dtNsTugphxIADwspS+AraAUePCKrSVtPLFj/F88w==}
+
   picocolors@1.1.1:
     resolution: {integrity: sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==}
 
@@ -1180,6 +1252,66 @@ packages:
     resolution: {integrity: sha512-OW/rX8O/jXnm82Ey1k44pObPtdblfiuWnrd8X7GJ7emImCOstunGbXUpp7HdBrFQX6rJzn3sPT397Wp5aCwCHg==}
     engines: {node: ^10 || ^12 || >=14}
 
+  prettier-plugin-tailwindcss@0.8.0:
+    resolution: {integrity: sha512-V8ITGH87yuBDF6JpEZTOVlUz/saAwqb8f3HRgUj8Lh+tGCcrmorhsLpYqzygwFwK0PE2Ib6Mv3M7T/uE2tZV1g==}
+    engines: {node: '>=20.19'}
+    peerDependencies:
+      '@ianvs/prettier-plugin-sort-imports': '*'
+      '@prettier/plugin-hermes': '*'
+      '@prettier/plugin-oxc': '*'
+      '@prettier/plugin-pug': '*'
+      '@shopify/prettier-plugin-liquid': '*'
+      '@trivago/prettier-plugin-sort-imports': '*'
+      '@zackad/prettier-plugin-twig': '*'
+      prettier: ^3.0
+      prettier-plugin-astro: '*'
+      prettier-plugin-css-order: '*'
+      prettier-plugin-jsdoc: '*'
+      prettier-plugin-marko: '*'
+      prettier-plugin-multiline-arrays: '*'
+      prettier-plugin-organize-attributes: '*'
+      prettier-plugin-organize-imports: '*'
+      prettier-plugin-sort-imports: '*'
+      prettier-plugin-svelte: '*'
+    peerDependenciesMeta:
+      '@ianvs/prettier-plugin-sort-imports':
+        optional: true
+      '@prettier/plugin-hermes':
+        optional: true
+      '@prettier/plugin-oxc':
+        optional: true
+      '@prettier/plugin-pug':
+        optional: true
+      '@shopify/prettier-plugin-liquid':
+        optional: true
+      '@trivago/prettier-plugin-sort-imports':
+        optional: true
+      '@zackad/prettier-plugin-twig':
+        optional: true
+      prettier-plugin-astro:
+        optional: true
+      prettier-plugin-css-order:
+        optional: true
+      prettier-plugin-jsdoc:
+        optional: true
+      prettier-plugin-marko:
+        optional: true
+      prettier-plugin-multiline-arrays:
+        optional: true
+      prettier-plugin-organize-attributes:
+        optional: true
+      prettier-plugin-organize-imports:
+        optional: true
+      prettier-plugin-sort-imports:
+        optional: true
+      prettier-plugin-svelte:
+        optional: true
+
+  prettier@3.9.4:
+    resolution: {integrity: sha512-yWG/o/4oJfo036EKAfK6ACAoDOfHeRHx4tuxkfBZiauURiaSmYwlpOr5LQqKtIkRD2z1PLteme2WoxEnj4tHTg==}
+    engines: {node: '>=14'}
+    hasBin: true
+
   react-dom@19.2.4:
     resolution: {integrity: sha512-AXJdLo8kgMbimY95O2aKQqsz2iWi9jMgKJhRBAxECE4IFxfcazB2LmzloIoibJI3C12IlY20+KFaLv+71bUJeQ==}
     peerDependencies:
@@ -1214,10 +1346,19 @@ packages:
     resolution: {integrity: sha512-Ou9I5Ft9WNcCbXrU9cMgPBcCK8LiwLqcbywW3t4oDV37n1pzpuNLsYiAV8eODnjbtQlSDwZ2cUEeQz4E54Hltg==}
     engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
 
+  siginfo@2.0.0:
+    resolution: {integrity: sha512-ybx0WO1/8bSBLEWXZvEd7gMW3Sn3JFlW3TvX1nREbDLRNQNaeNN8WK0meBwPdAaOI7TtRRRJn/Es1zhrrCHu7g==}
+
   source-map-js@1.2.1:
     resolution: {integrity: sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==}
     engines: {node: '>=0.10.0'}
 
+  stackback@0.0.2:
+    resolution: {integrity: sha512-1XMJE5fQo1jGH6Y/7ebnwPOBEkIEnT4QF32d5R1+VXdXveM0IBMJt8zfaxX1P3QhVwrYe+576+jkANtSS2mBbw==}
+
+  std-env@4.1.0:
+    resolution: {integrity: sha512-Rq7ybcX2RuC55r9oaPVEW7/xu3tj8u4GeBYHBWCychFtzMIr86A7e3PPEBPT37sHStKX3+TiX/Fr/ACmJLVlLQ==}
+
   tailwindcss@4.2.2:
     resolution: {integrity: sha512-KWBIxs1Xb6NoLdMVqhbhgwZf2PGBpPEiwOqgI4pFIYbNTfBXiKYyWoTsXgBQ9WFg/OlhnvHaY+AEpW7wSmFo2Q==}
 
@@ -1225,10 +1366,21 @@ packages:
     resolution: {integrity: sha512-1MOpMXuhGzGL5TTCZFItxCc0AARf1EZFQkGqMm7ERKj8+Hgr5oLvJOVFcC+lRmR8hCe2S3jC4T5D7Vg/d7/fhA==}
     engines: {node: '>=6'}
 
+  tinybench@2.9.0:
+    resolution: {integrity: sha512-0+DUvqWMValLmha6lr4kD8iAMK1HzV0/aKnCtWb9v9641TnP/MFb7Pc2bxoxQjTXAErryXVgUOfv2YqNllqGeg==}
+
+  tinyexec@1.2.4:
+    resolution: {integrity: sha512-SHf/r48b7vOrjve9PxJo3MN5v5yuyjHvdUcrQffT3WXMUfnGmHDVbC4k3sHJaJTgZCwpUplIaAo5ANtMyp3YHg==}
+    engines: {node: '>=18'}
+
   tinyglobby@0.2.15:
     resolution: {integrity: sha512-j2Zq4NyQYG5XMST4cbs02Ak8iJUdxRM0XI5QyxXuZOzKOINmWurp3smXu3y5wDcJrptwpSjgXHzIQxR0omXljQ==}
     engines: {node: '>=12.0.0'}
 
+  tinyrainbow@3.1.0:
+    resolution: {integrity: sha512-Bf+ILmBgretUrdJxzXM0SgXLZ3XfiaUuOj/IKQHuTXip+05Xn+uyEYdVg0kYDipTBcLrCVyUzAPz7QmArb0mmw==}
+    engines: {node: '>=14.0.0'}
+
   tslib@2.8.1:
     resolution: {integrity: sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==}
 
@@ -1292,6 +1444,52 @@ packages:
       yaml:
         optional: true
 
+  vitest@4.1.9:
+    resolution: {integrity: sha512-nE3/LEyc0z87uHYLZebqCUOaJr2hdtuPp7BQ4BosVFnfltxgAvMG08NyrSGlPpOUWvR27c5flSmYFTNr78L9GQ==}
+    engines: {node: ^20.0.0 || ^22.0.0 || >=24.0.0}
+    hasBin: true
+    peerDependencies:
+      '@edge-runtime/vm': '*'
+      '@opentelemetry/api': ^1.9.0
+      '@types/node': ^20.0.0 || ^22.0.0 || >=24.0.0
+      '@vitest/browser-playwright': 4.1.9
+      '@vitest/browser-preview': 4.1.9
+      '@vitest/browser-webdriverio': 4.1.9
+      '@vitest/coverage-istanbul': 4.1.9
+      '@vitest/coverage-v8': 4.1.9
+      '@vitest/ui': 4.1.9
+      happy-dom: '*'
+      jsdom: '*'
+      vite: ^6.0.0 || ^7.0.0 || ^8.0.0
+    peerDependenciesMeta:
+      '@edge-runtime/vm':
+        optional: true
+      '@opentelemetry/api':
+        optional: true
+      '@types/node':
+        optional: true
+      '@vitest/browser-playwright':
+        optional: true
+      '@vitest/browser-preview':
+        optional: true
+      '@vitest/browser-webdriverio':
+        optional: true
+      '@vitest/coverage-istanbul':
+        optional: true
+      '@vitest/coverage-v8':
+        optional: true
+      '@vitest/ui':
+        optional: true
+      happy-dom:
+        optional: true
+      jsdom:
+        optional: true
+
+  why-is-node-running@2.3.0:
+    resolution: {integrity: sha512-hUrmaWBdVDcxvYqnyh09zunKzROWjbZTiNy8dBEjkS7ehEDQibXJ7XvlmtbwuTclUiIyN+CyXQD4Vmko8fNm8w==}
+    engines: {node: '>=8'}
+    hasBin: true
+
   yallist@3.1.1:
     resolution: {integrity: sha512-a4UGQaWPH59mOXUYnAG2ewncQS4i4F43Tv3JoAM+s2VDAmS9NsK8GpDMLrCHPksFT7h3K6TOoUNn2pb7RoXx4g==}
 
@@ -1718,6 +1916,8 @@ snapshots:
   '@rollup/rollup-win32-x64-msvc@4.60.1':
     optional: true
 
+  '@standard-schema/spec@1.1.0': {}
+
   '@tailwindcss/node@4.2.2':
     dependencies:
       '@jridgewell/remapping': 2.3.5
@@ -1888,8 +2088,15 @@ snapshots:
     dependencies:
       '@babel/types': 7.29.0
 
+  '@types/chai@5.2.3':
+    dependencies:
+      '@types/deep-eql': 4.0.2
+      assertion-error: 2.0.1
+
   '@types/d3-force@3.0.10': {}
 
+  '@types/deep-eql@4.0.2': {}
+
   '@types/estree@1.0.8': {}
 
   '@types/node@26.0.1':
@@ -1916,6 +2123,49 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
+  '@vitest/expect@4.1.9':
+    dependencies:
+      '@standard-schema/spec': 1.1.0
+      '@types/chai': 5.2.3
+      '@vitest/spy': 4.1.9
+      '@vitest/utils': 4.1.9
+      chai: 6.2.2
+      tinyrainbow: 3.1.0
+
+  '@vitest/mocker@4.1.9(vite@7.3.1(@types/node@26.0.1)(jiti@2.6.1)(lightningcss@1.32.0))':
+    dependencies:
+      '@vitest/spy': 4.1.9
+      estree-walker: 3.0.3
+      magic-string: 0.30.21
+    optionalDependencies:
+      vite: 7.3.1(@types/node@26.0.1)(jiti@2.6.1)(lightningcss@1.32.0)
+
+  '@vitest/pretty-format@4.1.9':
+    dependencies:
+      tinyrainbow: 3.1.0
+
+  '@vitest/runner@4.1.9':
+    dependencies:
+      '@vitest/utils': 4.1.9
+      pathe: 2.0.3
+
+  '@vitest/snapshot@4.1.9':
+    dependencies:
+      '@vitest/pretty-format': 4.1.9
+      '@vitest/utils': 4.1.9
+      magic-string: 0.30.21
+      pathe: 2.0.3
+
+  '@vitest/spy@4.1.9': {}
+
+  '@vitest/utils@4.1.9':
+    dependencies:
+      '@vitest/pretty-format': 4.1.9
+      convert-source-map: 2.0.0
+      tinyrainbow: 3.1.0
+
+  assertion-error@2.0.1: {}
+
   baseline-browser-mapping@2.10.14: {}
 
   browserslist@4.28.2:
@@ -1928,6 +2178,8 @@ snapshots:
 
   caniuse-lite@1.0.30001785: {}
 
+  chai@6.2.2: {}
+
   convert-source-map@2.0.0: {}
 
   csstype@3.2.3: {}
@@ -1957,6 +2209,8 @@ snapshots:
       graceful-fs: 4.2.11
       tapable: 2.3.2
 
+  es-module-lexer@2.3.0: {}
+
   esbuild@0.27.7:
     optionalDependencies:
       '@esbuild/aix-ppc64': 0.27.7
@@ -1990,6 +2244,12 @@ snapshots:
 
   estree-walker@2.0.2: {}
 
+  estree-walker@3.0.3:
+    dependencies:
+      '@types/estree': 1.0.8
+
+  expect-type@1.4.0: {}
+
   fdir@6.5.0(picomatch@4.0.4):
     optionalDependencies:
       picomatch: 4.0.4
@@ -2092,6 +2352,10 @@ snapshots:
 
   node-releases@2.0.37: {}
 
+  obug@2.1.3: {}
+
+  pathe@2.0.3: {}
+
   picocolors@1.1.1: {}
 
   picomatch@4.0.4: {}
@@ -2110,6 +2374,12 @@ snapshots:
       picocolors: 1.1.1
       source-map-js: 1.2.1
 
+  prettier-plugin-tailwindcss@0.8.0(prettier@3.9.4):
+    dependencies:
+      prettier: 3.9.4
+
+  prettier@3.9.4: {}
+
   react-dom@19.2.4(react@19.2.4):
     dependencies:
       react: 19.2.4
@@ -2187,17 +2457,29 @@ snapshots:
       '@img/sharp-win32-ia32': 0.34.5
       '@img/sharp-win32-x64': 0.34.5
 
+  siginfo@2.0.0: {}
+
   source-map-js@1.2.1: {}
 
+  stackback@0.0.2: {}
+
+  std-env@4.1.0: {}
+
   tailwindcss@4.2.2: {}
 
   tapable@2.3.2: {}
 
+  tinybench@2.9.0: {}
+
+  tinyexec@1.2.4: {}
+
   tinyglobby@0.2.15:
     dependencies:
       fdir: 6.5.0(picomatch@4.0.4)
       picomatch: 4.0.4
 
+  tinyrainbow@3.1.0: {}
+
   tslib@2.8.1: {}
 
   typescript@5.8.3: {}
@@ -2233,6 +2515,38 @@ snapshots:
       jiti: 2.6.1
       lightningcss: 1.32.0
 
+  vitest@4.1.9(@types/node@26.0.1)(vite@7.3.1(@types/node@26.0.1)(jiti@2.6.1)(lightningcss@1.32.0)):
+    dependencies:
+      '@vitest/expect': 4.1.9
+      '@vitest/mocker': 4.1.9(vite@7.3.1(@types/node@26.0.1)(jiti@2.6.1)(lightningcss@1.32.0))
+      '@vitest/pretty-format': 4.1.9
+      '@vitest/runner': 4.1.9
+      '@vitest/snapshot': 4.1.9
+      '@vitest/spy': 4.1.9
+      '@vitest/utils': 4.1.9
+      es-module-lexer: 2.3.0
+      expect-type: 1.4.0
+      magic-string: 0.30.21
+      obug: 2.1.3
+      pathe: 2.0.3
+      picomatch: 4.0.4
+      std-env: 4.1.0
+      tinybench: 2.9.0
+      tinyexec: 1.2.4
+      tinyglobby: 0.2.15
+      tinyrainbow: 3.1.0
+      vite: 7.3.1(@types/node@26.0.1)(jiti@2.6.1)(lightningcss@1.32.0)
+      why-is-node-running: 2.3.0
+    optionalDependencies:
+      '@types/node': 26.0.1
+    transitivePeerDependencies:
+      - msw
+
+  why-is-node-running@2.3.0:
+    dependencies:
+      siginfo: 2.0.0
+      stackback: 0.0.2
+
   yallist@3.1.1: {}
 
   zustand@5.0.12(@types/react@19.2.14)(react@19.2.4):

src-tauri/Cargo.lock

@@ -4595,7 +4595,7 @@ dependencies = [
 
 [[package]]
 name = "phokus"
-version = "0.1.1"
+version = "0.2.0"
 dependencies = [
  "anyhow",
  "candle-core",

src-tauri/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "phokus"
-version = "0.1.1"
+version = "0.2.0"
 description = "Local-first desktop media library"
 authors = ["JezzWTF"]
 license = "MIT"

src-tauri/capabilities/default.json

@@ -2,7 +2,9 @@
   "$schema": "../gen/schemas/desktop-schema.json",
   "identifier": "default",
   "description": "Capability for the main window",
-  "windows": ["main"],
+  "windows": [
+    "main"
+  ],
   "permissions": [
     "core:default",
     "opener:default",
@@ -19,6 +21,8 @@
     "core:window:allow-minimize",
     "core:window:allow-close",
     "core:window:allow-toggle-maximize",
-    "core:window:allow-is-maximized"
+    "core:window:allow-is-maximized",
+    "core:window:allow-start-dragging",
+    "core:window:allow-start-resize-dragging"
   ]
 }

src-tauri/src/ai_tag_filter.rs

@@ -42,4 +42,13 @@ mod tests {
             assert!(!is_removed_ai_tag(tag), "{tag} should be kept");
         }
     }
+
+    #[test]
+    fn removed_ai_tags_tolerate_padding_and_mixed_separators() {
+        assert!(is_removed_ai_tag("  1girl  "));
+        assert!(is_removed_ai_tag("1_-_girl"));
+        assert!(is_removed_ai_tag("No Humans"));
+        assert!(!is_removed_ai_tag(""));
+        assert!(!is_removed_ai_tag("   "));
+    }
 }

src-tauri/src/captioner.rs

@@ -1,3 +1,6 @@
+use crate::onnx_runtime::{
+    self, DIRECTML_DLL_FILE, ONNX_RUNTIME_DLL_FILE, ONNX_RUNTIME_PROVIDERS_DLL_FILE,
+};
 use anyhow::Result;
 use hf_hub::{api::sync::Api, Repo, RepoType};
 use image::{imageops::FilterType, ImageReader};
@@ -8,50 +11,16 @@ use ort::session::{builder::GraphOptimizationLevel, Session};
 use ort::value::{Shape, Tensor};
 use serde::{Deserialize, Serialize};
 use std::borrow::Cow;
-use std::io::Read;
 use std::path::{Path, PathBuf};
-use std::process::Command;
 use std::sync::atomic::{AtomicBool, Ordering};
-use std::sync::Mutex;
 use std::time::Instant;
 use tokenizers::Tokenizer;
 
-// Suppress the console window when spawning curl.exe from the GUI app.
-#[cfg(target_os = "windows")]
-use std::os::windows::process::CommandExt;
-#[cfg(target_os = "windows")]
-const CREATE_NO_WINDOW: u32 = 0x08000000;
-
 pub const FLORENCE_MODEL_ID: &str = "onnx-community/Florence-2-base-ft";
 pub const FLORENCE_CAPTION_MODEL_NAME: &str = "florence-2-base-ft-onnx-q4";
-const ONNX_RUNTIME_NUGET_URL: &str =
-    "https://www.nuget.org/api/v2/package/Microsoft.ML.OnnxRuntime.DirectML/1.24.2";
-const DIRECTML_NUGET_URL: &str =
-    "https://www.nuget.org/api/v2/package/Microsoft.AI.DirectML/1.15.4";
-const ONNX_RUNTIME_DLL_FILE: &str = "onnxruntime/onnxruntime.dll";
-const ONNX_RUNTIME_PROVIDERS_DLL_FILE: &str = "onnxruntime/onnxruntime_providers_shared.dll";
-const DIRECTML_DLL_FILE: &str = "onnxruntime/DirectML.dll";
 const CAPTION_ACCELERATION_FILE: &str = "settings/caption_acceleration.txt";
 const CAPTION_DETAIL_FILE: &str = "settings/caption_detail.txt";
 
-const ONNX_RUNTIME_FILES: &[(&str, &str, &str)] = &[
-    (
-        ONNX_RUNTIME_DLL_FILE,
-        ONNX_RUNTIME_NUGET_URL,
-        "runtimes/win-x64/native/onnxruntime.dll",
-    ),
-    (
-        ONNX_RUNTIME_PROVIDERS_DLL_FILE,
-        ONNX_RUNTIME_NUGET_URL,
-        "runtimes/win-x64/native/onnxruntime_providers_shared.dll",
-    ),
-    (
-        DIRECTML_DLL_FILE,
-        DIRECTML_NUGET_URL,
-        "bin/x64-win/DirectML.dll",
-    ),
-];
-
 const REQUIRED_FILES: &[&str] = &[
     ONNX_RUNTIME_DLL_FILE,
     ONNX_RUNTIME_PROVIDERS_DLL_FILE,
@@ -69,11 +38,6 @@ const REQUIRED_FILES: &[&str] = &[
     "onnx/embed_tokens_fp16.onnx",
 ];
 
-// Mutex<bool> rather than OnceLock<Result>: a failed attempt (DLL not yet
-// downloaded) must NOT be cached, or a later successful download could never
-// recover within the same app session.
-static ORT_RUNTIME_INIT: Mutex<bool> = Mutex::new(false);
-
 /// Set to `true` by `set_caption_acceleration` so the caption worker loop
 /// knows to drop its cached `FlorenceCaptioner` and reload with the new EP.
 pub static CAPTION_SESSION_DIRTY: AtomicBool = AtomicBool::new(false);
@@ -294,11 +258,11 @@ pub fn prepare_caption_model_with_progress(
         if let Some(parent) = destination.parent() {
             std::fs::create_dir_all(parent)?;
         }
-        if ONNX_RUNTIME_FILES
+        if onnx_runtime::ONNX_RUNTIME_FILES
             .iter()
             .any(|(runtime_file, _, _)| runtime_file == file)
         {
-            download_onnx_runtime_files(&local_dir)?;
+            onnx_runtime::download_onnx_runtime_files(&local_dir)?;
             completed_files = REQUIRED_FILES
                 .iter()
                 .filter(|file| local_dir.join(file).exists())
@@ -344,7 +308,7 @@ pub fn probe_caption_runtime(app_data_dir: &Path) -> Result<CaptionRuntimeProbe>
     }
 
     let local_dir = model_dir(app_data_dir);
-    ensure_onnx_runtime(&local_dir)?;
+    onnx_runtime::ensure_onnx_runtime(&local_dir)?;
     let tokenizer =
         Tokenizer::from_file(local_dir.join("tokenizer.json")).map_err(anyhow::Error::msg)?;
 
@@ -393,7 +357,7 @@ pub fn probe_caption_vision(app_data_dir: &Path, image_path: &Path) -> Result<Ca
     }
 
     let local_dir = model_dir(app_data_dir);
-    ensure_onnx_runtime(&local_dir)?;
+    onnx_runtime::ensure_onnx_runtime(&local_dir)?;
     let pixels = preprocess_image(image_path)?;
     let input_shape = vec![1, 3, 768, 768];
     let input = Tensor::from_array(([1usize, 3, 768, 768], pixels.into_boxed_slice()))
@@ -438,7 +402,7 @@ impl FlorenceCaptioner {
         }
 
         let local_dir = model_dir(app_data_dir);
-        ensure_onnx_runtime(&local_dir)?;
+        onnx_runtime::ensure_onnx_runtime(&local_dir)?;
         let tokenizer =
             Tokenizer::from_file(local_dir.join("tokenizer.json")).map_err(anyhow::Error::msg)?;
         let caption_detail = caption_detail(app_data_dir);
@@ -647,288 +611,6 @@ fn probe_vision_session(
     })
 }
 
-pub fn ensure_onnx_runtime(local_dir: &Path) -> Result<()> {
-    let mut initialized = ORT_RUNTIME_INIT
-        .lock()
-        .map_err(|_| anyhow::anyhow!("ONNX runtime init lock poisoned"))?;
-    if *initialized {
-        return Ok(());
-    }
-    let dll_path = local_dir.join(ONNX_RUNTIME_DLL_FILE);
-    if !dll_path.exists() {
-        anyhow::bail!("ONNX Runtime DLL is missing: {}", dll_path.display());
-    }
-    ort::environment::init_from(&dll_path)
-        .map_err(|error| anyhow::anyhow!(error.to_string()))?
-        .with_name("phokus-florence")
-        .commit();
-    *initialized = true;
-    Ok(())
-}
-
-/// Download any ONNX Runtime DLLs missing from `local_dir`, reporting per-file
-/// byte progress as `(short_label, downloaded_bytes, total_bytes)`.
-/// `total_bytes` is `None` when the server omits Content-Length. Unlike
-/// `ensure_onnx_runtime` (init only), this actually provisions the files —
-/// callers that can run on a clean install must call this first. The callback
-/// fires per chunk; callers should throttle.
-pub fn provision_onnx_runtime_with_progress(
-    local_dir: &Path,
-    mut on_progress: impl FnMut(&str, u64, Option<u64>),
-) -> Result<()> {
-    for (destination_file, source_url, archive_path) in ONNX_RUNTIME_FILES {
-        let destination = local_dir.join(destination_file);
-        if destination.exists() {
-            continue;
-        }
-        // Strip the "onnxruntime/" prefix for a clean label.
-        let label = destination_file
-            .rsplit('/')
-            .next()
-            .unwrap_or(destination_file);
-        download_nuget_file(
-            source_url,
-            archive_path,
-            &destination,
-            |downloaded, total| on_progress(label, downloaded, total),
-        )?;
-    }
-    Ok(())
-}
-
-/// Number of ONNX Runtime DLLs still missing from `local_dir` (for progress
-/// step counts before downloading).
-pub fn missing_onnx_runtime_count(local_dir: &Path) -> usize {
-    ONNX_RUNTIME_FILES
-        .iter()
-        .filter(|(destination_file, _, _)| !local_dir.join(destination_file).exists())
-        .count()
-}
-
-fn download_onnx_runtime_files(local_dir: &Path) -> Result<()> {
-    if !cfg!(target_os = "windows") {
-        anyhow::bail!(
-            "Florence-2 ONNX Runtime download is currently configured for Windows builds"
-        );
-    }
-
-    for (destination_file, source_url, archive_path) in ONNX_RUNTIME_FILES {
-        let destination = local_dir.join(destination_file);
-        download_nuget_file(source_url, archive_path, &destination, |_, _| {})?;
-    }
-
-    Ok(())
-}
-
-// Give up only after this many *consecutive* curl runs that download nothing;
-// a run that makes any progress resets the counter, so a large file completes
-// across however many resumes it takes. Kept low so a hard stall (e.g. a
-// broken VM NIC) fails in a couple of minutes — surfacing a retryable error —
-// rather than locking the UI on "preparing" for many minutes.
-const MAX_STALL_RETRIES: usize = 3;
-
-/// Resiliently download `url` to `destination` using the system `curl.exe`.
-///
-/// ureq's read timeout does not fire on a stalled large transfer on Windows
-/// (schannel doesn't honor the socket read timeout), so a stall there hangs
-/// forever. curl detects an inactivity stall (`--speed-time`), resumes from
-/// the partial file (`-C -`), and retries internally — the same behavior a
-/// browser gets. We monitor the `.part` file's size for the progress bar and
-/// wrap curl in an outer progress-aware retry as a backstop. The partial file
-/// survives an app restart, so a later retry continues from disk.
-pub fn download_file_resilient(
-    url: &str,
-    destination: &Path,
-    mut on_progress: impl FnMut(u64, Option<u64>),
-) -> Result<()> {
-    if let Some(parent) = destination.parent() {
-        std::fs::create_dir_all(parent)?;
-    }
-    let part = match destination.extension() {
-        Some(ext) => destination.with_extension(format!("{}.part", ext.to_string_lossy())),
-        None => destination.with_extension("part"),
-    };
-    let name = destination
-        .file_name()
-        .map(|n| n.to_string_lossy().into_owned())
-        .unwrap_or_else(|| url.to_string());
-
-    log::info!("{name}: resolving download size");
-    let total = remote_content_length(url);
-
-    // Reconcile any existing `.part` against the real size: exactly complete →
-    // finish; oversized (stale/corrupt) → discard so curl restarts cleanly
-    // (otherwise `curl -C -` would 416 forever).
-    if let Some(total) = total {
-        let size = std::fs::metadata(&part).map(|m| m.len()).unwrap_or(0);
-        if size == total {
-            std::fs::rename(&part, destination)?;
-            return Ok(());
-        }
-        if size > total {
-            let _ = std::fs::remove_file(&part);
-        }
-    }
-    log::info!(
-        "{name}: downloading via curl ({} bytes)",
-        total
-            .map(|t| t.to_string())
-            .unwrap_or_else(|| "unknown size".into())
-    );
-
-    let mut stalls = 0usize;
-    loop {
-        let before = std::fs::metadata(&part).map(|m| m.len()).unwrap_or(0);
-        match run_curl_download(url, &part, total, &mut on_progress) {
-            Ok(()) => break,
-            Err(error) => {
-                let after = std::fs::metadata(&part).map(|m| m.len()).unwrap_or(0);
-                if after > before {
-                    log::warn!("{name}: curl interrupted at {after} bytes, resuming: {error}");
-                    stalls = 0;
-                } else {
-                    stalls += 1;
-                    log::warn!(
-                        "{name}: curl made no progress ({stalls}/{MAX_STALL_RETRIES}): {error}"
-                    );
-                    if stalls >= MAX_STALL_RETRIES {
-                        // Discard the partial so a future attempt restarts clean
-                        // rather than getting stuck re-resuming a bad file.
-                        let _ = std::fs::remove_file(&part);
-                        return Err(error);
-                    }
-                }
-                std::thread::sleep(std::time::Duration::from_secs(2));
-            }
-        }
-    }
-
-    if let Some(total) = total {
-        let got = std::fs::metadata(&part).map(|m| m.len()).unwrap_or(0);
-        if got < total {
-            anyhow::bail!("{name}: incomplete after curl ({got}/{total} bytes)");
-        }
-    }
-    std::fs::rename(&part, destination)?;
-    Ok(())
-}
-
-/// Size probe via `curl -r 0-0` (a 1-byte Range request), parsing the total
-/// from the `Content-Range: bytes 0-0/<total>` header. Uses curl rather than
-/// ureq so no part of the download path depends on ureq (which hangs on this
-/// VM's TLS stack). Returns None if the server doesn't report a size.
-fn remote_content_length(url: &str) -> Option<u64> {
-    let mut command = Command::new("curl.exe");
-    command.args([
-        "-sL",
-        "-r",
-        "0-0",
-        "-D",
-        "-",
-        "-o",
-        "NUL",
-        "--connect-timeout",
-        "30",
-        "--max-time",
-        "30",
-        url,
-    ]);
-    #[cfg(target_os = "windows")]
-    command.creation_flags(CREATE_NO_WINDOW);
-    let output = command.output().ok()?;
-    let headers = String::from_utf8_lossy(&output.stdout);
-    for line in headers.lines() {
-        if let Some(rest) = line.to_ascii_lowercase().strip_prefix("content-range:") {
-            if let Some(total) = rest.rsplit('/').next().map(str::trim) {
-                if let Ok(n) = total.parse::<u64>() {
-                    return Some(n);
-                }
-            }
-        }
-    }
-    None
-}
-
-/// Run one `curl.exe` download to `dest`, resuming from any partial file, while
-/// reporting progress from the growing file size. Returns an error (leaving the
-/// partial in place) if curl exits non-zero.
-fn run_curl_download(
-    url: &str,
-    dest: &Path,
-    total: Option<u64>,
-    on_progress: &mut impl FnMut(u64, Option<u64>),
-) -> Result<()> {
-    let mut command = Command::new("curl.exe");
-    command
-        .arg("-fSL") // fail on HTTP errors, follow redirects, show errors
-        .args(["-C", "-"]) // resume from the existing output file
-        .args(["--retry", "3", "--retry-delay", "1", "--retry-connrefused"])
-        .args(["--connect-timeout", "30"])
-        // Abort (then --retry resumes) if under 1 KB/s for 30s — a real
-        // inactivity timeout, which is what ureq couldn't deliver here.
-        .args(["--speed-limit", "1024", "--speed-time", "30"])
-        .arg("-s") // no progress meter (we watch the file instead)
-        .arg("-o")
-        .arg(dest)
-        .arg(url)
-        .stdout(std::process::Stdio::null())
-        .stderr(std::process::Stdio::piped());
-    #[cfg(target_os = "windows")]
-    command.creation_flags(CREATE_NO_WINDOW);
-
-    let mut child = command
-        .spawn()
-        .map_err(|e| anyhow::anyhow!("failed to launch curl.exe (required for downloads): {e}"))?;
-
-    loop {
-        if let Some(status) = child.try_wait()? {
-            if status.success() {
-                return Ok(());
-            }
-            let mut stderr = String::new();
-            if let Some(mut pipe) = child.stderr.take() {
-                let _ = pipe.read_to_string(&mut stderr);
-            }
-            anyhow::bail!(
-                "curl exited with {}: {}",
-                status
-                    .code()
-                    .map(|c| c.to_string())
-                    .unwrap_or_else(|| "signal".into()),
-                stderr.trim()
-            );
-        }
-        let downloaded = std::fs::metadata(dest).map(|m| m.len()).unwrap_or(0);
-        on_progress(downloaded, total);
-        std::thread::sleep(std::time::Duration::from_millis(300));
-    }
-}
-
-fn download_nuget_file(
-    source_url: &str,
-    archive_path: &str,
-    destination: &Path,
-    on_progress: impl FnMut(u64, Option<u64>),
-) -> Result<()> {
-    // Download the .nupkg (a zip) resiliently, then extract the one DLL.
-    let package = destination.with_extension("nupkg");
-    download_file_resilient(source_url, &package, on_progress)?;
-
-    log::info!("extracting {archive_path} from package");
-    let file = std::fs::File::open(&package)?;
-    let mut archive = zip::ZipArchive::new(file)?;
-    let mut dll = archive.by_name(archive_path)?;
-    let temp_destination = destination.with_extension("tmp");
-    {
-        let mut out = std::fs::File::create(&temp_destination)?;
-        std::io::copy(&mut dll, &mut out)?;
-    }
-    std::fs::rename(&temp_destination, destination)?;
-    let _ = std::fs::remove_file(&package);
-    log::info!("extracted {archive_path}");
-    Ok(())
-}
-
 fn run_vision_encoder(session: &mut Session, image_path: &Path) -> Result<TensorData> {
     let pixels = preprocess_image(image_path)?;
     let input = Tensor::from_array(([1usize, 3, 768, 768], pixels.into_boxed_slice()))

src-tauri/src/commands.rs

@@ -2159,6 +2159,7 @@ pub struct SetTaggerModelParams {
 #[derive(Deserialize)]
 pub struct SetTaggerThresholdParams {
     pub threshold: f32,
+    pub model: Option<TaggerModel>,
 }
 
 #[derive(Deserialize)]
@@ -2258,7 +2259,11 @@ pub async fn set_tagger_threshold(
     params: SetTaggerThresholdParams,
 ) -> Result<f32, String> {
     let app_dir = app.path().app_data_dir().map_err(|e| e.to_string())?;
-    tagger::set_tagger_threshold(&app_dir, params.threshold).map_err(|e| e.to_string())
+    match params.model {
+        Some(model) => tagger::set_tagger_threshold_for_model(&app_dir, model, params.threshold),
+        None => tagger::set_tagger_threshold(&app_dir, params.threshold),
+    }
+    .map_err(|e| e.to_string())
 }
 
 #[tauri::command]
@@ -2400,8 +2405,8 @@ pub async fn reset_ai_tags(
             (None, false) => {
                 let mut total = 0usize;
                 for &folder_id in &requested_folder_ids {
-                    total += db::reset_ai_tags(&conn, Some(folder_id))
-                        .map_err(|e| e.to_string())?;
+                    total +=
+                        db::reset_ai_tags(&conn, Some(folder_id)).map_err(|e| e.to_string())?;
                 }
                 (total, requested_folder_ids)
             }

src-tauri/src/db.rs

@@ -303,6 +303,7 @@ pub fn migrate(conn: &Connection) -> Result<()> {
         CREATE INDEX IF NOT EXISTS idx_image_tags_image_id ON image_tags(image_id);
         CREATE INDEX IF NOT EXISTS idx_image_tags_source ON image_tags(source);
         CREATE INDEX IF NOT EXISTS idx_image_tags_tag ON image_tags(tag);
+        CREATE INDEX IF NOT EXISTS idx_image_tags_tag_image_id ON image_tags(tag, image_id);
 
         CREATE TABLE IF NOT EXISTS albums (
             id             INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -1303,6 +1304,16 @@ fn media_kind_clause(include_videos: bool) -> &'static str {
     }
 }
 
+/// Escapes `%`, `_`, and `\` so a user-supplied string can be safely embedded
+/// in a `LIKE` pattern (paired with `ESCAPE '\\'` in the query) without the
+/// wildcards being interpreted literally.
+fn escape_like_pattern(value: &str) -> String {
+    value
+        .replace('\\', "\\\\")
+        .replace('%', "\\%")
+        .replace('_', "\\_")
+}
+
 /// True if any claimable (pending, non-excluded) jobs exist in `job_table`.
 /// Used by lower-priority workers to defer to higher-priority queues.
 /// `extra_predicate` narrows the image join (e.g. videos only for metadata).
@@ -2126,7 +2137,7 @@ pub fn get_images(
         _ => "modified_at DESC NULLS LAST",
     };
 
-    let search_pattern = search.map(|value| format!("%{value}%"));
+    let search_pattern = search.map(|value| format!("%{}%", escape_like_pattern(value)));
     let favorites_flag = i64::from(favorites_only);
     let embedding_failed_flag = i64::from(embedding_failed_only);
     let tagging_failed_flag = i64::from(tagging_failed_only);
@@ -2142,7 +2153,7 @@ pub fn get_images(
                 ai_rating, ai_tagger_model, ai_tagged_at, ai_tagger_error
          FROM images
          WHERE (?1 IS NULL OR folder_id = ?1)
-           AND (?2 IS NULL OR filename LIKE ?2)
+           AND (?2 IS NULL OR filename LIKE ?2 ESCAPE '\\')
            AND (?3 IS NULL OR media_kind = ?3)
            AND (?4 = 0 OR favorite = 1)
            AND rating >= ?5
@@ -2193,7 +2204,7 @@ pub fn count_images(
     tagging_failed_only: bool,
     color: Option<(u8, u8, u8)>,
 ) -> Result<i64> {
-    let search_pattern = search.map(|value| format!("%{value}%"));
+    let search_pattern = search.map(|value| format!("%{}%", escape_like_pattern(value)));
 
     let favorites_flag = i64::from(favorites_only);
     let embedding_failed_flag = i64::from(embedding_failed_only);
@@ -2205,7 +2216,7 @@ pub fn count_images(
     let count = conn.query_row(
         "SELECT COUNT(*) FROM images
          WHERE (?1 IS NULL OR folder_id = ?1)
-           AND (?2 IS NULL OR filename LIKE ?2)
+           AND (?2 IS NULL OR filename LIKE ?2 ESCAPE '\\')
            AND (?3 IS NULL OR media_kind = ?3)
            AND (?4 = 0 OR favorite = 1)
            AND rating >= ?5
@@ -2341,7 +2352,7 @@ pub fn search_tags_autocomplete(
     folder_id: Option<i64>,
     limit: usize,
 ) -> Result<Vec<ExploreTagEntry>> {
-    let pattern = format!("%{}%", query.to_lowercase());
+    let pattern = format!("%{}%", escape_like_pattern(&query.to_lowercase()));
     let mut stmt = conn.prepare(
         "SELECT t.tag, COUNT(DISTINCT t.image_id) AS tag_count, MIN(t.image_id) AS representative_image_id,
                 MAX(CASE WHEN t.source = 'ai' THEN 1 ELSE 0 END) AS has_ai_source,
@@ -2349,7 +2360,7 @@ pub fn search_tags_autocomplete(
          FROM image_tags t
          JOIN images i ON i.id = t.image_id
          WHERE (?1 IS NULL OR i.folder_id = ?1)
-           AND LOWER(t.tag) LIKE ?2
+           AND LOWER(t.tag) LIKE ?2 ESCAPE '\\'
          GROUP BY t.tag
          ORDER BY tag_count DESC, t.tag ASC
          LIMIT ?3",
@@ -2446,7 +2457,10 @@ pub fn get_explore_tags(
     limit: usize,
 ) -> Result<Vec<ExploreTagEntry>> {
     let mut stmt = conn.prepare(
-        "SELECT t.tag, COUNT(DISTINCT t.image_id) AS tag_count, MIN(t.image_id) AS representative_image_id,
+        "WITH tag_counts AS (
+             SELECT t.tag,
+                    COUNT(DISTINCT t.image_id) AS tag_count,
+                    MIN(t.image_id) AS representative_image_id,
                     MAX(CASE WHEN t.source = 'ai' THEN 1 ELSE 0 END) AS has_ai_source,
                     MAX(CASE WHEN t.source = 'user' THEN 1 ELSE 0 END) AS has_user_source
              FROM image_tags t
@@ -2455,23 +2469,30 @@ pub fn get_explore_tags(
              GROUP BY t.tag
              HAVING COUNT(DISTINCT t.image_id) >= 1
              ORDER BY tag_count DESC, t.tag ASC
-         LIMIT ?2",
+             LIMIT ?2
+         )
+         SELECT c.tag,
+                c.tag_count,
+                c.representative_image_id,
+                i.thumbnail_path,
+                c.has_ai_source,
+                c.has_user_source
+         FROM tag_counts c
+         JOIN images i ON i.id = c.representative_image_id
+         ORDER BY c.tag_count DESC, c.tag ASC",
     )?;
 
     let rows = stmt
         .query_map(params![folder_id, limit as i64], |row| {
             let representative_image_id = row.get::<_, i64>(2)?;
-            let thumbnail_path = get_image_by_id(conn, representative_image_id)
-                .ok()
-                .and_then(|image| image.thumbnail_path);
 
             Ok(ExploreTagEntry {
                 tag: row.get(0)?,
                 count: row.get(1)?,
                 representative_image_id,
-                thumbnail_path,
-                has_ai_source: row.get::<_, i64>(3)? != 0,
-                has_user_source: row.get::<_, i64>(4)? != 0,
+                thumbnail_path: row.get(3)?,
+                has_ai_source: row.get::<_, i64>(4)? != 0,
+                has_user_source: row.get::<_, i64>(5)? != 0,
             })
         })?
         .collect::<rusqlite::Result<Vec<_>>>()?;
@@ -3254,3 +3275,492 @@ fn folder_exclusion_clause(
         .join(",");
     format!("AND {image_alias}.folder_id NOT IN ({id_list})")
 }
+
+/// Shared fixtures for unit tests across modules (db, vector, …).
+#[cfg(test)]
+pub(crate) mod test_support {
+    use super::*;
+
+    pub(crate) fn test_conn() -> Connection {
+        vector::register_sqlite_vec();
+        let conn = Connection::open_in_memory().unwrap();
+        // The r2d2 pool customizer normally sets this; mirror it so FK cascades
+        // (album deletion, folder deletion) behave like production.
+        conn.execute_batch("PRAGMA foreign_keys=ON;").unwrap();
+        migrate(&conn).unwrap();
+        vector::migrate(&conn).unwrap();
+        conn
+    }
+
+    pub(crate) fn test_image(folder_id: i64, path: &str) -> ImageRecord {
+        ImageRecord {
+            id: 0,
+            folder_id,
+            path: path.to_string(),
+            filename: path.rsplit('/').next().unwrap_or(path).to_string(),
+            thumbnail_path: None,
+            width: Some(100),
+            height: Some(100),
+            file_size: 1024,
+            created_at: None,
+            modified_at: Some("2026-01-01T00:00:00Z".into()),
+            taken_at: None,
+            mime_type: "image/jpeg".into(),
+            media_kind: "image".into(),
+            duration_ms: None,
+            video_codec: None,
+            audio_codec: None,
+            metadata_updated_at: None,
+            metadata_error: None,
+            favorite: false,
+            rating: 0,
+            embedding_status: "pending".into(),
+            embedding_model: None,
+            embedding_updated_at: None,
+            embedding_error: None,
+            generated_caption: None,
+            caption_model: None,
+            caption_updated_at: None,
+            caption_error: None,
+            ai_rating: None,
+            ai_tagger_model: None,
+            ai_tagged_at: None,
+            ai_tagger_error: None,
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::test_support::{test_conn, test_image};
+    use super::*;
+
+    #[test]
+    fn escape_like_pattern_escapes_wildcards_and_backslash() {
+        assert_eq!(escape_like_pattern("50%off"), "50\\%off");
+        assert_eq!(escape_like_pattern("a_b"), "a\\_b");
+        assert_eq!(escape_like_pattern(r"C:\images"), r"C:\\images");
+        assert_eq!(escape_like_pattern("50%_x\\"), "50\\%\\_x\\\\");
+        assert_eq!(escape_like_pattern("plain text"), "plain text");
+    }
+
+    #[test]
+    fn insert_folder_is_idempotent_per_path() {
+        let conn = test_conn();
+        let first = insert_folder(&conn, "C:/media", "media").unwrap();
+        let second = insert_folder(&conn, "C:/media", "media again").unwrap();
+        assert_eq!(first, second);
+
+        insert_folder(&conn, "C:/other", "other").unwrap();
+        let folders = get_folders(&conn).unwrap();
+        assert_eq!(folders.len(), 2);
+        assert_eq!(folders[0].name, "media");
+    }
+
+    #[test]
+    fn upsert_image_updates_in_place_and_preserves_user_state() {
+        let conn = test_conn();
+        let folder_id = insert_folder(&conn, "C:/media", "media").unwrap();
+        let mut img = test_image(folder_id, "C:/media/a.jpg");
+        let id = upsert_image(&conn, &img).unwrap();
+
+        // Simulate user state + AI state on the stored row.
+        conn.execute(
+            "UPDATE images SET favorite = 1, rating = 4, ai_tagger_model = 'wd' WHERE id = ?1",
+            [id],
+        )
+        .unwrap();
+        add_user_tag(&conn, id, "keeper").unwrap();
+        conn.execute(
+            "INSERT INTO image_tags (image_id, tag, source, ai_model, confidence, created_at)
+             VALUES (?1, 'cat', 'ai', 'wd', 0.9, datetime('now'))",
+            [id],
+        )
+        .unwrap();
+
+        img.file_size = 2048;
+        let same_id = upsert_image(&conn, &img).unwrap();
+        assert_eq!(same_id, id);
+
+        let stored = get_image_by_id(&conn, id).unwrap();
+        assert_eq!(stored.file_size, 2048);
+        // favorite/rating survive re-index; AI tag state is invalidated.
+        assert!(stored.favorite);
+        assert_eq!(stored.rating, 4);
+        assert_eq!(stored.ai_tagger_model, None);
+
+        let tags = get_image_tags(&conn, id).unwrap();
+        assert_eq!(tags.len(), 1);
+        assert_eq!(tags[0].tag, "keeper");
+        assert_eq!(tags[0].source, "user");
+    }
+
+    #[test]
+    fn get_images_applies_filters_and_agrees_with_count() {
+        let conn = test_conn();
+        let folder_a = insert_folder(&conn, "C:/a", "a").unwrap();
+        let folder_b = insert_folder(&conn, "C:/b", "b").unwrap();
+
+        upsert_image(&conn, &test_image(folder_a, "C:/a/cat.jpg")).unwrap();
+        let dog_id = upsert_image(&conn, &test_image(folder_a, "C:/a/dog.jpg")).unwrap();
+        let mut video = test_image(folder_b, "C:/b/clip.mp4");
+        video.media_kind = "video".into();
+        video.embedding_status = "failed".into();
+        upsert_image(&conn, &video).unwrap();
+        conn.execute(
+            "UPDATE images SET favorite = 1, rating = 5 WHERE id = ?1",
+            [dog_id],
+        )
+        .unwrap();
+
+        let no_filter = get_images(
+            &conn, None, None, None, false, 0, false, false, None, "name_asc", 0, 100,
+        )
+        .unwrap();
+        assert_eq!(no_filter.len(), 3);
+        assert_eq!(
+            count_images(&conn, None, None, None, false, 0, false, false, None).unwrap(),
+            3
+        );
+
+        let by_folder = get_images(
+            &conn,
+            Some(folder_a),
+            None,
+            None,
+            false,
+            0,
+            false,
+            false,
+            None,
+            "name_asc",
+            0,
+            100,
+        )
+        .unwrap();
+        assert_eq!(by_folder.len(), 2);
+
+        let by_search = get_images(
+            &conn,
+            None,
+            Some("cat"),
+            None,
+            false,
+            0,
+            false,
+            false,
+            None,
+            "name_asc",
+            0,
+            100,
+        )
+        .unwrap();
+        assert_eq!(by_search.len(), 1);
+        assert_eq!(by_search[0].filename, "cat.jpg");
+
+        let videos = get_images(
+            &conn,
+            None,
+            None,
+            Some("video"),
+            false,
+            0,
+            false,
+            false,
+            None,
+            "name_asc",
+            0,
+            100,
+        )
+        .unwrap();
+        assert_eq!(videos.len(), 1);
+
+        let favorites = get_images(
+            &conn, None, None, None, true, 0, false, false, None, "name_asc", 0, 100,
+        )
+        .unwrap();
+        assert_eq!(favorites.len(), 1);
+        assert_eq!(favorites[0].filename, "dog.jpg");
+
+        let rated = get_images(
+            &conn, None, None, None, false, 3, false, false, None, "name_asc", 0, 100,
+        )
+        .unwrap();
+        assert_eq!(rated.len(), 1);
+
+        let failed = get_images(
+            &conn, None, None, None, false, 0, true, false, None, "name_asc", 0, 100,
+        )
+        .unwrap();
+        assert_eq!(failed.len(), 1);
+        assert_eq!(failed[0].filename, "clip.mp4");
+
+        // Pagination: page size 2 then the remaining 1.
+        let page_one = get_images(
+            &conn, None, None, None, false, 0, false, false, None, "name_asc", 0, 2,
+        )
+        .unwrap();
+        let page_two = get_images(
+            &conn, None, None, None, false, 0, false, false, None, "name_asc", 2, 2,
+        )
+        .unwrap();
+        assert_eq!(page_one.len(), 2);
+        assert_eq!(page_two.len(), 1);
+        assert_eq!(page_one[0].filename, "cat.jpg");
+        assert_eq!(page_two[0].filename, "dog.jpg");
+    }
+
+    #[test]
+    fn user_tags_upgrade_ai_tags_and_survive_tag_maintenance() {
+        let conn = test_conn();
+        let folder_id = insert_folder(&conn, "C:/a", "a").unwrap();
+        let id = upsert_image(&conn, &test_image(folder_id, "C:/a/a.jpg")).unwrap();
+
+        conn.execute(
+            "INSERT INTO image_tags (image_id, tag, source, ai_model, confidence, created_at)
+             VALUES (?1, 'cat', 'ai', 'wd', 0.9, datetime('now'))",
+            [id],
+        )
+        .unwrap();
+        let upgraded = add_user_tag(&conn, id, "cat").unwrap();
+        assert_eq!(upgraded.source, "user");
+        assert_eq!(upgraded.ai_model, None);
+        assert_eq!(get_image_tags(&conn, id).unwrap().len(), 1);
+
+        let tag = add_user_tag(&conn, id, "kitty").unwrap();
+        remove_tag(&conn, tag.id).unwrap();
+        assert_eq!(get_image_tags(&conn, id).unwrap().len(), 1);
+    }
+
+    #[test]
+    fn rename_tag_merges_into_existing_tag() {
+        let conn = test_conn();
+        let folder_id = insert_folder(&conn, "C:/a", "a").unwrap();
+        let with_both = upsert_image(&conn, &test_image(folder_id, "C:/a/a.jpg")).unwrap();
+        let with_old = upsert_image(&conn, &test_image(folder_id, "C:/a/b.jpg")).unwrap();
+
+        add_user_tag(&conn, with_both, "cat").unwrap();
+        add_user_tag(&conn, with_both, "kitty").unwrap();
+        add_user_tag(&conn, with_old, "kitty").unwrap();
+
+        rename_tag(&conn, "kitty", "cat").unwrap();
+
+        let both_tags = get_image_tags(&conn, with_both).unwrap();
+        assert_eq!(both_tags.len(), 1);
+        assert_eq!(both_tags[0].tag, "cat");
+        let old_tags = get_image_tags(&conn, with_old).unwrap();
+        assert_eq!(old_tags.len(), 1);
+        assert_eq!(old_tags[0].tag, "cat");
+    }
+
+    #[test]
+    fn delete_tag_removes_it_everywhere_and_reports_count() {
+        let conn = test_conn();
+        let folder_id = insert_folder(&conn, "C:/a", "a").unwrap();
+        let first = upsert_image(&conn, &test_image(folder_id, "C:/a/a.jpg")).unwrap();
+        let second = upsert_image(&conn, &test_image(folder_id, "C:/a/b.jpg")).unwrap();
+        add_user_tag(&conn, first, "cat").unwrap();
+        add_user_tag(&conn, second, "cat").unwrap();
+        add_user_tag(&conn, second, "dog").unwrap();
+
+        assert_eq!(delete_tag(&conn, "cat").unwrap(), 2);
+        assert_eq!(get_image_tags(&conn, first).unwrap().len(), 0);
+        assert_eq!(get_image_tags(&conn, second).unwrap().len(), 1);
+    }
+
+    #[test]
+    fn album_crud_and_membership() {
+        let conn = test_conn();
+        let folder_id = insert_folder(&conn, "C:/a", "a").unwrap();
+        let first = upsert_image(&conn, &test_image(folder_id, "C:/a/a.jpg")).unwrap();
+        let second = upsert_image(&conn, &test_image(folder_id, "C:/a/b.jpg")).unwrap();
+
+        let album = create_album(&conn, "Holiday").unwrap();
+        assert_eq!(album.name, "Holiday");
+        assert_eq!(album.image_count, 0);
+
+        // Adding is idempotent.
+        assert_eq!(
+            add_images_to_album(&conn, album.id, &[first, second]).unwrap(),
+            2
+        );
+        assert_eq!(add_images_to_album(&conn, album.id, &[first]).unwrap(), 0);
+        assert_eq!(count_album_images(&conn, album.id).unwrap(), 2);
+
+        remove_images_from_album(&conn, album.id, &[first]).unwrap();
+        assert_eq!(count_album_images(&conn, album.id).unwrap(), 1);
+
+        rename_album(&conn, album.id, "Trip").unwrap();
+        assert_eq!(get_album(&conn, album.id).unwrap().name, "Trip");
+
+        delete_album(&conn, album.id).unwrap();
+        assert!(list_albums(&conn).unwrap().is_empty());
+        // Membership rows cascade away with the album.
+        let orphans: i64 = conn
+            .query_row("SELECT COUNT(*) FROM album_images", [], |row| row.get(0))
+            .unwrap();
+        assert_eq!(orphans, 0);
+    }
+
+    #[test]
+    fn backfill_enqueues_only_unqueued_unready_images() {
+        let conn = test_conn();
+        let folder_id = insert_folder(&conn, "C:/a", "a").unwrap();
+        let pending = upsert_image(&conn, &test_image(folder_id, "C:/a/a.jpg")).unwrap();
+        let mut ready = test_image(folder_id, "C:/a/b.jpg");
+        ready.embedding_status = "ready".into();
+        upsert_image(&conn, &ready).unwrap();
+        let queued = upsert_image(&conn, &test_image(folder_id, "C:/a/c.jpg")).unwrap();
+        enqueue_embedding_job(&conn, queued).unwrap();
+
+        assert_eq!(backfill_embedding_jobs(&conn).unwrap(), 1);
+        let has_job: i64 = conn
+            .query_row(
+                "SELECT COUNT(*) FROM embedding_jobs WHERE image_id = ?1",
+                [pending],
+                |row| row.get(0),
+            )
+            .unwrap();
+        assert_eq!(has_job, 1);
+    }
+
+    #[test]
+    fn retry_failed_embeddings_skips_thumbnailless_videos() {
+        let conn = test_conn();
+        let folder_id = insert_folder(&conn, "C:/a", "a").unwrap();
+        let mut failed_image = test_image(folder_id, "C:/a/a.jpg");
+        failed_image.embedding_status = "failed".into();
+        let failed_image_id = upsert_image(&conn, &failed_image).unwrap();
+
+        let mut failed_video = test_image(folder_id, "C:/a/clip.mp4");
+        failed_video.media_kind = "video".into();
+        failed_video.embedding_status = "failed".into();
+        failed_video.thumbnail_path = None;
+        upsert_image(&conn, &failed_video).unwrap();
+
+        assert_eq!(retry_failed_embedding_jobs(&conn, folder_id).unwrap(), 1);
+        let requeued = get_image_by_id(&conn, failed_image_id).unwrap();
+        assert_eq!(requeued.embedding_status, "pending");
+    }
+
+    #[test]
+    fn repair_embedding_consistency_requeues_ready_images_without_vectors() {
+        let conn = test_conn();
+        let folder_id = insert_folder(&conn, "C:/a", "a").unwrap();
+        let mut ready = test_image(folder_id, "C:/a/a.jpg");
+        ready.embedding_status = "ready".into();
+        let ready_id = upsert_image(&conn, &ready).unwrap();
+
+        let (orphaned, requeued) = repair_embedding_consistency(&conn).unwrap();
+        assert_eq!(orphaned, 0);
+        assert_eq!(requeued, 1);
+        let repaired = get_image_by_id(&conn, ready_id).unwrap();
+        assert_eq!(repaired.embedding_status, "pending");
+    }
+
+    #[test]
+    fn search_images_by_tag_is_case_insensitive_and_paginates() {
+        let conn = test_conn();
+        let folder_a = insert_folder(&conn, "C:/a", "a").unwrap();
+        let folder_b = insert_folder(&conn, "C:/b", "b").unwrap();
+        let first = upsert_image(&conn, &test_image(folder_a, "C:/a/a.jpg")).unwrap();
+        let second = upsert_image(&conn, &test_image(folder_a, "C:/a/b.jpg")).unwrap();
+        let third = upsert_image(&conn, &test_image(folder_b, "C:/b/c.jpg")).unwrap();
+        add_user_tag(&conn, first, "Cat").unwrap();
+        add_user_tag(&conn, second, "cat").unwrap();
+        add_user_tag(&conn, third, "cat").unwrap();
+        add_user_tag(&conn, third, "dog").unwrap();
+
+        // Query is trimmed and matched case-insensitively against stored tags.
+        let (all, total) =
+            search_images_by_tag(&conn, "  CAT ", None, None, false, 0, None, 10, 0).unwrap();
+        assert_eq!(total, 3);
+        assert_eq!(all.len(), 3);
+
+        let (scoped, scoped_total) =
+            search_images_by_tag(&conn, "cat", Some(folder_a), None, false, 0, None, 10, 0)
+                .unwrap();
+        assert_eq!(scoped_total, 2);
+        assert_eq!(scoped.len(), 2);
+
+        // Pagination: total stays the full count while the page shrinks.
+        let (page, page_total) =
+            search_images_by_tag(&conn, "cat", None, None, false, 0, None, 2, 2).unwrap();
+        assert_eq!(page_total, 3);
+        assert_eq!(page.len(), 1);
+
+        // Blank queries return nothing instead of matching everything.
+        let (empty, empty_total) =
+            search_images_by_tag(&conn, "   ", None, None, false, 0, None, 10, 0).unwrap();
+        assert!(empty.is_empty());
+        assert_eq!(empty_total, 0);
+    }
+
+    #[test]
+    fn update_ai_tags_replaces_ai_state_without_downgrading_user_tags() {
+        let conn = test_conn();
+        let folder_id = insert_folder(&conn, "C:/a", "a").unwrap();
+        let id = upsert_image(&conn, &test_image(folder_id, "C:/a/a.jpg")).unwrap();
+        add_user_tag(&conn, id, "cat").unwrap();
+        conn.execute(
+            "INSERT INTO image_tags (image_id, tag, source, ai_model, confidence, created_at)
+             VALUES (?1, 'stale', 'ai', 'wd', 0.5, datetime('now'))",
+            [id],
+        )
+        .unwrap();
+        enqueue_tagging_job(&conn, id).unwrap();
+
+        update_ai_tags(
+            &conn,
+            id,
+            &[("cat".into(), 0.9), ("outdoors".into(), 0.7)],
+            "general",
+            "wd",
+        )
+        .unwrap();
+
+        let tags = get_image_tags(&conn, id).unwrap();
+        assert_eq!(tags.len(), 2, "stale AI tag should be gone");
+        let cat = tags.iter().find(|tag| tag.tag == "cat").unwrap();
+        assert_eq!(cat.source, "user", "user tag must not be downgraded to ai");
+        let outdoors = tags.iter().find(|tag| tag.tag == "outdoors").unwrap();
+        assert_eq!(outdoors.source, "ai");
+        assert_eq!(outdoors.confidence, Some(0.7));
+
+        let record = get_image_by_id(&conn, id).unwrap();
+        assert_eq!(record.ai_rating.as_deref(), Some("general"));
+        assert_eq!(record.ai_tagger_model.as_deref(), Some("wd"));
+        assert_eq!(record.ai_tagger_error, None);
+
+        let pending_jobs: i64 = conn
+            .query_row(
+                "SELECT COUNT(*) FROM tagging_jobs WHERE image_id = ?1",
+                [id],
+                |row| row.get(0),
+            )
+            .unwrap();
+        assert_eq!(pending_jobs, 0, "completed job should be dequeued");
+    }
+
+    #[test]
+    fn delete_folder_cascades_images_tags_and_vectors() {
+        let conn = test_conn();
+        let folder_id = insert_folder(&conn, "C:/a", "a").unwrap();
+        let id = upsert_image(&conn, &test_image(folder_id, "C:/a/a.jpg")).unwrap();
+        add_user_tag(&conn, id, "cat").unwrap();
+        vector::upsert_embedding(&conn, id, &vec![0.5f32; vector::CLIP_VECTOR_DIM]).unwrap();
+
+        delete_folder(&conn, folder_id).unwrap();
+
+        assert!(get_folders(&conn).unwrap().is_empty());
+        let remaining_images: i64 = conn
+            .query_row("SELECT COUNT(*) FROM images", [], |row| row.get(0))
+            .unwrap();
+        assert_eq!(remaining_images, 0);
+        let remaining_tags: i64 = conn
+            .query_row("SELECT COUNT(*) FROM image_tags", [], |row| row.get(0))
+            .unwrap();
+        assert_eq!(remaining_tags, 0);
+        assert!(!vector::has_image_vector(&conn, id).unwrap());
+    }
+}

src-tauri/src/download.rs

@@ -0,0 +1,240 @@
+//! Resilient file downloads via the system `curl` binary.
+//!
+//! Used for all large model/runtime downloads (tagger models, ONNX Runtime
+//! DLLs, caption model). ureq's read timeout does not fire on a stalled large
+//! transfer on Windows (schannel doesn't honor the socket read timeout), so a
+//! stall there hangs forever. curl detects an inactivity stall
+//! (`--speed-time`), resumes from the partial file (`-C -`), and retries
+//! internally — the same behavior a browser gets.
+
+use anyhow::Result;
+use std::io::Read;
+use std::path::Path;
+use std::process::Command;
+
+// Suppress the console window when spawning curl from the GUI app.
+#[cfg(target_os = "windows")]
+use std::os::windows::process::CommandExt;
+#[cfg(target_os = "windows")]
+const CREATE_NO_WINDOW: u32 = 0x08000000;
+
+/// Discard target for curl output we only need the headers of.
+#[cfg(target_os = "windows")]
+const NULL_DEVICE: &str = "NUL";
+#[cfg(not(target_os = "windows"))]
+const NULL_DEVICE: &str = "/dev/null";
+
+/// Build a `curl` command with platform quirks applied. Windows resolves the
+/// bare name to `curl.exe` (bundled since Windows 10 1803) and needs the
+/// no-window flag; macOS ships curl; Linux is expected to have it installed.
+fn curl_command() -> Command {
+    #[allow(unused_mut)]
+    let mut command = Command::new("curl");
+    #[cfg(target_os = "windows")]
+    command.creation_flags(CREATE_NO_WINDOW);
+    command
+}
+
+// Give up only after this many *consecutive* curl runs that download nothing;
+// a run that makes any progress resets the counter, so a large file completes
+// across however many resumes it takes. Kept low so a hard stall (e.g. a
+// broken VM NIC) fails in a couple of minutes — surfacing a retryable error —
+// rather than locking the UI on "preparing" for many minutes.
+const MAX_STALL_RETRIES: usize = 3;
+
+/// Resiliently download `url` to `destination` using the system `curl`.
+///
+/// We monitor the `.part` file's size for the progress bar and wrap curl in an
+/// outer progress-aware retry as a backstop. The partial file survives an app
+/// restart, so a later retry continues from disk.
+pub fn download_file_resilient(
+    url: &str,
+    destination: &Path,
+    mut on_progress: impl FnMut(u64, Option<u64>),
+) -> Result<()> {
+    if let Some(parent) = destination.parent() {
+        std::fs::create_dir_all(parent)?;
+    }
+    let part = match destination.extension() {
+        Some(ext) => destination.with_extension(format!("{}.part", ext.to_string_lossy())),
+        None => destination.with_extension("part"),
+    };
+    let name = destination
+        .file_name()
+        .map(|n| n.to_string_lossy().into_owned())
+        .unwrap_or_else(|| url.to_string());
+
+    log::info!("{name}: resolving download size");
+    let total = remote_content_length(url);
+
+    // Reconcile any existing `.part` against the real size: exactly complete →
+    // finish; oversized (stale/corrupt) → discard so curl restarts cleanly
+    // (otherwise `curl -C -` would 416 forever).
+    if let Some(total) = total {
+        let size = std::fs::metadata(&part).map(|m| m.len()).unwrap_or(0);
+        if size == total {
+            std::fs::rename(&part, destination)?;
+            return Ok(());
+        }
+        if size > total {
+            let _ = std::fs::remove_file(&part);
+        }
+    }
+    log::info!(
+        "{name}: downloading via curl ({} bytes)",
+        total
+            .map(|t| t.to_string())
+            .unwrap_or_else(|| "unknown size".into())
+    );
+
+    let mut stalls = 0usize;
+    loop {
+        let before = std::fs::metadata(&part).map(|m| m.len()).unwrap_or(0);
+        match run_curl_download(url, &part, total, &mut on_progress) {
+            Ok(()) => break,
+            Err(error) => {
+                let after = std::fs::metadata(&part).map(|m| m.len()).unwrap_or(0);
+                if after > before {
+                    log::warn!("{name}: curl interrupted at {after} bytes, resuming: {error}");
+                    stalls = 0;
+                } else {
+                    stalls += 1;
+                    log::warn!(
+                        "{name}: curl made no progress ({stalls}/{MAX_STALL_RETRIES}): {error}"
+                    );
+                    if stalls >= MAX_STALL_RETRIES {
+                        // Discard the partial so a future attempt restarts clean
+                        // rather than getting stuck re-resuming a bad file.
+                        let _ = std::fs::remove_file(&part);
+                        return Err(error);
+                    }
+                }
+                std::thread::sleep(std::time::Duration::from_secs(2));
+            }
+        }
+    }
+
+    if let Some(total) = total {
+        let got = std::fs::metadata(&part).map(|m| m.len()).unwrap_or(0);
+        if got < total {
+            anyhow::bail!("{name}: incomplete after curl ({got}/{total} bytes)");
+        }
+    }
+    std::fs::rename(&part, destination)?;
+    Ok(())
+}
+
+/// Size probe via `curl -r 0-0` (a 1-byte Range request), parsing the total
+/// from the `Content-Range: bytes 0-0/<total>` header. Uses curl rather than
+/// ureq so no part of the download path depends on ureq (which hangs on this
+/// VM's TLS stack). Returns None if the server doesn't report a size.
+fn remote_content_length(url: &str) -> Option<u64> {
+    let mut command = curl_command();
+    command.args([
+        "-sL",
+        "-r",
+        "0-0",
+        "-D",
+        "-",
+        "-o",
+        NULL_DEVICE,
+        "--connect-timeout",
+        "30",
+        "--max-time",
+        "30",
+        "--",
+        url,
+    ]);
+    let output = command.output().ok()?;
+    let headers = String::from_utf8_lossy(&output.stdout);
+    for line in headers.lines() {
+        if let Some(rest) = line.to_ascii_lowercase().strip_prefix("content-range:") {
+            if let Some(total) = rest.rsplit('/').next().map(str::trim) {
+                if let Ok(n) = total.parse::<u64>() {
+                    return Some(n);
+                }
+            }
+        }
+    }
+    None
+}
+
+/// Run one `curl` download to `dest`, resuming from any partial file, while
+/// reporting progress from the growing file size. Returns an error (leaving the
+/// partial in place) if curl exits non-zero.
+fn run_curl_download(
+    url: &str,
+    dest: &Path,
+    total: Option<u64>,
+    on_progress: &mut impl FnMut(u64, Option<u64>),
+) -> Result<()> {
+    let mut command = curl_command();
+    command
+        .arg("-fSL") // fail on HTTP errors, follow redirects, show errors
+        .args(["-C", "-"]) // resume from the existing output file
+        .args(["--retry", "3", "--retry-delay", "1", "--retry-connrefused"])
+        .args(["--connect-timeout", "30"])
+        // Abort (then --retry resumes) if under 1 KB/s for 30s — a real
+        // inactivity timeout, which is what ureq couldn't deliver here.
+        .args(["--speed-limit", "1024", "--speed-time", "30"])
+        .arg("-s") // no progress meter (we watch the file instead)
+        .arg("-o")
+        .arg(dest)
+        .arg("--")
+        .arg(url)
+        .stdout(std::process::Stdio::null())
+        .stderr(std::process::Stdio::piped());
+
+    let mut child = command
+        .spawn()
+        .map_err(|e| anyhow::anyhow!("failed to launch curl (required for downloads): {e}"))?;
+
+    loop {
+        if let Some(status) = child.try_wait()? {
+            if status.success() {
+                return Ok(());
+            }
+            let mut stderr = String::new();
+            if let Some(mut pipe) = child.stderr.take() {
+                let _ = pipe.read_to_string(&mut stderr);
+            }
+            anyhow::bail!(
+                "curl exited with {}: {}",
+                status
+                    .code()
+                    .map(|c| c.to_string())
+                    .unwrap_or_else(|| "signal".into()),
+                stderr.trim()
+            );
+        }
+        let downloaded = std::fs::metadata(dest).map(|m| m.len()).unwrap_or(0);
+        on_progress(downloaded, total);
+        std::thread::sleep(std::time::Duration::from_millis(300));
+    }
+}
+
+/// Download a NuGet package (a zip) resiliently, then extract the single file
+/// at `archive_path` into `destination`.
+pub fn download_nuget_file(
+    source_url: &str,
+    archive_path: &str,
+    destination: &Path,
+    on_progress: impl FnMut(u64, Option<u64>),
+) -> Result<()> {
+    let package = destination.with_extension("nupkg");
+    download_file_resilient(source_url, &package, on_progress)?;
+
+    log::info!("extracting {archive_path} from package");
+    let file = std::fs::File::open(&package)?;
+    let mut archive = zip::ZipArchive::new(file)?;
+    let mut dll = archive.by_name(archive_path)?;
+    let temp_destination = destination.with_extension("tmp");
+    {
+        let mut out = std::fs::File::create(&temp_destination)?;
+        std::io::copy(&mut dll, &mut out)?;
+    }
+    std::fs::rename(&temp_destination, destination)?;
+    let _ = std::fs::remove_file(&package);
+    log::info!("extracted {archive_path}");
+    Ok(())
+}

src-tauri/src/indexer.rs

@@ -1995,3 +1995,42 @@ fn process_watcher_rename(
         Err(e) => log::error!("Watcher rename: post-update fetch error: {e}"),
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn supported_media_matches_known_extensions_case_insensitively() {
+        for path in ["a.jpg", "b.JPEG", "c.PNG", "d.avif", "e.mp4", "f.WEBM"] {
+            assert!(
+                is_supported_media(Path::new(path)),
+                "{path} should be supported"
+            );
+        }
+        for path in ["notes.txt", "archive.zip", "no_extension", "clip.mkv"] {
+            assert!(
+                !is_supported_media(Path::new(path)),
+                "{path} should be skipped"
+            );
+        }
+    }
+
+    #[test]
+    fn media_kind_splits_video_from_image_extensions() {
+        for ext in ["mp4", "MOV", "m4v", "webm"] {
+            assert_eq!(media_kind_for_ext(ext), "video");
+        }
+        for ext in ["jpg", "PNG", "webp", "avif"] {
+            assert_eq!(media_kind_for_ext(ext), "image");
+        }
+    }
+
+    #[test]
+    fn mime_types_map_per_extension() {
+        assert_eq!(mime_for_ext("JPG"), "image/jpeg");
+        assert_eq!(mime_for_ext("png"), "image/png");
+        assert_eq!(mime_for_ext("mov"), "video/quicktime");
+        assert_eq!(mime_for_ext("m4v"), "video/mp4");
+    }
+}

src-tauri/src/lib.rs

@@ -3,10 +3,12 @@ mod captioner;
 mod color;
 mod commands;
 mod db;
+mod download;
 mod embedder;
 mod hnsw_index;
 mod indexer;
 mod media;
+mod onnx_runtime;
 mod storage;
 mod tagger;
 mod thumbnail;

src-tauri/src/onnx_runtime.rs

@@ -0,0 +1,137 @@
+//! Shared ONNX Runtime provisioning: downloading the runtime + DirectML DLLs
+//! and initializing `ort` from them.
+//!
+//! Both ONNX consumers go through here — the tagger (live) and the Florence-2
+//! captioner (backend intact, UI disabled). The DLLs are Windows/DirectML
+//! specific; a future cross-platform build needs a per-OS runtime strategy.
+
+use crate::download;
+use anyhow::Result;
+use std::path::{Path, PathBuf};
+use std::sync::Mutex;
+
+const ONNX_RUNTIME_NUGET_URL: &str =
+    "https://www.nuget.org/api/v2/package/Microsoft.ML.OnnxRuntime.DirectML/1.24.2";
+const DIRECTML_NUGET_URL: &str =
+    "https://www.nuget.org/api/v2/package/Microsoft.AI.DirectML/1.15.4";
+
+pub const ONNX_RUNTIME_DLL_FILE: &str = "onnxruntime/onnxruntime.dll";
+pub const ONNX_RUNTIME_PROVIDERS_DLL_FILE: &str = "onnxruntime/onnxruntime_providers_shared.dll";
+pub const DIRECTML_DLL_FILE: &str = "onnxruntime/DirectML.dll";
+
+/// The shared runtime DLLs, as paths relative to [`runtime_dir`].
+pub const RUNTIME_DLLS: &[&str] = &[
+    ONNX_RUNTIME_DLL_FILE,
+    ONNX_RUNTIME_PROVIDERS_DLL_FILE,
+    DIRECTML_DLL_FILE,
+];
+
+/// `(destination_file, nuget_package_url, path_inside_package)` for each DLL.
+pub const ONNX_RUNTIME_FILES: &[(&str, &str, &str)] = &[
+    (
+        ONNX_RUNTIME_DLL_FILE,
+        ONNX_RUNTIME_NUGET_URL,
+        "runtimes/win-x64/native/onnxruntime.dll",
+    ),
+    (
+        ONNX_RUNTIME_PROVIDERS_DLL_FILE,
+        ONNX_RUNTIME_NUGET_URL,
+        "runtimes/win-x64/native/onnxruntime_providers_shared.dll",
+    ),
+    (
+        DIRECTML_DLL_FILE,
+        DIRECTML_NUGET_URL,
+        "bin/x64-win/DirectML.dll",
+    ),
+];
+
+// Mutex<bool> rather than OnceLock<Result>: a failed attempt (DLL not yet
+// downloaded) must NOT be cached, or a later successful download could never
+// recover within the same app session.
+static ORT_RUNTIME_INIT: Mutex<bool> = Mutex::new(false);
+
+/// Directory the shared runtime DLLs are provisioned into.
+///
+/// Historically the DLLs were downloaded as part of the Florence-2 caption
+/// model, so they live inside that model's directory
+/// (`models/florence-2-base-ft/onnxruntime/`). The location is kept even
+/// though the tagger is now the main consumer, so existing installs don't
+/// have to re-download the runtime.
+pub fn runtime_dir(app_data_dir: &Path) -> PathBuf {
+    crate::captioner::model_dir(app_data_dir)
+}
+
+/// Initialize `ort` from the already-downloaded runtime DLL in `local_dir`.
+/// Fails if the DLL is missing — use [`provision_onnx_runtime_with_progress`]
+/// to download it first on a clean install.
+pub fn ensure_onnx_runtime(local_dir: &Path) -> Result<()> {
+    let mut initialized = ORT_RUNTIME_INIT
+        .lock()
+        .map_err(|_| anyhow::anyhow!("ONNX runtime init lock poisoned"))?;
+    if *initialized {
+        return Ok(());
+    }
+    let dll_path = local_dir.join(ONNX_RUNTIME_DLL_FILE);
+    if !dll_path.exists() {
+        anyhow::bail!("ONNX Runtime DLL is missing: {}", dll_path.display());
+    }
+    ort::environment::init_from(&dll_path)
+        .map_err(|error| anyhow::anyhow!(error.to_string()))?
+        .with_name("phokus-florence")
+        .commit();
+    *initialized = true;
+    Ok(())
+}
+
+/// Download any ONNX Runtime DLLs missing from `local_dir`, reporting per-file
+/// byte progress as `(short_label, downloaded_bytes, total_bytes)`.
+/// `total_bytes` is `None` when the server omits Content-Length. Unlike
+/// `ensure_onnx_runtime` (init only), this actually provisions the files —
+/// callers that can run on a clean install must call this first. The callback
+/// fires per chunk; callers should throttle.
+pub fn provision_onnx_runtime_with_progress(
+    local_dir: &Path,
+    mut on_progress: impl FnMut(&str, u64, Option<u64>),
+) -> Result<()> {
+    for (destination_file, source_url, archive_path) in ONNX_RUNTIME_FILES {
+        let destination = local_dir.join(destination_file);
+        if destination.exists() {
+            continue;
+        }
+        // Strip the "onnxruntime/" prefix for a clean label.
+        let label = destination_file
+            .rsplit('/')
+            .next()
+            .unwrap_or(destination_file);
+        download::download_nuget_file(
+            source_url,
+            archive_path,
+            &destination,
+            |downloaded, total| on_progress(label, downloaded, total),
+        )?;
+    }
+    Ok(())
+}
+
+/// Number of ONNX Runtime DLLs still missing from `local_dir` (for progress
+/// step counts before downloading).
+pub fn missing_onnx_runtime_count(local_dir: &Path) -> usize {
+    ONNX_RUNTIME_FILES
+        .iter()
+        .filter(|(destination_file, _, _)| !local_dir.join(destination_file).exists())
+        .count()
+}
+
+/// Download all missing runtime DLLs without progress reporting.
+pub fn download_onnx_runtime_files(local_dir: &Path) -> Result<()> {
+    if !cfg!(target_os = "windows") {
+        anyhow::bail!("ONNX Runtime DLL download is currently configured for Windows builds");
+    }
+
+    for (destination_file, source_url, archive_path) in ONNX_RUNTIME_FILES {
+        let destination = local_dir.join(destination_file);
+        download::download_nuget_file(source_url, archive_path, &destination, |_, _| {})?;
+    }
+
+    Ok(())
+}

src-tauri/src/storage.rs

@@ -122,3 +122,53 @@ fn fallback_profile_for_path(path: &Path) -> StorageProfile {
 
     StorageProfile::Balanced
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::time::Duration;
+
+    #[test]
+    fn thumbnail_workers_scale_with_parallelism_within_clamps() {
+        assert_eq!(StorageProfile::Fast.thumbnail_workers(3), 2);
+        assert_eq!(StorageProfile::Fast.thumbnail_workers(12), 4);
+        assert_eq!(StorageProfile::Fast.thumbnail_workers(64), 4);
+        assert_eq!(StorageProfile::Balanced.thumbnail_workers(4), 2);
+        assert_eq!(StorageProfile::Balanced.thumbnail_workers(12), 3);
+        assert_eq!(StorageProfile::Balanced.thumbnail_workers(64), 3);
+        assert_eq!(StorageProfile::Conservative.thumbnail_workers(64), 1);
+    }
+
+    #[test]
+    fn adaptive_profile_tracks_scan_speed() {
+        let mut adaptive = RuntimeAdaptiveProfile::new(StorageProfile::Balanced);
+        assert_eq!(adaptive.profile(), StorageProfile::Balanced);
+
+        // 1 ms/item → fast storage.
+        adaptive.observe_scan_batch(10, Duration::from_millis(10));
+        assert_eq!(adaptive.profile(), StorageProfile::Fast);
+
+        // A very slow batch drags the EMA over the conservative threshold.
+        adaptive.observe_scan_batch(1, Duration::from_millis(100));
+        assert_eq!(adaptive.profile(), StorageProfile::Conservative);
+    }
+
+    #[test]
+    fn adaptive_profile_ignores_empty_batches() {
+        let mut adaptive = RuntimeAdaptiveProfile::new(StorageProfile::Fast);
+        adaptive.observe_scan_batch(0, Duration::from_secs(10));
+        assert_eq!(adaptive.profile(), StorageProfile::Fast);
+    }
+
+    #[test]
+    fn fallback_profile_treats_unc_paths_as_conservative() {
+        assert_eq!(
+            fallback_profile_for_path(Path::new("\\\\server\\share\\photos")),
+            StorageProfile::Conservative
+        );
+        assert_eq!(
+            fallback_profile_for_path(Path::new("C:\\photos")),
+            StorageProfile::Balanced
+        );
+    }
+}

src-tauri/src/tagger.rs

@@ -16,6 +16,7 @@ pub const WD_TAGGER_MODEL_NAME: &str = "wd-swinv2-tagger-v3";
 
 const TAGGER_ACCELERATION_FILE: &str = "settings/tagger_acceleration.txt";
 const TAGGER_THRESHOLD_FILE: &str = "settings/tagger_threshold.txt";
+const JOYTAG_THRESHOLD_FILE: &str = "settings/joytag_threshold.txt";
 const TAGGER_BATCH_SIZE_FILE: &str = "settings/tagger_batch_size.txt";
 const TAGGER_MODEL_FILE: &str = "settings/tagger_model.txt";
 
@@ -27,19 +28,9 @@ pub const JOYTAG_MODEL_NAME: &str = "joytag";
 // NCHW layout (not NHWC). These are the OpenAI CLIP normalization constants.
 const JOYTAG_MEAN: [f32; 3] = [0.481_454_66, 0.457_827_5, 0.408_210_73];
 const JOYTAG_STD: [f32; 3] = [0.268_629_54, 0.261_302_6, 0.275_777_1];
-// JoyTag's recommended detection threshold (used as the default; the user's
-// tagger_threshold setting still overrides it).
+// JoyTag's recommended detection threshold.
 const JOYTAG_DEFAULT_THRESHOLD: f32 = 0.4;
 
-// Shared ONNX Runtime DLLs (live in the caption model's `onnxruntime/` dir and
-// are reused by the tagger). The per-model weight + label files are listed by
-// `TaggerModel::download_files`.
-const TAGGER_RUNTIME_DLLS: &[&str] = &[
-    "onnxruntime/onnxruntime.dll",
-    "onnxruntime/onnxruntime_providers_shared.dll",
-    "onnxruntime/DirectML.dll",
-];
-
 // Tags in these Danbooru categories are kept in the output.
 // Category 0 = general, category 4 = character.
 // Category 9 = rating (explicit/questionable/sensitive/general) – used for
@@ -64,8 +55,8 @@ pub const TAGGER_INFER_CHUNK: usize = 4;
 /// claim the GPU/CPU between dispatches. Negligible against per-chunk inference.
 pub const TAGGER_INFER_YIELD_MS: u64 = 40;
 
-/// Set to `true` by `set_tagger_acceleration` so the tagging worker loop
-/// knows to drop its cached `WdTagger` and reload with the new EP.
+/// Set to `true` by tagger setting changes so the tagging worker loop knows to
+/// drop its cached model session and reload with the current settings.
 pub static TAGGER_SESSION_DIRTY: AtomicBool = AtomicBool::new(false);
 
 // ---------------------------------------------------------------------------
@@ -112,6 +103,20 @@ impl TaggerModel {
         }
     }
 
+    fn threshold_file(self) -> &'static str {
+        match self {
+            Self::Wd => TAGGER_THRESHOLD_FILE,
+            Self::JoyTag => JOYTAG_THRESHOLD_FILE,
+        }
+    }
+
+    fn default_threshold(self) -> f32 {
+        match self {
+            Self::Wd => DEFAULT_THRESHOLD,
+            Self::JoyTag => JOYTAG_DEFAULT_THRESHOLD,
+        }
+    }
+
     /// Hugging Face repo the model files are fetched from.
     fn repo_id(self) -> &'static str {
         match self {
@@ -280,21 +285,33 @@ pub fn set_tagger_acceleration(
     Ok(acceleration)
 }
 
-pub fn tagger_threshold(app_data_dir: &Path) -> f32 {
-    let path = app_data_dir.join(TAGGER_THRESHOLD_FILE);
+fn tagger_threshold_for_model(app_data_dir: &Path, model: TaggerModel) -> f32 {
+    let path = app_data_dir.join(model.threshold_file());
     let Ok(value) = std::fs::read_to_string(path) else {
-        return DEFAULT_THRESHOLD;
+        return model.default_threshold();
     };
     value
         .trim()
         .parse::<f32>()
-        .unwrap_or(DEFAULT_THRESHOLD)
+        .unwrap_or_else(|_| model.default_threshold())
         .clamp(0.01, 1.0)
 }
 
+pub fn tagger_threshold(app_data_dir: &Path) -> f32 {
+    tagger_threshold_for_model(app_data_dir, tagger_model(app_data_dir))
+}
+
 pub fn set_tagger_threshold(app_data_dir: &Path, threshold: f32) -> Result<f32> {
+    set_tagger_threshold_for_model(app_data_dir, tagger_model(app_data_dir), threshold)
+}
+
+pub fn set_tagger_threshold_for_model(
+    app_data_dir: &Path,
+    model: TaggerModel,
+    threshold: f32,
+) -> Result<f32> {
     let clamped = threshold.clamp(0.01, 1.0);
-    let path = app_data_dir.join(TAGGER_THRESHOLD_FILE);
+    let path = app_data_dir.join(model.threshold_file());
     if let Some(parent) = path.parent() {
         std::fs::create_dir_all(parent)?;
     }
@@ -328,12 +345,11 @@ pub fn set_tagger_batch_size(app_data_dir: &Path, batch_size: usize) -> Result<u
 pub fn tagger_model_status(app_data_dir: &Path) -> TaggerModelStatus {
     let model = tagger_model(app_data_dir);
     let local_dir = model_dir(app_data_dir);
-    // The ONNX runtime DLLs live in the caption model dir; reuse them.
-    let caption_model_dir = app_data_dir.join("models").join("florence-2-base-ft");
+    let runtime_dir = crate::onnx_runtime::runtime_dir(app_data_dir);
 
-    let mut missing_files: Vec<String> = TAGGER_RUNTIME_DLLS
+    let mut missing_files: Vec<String> = crate::onnx_runtime::RUNTIME_DLLS
         .iter()
-        .filter(|file| !caption_model_dir.join(file).exists())
+        .filter(|file| !runtime_dir.join(file).exists())
         .map(|file| (*file).to_string())
         .collect();
     missing_files.extend(
@@ -361,15 +377,14 @@ pub fn prepare_tagger_model_with_progress(
     let local_dir = model_dir(app_data_dir);
     std::fs::create_dir_all(&local_dir)?;
 
-    // The tagger shares the ONNX runtime DLLs with the captioner; download
-    // them here so the tagger works even on a clean install where the caption
-    // model has never been fetched (ensure_onnx_runtime only initializes).
+    // Download the shared ONNX Runtime DLLs here so the tagger works even on
+    // a clean install (ensure_onnx_runtime only initializes).
     let download_files = model.download_files();
-    let caption_model_dir = crate::captioner::model_dir(app_data_dir);
-    std::fs::create_dir_all(&caption_model_dir)?;
+    let runtime_dir = crate::onnx_runtime::runtime_dir(app_data_dir);
+    std::fs::create_dir_all(&runtime_dir)?;
 
     // Unified step count across DLLs and tagger files so the bar is coherent.
-    let dll_count = crate::captioner::missing_onnx_runtime_count(&caption_model_dir);
+    let dll_count = crate::onnx_runtime::missing_onnx_runtime_count(&runtime_dir);
     let model_pending = download_files
         .iter()
         .filter(|file| !local_dir.join(file).exists())
@@ -389,8 +404,8 @@ pub fn prepare_tagger_model_with_progress(
     // ── ONNX runtime DLLs (small, but non-trivial on a slow link) ──
     {
         let mut last_emit = Instant::now() - std::time::Duration::from_secs(1);
-        crate::captioner::provision_onnx_runtime_with_progress(
-            &caption_model_dir,
+        crate::onnx_runtime::provision_onnx_runtime_with_progress(
+            &runtime_dir,
             |label, downloaded, total| {
                 if last_emit.elapsed() >= std::time::Duration::from_millis(200) {
                     last_emit = Instant::now();
@@ -408,7 +423,7 @@ pub fn prepare_tagger_model_with_progress(
         completed_files += dll_count;
     }
     log::info!("Tagger: ONNX runtime DLLs ready; initializing runtime");
-    crate::captioner::ensure_onnx_runtime(&caption_model_dir)?;
+    crate::onnx_runtime::ensure_onnx_runtime(&runtime_dir)?;
     log::info!("Tagger: runtime initialized; downloading model files");
 
     // ── Tagger model files (model.onnx is ~446 MB) ──
@@ -426,7 +441,7 @@ pub fn prepare_tagger_model_with_progress(
         let url = repo.url(file);
         let label = (*file).to_string();
         let mut last_emit = Instant::now() - std::time::Duration::from_secs(1);
-        crate::captioner::download_file_resilient(&url, &destination, |downloaded, total| {
+        crate::download::download_file_resilient(&url, &destination, |downloaded, total| {
             if last_emit.elapsed() >= std::time::Duration::from_millis(200) {
                 last_emit = Instant::now();
                 emit_progress(TaggerModelProgress {
@@ -466,15 +481,15 @@ pub fn probe_tagger_runtime(app_data_dir: &Path) -> Result<TaggerRuntimeProbe> {
     let status = tagger_model_status(app_data_dir);
     if !status.ready {
         anyhow::bail!(
-            "WD Tagger model is missing {} required file(s): {}",
+            "{} is missing {} required file(s): {}",
+            status.model_name,
             status.missing_files.len(),
             status.missing_files.join(", ")
         );
     }
 
     let local_dir = model_dir(app_data_dir);
-    let caption_model_dir = app_data_dir.join("models").join("florence-2-base-ft");
-    crate::captioner::ensure_onnx_runtime(&caption_model_dir)?;
+    crate::onnx_runtime::ensure_onnx_runtime(&crate::onnx_runtime::runtime_dir(app_data_dir))?;
 
     let acceleration = tagger_acceleration(app_data_dir);
     let model_path = local_dir.join("model.onnx");
@@ -636,13 +651,11 @@ impl WdTagger {
 
         let local_dir = model_dir(app_data_dir);
 
-        // The ONNX runtime DLLs are shared with the captioner; use the
-        // captioner's shared ORT init lock to avoid double-initialisation.
-        let caption_model_dir = app_data_dir.join("models").join("florence-2-base-ft");
-        crate::captioner::ensure_onnx_runtime(&caption_model_dir).map_err(|e| {
+        let runtime_dir = crate::onnx_runtime::runtime_dir(app_data_dir);
+        crate::onnx_runtime::ensure_onnx_runtime(&runtime_dir).map_err(|e| {
             anyhow::anyhow!(
-                "ONNX Runtime not initialised — download the Florence-2 caption model first \
-                 to get the shared runtime DLLs. Original error: {e}"
+                "ONNX Runtime not initialised — the shared runtime DLLs are missing; \
+                 re-run the tagger model download. Original error: {e}"
             )
         })?;
 
@@ -829,11 +842,11 @@ impl JoyTagger {
         let local_dir = model_dir(app_data_dir);
 
         // Shared ONNX runtime DLLs (see WdTagger::new).
-        let caption_model_dir = app_data_dir.join("models").join("florence-2-base-ft");
-        crate::captioner::ensure_onnx_runtime(&caption_model_dir).map_err(|e| {
+        let runtime_dir = crate::onnx_runtime::runtime_dir(app_data_dir);
+        crate::onnx_runtime::ensure_onnx_runtime(&runtime_dir).map_err(|e| {
             anyhow::anyhow!(
-                "ONNX Runtime not initialised — download the Florence-2 caption model first \
-                 to get the shared runtime DLLs. Original error: {e}"
+                "ONNX Runtime not initialised — the shared runtime DLLs are missing; \
+                 re-run the tagger model download. Original error: {e}"
             )
         })?;
 
@@ -1056,17 +1069,10 @@ fn load_joytag_labels(path: &Path) -> Result<Vec<String>> {
     Ok(labels)
 }
 
-/// JoyTag detection threshold. Honours the shared `tagger_threshold` setting if
-/// the user has set it, otherwise uses JoyTag's recommended default (0.4).
+/// JoyTag detection threshold. Uses JoyTag's own setting so WD tuning does not
+/// leak into the general/photo-friendly model.
 fn joytag_threshold(app_data_dir: &Path) -> f32 {
-    match std::fs::read_to_string(app_data_dir.join(TAGGER_THRESHOLD_FILE)) {
-        Ok(value) => value
-            .trim()
-            .parse::<f32>()
-            .unwrap_or(JOYTAG_DEFAULT_THRESHOLD)
-            .clamp(0.01, 1.0),
-        Err(_) => JOYTAG_DEFAULT_THRESHOLD,
-    }
+    tagger_threshold_for_model(app_data_dir, TaggerModel::JoyTag)
 }
 
 fn sigmoid(x: f32) -> f32 {

src-tauri/src/thumbnail.rs

@@ -383,6 +383,26 @@ fn fit_dimensions(width: u32, height: u32, max_size: u32) -> (u32, u32) {
 mod tests {
     use super::*;
 
+    #[test]
+    fn fit_dimensions_preserves_aspect_ratio_within_max() {
+        // Already small enough: unchanged.
+        assert_eq!(fit_dimensions(100, 50, THUMB_SIZE), (100, 50));
+        // Landscape and portrait scale to the max on their long edge.
+        assert_eq!(fit_dimensions(6400, 3200, THUMB_SIZE), (320, 160));
+        assert_eq!(fit_dimensions(3200, 6400, THUMB_SIZE), (160, 320));
+        // Extreme ratios never collapse to zero.
+        assert_eq!(fit_dimensions(1, 100_000, 320), (1, 320));
+        assert_eq!(fit_dimensions(100_000, 1, 320), (320, 1));
+    }
+
+    #[test]
+    fn is_jpeg_checks_extension_only() {
+        assert!(is_jpeg(Path::new("photo.jpg")));
+        assert!(is_jpeg(Path::new("photo.JPEG")));
+        assert!(!is_jpeg(Path::new("photo.png")));
+        assert!(!is_jpeg(Path::new("photo")));
+    }
+
     #[test]
     fn scale_numerator_picks_smallest_sufficient() {
         assert_eq!(scale_numerator(6000, THUMB_SIZE), 1);

src-tauri/src/vector.rs

@@ -562,3 +562,81 @@ fn pack_f32(values: &[f32]) -> Vec<u8> {
     }
     out
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::db::test_support::{test_conn, test_image};
+
+    #[test]
+    fn pack_unpack_roundtrip() {
+        let values = vec![0.0f32, 1.5, -2.25, f32::MIN_POSITIVE, 1e10];
+        assert_eq!(unpack_f32(&pack_f32(&values)), values);
+        assert!(unpack_f32(&pack_f32(&[])).is_empty());
+    }
+
+    #[test]
+    fn upsert_embedding_rejects_wrong_dimension() {
+        let conn = test_conn();
+        let error = upsert_embedding(&conn, 1, &[0.5f32; 3]).unwrap_err();
+        assert!(error.to_string().contains("dimension"));
+    }
+
+    #[test]
+    fn upsert_and_delete_embedding_roundtrip() {
+        let conn = test_conn();
+        let embedding = vec![0.25f32; CLIP_VECTOR_DIM];
+        upsert_embedding(&conn, 42, &embedding).unwrap();
+        assert!(has_image_vector(&conn, 42).unwrap());
+
+        // Upsert replaces rather than duplicates.
+        upsert_embedding(&conn, 42, &embedding).unwrap();
+        let rows: i64 = conn
+            .query_row(
+                "SELECT COUNT(*) FROM image_vec WHERE image_id = 42",
+                [],
+                |row| row.get(0),
+            )
+            .unwrap();
+        assert_eq!(rows, 1);
+
+        delete_embedding(&conn, 42).unwrap();
+        assert!(!has_image_vector(&conn, 42).unwrap());
+    }
+
+    #[test]
+    fn find_similar_image_ids_ranks_by_cosine_distance() {
+        let conn = test_conn();
+        let folder_id = crate::db::insert_folder(&conn, "C:/a", "a").unwrap();
+        let base_id =
+            crate::db::upsert_image(&conn, &test_image(folder_id, "C:/a/base.jpg")).unwrap();
+        let close_id =
+            crate::db::upsert_image(&conn, &test_image(folder_id, "C:/a/close.jpg")).unwrap();
+        let far_id =
+            crate::db::upsert_image(&conn, &test_image(folder_id, "C:/a/far.jpg")).unwrap();
+
+        let mut base = vec![0.0f32; CLIP_VECTOR_DIM];
+        base[0] = 1.0;
+        let mut close = vec![0.0f32; CLIP_VECTOR_DIM];
+        close[0] = 1.0;
+        close[1] = 0.2;
+        let mut far = vec![0.0f32; CLIP_VECTOR_DIM];
+        far[1] = 1.0;
+        upsert_embedding(&conn, base_id, &base).unwrap();
+        upsert_embedding(&conn, close_id, &close).unwrap();
+        upsert_embedding(&conn, far_id, &far).unwrap();
+
+        // Global KNN path: nearest first, query image excluded.
+        let global = find_similar_image_ids(&conn, base_id, 2, None).unwrap();
+        assert_eq!(global, vec![close_id, far_id]);
+
+        // Folder-scoped brute-force path returns the same ranking.
+        let scoped = find_similar_image_ids(&conn, base_id, 2, Some(folder_id)).unwrap();
+        assert_eq!(scoped, vec![close_id, far_id]);
+
+        // Images without an embedding yield no matches instead of an error.
+        assert!(find_similar_image_ids(&conn, 9999, 5, None)
+            .unwrap()
+            .is_empty());
+    }
+}

src/App.tsx

@@ -1,96 +1,100 @@
-import { useEffect } from "react";
-import { useGalleryStore } from "./store";
-import { Sidebar } from "./components/Sidebar";
-import { BackgroundTasks } from "./components/BackgroundTasks";
-import { Toolbar } from "./components/Toolbar";
-import { Gallery } from "./components/Gallery";
-import { Lightbox } from "./components/Lightbox";
-import { ExploreView } from "./components/ExploreView";
-import { DuplicateFinder } from "./components/DuplicateFinder";
-import { Timeline } from "./components/Timeline";
-import { TitleBar } from "./components/TitleBar";
-import { SettingsModal } from "./components/SettingsModal";
-import { FolderPickerModal } from "./components/FolderPickerModal";
-import { UpdateToast } from "./components/UpdateToast";
-import { WhatsNewToast } from "./components/WhatsNewToast";
-import { WhatsNewModal } from "./components/WhatsNewModal";
-import { OnboardingOverlay } from "./components/onboarding/OnboardingOverlay";
-import { DemoPanel } from "./components/DemoPanel";
-import { initializeNotifications } from "./notifications";
+import { useEffect } from 'react'
+import { useGalleryStore } from './store'
+import { Sidebar } from './components/Sidebar'
+import { BackgroundTasks } from './components/BackgroundTasks'
+import { Toolbar } from './components/Toolbar'
+import { Gallery } from './components/Gallery'
+import { Lightbox } from './components/Lightbox'
+import { ExploreView } from './components/ExploreView'
+import { DuplicateFinder } from './components/DuplicateFinder'
+import { Timeline } from './components/Timeline'
+import { TitleBar } from './components/TitleBar'
+import { SettingsModal } from './components/SettingsModal'
+import { FolderPickerModal } from './components/FolderPickerModal'
+import { UpdateToast } from './components/UpdateToast'
+import { WhatsNewToast } from './components/WhatsNewToast'
+import { WhatsNewModal } from './components/WhatsNewModal'
+import { OnboardingOverlay } from './components/onboarding/OnboardingOverlay'
+import { DemoPanel } from './dev/DemoPanel'
+import { initializeNotifications } from './notifications'
 
 export default function App() {
-  const loadFolders = useGalleryStore((state) => state.loadFolders);
-  const loadBackgroundJobProgress = useGalleryStore((state) => state.loadBackgroundJobProgress);
-  const loadImages = useGalleryStore((state) => state.loadImages);
-  const loadCaptionModelStatus = useGalleryStore((state) => state.loadCaptionModelStatus);
-  const loadDuplicateScanCache = useGalleryStore((state) => state.loadDuplicateScanCache);
-  const loadAlbums = useGalleryStore((state) => state.loadAlbums);
-  const loadMutedFolderIds = useGalleryStore((state) => state.loadMutedFolderIds);
-  const loadNotificationsPaused = useGalleryStore((state) => state.loadNotificationsPaused);
-  const loadWorkerPausesPersist = useGalleryStore((state) => state.loadWorkerPausesPersist);
-  const subscribeToProgress = useGalleryStore((state) => state.subscribeToProgress);
-  const loadAppVersion = useGalleryStore((state) => state.loadAppVersion);
-  const checkForUpdates = useGalleryStore((state) => state.checkForUpdates);
-  const loadFfmpegStatus = useGalleryStore((state) => state.loadFfmpegStatus);
-  const loadOnboardingCompleted = useGalleryStore((state) => state.loadOnboardingCompleted);
-  const initWhatsNew = useGalleryStore((state) => state.initWhatsNew);
-  const activeView = useGalleryStore((state) => state.activeView);
+  const loadFolders = useGalleryStore((state) => state.loadFolders)
+  const loadBackgroundJobProgress = useGalleryStore((state) => state.loadBackgroundJobProgress)
+  const loadImages = useGalleryStore((state) => state.loadImages)
+  const loadCaptionModelStatus = useGalleryStore((state) => state.loadCaptionModelStatus)
+  const loadTaggerModelStatus = useGalleryStore((state) => state.loadTaggerModelStatus)
+  const loadTaggerModel = useGalleryStore((state) => state.loadTaggerModel)
+  const loadDuplicateScanCache = useGalleryStore((state) => state.loadDuplicateScanCache)
+  const loadAlbums = useGalleryStore((state) => state.loadAlbums)
+  const loadMutedFolderIds = useGalleryStore((state) => state.loadMutedFolderIds)
+  const loadNotificationsPaused = useGalleryStore((state) => state.loadNotificationsPaused)
+  const loadWorkerPausesPersist = useGalleryStore((state) => state.loadWorkerPausesPersist)
+  const subscribeToProgress = useGalleryStore((state) => state.subscribeToProgress)
+  const loadAppVersion = useGalleryStore((state) => state.loadAppVersion)
+  const checkForUpdates = useGalleryStore((state) => state.checkForUpdates)
+  const loadFfmpegStatus = useGalleryStore((state) => state.loadFfmpegStatus)
+  const loadOnboardingCompleted = useGalleryStore((state) => state.loadOnboardingCompleted)
+  const initWhatsNew = useGalleryStore((state) => state.initWhatsNew)
+  const activeView = useGalleryStore((state) => state.activeView)
 
   useEffect(() => {
-    void initializeNotifications();
-    void loadMutedFolderIds();
-    void loadNotificationsPaused();
-    void loadWorkerPausesPersist();
-    void loadFfmpegStatus();
-    void loadOnboardingCompleted();
+    void initializeNotifications()
+    void loadMutedFolderIds()
+    void loadNotificationsPaused()
+    void loadWorkerPausesPersist()
+    void loadFfmpegStatus()
+    void loadOnboardingCompleted()
     // Load the app version first so the What's New toast/modal (which read
     // appVersion from the store) have it before the greeting can appear.
-    void loadAppVersion().then(() => initWhatsNew());
+    void loadAppVersion().then(() => initWhatsNew())
     // Quiet launch check — dev builds have no signed artifacts to update to.
     if (import.meta.env.PROD) {
-      void checkForUpdates({ quiet: true });
+      void checkForUpdates({ quiet: true })
     }
     loadFolders().then(async () => {
-      void loadBackgroundJobProgress();
-      void loadCaptionModelStatus();
-      void loadDuplicateScanCache();
-      await loadAlbums();
-      await loadImages(true);
-      if (import.meta.env.MODE === "ui") {
-        const { applyMockScenario } = await import("./dev/applyMockScenario");
-        applyMockScenario();
+      void loadBackgroundJobProgress()
+      void loadCaptionModelStatus()
+      void loadTaggerModel()
+      void loadTaggerModelStatus()
+      void loadDuplicateScanCache()
+      await loadAlbums()
+      await loadImages(true)
+      if (import.meta.env.MODE === 'ui') {
+        const { applyMockScenario } = await import('./dev/applyMockScenario')
+        applyMockScenario()
       }
-    });
-    let unlisten: (() => void) | undefined;
+    })
+    let unlisten: (() => void) | undefined
     subscribeToProgress().then((fn) => {
-      unlisten = fn;
-    });
+      unlisten = fn
+    })
     return () => {
-      unlisten?.();
-    };
-  }, []);
+      unlisten?.()
+    }
+  }, [])
 
   return (
-    <div className="flex h-screen flex-col bg-gray-950 text-white overflow-hidden select-none">
+    <div className="flex h-screen flex-col overflow-hidden bg-gray-950 text-white select-none">
       {/* Custom title bar — sits at the very top */}
       <TitleBar />
 
       {/* Main app content below the title bar */}
-      <div className="flex flex-1 min-h-0">
+      <div className="flex min-h-0 flex-1">
         <Sidebar />
-        <main className="flex-1 flex flex-col min-w-0">
-          {activeView === "timeline" ? (
+        <main className="flex min-w-0 flex-1 flex-col">
+          {activeView === 'timeline' ? (
             <>
               <Toolbar />
               <BackgroundTasks />
               <Timeline />
             </>
-          ) : activeView === "explore" ? (
+          ) : activeView === 'explore' ? (
             <>
               <BackgroundTasks />
               <ExploreView />
             </>
-          ) : activeView === "duplicates" ? (
+          ) : activeView === 'duplicates' ? (
             <>
               <BackgroundTasks />
               <DuplicateFinder />
@@ -114,5 +118,5 @@ export default function App() {
       <OnboardingOverlay />
       {import.meta.env.DEV && <DemoPanel />}
     </div>
-  );
+  )
 }

src/changelog.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it } from 'vitest'
+import { getChangelogForVersion } from './changelog'
+
+describe('getChangelogForVersion', () => {
+  it('returns null for a null/undefined version', () => {
+    expect(getChangelogForVersion(null)).toBeNull()
+    expect(getChangelogForVersion(undefined)).toBeNull()
+  })
+
+  it('never surfaces the in-progress Unreleased section', () => {
+    expect(getChangelogForVersion('Unreleased')).toBeNull()
+    expect(getChangelogForVersion('unreleased')).toBeNull()
+  })
+
+  it('returns null for a version with no matching entry', () => {
+    expect(getChangelogForVersion('99.9.9')).toBeNull()
+  })
+
+  it('resolves a plain released version', () => {
+    const entry = getChangelogForVersion('0.1.1')
+    expect(entry?.version).toBe('0.1.1')
+    expect(entry?.date).toBe('2026-06-23')
+  })
+
+  it('strips a leading "v" from the version string', () => {
+    expect(getChangelogForVersion('v0.1.1')?.version).toBe('0.1.1')
+  })
+
+  it('strips dev/UI-lab build suffixes so they resolve to the base version', () => {
+    expect(getChangelogForVersion('0.1.1-dev')?.version).toBe('0.1.1')
+    expect(getChangelogForVersion('0.1.1-ui')?.version).toBe('0.1.1')
+    expect(getChangelogForVersion('0.1.1-beta.1')?.version).toBe('0.1.1')
+  })
+})

src/changelog.ts

@@ -2,113 +2,175 @@
 // data so the "What's New" UI can render it nicely instead of dumping markdown.
 // Keeping the changelog as the single source of truth means there's no separate
 // per-release copy to maintain — whatever ships in CHANGELOG.md is what users see.
-import changelogRaw from "../CHANGELOG.md?raw";
+import changelogRaw from '../CHANGELOG.md?raw'
 
 export interface ChangelogItem {
   /** The bold lead-in at the start of a bullet (e.g. "Custom multi-folder picker"), if any. */
-  lead: string | null;
+  lead: string | null
   /** The remaining descriptive text. May still contain inline `code` / **bold** markers. */
-  body: string;
+  body: string
 }
 
 export interface ChangelogSection {
   /** "Added" | "Changed" | "Fixed" | "Removed" | "Deprecated" | "Security" */
-  title: string;
-  items: ChangelogItem[];
+  title: string
+  items: ChangelogItem[]
 }
 
 export interface ChangelogEntry {
-  version: string;
-  date: string | null;
-  sections: ChangelogSection[];
+  version: string
+  date: string | null
+  sections: ChangelogSection[]
 }
 
 // "## [0.1.1] — 2026-06-23" / "## [Unreleased]"
-const VERSION_HEADING = /^##\s+\[([^\]]+)\]\s*(?:[—–-]\s*(.+?)\s*)?$/;
+const VERSION_HEADING = /^##\s+\[([^\]]+)\]\s*(?:[—–-]\s*(.+?)\s*)?$/
 // "### Added"
-const SECTION_HEADING = /^###\s+(.+?)\s*$/;
+const SECTION_HEADING = /^###\s+(.+?)\s*$/
 // "- bullet text"
-const BULLET = /^[-*]\s+(.*)$/;
+const BULLET = /^[-*]\s+(.*)$/
 // Leading "**Title**" optionally followed by an em dash, used as the item's lead-in.
 // (Item text is whitespace-collapsed before matching, so no dotAll flag needed.)
-const LEAD = /^\*\*(.+?)\*\*\s*(?:[—–-]\s*)?(.*)$/;
+const LEAD = /^\*\*(.+?)\*\*\s*(?:[—–-]\s*)?(.*)$/
 
 function toItem(text: string): ChangelogItem {
-  const collapsed = text.replace(/\s+/g, " ").trim();
-  const match = collapsed.match(LEAD);
+  const collapsed = text.replace(/\s+/g, ' ').trim()
+  const match = collapsed.match(LEAD)
   if (match) {
-    return { lead: match[1].trim(), body: match[2].trim() };
+    return { lead: match[1].trim(), body: match[2].trim() }
   }
-  return { lead: null, body: collapsed };
+  return { lead: null, body: collapsed }
 }
 
 function parseChangelog(raw: string): ChangelogEntry[] {
-  const lines = raw.split(/\r?\n/);
-  const entries: ChangelogEntry[] = [];
+  const lines = raw.split(/\r?\n/)
+  const entries: ChangelogEntry[] = []
 
-  let entry: ChangelogEntry | null = null;
-  let section: ChangelogSection | null = null;
-  let buffer: string[] = [];
+  let entry: ChangelogEntry | null = null
+  let section: ChangelogSection | null = null
+  let buffer: string[] = []
 
   const flushItem = () => {
     if (section && buffer.length > 0) {
-      section.items.push(toItem(buffer.join(" ")));
+      section.items.push(toItem(buffer.join(' ')))
+    }
+    buffer = []
   }
-    buffer = [];
-  };
 
   for (const line of lines) {
-    const versionMatch = line.match(VERSION_HEADING);
+    const versionMatch = line.match(VERSION_HEADING)
     if (versionMatch) {
-      flushItem();
-      section = null;
-      entry = { version: versionMatch[1].trim(), date: versionMatch[2]?.trim() ?? null, sections: [] };
-      entries.push(entry);
-      continue;
+      flushItem()
+      section = null
+      entry = {
+        version: versionMatch[1].trim(),
+        date: versionMatch[2]?.trim() ?? null,
+        sections: [],
+      }
+      entries.push(entry)
+      continue
     }
 
     // Stop collecting once we leave the changelog body (e.g. link-reference defs at EOF).
-    if (!entry) continue;
+    if (!entry) continue
 
-    const sectionMatch = line.match(SECTION_HEADING);
+    const sectionMatch = line.match(SECTION_HEADING)
     if (sectionMatch) {
-      flushItem();
-      section = { title: sectionMatch[1].trim(), items: [] };
-      entry.sections.push(section);
-      continue;
+      flushItem()
+      section = { title: sectionMatch[1].trim(), items: [] }
+      entry.sections.push(section)
+      continue
     }
 
-    const bulletMatch = line.match(BULLET);
+    const bulletMatch = line.match(BULLET)
     if (bulletMatch) {
-      flushItem();
-      buffer.push(bulletMatch[1]);
-      continue;
+      flushItem()
+      buffer.push(bulletMatch[1])
+      continue
     }
 
-    if (line.trim() === "") {
+    if (line.trim() === '') {
       // A blank line ends a (possibly wrapped) multi-line bullet.
-      flushItem();
-      continue;
+      flushItem()
+      continue
     }
 
     // Indented continuation of the current wrapped bullet.
     if (buffer.length > 0) {
-      buffer.push(line.trim());
+      buffer.push(line.trim())
     }
   }
 
-  flushItem();
-  return entries.map((e) => ({ ...e, sections: e.sections.filter((s) => s.items.length > 0) }));
+  flushItem()
+  return entries.map((e) => ({ ...e, sections: e.sections.filter((s) => s.items.length > 0) }))
 }
 
-const ENTRIES = parseChangelog(changelogRaw);
+const ENTRIES = parseChangelog(changelogRaw)
+
+// Synthetic small release for UI Lab (`?changelog=small`). The What's New modal
+// switches layout by release size, and every real entry in CHANGELOG.md is
+// large — so the compact single-column layout can't be exercised from real
+// data. This stays below the modal's rail threshold on purpose.
+const SMALL_PREVIEW_ENTRY: ChangelogEntry = {
+  version: '0.0.0-preview',
+  date: '2026-01-01',
+  sections: [
+    {
+      title: 'Added',
+      items: [
+        {
+          lead: 'Sample setting',
+          body: 'a small toggle that exists purely so this preview has an Added section.',
+        },
+      ],
+    },
+    {
+      title: 'Changed',
+      items: [
+        {
+          lead: 'Snappier previews',
+          body: 'the preview fixture now loads instantly, because it is made up.',
+        },
+        { lead: null, body: 'A plain full-sentence bullet without a bold lead, for coverage.' },
+      ],
+    },
+    {
+      title: 'Fixed',
+      items: [
+        {
+          lead: 'Hotfix-sized fix',
+          body: 'a believable one-liner about a bug that never shipped.',
+        },
+        {
+          lead: 'Another small fix',
+          body: 'keeps the total item count comfortably under the rail threshold.',
+        },
+      ],
+    },
+  ],
+}
+
+// UI Lab affordance (browser-only `ui` mode): `?changelog=` previews an entry
+// other than the running version's, mirroring the `?scenario=` pattern.
+//   ?changelog=unreleased — the in-progress [Unreleased] notes (large release)
+//   ?changelog=small      — synthetic hotfix-sized entry (compact layout)
+//   ?changelog=0.1.1      — any specific released version
+function previewOverride(): ChangelogEntry | null {
+  if (import.meta.env.MODE !== 'ui') return null
+  const preview = new URLSearchParams(window.location.search).get('changelog')
+  if (!preview) return null
+  if (preview === 'small') return SMALL_PREVIEW_ENTRY
+  return ENTRIES.find((e) => e.version.toLowerCase() === preview.toLowerCase()) ?? null
+}
 
 export function getChangelogForVersion(version: string | null | undefined): ChangelogEntry | null {
-  if (!version) return null;
+  const override = previewOverride()
+  if (override) return override
+  if (!version) return null
   // Strip leading "v" and any build suffix (e.g. "-ui", "-dev", "-beta.1") so
   // dev/UI-lab builds still resolve to the correct changelog entry.
-  const normalized = version.replace(/^v/, "").replace(/-[a-z].*/i, "");
+  const normalized = version.replace(/^v/, '').replace(/-[a-z].*/i, '')
   // Never surface the in-progress [Unreleased] section to users.
-  if (normalized.toLowerCase() === "unreleased") return null;
-  return ENTRIES.find((e) => e.version.replace(/^v/, "") === normalized) ?? null;
+  if (normalized.toLowerCase() === 'unreleased') return null
+  return ENTRIES.find((e) => e.version.replace(/^v/, '') === normalized) ?? null
 }

src/components/AlbumPicker.tsx

@@ -0,0 +1,70 @@
+import { useState } from 'react'
+import { useGalleryStore } from '../store'
+
+/**
+ * Album list plus a create-new-album form. The host decides what picking
+ * means — the bulk bar adds the current selection; a newly created album is
+ * picked immediately.
+ */
+export function AlbumPicker({ onPick }: { onPick: (albumId: number) => Promise<void> | void }) {
+  const albums = useGalleryStore((state) => state.albums)
+  const createAlbum = useGalleryStore((state) => state.createAlbum)
+  const [creating, setCreating] = useState(false)
+  const [newAlbumName, setNewAlbumName] = useState('')
+
+  const handleCreate = async () => {
+    const name = newAlbumName.trim()
+    if (!name || creating) return
+    setCreating(true)
+    try {
+      const album = await createAlbum(name)
+      setNewAlbumName('')
+      await onPick(album.id)
+    } finally {
+      setCreating(false)
+    }
+  }
+
+  return (
+    <>
+      <div className="max-h-48 overflow-y-auto">
+        {albums.length === 0 ? (
+          <p className="px-2 py-2 text-[11px] text-gray-600">No albums yet — create one below.</p>
+        ) : (
+          albums.map((album) => (
+            <button
+              key={album.id}
+              className="flex w-full items-center justify-between gap-2 rounded-md px-2 py-1.5 text-left text-xs text-gray-300 transition-colors hover:bg-white/5 hover:text-white"
+              onClick={() => void onPick(album.id)}
+            >
+              <span className="truncate">{album.name}</span>
+              <span className="shrink-0 text-[10px] text-gray-600">{album.image_count}</span>
+            </button>
+          ))
+        )}
+      </div>
+      <form
+        className="mt-1 flex gap-1 border-t border-white/[0.06] pt-2"
+        onSubmit={(event) => {
+          event.preventDefault()
+          void handleCreate()
+        }}
+      >
+        <input
+          className="min-w-0 flex-1 rounded-md border border-white/10 bg-white/5 px-2 py-1 text-xs text-white placeholder-gray-600 focus:border-white/20 focus:outline-none"
+          placeholder="New album…"
+          value={newAlbumName}
+          onChange={(event) => setNewAlbumName(event.target.value)}
+          disabled={creating}
+        />
+        <button
+          type="submit"
+          className="rounded-md border border-white/10 bg-white/5 px-2 py-1 text-xs text-gray-300 transition-colors hover:bg-white/10 hover:text-white disabled:opacity-50"
+          disabled={creating || !newAlbumName.trim()}
+        >
+          Add
+        </button>
+      </form>
+    </>
+  )
+}

src/components/BackgroundTasks.tsx

@@ -1,614 +1,155 @@
-import { useEffect, useMemo, useState } from "react";
-import { invoke } from "@tauri-apps/api/core";
-import { revealItemInDir } from "@tauri-apps/plugin-opener";
-import { useGalleryStore, WorkerKey } from "../store";
-import { Tooltip } from "./Tooltip";
-
-const WORKER_FOR_STAGE: Record<string, WorkerKey> = {
-  Thumbnails: "thumbnail",
-  Metadata: "metadata",
-  Embeddings: "embedding",
-  Tags: "tagging",
-};
-
-interface TaskStage {
-  label: string;
-  detail: string;
-  progress: number | null; // 0–100, or null for indeterminate
-  failed: boolean;
-}
-
-interface Task {
-  id: number;
-  name: string;
-  stages: TaskStage[];
-  isActive: boolean;
-  hasFailedEmbeddings: boolean;
-  hasFailedTagging: boolean;
-  hasFailedCaptions: boolean;
-  pendingMediaWork: number;
-  embeddingProcessed: number;
-  embeddingTotal: number;
-  currentFile: string | null;
-  snapshot: string;
-}
-
-interface FailedWorkerItem {
-  image_id: number;
-  filename: string;
-  path: string;
-  error: string | null;
-}
-
-function FailedWorkerItemRow({ item }: { item: FailedWorkerItem }) {
-  return (
-    <div className="flex min-w-0 items-start gap-1.5">
-      <svg className="mt-px h-2.5 w-2.5 shrink-0 text-amber-500 light-theme:text-amber-700" fill="none" viewBox="0 0 24 24" stroke="currentColor">
-        <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2.5}
-          d="M12 9v2m0 4h.01M10.29 3.86L1.82 18a2 2 0 001.71 3h16.94a2 2 0 001.71-3L13.71 3.86a2 2 0 00-3.42 0z" />
-      </svg>
-      <div className="min-w-0 flex-1">
-        <p className="truncate text-[10px] font-medium text-amber-400/80 light-theme:text-amber-700">{item.filename}</p>
-        {item.error && (
-          <p className="truncate text-[9px] text-gray-600">{item.error}</p>
-        )}
-      </div>
-      <Tooltip label="Reveal in Explorer" anchorToCursor>
-      <button
-        className="shrink-0 text-gray-700 transition-colors hover:text-gray-300 light-theme:text-gray-600 light-theme:hover:text-gray-100"
-        onClick={() => void revealItemInDir(item.path)}
-      >
-        <svg className="h-3 w-3" fill="none" viewBox="0 0 24 24" stroke="currentColor">
-          <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={1.5} d="M3 7a2 2 0 012-2h4l2 2h8a2 2 0 012 2v8a2 2 0 01-2 2H5a2 2 0 01-2-2V7z" />
-        </svg>
-      </button>
-      </Tooltip>
-    </div>
-  );
-}
+import { useEffect, useMemo, useState } from 'react'
+import { invoke } from '@tauri-apps/api/core'
+import { useGalleryStore, type WorkerKey } from '../store'
+import { BackgroundTaskSummary } from './backgroundTasks/BackgroundTaskSummary'
+import { ExpandedTaskPanel } from './backgroundTasks/ExpandedTaskPanel'
+import {
+  buildDuplicateScanTask,
+  buildFolderTasks,
+  taskHasTerminalFailure,
+  taskProgress,
+} from './backgroundTasks/taskModel'
+import type { BackgroundTask, FailedWorkerItem } from './backgroundTasks/types'
 
 export function BackgroundTasks() {
-  const folders = useGalleryStore((state) => state.folders);
-  const indexingProgress = useGalleryStore((state) => state.indexingProgress);
-  const mediaJobProgress = useGalleryStore((state) => state.mediaJobProgress);
-  const retryFailedEmbeddings = useGalleryStore((state) => state.retryFailedEmbeddings);
-  const queueTaggingJobs = useGalleryStore((state) => state.queueTaggingJobs);
-  const showFailedTagging = useGalleryStore((state) => state.showFailedTagging);
-  const duplicateScanning = useGalleryStore((state) => state.duplicateScanning);
-  const duplicateScanProgress = useGalleryStore((state) => state.duplicateScanProgress);
-  const [expanded, setExpanded] = useState(false);
-  const [dismissed, setDismissed] = useState<Record<number, string>>({});
-  const [failedEmbeddingItems, setFailedEmbeddingItems] = useState<Record<number, FailedWorkerItem[]>>({});
-  const [failedTaggingItems, setFailedTaggingItems] = useState<Record<number, FailedWorkerItem[]>>({});
-
-  const workerPaused = useGalleryStore((state) => state.workerPaused);
-  const loadWorkerStates = useGalleryStore((state) => state.loadWorkerStates);
-  const setWorkerPaused = useGalleryStore((state) => state.setWorkerPaused);
+  const folders = useGalleryStore((state) => state.folders)
+  const indexingProgress = useGalleryStore((state) => state.indexingProgress)
+  const mediaJobProgress = useGalleryStore((state) => state.mediaJobProgress)
+  const retryFailedEmbeddings = useGalleryStore((state) => state.retryFailedEmbeddings)
+  const queueTaggingJobs = useGalleryStore((state) => state.queueTaggingJobs)
+  const showFailedTagging = useGalleryStore((state) => state.showFailedTagging)
+  const duplicateScanning = useGalleryStore((state) => state.duplicateScanning)
+  const duplicateScanProgress = useGalleryStore((state) => state.duplicateScanProgress)
+  const workerPaused = useGalleryStore((state) => state.workerPaused)
+  const loadWorkerStates = useGalleryStore((state) => state.loadWorkerStates)
+  const setWorkerPaused = useGalleryStore((state) => state.setWorkerPaused)
+  const [expanded, setExpanded] = useState(false)
+  const [dismissed, setDismissed] = useState<Record<number, string>>({})
+  const [failedEmbeddingItems, setFailedEmbeddingItems] = useState<
+    Record<number, FailedWorkerItem[]>
+  >({})
+  const [failedTaggingItems, setFailedTaggingItems] = useState<Record<number, FailedWorkerItem[]>>(
+    {}
+  )
 
   useEffect(() => {
-    void loadWorkerStates();
-  }, [folders, loadWorkerStates]);
+    void loadWorkerStates()
+  }, [folders, loadWorkerStates])
 
-  // Fetch failed filenames whenever the expanded panel opens or failure counts change.
   const failedEmbeddingCounts = useMemo(
     () =>
       Object.fromEntries(
-        Object.entries(mediaJobProgress).map(([id, p]) => [id, p?.embedding_failed ?? 0]),
+        Object.entries(mediaJobProgress).map(([id, progress]) => [
+          id,
+          progress?.embedding_failed ?? 0,
+        ])
       ),
-    [mediaJobProgress],
-  );
+    [mediaJobProgress]
+  )
   const failedTaggingCounts = useMemo(
     () =>
       Object.fromEntries(
-        Object.entries(mediaJobProgress).map(([id, p]) => [id, p?.tagging_failed ?? 0]),
+        Object.entries(mediaJobProgress).map(([id, progress]) => [
+          id,
+          progress?.tagging_failed ?? 0,
+        ])
       ),
-    [mediaJobProgress],
-  );
+    [mediaJobProgress]
+  )
 
   useEffect(() => {
-    if (!expanded) return;
+    if (!expanded) return
     for (const [folderId, count] of Object.entries(failedEmbeddingCounts)) {
       if (count > 0) {
-        invoke<FailedWorkerItem[]>("get_failed_embedding_images", {
+        invoke<FailedWorkerItem[]>('get_failed_embedding_images', {
           folderId: Number(folderId),
         })
           .then((items) => setFailedEmbeddingItems((prev) => ({ ...prev, [folderId]: items })))
-          .catch(() => undefined);
+          .catch(() => undefined)
       }
     }
     for (const [folderId, count] of Object.entries(failedTaggingCounts)) {
       if (count > 0) {
-        invoke<FailedWorkerItem[]>("get_failed_tagging_images", {
+        invoke<FailedWorkerItem[]>('get_failed_tagging_images', {
           folderId: Number(folderId),
         })
           .then((items) => setFailedTaggingItems((prev) => ({ ...prev, [folderId]: items })))
-          .catch(() => undefined);
+          .catch(() => undefined)
       }
     }
-  }, [expanded, failedEmbeddingCounts, failedTaggingCounts]);
+  }, [expanded, failedEmbeddingCounts, failedTaggingCounts])
 
-  const isWorkerPaused = (folderId: number, worker: WorkerKey) => {
-    return workerPaused[folderId]?.[worker] ?? false;
-  };
+  const folderTasks = useMemo(
+    () =>
+      buildFolderTasks({
+        dismissed,
+        folders,
+        indexingProgress,
+        mediaJobProgress,
+        workerPaused,
+      }),
+    [dismissed, folders, indexingProgress, mediaJobProgress, workerPaused]
+  )
+
+  const duplicateScanTask = useMemo(
+    () => buildDuplicateScanTask(duplicateScanning, duplicateScanProgress),
+    [duplicateScanning, duplicateScanProgress]
+  )
+  const allTasks = duplicateScanTask ? [duplicateScanTask, ...folderTasks] : folderTasks
+
+  if (allTasks.length === 0) return null
+
+  const isWorkerPaused = (folderId: number, worker: WorkerKey) =>
+    workerPaused[folderId]?.[worker] ?? false
 
   const toggleWorker = (folderId: number, worker: WorkerKey) => {
-    setWorkerPaused(folderId, worker, !isWorkerPaused(folderId, worker));
-  };
-
-  const dismissTask = (id: number, snapshot: string) => {
-    if (id < 0) return; // system tasks (duplicate scan) cannot be dismissed
-    setDismissed((prev) => ({ ...prev, [id]: snapshot }));
-    setExpanded(false);
-  };
-
-  const tasks = useMemo<Task[]>(() => {
-    return folders
-      .map((folder): Task | null => {
-        const index = indexingProgress[folder.id];
-        const jobs = mediaJobProgress[folder.id];
-
-        const thumbnailPending = jobs?.thumbnail_pending ?? 0;
-        const metadataPending = jobs?.metadata_pending ?? 0;
-        const embeddingPending = jobs?.embedding_pending ?? 0;
-        const embeddingReady = jobs?.embedding_ready ?? 0;
-        const embeddingFailed = jobs?.embedding_failed ?? 0;
-        const taggingPending = jobs?.tagging_pending ?? 0;
-        const taggingReady = jobs?.tagging_ready ?? 0;
-        const taggingFailed = jobs?.tagging_failed ?? 0;
-        const captionPending = jobs?.caption_pending ?? 0;
-        const captionReady = jobs?.caption_ready ?? 0;
-        const captionFailed = jobs?.caption_failed ?? 0;
-
-        // A folder is "actively processing" when something is genuinely moving:
-        // an in-progress scan, or pending work on a worker that isn't paused.
-        // Captions have no per-folder pause toggle, so any caption work counts.
-        const paused = workerPaused[folder.id];
-        const isActive =
-          (!!index && !index.done) ||
-          (thumbnailPending > 0 && !(paused?.thumbnail ?? false)) ||
-          (metadataPending > 0 && !(paused?.metadata ?? false)) ||
-          (embeddingPending > 0 && !(paused?.embedding ?? false)) ||
-          (taggingPending > 0 && !(paused?.tagging ?? false)) ||
-          captionPending > 0;
-
-        const pendingMediaWork = thumbnailPending + metadataPending + embeddingPending + taggingPending + captionPending;
-        const embeddingProcessed = embeddingReady + embeddingFailed;
-        const embeddingTotal = embeddingProcessed + embeddingPending;
-        const taggingProcessed = taggingReady + taggingFailed;
-        const taggingTotal = taggingProcessed + taggingPending;
-        const captionProcessed = captionReady + captionFailed;
-        const captionTotal = captionProcessed + captionPending;
-        const hasFailedEmbeddings = embeddingFailed > 0;
-        const hasFailedTagging = taggingFailed > 0;
-        const hasFailedCaptions = captionFailed > 0;
-
-        if (!index && pendingMediaWork === 0 && !hasFailedEmbeddings && !hasFailedTagging && !hasFailedCaptions) return null;
-
-        const stages: TaskStage[] = [];
-
-        if (index && !index.done) {
-          const pct = index.total > 0 ? (index.indexed / index.total) * 100 : 0;
-          stages.push({
-            label: "Scanning",
-            detail: `${index.indexed.toLocaleString()} / ${index.total.toLocaleString()}`,
-            progress: pct,
-            failed: false,
-          });
+    setWorkerPaused(folderId, worker, !isWorkerPaused(folderId, worker))
   }
 
-        if (thumbnailPending > 0) {
-          stages.push({
-            label: "Thumbnails",
-            detail: thumbnailPending.toLocaleString(),
-            progress: null,
-            failed: false,
-          });
+  const dismissTask = (task: BackgroundTask) => {
+    if (task.id < 0) return
+    setDismissed((prev) => ({ ...prev, [task.id]: task.snapshot }))
+    setExpanded(false)
   }
 
-        if (metadataPending > 0) {
-          stages.push({
-            label: "Metadata",
-            detail: metadataPending.toLocaleString(),
-            progress: null,
-            failed: false,
-          });
+  const retryTask = (task: BackgroundTask) => {
+    if (task.hasFailedEmbeddings) void retryFailedEmbeddings(task.id)
+    if (task.hasFailedTagging) void queueTaggingJobs(task.id)
   }
 
-        if (embeddingPending > 0) {
-          const pct = embeddingTotal > 0 ? (embeddingProcessed / embeddingTotal) * 100 : 0;
-          stages.push({
-            label: "Embeddings",
-            detail: `${embeddingProcessed.toLocaleString()} / ${embeddingTotal.toLocaleString()}`,
-            progress: pct,
-            failed: false,
-          });
-        }
-
-        if (taggingPending > 0) {
-          const pct = taggingTotal > 0 ? (taggingProcessed / taggingTotal) * 100 : 0;
-          stages.push({
-            label: "Tags",
-            detail: `${taggingProcessed.toLocaleString()} / ${taggingTotal.toLocaleString()}`,
-            progress: pct,
-            failed: false,
-          });
-        }
-
-        if (captionPending > 0) {
-          const pct = captionTotal > 0 ? (captionProcessed / captionTotal) * 100 : 0;
-          stages.push({
-            label: "Captions",
-            detail: `${captionProcessed.toLocaleString()} / ${captionTotal.toLocaleString()}`,
-            progress: pct,
-            failed: false,
-          });
-        }
-
-        if (hasFailedEmbeddings && pendingMediaWork === 0) {
-          stages.push({
-            label: "Failed",
-            detail: `${embeddingFailed.toLocaleString()} embeddings`,
-            progress: null,
-            failed: true,
-          });
-        }
-
-        if (hasFailedTagging && pendingMediaWork === 0) {
-          stages.push({
-            label: "Failed",
-            detail: `${taggingFailed.toLocaleString()} tags`,
-            progress: null,
-            failed: true,
-          });
-        }
-
-        if (hasFailedCaptions && pendingMediaWork === 0) {
-          stages.push({
-            label: "Failed",
-            detail: `${captionFailed.toLocaleString()} captions`,
-            progress: null,
-            failed: true,
-          });
-        }
-
-        const snapshot = `${pendingMediaWork}:${embeddingFailed}:${taggingFailed}:${captionFailed}`;
-
-        return {
-          id: folder.id,
-          name: folder.name,
-          stages,
-          isActive,
-          hasFailedEmbeddings,
-          hasFailedTagging,
-          hasFailedCaptions,
-          pendingMediaWork,
-          embeddingProcessed,
-          embeddingTotal,
-          currentFile: index && !index.done ? (index.current_file || null) : null,
-          snapshot,
-        };
-      })
-      .filter((t): t is Task => t !== null)
-      .filter((t) => dismissed[t.id] !== t.snapshot)
-      // Surface actively-processing folders first so a paused folder never holds
-      // the primary (collapsed) slot while another is genuinely working. Array
-      // sort is stable, so folders within each group keep their existing order.
-      .sort((a, b) => Number(b.isActive) - Number(a.isActive));
-  }, [folders, indexingProgress, mediaJobProgress, workerPaused, dismissed]);
-
-  // Synthetic task for duplicate scanning — negative id so dismiss/retry are suppressed
-  const duplicateScanTask: Task | null = duplicateScanning ? {
-    id: -1,
-    name: "Duplicate Scan",
-    stages: [{
-      label: duplicateScanProgress?.phase === "checking"
-        ? "Checking"
-        : duplicateScanProgress?.phase === "confirming"
-          ? "Confirming"
-          : "Hashing",
-      detail: duplicateScanProgress
-        ? `${duplicateScanProgress.processed.toLocaleString()} / ${duplicateScanProgress.total.toLocaleString()}${duplicateScanProgress.skipped > 0 ? ` · ${duplicateScanProgress.skipped.toLocaleString()} skipped` : ""}`
-        : "Starting…",
-      progress: duplicateScanProgress && duplicateScanProgress.total > 0
-        ? (duplicateScanProgress.processed / duplicateScanProgress.total) * 100
-        : null,
-      failed: false,
-    }],
-    isActive: true,
-    hasFailedEmbeddings: false,
-    hasFailedTagging: false,
-    hasFailedCaptions: false,
-    pendingMediaWork: 1,
-    embeddingProcessed: 0,
-    embeddingTotal: 0,
-    currentFile: null,
-    snapshot: "",
-  } : null;
-
-  const allTasks = duplicateScanTask ? [duplicateScanTask, ...tasks] : tasks;
-
-  if (allTasks.length === 0) return null;
-
-  const primary = allTasks[0];
-  const extraCount = allTasks.length - 1;
-  const hasFailed = tasks.some((t) => (t.hasFailedEmbeddings || t.hasFailedTagging || t.hasFailedCaptions) && t.pendingMediaWork === 0);
-
-  // Best progress bar value: use embedding progress if available (most informative),
-  // otherwise tagging progress, otherwise fall back to scanning progress, otherwise indeterminate.
-  const embeddingStage = primary.stages.find((s) => s.label === "Embeddings");
-  const taggingStage = primary.stages.find((s) => s.label === "Tags");
-  const scanningStage = primary.stages.find((s) => s.label === "Scanning");
-  const duplicateStage = primary.id === -1 ? primary.stages[0] : null;
-  const barProgress = embeddingStage?.progress ?? taggingStage?.progress ?? scanningStage?.progress ?? duplicateStage?.progress ?? null;
+  const primary = allTasks[0]
+  const hasFailed = folderTasks.some(taskHasTerminalFailure)
+  const barProgress = taskProgress(primary)
 
   return (
     <div className="shrink-0 border-b border-white/[0.06]">
-      {/* Slim bar */}
-      <div
-        className={`group flex items-center gap-3 px-5 h-11 cursor-pointer select-none transition-colors ${
-          expanded ? "bg-white/[0.03]" : "hover:bg-white/[0.02]"
-        }`}
-        onClick={() => setExpanded((v) => !v)}
-      >
-        {/* Pulse dot */}
-        <div className="relative shrink-0">
-          <div className={`h-1.5 w-1.5 rounded-full ${hasFailed ? "bg-amber-400" : "bg-blue-400"}`} />
-          <div className={`absolute inset-0 h-1.5 w-1.5 rounded-full animate-ping opacity-60 ${hasFailed ? "bg-amber-400" : "bg-blue-400"}`} />
-        </div>
-
-        {/* Folder name */}
-        <span className="text-[13px] font-medium text-white/60 shrink-0">{primary.name}</span>
-
-        {/* Stage tags — all active stages visible simultaneously */}
-        <div className="flex items-center gap-1.5 flex-1 min-w-0 overflow-hidden">
-          {primary.stages.map((stage) => {
-            const workerKey = WORKER_FOR_STAGE[stage.label];
-            const isPaused = workerKey ? isWorkerPaused(primary.id, workerKey) : false;
-            return (
-              <span
-                key={stage.label}
-                className={`flex items-center gap-1 rounded-md px-2 py-0.5 text-[11px] shrink-0 ${
-                  stage.failed
-                    ? "bg-amber-500/10 text-amber-400 light-theme:border light-theme:border-amber-500/40 light-theme:bg-amber-100 light-theme:text-amber-700"
-                    : isPaused
-                      ? "bg-white/4 text-gray-600"
-                      : "bg-white/5 text-gray-400"
-                }`}
-              >
-                <span>{stage.label}</span>
-                <span className={`tabular-nums ${stage.failed ? "text-amber-500 light-theme:text-amber-700" : isPaused ? "text-gray-700" : "text-gray-600"}`}>
-                  {stage.detail}
-                </span>
-                {workerKey && (
-                  <Tooltip label={isPaused ? `Resume ${stage.label}` : `Pause ${stage.label}`} anchorToCursor>
-                  <button
-                    className="ml-0.5 opacity-0 group-hover:opacity-100 hover:text-white transition-opacity"
-                    onClick={(e) => { e.stopPropagation(); toggleWorker(primary.id, workerKey); }}
-                  >
-                    {isPaused ? (
-                      <svg className="h-2.5 w-2.5" fill="currentColor" viewBox="0 0 24 24">
-                        <path d="M8 5v14l11-7z" />
-                      </svg>
-                    ) : (
-                      <svg className="h-2.5 w-2.5" fill="currentColor" viewBox="0 0 24 24">
-                        <path d="M6 19h4V5H6v14zm8-14v14h4V5h-4z" />
-                      </svg>
-                    )}
-                  </button>
-                </Tooltip>
-              )}
-              </span>
-            );
-          })}
-        </div>
-
-        {/* Progress bar — embedding or scanning progress, pulsing if indeterminate */}
-        <div className="w-24 h-px bg-white/8 rounded-full overflow-hidden shrink-0">
-          <div
-            className={`h-full rounded-full transition-all duration-500 ${
-              hasFailed
-                ? "bg-amber-400/60"
-                : barProgress === null
-                  ? "bg-blue-500/40 animate-pulse w-full"
-                  : "bg-blue-500"
-            }`}
-            style={barProgress !== null ? { width: `${barProgress}%` } : undefined}
+      <BackgroundTaskSummary
+        expanded={expanded}
+        extraCount={allTasks.length - 1}
+        hasFailed={hasFailed}
+        isWorkerPaused={isWorkerPaused}
+        onDismiss={dismissTask}
+        onLocate={showFailedTagging}
+        onRetry={retryTask}
+        onToggleExpanded={() => setExpanded((value) => !value)}
+        onToggleWorker={toggleWorker}
+        primary={primary}
+        progress={barProgress}
+        taskCount={allTasks.length}
       />
-        </div>
 
-        {/* Extra folders badge */}
-        {extraCount > 0 && (
-          <span className="rounded-full bg-white/8 px-2 py-0.5 text-[10px] text-gray-500 shrink-0">
-            +{extraCount}
-          </span>
-        )}
-
-        {primary.pendingMediaWork === 0 && (primary.hasFailedEmbeddings || primary.hasFailedTagging) && (
-          <div className="flex shrink-0 items-center gap-1.5">
-            {primary.hasFailedTagging ? (
-              <button
-                className="rounded-lg border border-amber-500/20 bg-amber-500/10 px-2.5 py-1 text-[11px] text-amber-300 transition-colors hover:bg-amber-500/20 light-theme:border-amber-500/50 light-theme:bg-amber-100 light-theme:text-amber-700 light-theme:hover:bg-amber-200"
-                onClick={(e) => { e.stopPropagation(); showFailedTagging(primary.id); }}
-              >
-                Locate
-              </button>
-            ) : null}
-            <button
-              className="rounded-lg border border-amber-500/20 bg-amber-500/10 px-2.5 py-1 text-[11px] text-amber-300 transition-colors hover:bg-amber-500/20 light-theme:border-amber-500/50 light-theme:bg-amber-100 light-theme:text-amber-700 light-theme:hover:bg-amber-200"
-              onClick={(e) => {
-                e.stopPropagation();
-                if (primary.hasFailedEmbeddings) void retryFailedEmbeddings(primary.id);
-                if (primary.hasFailedTagging) void queueTaggingJobs(primary.id);
-              }}
-            >
-              Retry
-            </button>
-          </div>
-        )}
-
-        {/* Expand chevron (only when multiple tasks) */}
-        {allTasks.length > 1 && (
-          <svg
-            className={`h-3.5 w-3.5 text-gray-600 transition-transform duration-200 shrink-0 ${expanded ? "rotate-180" : ""}`}
-            fill="none" viewBox="0 0 24 24" stroke="currentColor"
-          >
-            <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M19 9l-7 7-7-7" />
-          </svg>
-        )}
-
-        {/* Dismiss — hidden for system tasks like duplicate scan */}
-        {primary.id >= 0 && (
-          <Tooltip label="Dismiss" anchorToCursor>
-          <button
-            className="p-1 rounded-md text-gray-600 hover:text-gray-300 hover:bg-white/8 transition-colors shrink-0"
-            onClick={(e) => { e.stopPropagation(); dismissTask(primary.id, primary.snapshot); }}
-          >
-            <svg className="h-3.5 w-3.5" fill="none" viewBox="0 0 24 24" stroke="currentColor">
-              <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M6 18L18 6M6 6l12 12" />
-            </svg>
-          </button>
-        </Tooltip>
-      )}
-      </div>
-
-      {/* Expanded panel — one row per folder */}
-      {expanded && (
-        <div className="border-t border-white/[0.06] bg-white/[0.02] px-5 py-3 space-y-3">
-          {allTasks.map((task) => {
-            const taskEmbeddingStage = task.stages.find((s) => s.label === "Embeddings");
-            const taskTaggingStage = task.stages.find((s) => s.label === "Tags");
-            const taskScanningStage = task.stages.find((s) => s.label === "Scanning");
-            const taskDuplicateStage = task.id === -1 ? task.stages[0] : null;
-            const taskBarProgress = taskEmbeddingStage?.progress ?? taskTaggingStage?.progress ?? taskScanningStage?.progress ?? taskDuplicateStage?.progress ?? null;
-            const taskHasFailed = (task.hasFailedEmbeddings || task.hasFailedTagging || task.hasFailedCaptions) && task.pendingMediaWork === 0;
-
-            return (
-              <div key={task.id}>
-                <div className="flex items-center gap-3">
-                  <span className="text-[12px] text-white/50 w-28 truncate shrink-0">{task.name}</span>
-
-                  <div className="flex items-center gap-1.5 flex-1 min-w-0 overflow-hidden">
-                    {task.stages.map((stage) => {
-                      const workerKey = WORKER_FOR_STAGE[stage.label];
-                      const isPaused = workerKey ? isWorkerPaused(task.id, workerKey) : false;
-                      return (
-                        <span
-                          key={stage.label}
-                          className={`flex items-center gap-1 rounded-md px-2 py-0.5 text-[11px] shrink-0 ${
-                            stage.failed
-                              ? "bg-amber-500/10 text-amber-400 light-theme:border light-theme:border-amber-500/40 light-theme:bg-amber-100 light-theme:text-amber-700"
-                              : isPaused
-                                ? "bg-white/4 text-gray-600"
-                                : "bg-white/5 text-gray-500"
-                          }`}
-                        >
-                          {isPaused && (
-                            <svg className="h-2 w-2 text-gray-600" fill="currentColor" viewBox="0 0 24 24">
-                              <path d="M6 19h4V5H6v14zm8-14v14h4V5h-4z" />
-                            </svg>
-                          )}
-                          <span>{stage.label}</span>
-                          <span className={`tabular-nums ${stage.failed ? "text-amber-500 light-theme:text-amber-700" : "text-gray-600"}`}>
-                            {stage.detail}
-                          </span>
-                          {workerKey && (
-                            <Tooltip label={isPaused ? `Resume ${stage.label}` : `Pause ${stage.label}`} anchorToCursor>
-                            <button
-                              className="ml-0.5 text-gray-600 hover:text-white transition-colors"
-                              onClick={() => toggleWorker(task.id, workerKey)}
-                            >
-                              {isPaused ? (
-                                <svg className="h-2.5 w-2.5" fill="currentColor" viewBox="0 0 24 24">
-                                  <path d="M8 5v14l11-7z" />
-                                </svg>
-                              ) : (
-                                <svg className="h-2.5 w-2.5" fill="currentColor" viewBox="0 0 24 24">
-                                  <path d="M6 19h4V5H6v14zm8-14v14h4V5h-4z" />
-                                </svg>
-                              )}
-                            </button>
-                          </Tooltip>
-                        )}
-                        </span>
-                      );
-                    })}
-                  </div>
-
-                  <div className="w-20 h-px bg-white/8 rounded-full overflow-hidden shrink-0">
-                    <div
-                      className={`h-full rounded-full transition-all duration-500 ${
-                        taskHasFailed
-                          ? "bg-amber-400/60"
-                          : taskBarProgress === null
-                            ? "bg-blue-500/40 animate-pulse w-full"
-                            : "bg-blue-500"
-                      }`}
-                      style={taskBarProgress !== null ? { width: `${taskBarProgress}%` } : undefined}
+      {expanded ? (
+        <ExpandedTaskPanel
+          failedEmbeddingItems={failedEmbeddingItems}
+          failedTaggingItems={failedTaggingItems}
+          isWorkerPaused={isWorkerPaused}
+          onDismiss={dismissTask}
+          onLocate={showFailedTagging}
+          onRetry={retryTask}
+          onToggleWorker={toggleWorker}
+          tasks={allTasks}
         />
-                  </div>
-
-                  {taskHasFailed && (
-                    <div className="flex shrink-0 items-center gap-1.5">
-                      {task.hasFailedTagging ? (
-                        <button
-                          className="rounded-lg border border-amber-500/20 bg-amber-500/10 px-2 py-0.5 text-[11px] text-amber-300 transition-colors hover:bg-amber-500/20 light-theme:border-amber-500/50 light-theme:bg-amber-100 light-theme:text-amber-700 light-theme:hover:bg-amber-200"
-                          onClick={() => showFailedTagging(task.id)}
-                        >
-                          Locate
-                        </button>
       ) : null}
-                      <button
-                        className="rounded-lg border border-amber-500/20 bg-amber-500/10 px-2 py-0.5 text-[11px] text-amber-300 transition-colors hover:bg-amber-500/20 light-theme:border-amber-500/50 light-theme:bg-amber-100 light-theme:text-amber-700 light-theme:hover:bg-amber-200"
-                        onClick={() => {
-                          if (task.hasFailedEmbeddings) void retryFailedEmbeddings(task.id);
-                          if (task.hasFailedTagging) void queueTaggingJobs(task.id);
-                        }}
-                      >
-                        Retry
-                      </button>
     </div>
-                  )}
-
-                  {task.id >= 0 && (
-                    <Tooltip label="Dismiss" anchorToCursor>
-                    <button
-                      className="p-1 rounded-md text-gray-600 hover:text-gray-300 hover:bg-white/8 transition-colors shrink-0"
-                      onClick={() => dismissTask(task.id, task.snapshot)}
-                    >
-                      <svg className="h-3 w-3" fill="none" viewBox="0 0 24 24" stroke="currentColor">
-                        <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M6 18L18 6M6 6l12 12" />
-                      </svg>
-                    </button>
-                    </Tooltip>
-                  )}
-                </div>
-
-                {task.currentFile && (
-                  <p className="text-[10px] text-gray-600 truncate mt-1 pl-[calc(7rem+0.75rem)]">
-                    {task.currentFile}
-                  </p>
-                )}
-
-                {/* Failed worker file lists */}
-                {taskHasFailed && failedEmbeddingItems[task.id] && failedEmbeddingItems[task.id].length > 0 && (
-                  <div className="mt-2 pl-[calc(7rem+0.75rem)] space-y-0.5">
-                    {failedEmbeddingItems[task.id].map((item) => (
-                      <FailedWorkerItemRow key={item.image_id} item={item} />
-                    ))}
-                  </div>
-                )}
-                {taskHasFailed && failedTaggingItems[task.id] && failedTaggingItems[task.id].length > 0 && (
-                  <div className="mt-2 pl-[calc(7rem+0.75rem)] space-y-0.5">
-                    {failedTaggingItems[task.id].map((item) => (
-                      <FailedWorkerItemRow key={item.image_id} item={item} />
-                    ))}
-                  </div>
-                )}
-              </div>
-            );
-          })}
-        </div>
-      )}
-    </div>
-  );
+  )
 }

src/components/BulkActionBar.tsx

@@ -1,89 +1,67 @@
-import { useEffect, useRef, useState } from "react";
-import { useGalleryStore } from "../store";
-import { BulkTagPopover } from "./bulk/BulkTagPopover";
-import { Tooltip } from "./Tooltip"
-
-type Panel = "tag" | "rating" | "album" | "delete" | null;
+import { useEffect, useRef, useState } from 'react'
+import { useGalleryStore } from '../store'
+import { BulkAlbumPopover } from './bulk/BulkAlbumPopover'
+import { BulkDeleteConfirm } from './bulk/BulkDeleteConfirm'
+import { BulkRatingPopover } from './bulk/BulkRatingPopover'
+import { BulkSelectionSummary } from './bulk/BulkSelectionSummary'
+import { BulkTagPopover } from './bulk/BulkTagPopover'
+import { type BulkPanel } from './bulk/types'
+import { useDismissable } from './menu'
+import { Tooltip } from './Tooltip'
+import { CloseIcon } from './icons'
 
 export function BulkActionBar() {
-  const selectedCount = useGalleryStore((state) => state.gallerySelectedIds.size);
-  const selectedIds = useGalleryStore((state) => state.gallerySelectedIds);
-  const clearGallerySelection = useGalleryStore((state) => state.clearGallerySelection);
-  const selectAllGallery = useGalleryStore((state) => state.selectAllGallery);
-  const loadedCount = useGalleryStore((state) => state.loadedCount);
-  const totalImages = useGalleryStore((state) => state.totalImages);
-  const bulkSetFavorite = useGalleryStore((state) => state.bulkSetFavorite);
-  const bulkSetRating = useGalleryStore((state) => state.bulkSetRating);
-  const bulkDeleteSelected = useGalleryStore((state) => state.bulkDeleteSelected);
-  const activeView = useGalleryStore((state) => state.activeView);
-  const selectedAlbumId = useGalleryStore((state) => state.selectedAlbumId);
-  const albums = useGalleryStore((state) => state.albums);
-  const addToAlbum = useGalleryStore((state) => state.addToAlbum);
-  const removeFromAlbum = useGalleryStore((state) => state.removeFromAlbum);
-  const createAlbum = useGalleryStore((state) => state.createAlbum);
+  const selectedCount = useGalleryStore((state) => state.gallerySelectedIds.size)
+  const selectedIds = useGalleryStore((state) => state.gallerySelectedIds)
+  const clearGallerySelection = useGalleryStore((state) => state.clearGallerySelection)
+  const selectAllGallery = useGalleryStore((state) => state.selectAllGallery)
+  const loadedCount = useGalleryStore((state) => state.loadedCount)
+  const totalImages = useGalleryStore((state) => state.totalImages)
+  const bulkSetFavorite = useGalleryStore((state) => state.bulkSetFavorite)
+  const bulkSetRating = useGalleryStore((state) => state.bulkSetRating)
+  const bulkDeleteSelected = useGalleryStore((state) => state.bulkDeleteSelected)
+  const activeView = useGalleryStore((state) => state.activeView)
+  const selectedAlbumId = useGalleryStore((state) => state.selectedAlbumId)
+  const addToAlbum = useGalleryStore((state) => state.addToAlbum)
+  const removeFromAlbum = useGalleryStore((state) => state.removeFromAlbum)
 
-  const [panel, setPanel] = useState<Panel>(null);
-  const [deleting, setDeleting] = useState(false);
-  const [creatingAlbum, setCreatingAlbum] = useState(false);
-  const [newAlbumName, setNewAlbumName] = useState("");
-  const barRef = useRef<HTMLDivElement>(null);
+  const [panel, setPanel] = useState<BulkPanel>(null)
+  const [deleting, setDeleting] = useState(false)
+  const barRef = useRef<HTMLDivElement>(null)
 
-  // Close any open popover when clicking outside the bar.
-  useEffect(() => {
-    const onPointerDown = (event: PointerEvent) => {
-      if (barRef.current?.contains(event.target as Node)) return;
-      setPanel(null);
-    };
-    window.addEventListener("pointerdown", onPointerDown);
-    return () => window.removeEventListener("pointerdown", onPointerDown);
-  }, []);
+  // Close any open popover when clicking outside the bar or pressing Escape.
+  useDismissable(barRef, () => setPanel(null), panel !== null)
 
   // Reset transient UI whenever the selection empties.
   useEffect(() => {
-    if (selectedCount === 0) {
-      setPanel(null);
-      setNewAlbumName("");
-    }
-  }, [selectedCount]);
+    if (selectedCount === 0) setPanel(null)
+  }, [selectedCount])
 
-  if (selectedCount === 0) return null;
+  if (selectedCount === 0) return null
 
-  const ids = Array.from(selectedIds);
-  const inAlbumView = activeView === "album" && selectedAlbumId !== null;
-  const togglePanel = (next: Exclude<Panel, null>) => setPanel((current) => (current === next ? null : next));
+  const ids = Array.from(selectedIds)
+  const inAlbumView = activeView === 'album' && selectedAlbumId !== null
+  const togglePanel = (next: Exclude<BulkPanel, null>) =>
+    setPanel((current) => (current === next ? null : next))
 
   const handleDelete = async () => {
-    setDeleting(true);
+    setDeleting(true)
     try {
-      await bulkDeleteSelected();
+      await bulkDeleteSelected()
     } finally {
-      setDeleting(false);
-      setPanel(null);
+      setDeleting(false)
+      setPanel(null)
+    }
   }
-  };
 
   const handlePickAlbum = async (albumId: number) => {
-    await addToAlbum(albumId, ids);
-    setPanel(null);
-  };
-
-  const handleCreateAlbum = async () => {
-    const name = newAlbumName.trim();
-    if (!name || creatingAlbum) return;
-    setCreatingAlbum(true);
-    try {
-      const album = await createAlbum(name);
-      await addToAlbum(album.id, ids);
-      setNewAlbumName("");
-      setPanel(null);
-    } finally {
-      setCreatingAlbum(false);
+    await addToAlbum(albumId, ids)
+    setPanel(null)
   }
-  };
 
-  const btn = "rounded-md px-2.5 py-1.5 text-xs font-medium transition-colors";
-  const btnIdle = `${btn} text-gray-300 hover:bg-white/10 hover:text-white`;
-  const btnActive = `${btn} bg-white/10 text-white`;
+  const btn = 'rounded-md px-2.5 py-1.5 text-xs font-medium transition-colors'
+  const btnIdle = `${btn} text-gray-300 hover:bg-white/10 hover:text-white`
+  const btnActive = `${btn} bg-white/10 text-white`
 
   return (
     <div
@@ -91,67 +69,34 @@ export function BulkActionBar() {
       className="pointer-events-auto absolute bottom-6 left-1/2 z-30 flex -translate-x-1/2 items-center gap-1 rounded-xl border border-white/10 bg-gray-950/95 px-2 py-1.5 shadow-2xl shadow-black/50 backdrop-blur"
       onClick={(event) => event.stopPropagation()}
     >
-      <div className="flex items-center gap-2 px-1.5">
-        <span className="text-xs font-medium text-white">{selectedCount} selected</span>
-        {loadedCount < totalImages || loadedCount > selectedCount ? (
-          <Tooltip label={loadedCount < totalImages ? "Selects loaded items only" : "Select all loaded"}>
-          <button
-            className="text-[11px] text-gray-500 transition-colors hover:text-gray-300"
-            onClick={selectAllGallery}
-          >
-            Select all{loadedCount < totalImages ? " loaded" : ""}
-          </button>
-        </Tooltip>
-      ) : null}
-      </div>
+      <BulkSelectionSummary
+        loadedCount={loadedCount}
+        selectedCount={selectedCount}
+        totalImages={totalImages}
+        onSelectAll={selectAllGallery}
+      />
 
       <div className="h-5 w-px bg-white/10" />
 
       <div className="relative">
-        <button className={panel === "tag" ? btnActive : btnIdle} onClick={() => togglePanel("tag")}>
+        <button
+          className={panel === 'tag' ? btnActive : btnIdle}
+          onClick={() => togglePanel('tag')}
+        >
           Tag
         </button>
-        {panel === "tag" ? <BulkTagPopover onClose={() => setPanel(null)} /> : null}
+        {panel === 'tag' ? <BulkTagPopover onClose={() => setPanel(null)} /> : null}
       </div>
 
       <div className="relative">
-        <button className={panel === "rating" ? btnActive : btnIdle} onClick={() => togglePanel("rating")}>
+        <button
+          className={panel === 'rating' ? btnActive : btnIdle}
+          onClick={() => togglePanel('rating')}
+        >
           Rating
         </button>
-        {panel === "rating" ? (
-          <div
-            data-bulk-popover
-            className="absolute bottom-full left-1/2 mb-2 flex -translate-x-1/2 items-center gap-1 rounded-xl border border-white/10 bg-gray-950/98 p-2 shadow-2xl backdrop-blur"
-          >
-            {Array.from({ length: 5 }, (_, index) => {
-              const rating = index + 1;
-              return (
-                <Tooltip label={`Set ${rating} star${rating === 1 ? "" : "s"}`}>
-                <button
-                  key={rating}
-                  className="rounded-md p-1 text-white/25 transition-colors hover:bg-white/5 hover:text-amber-300"
-                  onClick={async () => {
-                    await bulkSetRating(rating);
-                    setPanel(null);
-                  }}
-                >
-                  <svg className="h-4 w-4" fill="currentColor" viewBox="0 0 20 20">
-                    <path d="M9.049 2.927c.3-.921 1.603-.921 1.902 0l1.07 3.292a1 1 0 00.95.69h3.462c.969 0 1.371 1.24.588 1.81l-2.8 2.034a1 1 0 00-.364 1.118l1.07 3.292c.3.921-.755 1.688-1.54 1.118l-2.8-2.034a1 1 0 00-1.176 0l-2.8 2.034c-.784.57-1.838-.197-1.539-1.118l1.07-3.292a1 1 0 00-.364-1.118L2.98 8.72c-.783-.57-.38-1.81.588-1.81H7.03a1 1 0 00.951-.69l1.07-3.292z" />
-                  </svg>
-                </button>
-                </Tooltip>
-              );
-            })}
-            <button
-              className="ml-1 rounded-md border border-white/10 px-2 py-1 text-[11px] text-gray-400 transition-colors hover:bg-white/5 hover:text-white"
-              onClick={async () => {
-                await bulkSetRating(0);
-                setPanel(null);
-              }}
-            >
-              Clear
-            </button>
-          </div>
+        {panel === 'rating' ? (
+          <BulkRatingPopover onSetRating={bulkSetRating} onClose={() => setPanel(null)} />
         ) : null}
       </div>
       <Tooltip label="Mark as favorite" followCursor>
@@ -160,54 +105,13 @@ export function BulkActionBar() {
         </button>
       </Tooltip>
       <div className="relative">
-        <button className={panel === "album" ? btnActive : btnIdle} onClick={() => togglePanel("album")}>
+        <button
+          className={panel === 'album' ? btnActive : btnIdle}
+          onClick={() => togglePanel('album')}
+        >
           Add to album
         </button>
-        {panel === "album" ? (
-          <div
-            data-bulk-popover
-            className="absolute bottom-full left-1/2 mb-2 w-60 -translate-x-1/2 rounded-xl border border-white/10 bg-gray-950/98 p-2 shadow-2xl backdrop-blur"
-          >
-            <div className="max-h-48 overflow-y-auto">
-              {albums.length === 0 ? (
-                <p className="px-2 py-2 text-[11px] text-gray-600">No albums yet — create one below.</p>
-              ) : (
-                albums.map((album) => (
-                  <button
-                    key={album.id}
-                    className="flex w-full items-center justify-between gap-2 rounded-md px-2 py-1.5 text-left text-xs text-gray-300 transition-colors hover:bg-white/5 hover:text-white"
-                    onClick={() => void handlePickAlbum(album.id)}
-                  >
-                    <span className="truncate">{album.name}</span>
-                    <span className="shrink-0 text-[10px] text-gray-600">{album.image_count}</span>
-                  </button>
-                ))
-              )}
-            </div>
-            <form
-              className="mt-1 flex gap-1 border-t border-white/[0.06] pt-2"
-              onSubmit={(event) => {
-                event.preventDefault();
-                void handleCreateAlbum();
-              }}
-            >
-              <input
-                className="min-w-0 flex-1 rounded-md border border-white/10 bg-white/5 px-2 py-1 text-xs text-white placeholder-gray-600 focus:border-white/20 focus:outline-none"
-                placeholder="New album…"
-                value={newAlbumName}
-                onChange={(event) => setNewAlbumName(event.target.value)}
-                disabled={creatingAlbum}
-              />
-              <button
-                type="submit"
-                className="rounded-md border border-white/10 bg-white/5 px-2 py-1 text-xs text-gray-300 transition-colors hover:bg-white/10 hover:text-white disabled:opacity-50"
-                disabled={creatingAlbum || !newAlbumName.trim()}
-              >
-                Add
-              </button>
-            </form>
-          </div>
-        ) : null}
+        {panel === 'album' ? <BulkAlbumPopover onPick={handlePickAlbum} /> : null}
       </div>
 
       {inAlbumView ? (
@@ -224,45 +128,24 @@ export function BulkActionBar() {
       <div className="relative">
         <Tooltip label="Delete files from disk" followCursor>
           <button
-          className={panel === "delete" ? `${btn} bg-red-500/15 text-red-300` : `${btn} text-gray-300 hover:bg-red-500/10 hover:text-red-300`}
-          onClick={() => togglePanel("delete")}
+            className={
+              panel === 'delete'
+                ? `${btn} bg-red-500/15 text-red-300`
+                : `${btn} text-gray-300 hover:bg-red-500/10 hover:text-red-300`
+            }
+            onClick={() => togglePanel('delete')}
             disabled={deleting}
           >
-          {deleting ? "Deleting…" : "Delete"}
+            {deleting ? 'Deleting…' : 'Delete'}
           </button>
         </Tooltip>
-        {panel === "delete" ? (
-          <div
-            data-bulk-popover
-            className="absolute bottom-full left-1/2 mb-2 w-64 -translate-x-1/2 rounded-xl border border-red-500/30 bg-gray-950/98 p-3 shadow-2xl backdrop-blur"
-          >
-            <div className="mb-1 flex items-center gap-1.5 text-red-300">
-              <svg className="h-3.5 w-3.5 shrink-0" fill="none" viewBox="0 0 24 24" stroke="currentColor">
-                <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2}
-                  d="M12 9v2m0 4h.01M10.29 3.86L1.82 18a2 2 0 001.71 3h16.94a2 2 0 001.71-3L13.71 3.86a2 2 0 00-3.42 0z" />
-              </svg>
-              <p className="text-xs font-semibold">Delete from disk</p>
-            </div>
-            <p className="mb-2.5 text-[11px] leading-relaxed text-gray-400">
-              Permanently delete {selectedCount} file{selectedCount === 1 ? "" : "s"} from your computer.
-              This removes the actual file{selectedCount === 1 ? "" : "s"} from disk and cannot be undone.
-            </p>
-            <div className="flex justify-end gap-1.5">
-              <button
-                className="rounded-md border border-white/10 bg-white/5 px-2.5 py-1 text-[11px] text-gray-300 transition-colors hover:bg-white/10 hover:text-white"
-                onClick={() => setPanel(null)}
-              >
-                Cancel
-              </button>
-              <button
-                className="rounded-md bg-red-500/20 px-2.5 py-1 text-[11px] font-medium text-red-300 transition-colors hover:bg-red-500/30 hover:text-red-200 disabled:opacity-50"
-                onClick={() => void handleDelete()}
-                disabled={deleting}
-              >
-                {deleting ? "Deleting…" : `Delete ${selectedCount} from disk`}
-              </button>
-            </div>
-          </div>
+        {panel === 'delete' ? (
+          <BulkDeleteConfirm
+            deleting={deleting}
+            selectedCount={selectedCount}
+            onCancel={() => setPanel(null)}
+            onDelete={handleDelete}
+          />
         ) : null}
       </div>
       <Tooltip label="Clear selection" followCursor>
@@ -270,11 +153,9 @@ export function BulkActionBar() {
           className="rounded-md p-1.5 text-gray-500 transition-colors hover:bg-white/[0.06] hover:text-white"
           onClick={clearGallerySelection}
         >
-        <svg className="h-4 w-4" fill="none" viewBox="0 0 24 24" stroke="currentColor">
-          <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M6 18L18 6M6 6l12 12" />
-        </svg>
+          <CloseIcon className="h-4 w-4" />
         </button>
       </Tooltip>
     </div>
-  );
+  )
 }

src/components/ColorFilter.tsx

@@ -1,75 +1,82 @@
-import { useEffect, useRef, useState } from "react";
-import { AnimatePresence, motion } from "framer-motion";
-import { useGalleryStore } from "../store";
-import { Tooltip } from "./Tooltip";
+import { useRef, useState } from 'react'
+import { AnimatePresence, motion } from 'framer-motion'
+import { useGalleryStore } from '../store'
+import { useDismissable } from './menu'
+import { Tooltip } from './Tooltip'
 
-type Rgb = [number, number, number];
+type Rgb = [number, number, number]
 
 // Representative colors for the quick-pick swatches. Each is just an RGB the
 // distance filter matches against — not a hard bucket.
 const SWATCHES: { name: string; rgb: Rgb }[] = [
-  { name: "Red", rgb: [226, 59, 59] },
-  { name: "Orange", rgb: [232, 134, 46] },
-  { name: "Yellow", rgb: [242, 207, 46] },
-  { name: "Green", rgb: [76, 175, 80] },
-  { name: "Teal", rgb: [31, 182, 166] },
-  { name: "Blue", rgb: [59, 125, 216] },
-  { name: "Purple", rgb: [139, 92, 246] },
-  { name: "Pink", rgb: [236, 72, 153] },
-  { name: "Brown", rgb: [139, 90, 43] },
-  { name: "Black", rgb: [26, 26, 26] },
-  { name: "White", rgb: [245, 245, 245] },
-  { name: "Gray", rgb: [154, 160, 166] },
-];
+  { name: 'Red', rgb: [226, 59, 59] },
+  { name: 'Orange', rgb: [232, 134, 46] },
+  { name: 'Yellow', rgb: [242, 207, 46] },
+  { name: 'Green', rgb: [76, 175, 80] },
+  { name: 'Teal', rgb: [31, 182, 166] },
+  { name: 'Blue', rgb: [59, 125, 216] },
+  { name: 'Purple', rgb: [139, 92, 246] },
+  { name: 'Pink', rgb: [236, 72, 153] },
+  { name: 'Brown', rgb: [139, 90, 43] },
+  { name: 'Black', rgb: [26, 26, 26] },
+  { name: 'White', rgb: [245, 245, 245] },
+  { name: 'Gray', rgb: [154, 160, 166] },
+]
 
 function rgbEquals(a: Rgb | null, b: Rgb): boolean {
-  return a !== null && a[0] === b[0] && a[1] === b[1] && a[2] === b[2];
+  return a !== null && a[0] === b[0] && a[1] === b[1] && a[2] === b[2]
 }
 
 function toHex([r, g, b]: Rgb): string {
-  return `#${[r, g, b].map((n) => n.toString(16).padStart(2, "0")).join("")}`;
+  return `#${[r, g, b].map((n) => n.toString(16).padStart(2, '0')).join('')}`
 }
 
 function fromHex(hex: string): Rgb {
-  const n = parseInt(hex.slice(1), 16);
-  return [(n >> 16) & 255, (n >> 8) & 255, n & 255];
+  const n = parseInt(hex.slice(1), 16)
+  return [(n >> 16) & 255, (n >> 8) & 255, n & 255]
 }
 
 export function ColorFilter() {
-  const colorFilter = useGalleryStore((state) => state.colorFilter);
-  const setColorFilter = useGalleryStore((state) => state.setColorFilter);
-  const colorBackfill = useGalleryStore((state) => state.colorBackfill);
-  const [open, setOpen] = useState(false);
-  const ref = useRef<HTMLDivElement>(null);
+  const colorFilter = useGalleryStore((state) => state.colorFilter)
+  const setColorFilter = useGalleryStore((state) => state.setColorFilter)
+  const colorBackfill = useGalleryStore((state) => state.colorBackfill)
+  const [open, setOpen] = useState(false)
+  const ref = useRef<HTMLDivElement>(null)
 
-  const isActive = colorFilter !== null;
-  const isCustom = isActive && !SWATCHES.some((swatch) => rgbEquals(colorFilter, swatch.rgb));
+  const isActive = colorFilter !== null
+  const isCustom = isActive && !SWATCHES.some((swatch) => rgbEquals(colorFilter, swatch.rgb))
 
-  // Collapse the panel when clicking elsewhere.
-  useEffect(() => {
-    if (!open) return;
-    const onPointerDown = (event: PointerEvent) => {
-      if (ref.current && !ref.current.contains(event.target as Node)) setOpen(false);
-    };
-    window.addEventListener("pointerdown", onPointerDown);
-    return () => window.removeEventListener("pointerdown", onPointerDown);
-  }, [open]);
+  // Collapse the panel when clicking elsewhere or pressing Escape.
+  useDismissable(ref, () => setOpen(false), open)
 
   return (
-    <div ref={ref} className="relative ml-1 flex shrink-0 items-center border-l border-white/6 pl-2">
+    <div
+      ref={ref}
+      className="relative ml-1 flex shrink-0 items-center border-l border-white/6 pl-2"
+    >
       {/* Trigger — a single palette icon; shows the active color as a dot when a
           filter is applied so the collapsed state still communicates it. */}
-      <Tooltip label={isActive ? "Color filter active" : "Filter by color"} delay={400} anchorToCursor>
+      <Tooltip
+        label={isActive ? 'Color filter active' : 'Filter by color'}
+        delay={400}
+        anchorToCursor
+      >
         <button
           className={`relative flex items-center gap-1.5 rounded-lg px-2 py-1.5 transition-colors ${
-            open || isActive ? "bg-white/10 text-white" : "text-gray-500 hover:bg-white/5 hover:text-gray-200"
+            open || isActive
+              ? 'bg-white/10 text-white'
+              : 'text-gray-500 hover:bg-white/5 hover:text-gray-200'
           }`}
           onClick={() => setOpen((value) => !value)}
           aria-label="Filter by color"
         >
           <svg className="h-3.5 w-3.5" fill="none" viewBox="0 0 24 24" stroke="currentColor">
-            <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={1.6}
-              d="M12 3a9 9 0 100 18c.83 0 1.5-.67 1.5-1.5 0-.39-.15-.74-.39-1.01-.23-.26-.39-.61-.39-1 0-.83.67-1.5 1.5-1.5H16a5 5 0 005-5c0-4.42-4.03-8-9-8z" />
+            <path
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              strokeWidth={1.6}
+              d="M12 3a9 9 0 100 18c.83 0 1.5-.67 1.5-1.5 0-.39-.15-.74-.39-1.01-.23-.26-.39-.61-.39-1 0-.83.67-1.5 1.5-1.5H16a5 5 0 005-5c0-4.42-4.03-8-9-8z"
+            />
             <circle cx="7.5" cy="11.5" r="1" fill="currentColor" stroke="none" />
             <circle cx="11.5" cy="7.5" r="1" fill="currentColor" stroke="none" />
             <circle cx="15.5" cy="9.5" r="1" fill="currentColor" stroke="none" />
@@ -92,42 +99,49 @@ export function ColorFilter() {
             initial={{ opacity: 0, y: -4, scale: 0.98 }}
             animate={{ opacity: 1, y: 0, scale: 1 }}
             exit={{ opacity: 0, y: -4, scale: 0.98 }}
-            transition={{ duration: 0.14, ease: "easeOut" }}
-            className="absolute right-0 top-full z-30 mt-2 w-max rounded-xl border border-white/10 bg-gray-950/98 p-2.5 shadow-2xl backdrop-blur light-theme:border-gray-700/50"
+            transition={{ duration: 0.14, ease: 'easeOut' }}
+            className="light-theme:border-gray-700/50 absolute top-full right-0 z-30 mt-2 w-max rounded-xl border border-white/10 bg-gray-950/98 p-2.5 shadow-2xl backdrop-blur"
           >
             <div className="grid grid-cols-7 gap-1.5">
               {SWATCHES.map((swatch) => {
-                const active = rgbEquals(colorFilter, swatch.rgb);
+                const active = rgbEquals(colorFilter, swatch.rgb)
                 return (
                   <Tooltip label={swatch.name} followCursor>
                     <button
                       key={swatch.name}
                       aria-label={`Filter by ${swatch.name}`}
                       className={`h-5 w-5 shrink-0 rounded-full border transition-transform ${
-                      active ? "scale-110 border-white/40 ring-2 ring-white/70" : "border-white/15 hover:scale-110"
+                        active
+                          ? 'scale-110 border-white/40 ring-2 ring-white/70'
+                          : 'border-white/15 hover:scale-110'
                       }`}
                       style={{ backgroundColor: toHex(swatch.rgb) }}
                       onClick={() => setColorFilter(active ? null : swatch.rgb)}
                     />
                   </Tooltip>
-                );
+                )
               })}
               <Tooltip label="Custom Colour" followCursor>
                 {/* Custom color picker — rainbow until a custom color is chosen. */}
                 <label
                   className={`relative h-5 w-5 shrink-0 cursor-pointer overflow-hidden rounded-full border ${
-                  isCustom ? "border-white/40 ring-2 ring-white/70" : "border-white/15 hover:scale-110"
+                    isCustom
+                      ? 'border-white/40 ring-2 ring-white/70'
+                      : 'border-white/15 hover:scale-110'
                   }`}
                   style={
                     isCustom
                       ? { backgroundColor: toHex(colorFilter as Rgb) }
-                    : { background: "conic-gradient(red, orange, yellow, lime, cyan, blue, magenta, red)" }
+                      : {
+                          background:
+                            'conic-gradient(red, orange, yellow, lime, cyan, blue, magenta, red)',
+                        }
                   }
                 >
                   <input
                     type="color"
                     className="absolute inset-0 cursor-pointer opacity-0"
-                  value={colorFilter ? toHex(colorFilter) : "#3b7dd8"}
+                    value={colorFilter ? toHex(colorFilter) : '#3b7dd8'}
                     onChange={(event) => setColorFilter(fromHex(event.target.value))}
                   />
                 </label>
@@ -135,14 +149,20 @@ export function ColorFilter() {
             </div>
 
             {isActive || (colorBackfill && colorBackfill.total > 0) ? (
-              <div className="mt-2 flex items-center justify-between gap-3 border-t border-white/6 pt-2 light-theme:border-gray-700/40">
+              <div className="light-theme:border-gray-700/40 mt-2 flex items-center justify-between gap-3 border-t border-white/6 pt-2">
                 {colorBackfill && colorBackfill.total > 0 ? (
-                  <Tooltip label="Sampling colours from existing thumbnails — colour search fills in as this runs" anchorToCursor>
+                  <Tooltip
+                    label="Sampling colours from existing thumbnails — colour search fills in as this runs"
+                    anchorToCursor
+                  >
                     <span className="text-[10px] text-gray-600">
-                      sampling {colorBackfill.processed.toLocaleString()}/{colorBackfill.total.toLocaleString()}
+                      sampling {colorBackfill.processed.toLocaleString()}/
+                      {colorBackfill.total.toLocaleString()}
                     </span>
                   </Tooltip>
-                ) : <span />}
+                ) : (
+                  <span />
+                )}
                 {isActive ? (
                   <Tooltip label="Clear colour filter" anchorToCursor>
                     <button
@@ -159,5 +179,5 @@ export function ColorFilter() {
         ) : null}
       </AnimatePresence>
     </div>
-  );
+  )
 }

src/components/DuplicateFinder.tsx

@@ -1,361 +1,125 @@
-import { useRef, useState } from "react";
-import { useVirtualizer } from "@tanstack/react-virtual";
-import { DuplicateGroup, useGalleryStore } from "../store";
-import { FolderScopeDropdown } from "./FolderScopeDropdown";
-import { mediaSrc } from "../lib/mediaSrc";
-import { Tooltip } from "./Tooltip";
-
-function formatBytes(bytes: number): string {
-  if (bytes >= 1_073_741_824) return `${(bytes / 1_073_741_824).toFixed(1)} GB`;
-  if (bytes >= 1_048_576) return `${(bytes / 1_048_576).toFixed(1)} MB`;
-  if (bytes >= 1024) return `${(bytes / 1024).toFixed(0)} KB`;
-  return `${bytes} B`;
-}
-
-function DuplicateGroupCard({ group }: { group: DuplicateGroup }) {
-  const selectedIds = useGalleryStore((state) => state.duplicateSelectedIds);
-  const toggleDuplicateSelected = useGalleryStore((state) => state.toggleDuplicateSelected);
-  const selectAllDuplicates = useGalleryStore((state) => state.selectAllDuplicates);
-  const groupSelectedCount = group.images.filter((img) => selectedIds.has(img.id)).length;
-  const noneSelected = groupSelectedCount === 0;
-
-  // "Keep all but the first" — a common quick action
-  const handleKeepFirst = () => {
-    const toDelete = group.images.slice(1).map((img) => img.id);
-    // Clear any selection for this group first, then add the ones to delete
-    for (const img of group.images) {
-      if (selectedIds.has(img.id)) toggleDuplicateSelected(img.id);
-    }
-    selectAllDuplicates(toDelete);
-  };
-
-  return (
-    <div className="rounded-2xl border border-white/[0.07] bg-white/[0.02] p-4">
-      {/* Group header */}
-      <div className="mb-3 flex items-center justify-between gap-3">
-        <div className="flex items-center gap-2">
-          <span className="rounded-md border border-white/10 bg-white/[0.04] px-2 py-0.5 text-[11px] text-gray-400">
-            {group.images.length} copies
-          </span>
-          <span className="text-[11px] text-white/30">{formatBytes(group.file_size)} each</span>
-          <span className="text-[11px] text-white/20">
-            {formatBytes(group.file_size * (group.images.length - 1))} wasted
-          </span>
-        </div>
-        <div className="flex items-center gap-2">
-          {noneSelected ? (
-            <button
-              className="text-[11px] text-white/35 transition-colors hover:text-white/70"
-              onClick={handleKeepFirst}
-            >
-              Keep first
-            </button>
-          ) : (
-            <button
-              className="text-[11px] text-white/35 transition-colors hover:text-white/70"
-              onClick={() => {
-                for (const img of group.images) {
-                  if (selectedIds.has(img.id)) toggleDuplicateSelected(img.id);
-                }
-              }}
-            >
-              Deselect all
-            </button>
-          )}
-        </div>
-      </div>
-
-      {/* Image grid */}
-      <div className="flex flex-wrap gap-3">
-        {group.images.map((image) => {
-          const isSelected = selectedIds.has(image.id);
-          const src = mediaSrc(image.thumbnail_path);
-          return (
-            <Tooltip label={image.path} anchorToCursor>
-            <button
-              key={image.id}
-              className={`media-dark-surface group relative overflow-hidden rounded-xl border transition-all ${
-                isSelected
-                  ? "border-red-400/50 ring-1 ring-red-400/30"
-                  : "border-white/8 hover:border-white/20"
-              }`}
-              style={{ width: 140, height: 105 }}
-              onClick={() => toggleDuplicateSelected(image.id)}
-            >
-              {src ? (
-                <img src={src} alt="" className="h-full w-full object-cover" draggable={false} />
-              ) : (
-                <div className="h-full w-full bg-white/[0.03]" />
-              )}
-              {/* Delete overlay */}
-              {isSelected ? (
-                <div className="absolute inset-0 flex items-center justify-center bg-red-950/60">
-                  <svg className="h-6 w-6 text-red-300" fill="none" viewBox="0 0 24 24" stroke="currentColor">
-                    <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M19 7l-.867 12.142A2 2 0 0116.138 21H7.862a2 2 0 01-1.995-1.858L5 7m5 4v6m4-6v6m1-10V4a1 1 0 00-1-1h-4a1 1 0 00-1 1v3M4 7h16" />
-                  </svg>
-                </div>
-              ) : null}
-              {/* Path tooltip on hover */}
-              <div className="absolute inset-x-0 bottom-0 bg-gradient-to-t from-black/90 to-transparent px-2 pb-1.5 pt-4 opacity-0 transition-opacity group-hover:opacity-100">
-                <p className="truncate text-[9px] text-white/60">{image.path.split(/[\\/]/).slice(-2).join("/")}</p>
-              </div>
-            </button>
-            </Tooltip>
-          );
-        })}
-      </div>
-    </div>
-  );
-}
-
-function formatRelativeTime(unixSecs: number): string {
-  const diff = Math.floor(Date.now() / 1000) - unixSecs;
-  if (diff < 60) return "just now";
-  if (diff < 3600) return `${Math.floor(diff / 60)}m ago`;
-  if (diff < 86400) return `${Math.floor(diff / 3600)}h ago`;
-  return `${Math.floor(diff / 86400)}d ago`;
-}
+import { useRef, useState } from 'react'
+import { useVirtualizer } from '@tanstack/react-virtual'
+import { useGalleryStore } from '../store'
+import {
+  DuplicateScanEmptyState,
+  DuplicateScanIntroState,
+  DuplicateScanLoadingState,
+} from './duplicateFinder/DuplicateFinderEmptyStates'
+import { DuplicateFinderHeader } from './duplicateFinder/DuplicateFinderHeader'
+import { DuplicateGroupCard } from './duplicateFinder/DuplicateGroupCard'
+import { duplicateProgressLabel } from './duplicateFinder/format'
 
 export function DuplicateFinder() {
-  const duplicateGroups = useGalleryStore((state) => state.duplicateGroups);
-  const duplicateScanning = useGalleryStore((state) => state.duplicateScanning);
-  const duplicateScanProgress = useGalleryStore((state) => state.duplicateScanProgress);
-  const duplicateScanError = useGalleryStore((state) => state.duplicateScanError);
-  const duplicateScanWarning = useGalleryStore((state) => state.duplicateScanWarning);
-  const duplicateSelectedIds = useGalleryStore((state) => state.duplicateSelectedIds);
-  const duplicateLastScanned = useGalleryStore((state) => state.duplicateLastScanned);
-  const selectedFolderId = useGalleryStore((state) => state.selectedFolderId);
-  const scanDuplicates = useGalleryStore((state) => state.scanDuplicates);
-  const clearDuplicateSelection = useGalleryStore((state) => state.clearDuplicateSelection);
-  const selectKeepFirstAllGroups = useGalleryStore((state) => state.selectKeepFirstAllGroups);
-  const deleteSelectedDuplicates = useGalleryStore((state) => state.deleteSelectedDuplicates);
+  const duplicateGroups = useGalleryStore((state) => state.duplicateGroups)
+  const duplicateScanning = useGalleryStore((state) => state.duplicateScanning)
+  const duplicateScanProgress = useGalleryStore((state) => state.duplicateScanProgress)
+  const duplicateScanError = useGalleryStore((state) => state.duplicateScanError)
+  const duplicateScanWarning = useGalleryStore((state) => state.duplicateScanWarning)
+  const duplicateSelectedIds = useGalleryStore((state) => state.duplicateSelectedIds)
+  const duplicateLastScanned = useGalleryStore((state) => state.duplicateLastScanned)
+  const selectedFolderId = useGalleryStore((state) => state.selectedFolderId)
+  const scanDuplicates = useGalleryStore((state) => state.scanDuplicates)
+  const clearDuplicateSelection = useGalleryStore((state) => state.clearDuplicateSelection)
+  const selectKeepFirstAllGroups = useGalleryStore((state) => state.selectKeepFirstAllGroups)
+  const deleteSelectedDuplicates = useGalleryStore((state) => state.deleteSelectedDuplicates)
 
-  const [deleting, setDeleting] = useState(false);
-  const [confirmingDelete, setConfirmingDelete] = useState(false);
-  const [deleteResult, setDeleteResult] = useState<string | null>(null);
+  const [deleting, setDeleting] = useState(false)
+  const [confirmingDelete, setConfirmingDelete] = useState(false)
+  const [deleteResult, setDeleteResult] = useState<string | null>(null)
 
   // Virtualize the group list so a large result set (e.g. thousands of pairs)
   // only mounts the on-screen cards. Group cards vary in height (number of
   // copies wraps across rows), so heights are measured dynamically.
-  const scrollRef = useRef<HTMLDivElement>(null);
+  const scrollRef = useRef<HTMLDivElement>(null)
   const virtualizer = useVirtualizer({
     count: duplicateGroups.length,
     getScrollElement: () => scrollRef.current,
     estimateSize: () => 220,
     overscan: 4,
-  });
-
-  const selectedCount = duplicateSelectedIds.size;
-  const hasResults = duplicateGroups.length > 0;
-  const hasScanned = hasResults || duplicateLastScanned !== null || (!duplicateScanning && duplicateScanProgress !== null);
-  const totalWasted = duplicateGroups.reduce(
-    (sum, g) => sum + g.file_size * (g.images.length - 1),
-    0,
-  );
-  const totalDuplicateImages = duplicateGroups.reduce((sum, g) => sum + g.images.length - 1, 0);
+  })
 
+  const selectedCount = duplicateSelectedIds.size
+  const hasResults = duplicateGroups.length > 0
+  const hasScanned =
+    hasResults ||
+    duplicateLastScanned !== null ||
+    (!duplicateScanning && duplicateScanProgress !== null)
   const handleDelete = async () => {
-    setDeleting(true);
-    setConfirmingDelete(false);
-    setDeleteResult(null);
+    setDeleting(true)
+    setConfirmingDelete(false)
+    setDeleteResult(null)
     try {
-      const deleted = await deleteSelectedDuplicates();
-      setDeleteResult(`Deleted ${deleted} file${deleted === 1 ? "" : "s"}.`);
+      const deleted = await deleteSelectedDuplicates()
+      setDeleteResult(`Deleted ${deleted} file${deleted === 1 ? '' : 's'}.`)
     } catch (e) {
-      setDeleteResult(String(e));
+      setDeleteResult(String(e))
     } finally {
-      setDeleting(false);
+      setDeleting(false)
+    }
   }
-  };
 
-  const progressPercent =
-    duplicateScanProgress && duplicateScanProgress.total > 0
-      ? Math.round((duplicateScanProgress.processed / duplicateScanProgress.total) * 100)
-      : 0;
-  const progressLabel = duplicateScanProgress
-    ? duplicateScanProgress.phase === "checking"
-      ? "Checking file sizes"
-      : duplicateScanProgress.phase === "hashing"
-        ? "Hashing duplicate candidates"
-        : "Confirming exact matches"
-    : null;
+  const progressLabel = duplicateProgressLabel(duplicateScanProgress)
 
   return (
     <div className="flex min-h-0 flex-1 flex-col overflow-hidden bg-gray-950">
-      {/* Header */}
-      <div className="shrink-0 border-b border-white/[0.05] px-6 py-4">
-        <div className="flex items-center justify-between gap-4">
-          <div>
-            <h2 className="text-[15px] font-semibold text-white">Duplicate Finder</h2>
-            <p className="mt-0.5 text-[11px] text-white/30">
-              {duplicateScanning
-                ? duplicateScanProgress
-                  ? `${progressLabel}… ${duplicateScanProgress.processed.toLocaleString()} / ${duplicateScanProgress.total.toLocaleString()}${duplicateScanProgress.skipped > 0 ? ` · ${duplicateScanProgress.skipped.toLocaleString()} skipped` : ""}`
-                  : "Starting scan…"
-                : hasResults
-                  ? `${duplicateGroups.length} group${duplicateGroups.length === 1 ? "" : "s"} · ${formatBytes(totalWasted)} reclaimable`
-                  : duplicateLastScanned !== null
-                    ? "No duplicates found"
-                    : "Scan your library for identical files"}
-            </p>
-            {!duplicateScanning && duplicateLastScanned !== null && (
-              <p className="mt-0.5 text-[10px] text-white/20">
-                Last scanned {formatRelativeTime(duplicateLastScanned)}
-              </p>
-            )}
-          </div>
-          <div className="flex items-center gap-2">
-            <FolderScopeDropdown />
-            {/* Batch select — only shown when there are groups and nothing is selected yet */}
-            {hasResults && selectedCount === 0 && !deleting && (
-              <Tooltip label={`Mark ${totalDuplicateImages} duplicate${totalDuplicateImages === 1 ? "" : "s"} for deletion across all groups (keeps first in each)`} anchorToCursor>
-              <button
-                className="rounded-lg border border-white/10 bg-white/[0.04] px-3 py-1.5 text-xs text-gray-400 transition-colors hover:bg-white/[0.07] hover:text-white light-theme:border-gray-700/50 light-theme:bg-gray-900 light-theme:text-white light-theme:hover:bg-gray-800 light-theme:hover:text-white"
-                onClick={selectKeepFirstAllGroups}
-              >
-                Select all duplicates
-              </button>
-              </Tooltip>
-            )}
-            {selectedCount > 0 ? (
-              <>
-                <span className="text-[11px] text-white/40">{selectedCount} marked for deletion</span>
-                <button
-                  className="rounded-lg border border-white/10 bg-white/[0.04] px-3 py-1.5 text-xs text-gray-400 transition-colors hover:bg-white/[0.07] hover:text-white disabled:opacity-40 light-theme:border-gray-700/50 light-theme:bg-gray-900 light-theme:text-white light-theme:hover:bg-gray-800 light-theme:hover:text-white"
-                  onClick={clearDuplicateSelection}
-                  disabled={deleting}
-                >
-                  Deselect all
-                </button>
-                <div className="relative">
-                  <button
-                    className="rounded-lg border border-red-400/25 bg-red-500/10 px-3 py-1.5 text-xs text-red-300 transition-colors hover:bg-red-500/15 disabled:cursor-not-allowed disabled:opacity-40"
-                    onClick={() => setConfirmingDelete((v) => !v)}
-                    disabled={deleting}
-                  >
-                    {deleting ? "Deleting…" : `Delete ${selectedCount} file${selectedCount === 1 ? "" : "s"}`}
-                  </button>
-                  {confirmingDelete && !deleting ? (
-                    <>
-                      {/* Click-away backdrop */}
-                      <div className="fixed inset-0 z-40" onClick={() => setConfirmingDelete(false)} />
-                      <div className="absolute right-0 top-full z-50 mt-2 w-72 rounded-xl border border-red-500/30 bg-gray-950/98 p-3 text-left shadow-2xl backdrop-blur">
-                        <div className="mb-1 flex items-center gap-1.5 text-red-300">
-                          <svg className="h-3.5 w-3.5 shrink-0" fill="none" viewBox="0 0 24 24" stroke="currentColor">
-                            <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2}
-                              d="M12 9v2m0 4h.01M10.29 3.86L1.82 18a2 2 0 001.71 3h16.94a2 2 0 001.71-3L13.71 3.86a2 2 0 00-3.42 0z" />
-                          </svg>
-                          <p className="text-xs font-semibold">Delete from disk</p>
-                        </div>
-                        <p className="mb-2.5 text-[11px] leading-relaxed text-gray-400">
-                          Permanently delete {selectedCount} file{selectedCount === 1 ? "" : "s"} from your computer.
-                          This removes the actual file{selectedCount === 1 ? "" : "s"} from disk and cannot be undone.
-                        </p>
-                        <div className="flex justify-end gap-1.5">
-                          <button
-                            className="rounded-md border border-white/10 bg-white/5 px-2.5 py-1 text-[11px] text-gray-300 transition-colors hover:bg-white/10 hover:text-white"
-                            onClick={() => setConfirmingDelete(false)}
-                          >
-                            Cancel
-                          </button>
-                          <button
-                            className="rounded-md bg-red-500/20 px-2.5 py-1 text-[11px] font-medium text-red-300 transition-colors hover:bg-red-500/30 hover:text-red-200"
-                            onClick={handleDelete}
-                          >
-                            Delete {selectedCount} from disk
-                          </button>
-                        </div>
-                      </div>
-                    </>
-                  ) : null}
-                </div>
-              </>
-            ) : null}
-            <button
-              className="rounded-lg border border-white/10 bg-white/[0.055] px-3 py-1.5 text-xs text-gray-300 transition-colors hover:bg-white/10 hover:text-white disabled:cursor-not-allowed disabled:opacity-40 light-theme:border-gray-700/50 light-theme:bg-gray-900 light-theme:text-white light-theme:hover:bg-gray-800 light-theme:hover:text-white"
-              onClick={() => { setDeleteResult(null); void scanDuplicates(selectedFolderId); }}
-              disabled={duplicateScanning}
-            >
-              {duplicateScanning ? "Scanning…" : hasScanned ? "Rescan" : "Scan for duplicates"}
-            </button>
-          </div>
-        </div>
-
-        {/* Progress bar */}
-        {duplicateScanning && duplicateScanProgress ? (
-          <div className="mt-3 h-px overflow-hidden rounded-full bg-white/[0.07]">
-            <div
-              className="h-full rounded-full bg-blue-500/60 transition-[width] duration-200"
-              style={{ width: `${progressPercent}%` }}
+      <DuplicateFinderHeader
+        confirmingDelete={confirmingDelete}
+        deleteResult={deleteResult}
+        deleting={deleting}
+        duplicateGroups={duplicateGroups}
+        duplicateLastScanned={duplicateLastScanned}
+        duplicateScanError={duplicateScanError}
+        duplicateScanning={duplicateScanning}
+        duplicateScanProgress={duplicateScanProgress}
+        duplicateScanWarning={duplicateScanWarning}
+        hasResults={hasResults}
+        hasScanned={hasScanned}
+        onClearSelection={clearDuplicateSelection}
+        onConfirmDelete={() => setConfirmingDelete(false)}
+        onDelete={handleDelete}
+        onScan={() => {
+          setDeleteResult(null)
+          void scanDuplicates(selectedFolderId)
+        }}
+        onSelectKeepFirstAll={selectKeepFirstAllGroups}
+        selectedCount={selectedCount}
+        setConfirmingDelete={setConfirmingDelete}
       />
-          </div>
-        ) : null}
 
-        {duplicateScanError ? (
-          <p className="mt-2 text-[11px] text-red-400/80">{duplicateScanError}</p>
-        ) : null}
-        {duplicateScanWarning ? (
-          <p className="mt-2 text-[11px] text-amber-300/70">{duplicateScanWarning}</p>
-        ) : null}
-        {deleteResult ? (
-          <p className="mt-2 text-[11px] text-white/40">{deleteResult}</p>
-        ) : null}
-      </div>
-
-      {/* Body */}
       {duplicateScanning && !hasResults ? (
-        <div className="flex flex-1 items-center justify-center gap-3 text-white/25">
-          <div className="h-5 w-5 animate-spin rounded-full border-2 border-white/15 border-t-white/50" />
-          <span className="text-sm">{progressLabel ? `${progressLabel}…` : "Preparing scan…"}</span>
-        </div>
+        <DuplicateScanLoadingState progressLabel={progressLabel} />
       ) : !hasScanned ? (
-        <div className="flex flex-1 items-center justify-center px-8">
-          <div className="max-w-sm text-center">
-            <svg className="mx-auto mb-4 h-10 w-10 text-white/10" fill="none" viewBox="0 0 24 24" stroke="currentColor">
-              <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={1}
-                d="M8 16H6a2 2 0 01-2-2V6a2 2 0 012-2h8a2 2 0 012 2v2m-6 12h8a2 2 0 002-2v-8a2 2 0 00-2-2h-8a2 2 0 00-2 2v8a2 2 0 002 2z" />
-            </svg>
-            <p className="text-sm text-white/30">
-              Finds files with identical content regardless of filename or location.
-              Click <strong className="text-white/50">Scan for duplicates</strong> to begin.
-            </p>
-            <p className="mt-2 text-xs text-white/20">
-              Large libraries may take a minute — files are hashed from disk.
-            </p>
-          </div>
-        </div>
+        <DuplicateScanIntroState />
       ) : duplicateGroups.length === 0 ? (
-        <div className="flex flex-1 items-center justify-center">
-          <p className="text-sm text-white/25">No duplicate files found.</p>
-        </div>
+        <DuplicateScanEmptyState />
       ) : (
         <div ref={scrollRef} className="overflow-y-auto px-6 py-5">
-          <div style={{ height: virtualizer.getTotalSize(), position: "relative" }}>
+          <div style={{ height: virtualizer.getTotalSize(), position: 'relative' }}>
             {virtualizer.getVirtualItems().map((virtualItem) => {
-              const group = duplicateGroups[virtualItem.index];
-              if (!group) return null;
+              const group = duplicateGroups[virtualItem.index]
+              if (!group) return null
               return (
                 <div
                   key={group.file_hash}
                   data-index={virtualItem.index}
                   ref={virtualizer.measureElement}
                   style={{
-                    position: "absolute",
+                    position: 'absolute',
                     top: 0,
                     left: 0,
-                    width: "100%",
+                    width: '100%',
                     transform: `translateY(${virtualItem.start}px)`,
                     paddingBottom: 16,
                   }}
                 >
                   <DuplicateGroupCard group={group} />
                 </div>
-              );
+              )
             })}
           </div>
         </div>
       )}
     </div>
-  );
+  )
 }
-

src/components/FolderPickerModal.tsx

@@ -1,423 +1,48 @@
-import { useEffect, useMemo, useRef, useState } from "react";
-import { useVirtualizer } from "@tanstack/react-virtual";
-import { DirEntry, DirListing, FolderAddResult, useGalleryStore } from "../store";
-import { Tooltip } from "./Tooltip";
-
-function normalizePath(path: string): string {
-  return path.replace(/\\/g, "/").replace(/\/+$/, "").toLowerCase();
-}
-
-function cleanAddressInput(path: string): string {
-  const trimmed = path.trim();
-  if (trimmed.length >= 2) {
-    const first = trimmed[0];
-    const last = trimmed[trimmed.length - 1];
-    if ((first === "\"" && last === "\"") || (first === "'" && last === "'")) {
-      return trimmed.slice(1, -1).trim();
-    }
-  }
-  return trimmed;
-}
-
-function friendlyDirectoryError(error: unknown): string {
-  const message = error instanceof Error ? error.message : String(error);
-  if (/cannot find the path|os error 3|not found|no such file/i.test(message)) {
-    return "Folder not found. Check the path and try again.";
-  }
-  return message;
-}
-
-function folderName(path: string): string {
-  const trimmed = path.replace(/[\\/]+$/, "");
-  const parts = trimmed.split(/[\\/]+/).filter(Boolean);
-  return parts.length > 0 ? parts[parts.length - 1] : path;
-}
-
-function buildBreadcrumbs(path: string | null): { label: string; path: string | null }[] {
-  if (!path) return [{ label: "This PC / Home", path: null }];
-
-  const separator = path.includes("\\") ? "\\" : "/";
-  const normalized = path.replace(/[\\/]+$/, "");
-  const windowsDrive = normalized.match(/^[A-Za-z]:/);
-
-  if (windowsDrive) {
-    const drive = windowsDrive[0] + "\\";
-    const rest = normalized.slice(2).split(/[\\/]+/).filter(Boolean);
-    let current = drive;
-    return [
-      { label: "This PC", path: null },
-      { label: drive, path: drive },
-      ...rest.map((part) => {
-        current = current.endsWith("\\") ? `${current}${part}` : `${current}\\${part}`;
-        return { label: part, path: current };
-      }),
-    ];
-  }
-
-  const parts = normalized.split(/[\\/]+/).filter(Boolean);
-  let current = separator === "/" ? "" : "";
-  return [
-    { label: "/", path: null },
-    ...parts.map((part) => {
-      current = `${current}/${part}`;
-      return { label: part, path: current };
-    }),
-  ];
-}
-
-function StatusLine({ results }: { results: FolderAddResult[] | null }) {
-  if (!results) return null;
-  const added = results.filter((result) => result.status === "added").length;
-  const skipped = results.filter((result) => result.status === "skipped").length;
-  const failed = results.filter((result) => result.status === "error").length;
-  return (
-    <p className="text-xs text-gray-500 light-theme:text-gray-600">
-      Added {added}, skipped {skipped}, failed {failed}.
-    </p>
-  );
-}
-
-function FolderRow({
-  entry,
-  selected,
-  alreadyAdded,
-  onToggle,
-  onNavigate,
-}: {
-  entry: DirEntry;
-  selected: boolean;
-  alreadyAdded: boolean;
-  onToggle: () => void;
-  onNavigate: () => void;
-}) {
-  return (
-    <div
-      className={`group flex h-11 items-center gap-3 rounded-md border px-3 transition-colors ${
-        alreadyAdded
-          ? "border-transparent bg-white/[0.025] text-gray-600 light-theme:bg-gray-900 light-theme:text-gray-500"
-          : selected
-            ? "border-white/15 bg-white/[0.085] text-white shadow-[inset_0_0_0_1px_rgb(255_255_255_/_0.035)] light-theme:border-gray-700/45 light-theme:bg-gray-800/55 light-theme:text-white"
-            : "border-transparent text-gray-300 hover:bg-white/[0.055] hover:text-white light-theme:text-gray-500 light-theme:hover:bg-gray-900 light-theme:hover:text-white"
-      }`}
-    >
-      <button
-        type="button"
-        className={`grid h-5 w-5 shrink-0 place-items-center rounded border transition-colors ${
-          selected
-            ? "border-white/30 bg-gray-200 text-gray-950 light-theme:border-gray-700/55 light-theme:bg-gray-700 light-theme:text-white"
-            : "border-white/15 bg-white/[0.035] text-transparent hover:border-white/30 light-theme:border-gray-700/50 light-theme:bg-gray-950"
-        } ${alreadyAdded ? "cursor-not-allowed opacity-40" : ""}`}
-        onClick={onToggle}
-        disabled={alreadyAdded}
-        aria-label={selected ? `Remove ${entry.name} from folders to add` : `Choose ${entry.name}`}
-      >
-        <svg className="h-3.5 w-3.5" fill="none" viewBox="0 0 24 24" stroke="currentColor">
-          <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2.5} d="M5 13l4 4L19 7" />
-        </svg>
-      </button>
-
-      <Tooltip label={entry.path} anchorToCursor className="min-w-0 flex-1">
-        <button
-          type="button"
-          className="flex w-full min-w-0 items-center gap-2 text-left"
-          onClick={onNavigate}
-        >
-          <svg className="h-4 w-4 shrink-0 text-amber-300/90" fill="currentColor" viewBox="0 0 24 24">
-            <path d="M3 6.5A2.5 2.5 0 015.5 4h4.1l2 2H18.5A2.5 2.5 0 0121 8.5v9A2.5 2.5 0 0118.5 20h-13A2.5 2.5 0 013 17.5v-11z" />
-          </svg>
-          <span className="truncate text-sm">{entry.name}</span>
-        </button>
-      </Tooltip>
-
-      {alreadyAdded ? (
-        <span className="rounded-md border border-white/10 bg-white/[0.04] px-2 py-0.5 text-[11px] text-gray-500 light-theme:border-gray-700/40 light-theme:bg-gray-950">
-          Added
-        </span>
-      ) : null}
-
-      <Tooltip label={entry.has_children ? "Open folder" : "No subfolders"} anchorToCursor>
-        <button
-          type="button"
-          className="rounded-md p-1 text-gray-500 transition-colors hover:bg-white/[0.06] hover:text-white light-theme:hover:bg-gray-900 light-theme:hover:text-white"
-          onClick={onNavigate}
-        >
-          <svg className={`h-4 w-4 ${entry.has_children ? "" : "opacity-45"}`} fill="none" viewBox="0 0 24 24" stroke="currentColor">
-            <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M9 5l7 7-7 7" />
-          </svg>
-        </button>
-      </Tooltip>
-    </div>
-  );
-}
-
-function StagedFoldersPanel({
-  stagedPaths,
-  onRemove,
-  onClear,
-}: {
-  stagedPaths: string[];
-  onRemove: (path: string) => void;
-  onClear: () => void;
-}) {
-  return (
-    <aside className="flex min-h-0 w-full flex-col border-t border-white/[0.07] bg-white/[0.018] light-theme:border-gray-300/70 light-theme:bg-gray-900/35 lg:w-80 lg:border-l lg:border-t-0">
-      <div className="flex items-center justify-between gap-3 border-b border-white/[0.07] px-5 py-4 light-theme:border-gray-300/70">
-        <p className="text-[11px] font-semibold uppercase tracking-[0.16em] text-gray-500">
-          Folders to add ({stagedPaths.length})
-        </p>
-        {stagedPaths.length > 0 ? (
-          <button
-            type="button"
-            className="rounded px-1.5 py-0.5 text-xs text-gray-400 transition-colors hover:bg-white/[0.06] hover:text-white light-theme:text-gray-500 light-theme:hover:bg-gray-800 light-theme:hover:text-white"
-            onClick={onClear}
-          >
-            Clear all
-          </button>
-        ) : null}
-      </div>
-
-      <div className="min-h-0 flex-1 overflow-y-auto p-3">
-        {stagedPaths.length === 0 ? (
-          <div className="flex h-full min-h-40 flex-col items-center justify-center rounded-md border border-dashed border-white/[0.08] px-5 text-center light-theme:border-gray-700/35">
-            <p className="text-sm text-gray-500">No folders selected.</p>
-            <p className="mt-1 max-w-52 text-xs leading-relaxed text-gray-600 light-theme:text-gray-500">
-              Choose folders on the left and they will collect here.
-            </p>
-          </div>
-        ) : (
-          <div className="space-y-2">
-            {stagedPaths.map((path) => (
-              <Tooltip key={path} label={path} anchorToCursor block>
-                <div className="group flex min-h-12 items-center gap-2 rounded-md border border-white/[0.07] bg-white/[0.045] px-3 py-2 text-gray-200 transition-colors hover:border-white/15 hover:bg-white/[0.07] light-theme:border-gray-700/40 light-theme:bg-gray-900 light-theme:text-white light-theme:hover:bg-gray-800">
-                  <svg className="h-4 w-4 shrink-0 text-amber-300/90" fill="currentColor" viewBox="0 0 24 24">
-                    <path d="M3 6.5A2.5 2.5 0 015.5 4h4.1l2 2H18.5A2.5 2.5 0 0121 8.5v9A2.5 2.5 0 0118.5 20h-13A2.5 2.5 0 013 17.5v-11z" />
-                  </svg>
-                  <div className="min-w-0 flex-1">
-                    <p className="truncate text-sm font-medium">{folderName(path)}</p>
-                    <p className="mt-0.5 truncate text-[11px] text-gray-600 light-theme:text-gray-500">{path}</p>
-                  </div>
-                  <Tooltip label="Remove from folders to add" anchorToCursor>
-                    <button
-                      type="button"
-                      className="rounded-md p-1 text-gray-500 opacity-80 transition-colors hover:bg-white/[0.08] hover:text-white group-hover:opacity-100 light-theme:hover:bg-gray-700"
-                      onClick={() => onRemove(path)}
-                      aria-label={`Remove ${path} from folders to add`}
-                    >
-                      <svg className="h-3.5 w-3.5" fill="none" viewBox="0 0 24 24" stroke="currentColor">
-                        <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M6 18L18 6M6 6l12 12" />
-                      </svg>
-                    </button>
-                  </Tooltip>
-                </div>
-              </Tooltip>
-            ))}
-          </div>
-        )}
-      </div>
-    </aside>
-  );
-}
+import { useVirtualizer } from '@tanstack/react-virtual'
+import { Tooltip } from './Tooltip'
+import { CloseIcon } from './icons'
+import { FolderRow } from './folderPicker/FolderRow'
+import { StagedFoldersPanel } from './folderPicker/StagedFoldersPanel'
+import { StatusLine } from './folderPicker/StatusLine'
+import { normalizePath } from './folderPicker/pathUtils'
+import { useFolderPicker } from './folderPicker/useFolderPicker'
 
 export function FolderPickerModal() {
-  const folderPickerOpen = useGalleryStore((state) => state.folderPickerOpen);
-  const setFolderPickerOpen = useGalleryStore((state) => state.setFolderPickerOpen);
-  const folders = useGalleryStore((state) => state.folders);
-  const listDirectories = useGalleryStore((state) => state.listDirectories);
-  const addFolders = useGalleryStore((state) => state.addFolders);
-
-  const [listing, setListing] = useState<DirListing | null>(null);
-  const [currentPath, setCurrentPath] = useState<string | null>(null);
-  const [addressDraft, setAddressDraft] = useState("");
-  const [addressEditing, setAddressEditing] = useState(false);
-  const [stagedPaths, setStagedPaths] = useState<string[]>([]);
-  const [loading, setLoading] = useState(false);
-  const [adding, setAdding] = useState(false);
-  const [error, setError] = useState<string | null>(null);
-  const [results, setResults] = useState<FolderAddResult[] | null>(null);
-  const scrollRef = useRef<HTMLDivElement>(null);
-  const addressInputRef = useRef<HTMLInputElement>(null);
-
-  const libraryPaths = useMemo(() => new Set(folders.map((folder) => normalizePath(folder.path))), [folders]);
-  const stagedSet = useMemo(() => new Set(stagedPaths.map(normalizePath)), [stagedPaths]);
-  const breadcrumbs = useMemo(() => buildBreadcrumbs(listing?.current ?? null), [listing?.current]);
+  const folderPicker = useFolderPicker()
 
   const virtualizer = useVirtualizer({
-    count: listing?.entries.length ?? 0,
-    getScrollElement: () => scrollRef.current,
+    count: folderPicker.entries.length,
+    getScrollElement: () => folderPicker.scrollRef.current,
     estimateSize: () => 48,
     overscan: 8,
-  });
-
-  useEffect(() => {
-    if (!folderPickerOpen) return;
-    let cancelled = false;
-    setLoading(true);
-    setError(null);
-    void listDirectories(currentPath)
-      .then((nextListing) => {
-        if (cancelled) return;
-        setListing(nextListing);
-        setAddressDraft(nextListing.current ?? "");
-        setAddressEditing(false);
-        scrollRef.current?.scrollTo({ top: 0, left: 0 });
   })
-      .catch((loadError) => {
-        if (cancelled) return;
-        setListing({ current: currentPath, parent: null, entries: [] });
-        setError(friendlyDirectoryError(loadError));
-      })
-      .finally(() => {
-        if (!cancelled) setLoading(false);
-      });
-    return () => {
-      cancelled = true;
-    };
-  }, [currentPath, folderPickerOpen, listDirectories]);
 
-  useEffect(() => {
-    if (!folderPickerOpen) return;
-    const handleKeyDown = (event: KeyboardEvent) => {
-      if (event.key === "Escape") {
-        if (addressEditing) {
-          setAddressDraft(listing?.current ?? "");
-          setAddressEditing(false);
-          return;
-        }
-        setFolderPickerOpen(false);
-      }
-    };
-    window.addEventListener("keydown", handleKeyDown);
-    return () => window.removeEventListener("keydown", handleKeyDown);
-  }, [addressEditing, folderPickerOpen, listing?.current, setFolderPickerOpen]);
-
-  useEffect(() => {
-    if (!addressEditing) return;
-    requestAnimationFrame(() => {
-      addressInputRef.current?.focus();
-      addressInputRef.current?.select();
-    });
-  }, [addressEditing]);
-
-  useEffect(() => {
-    if (folderPickerOpen) return;
-    setCurrentPath(null);
-    setAddressDraft("");
-    setAddressEditing(false);
-    setListing(null);
-    setStagedPaths([]);
-    setError(null);
-    setResults(null);
-    setAdding(false);
-  }, [folderPickerOpen]);
-
-  if (!folderPickerOpen) return null;
-
-  const entries = listing?.entries ?? [];
-  const addressPath = cleanAddressInput(addressEditing ? addressDraft : (listing?.current ?? ""));
-  const normalizedAddressPath = addressPath ? normalizePath(addressPath) : "";
-  const addressAlreadyAdded = normalizedAddressPath ? libraryPaths.has(normalizedAddressPath) : false;
-  const addressAlreadyStaged = normalizedAddressPath ? stagedSet.has(normalizedAddressPath) : false;
-
-  const togglePath = (path: string) => {
-    const normalized = normalizePath(path);
-    if (libraryPaths.has(normalized)) return;
-    setResults(null);
-    setStagedPaths((current) => {
-      const exists = current.some((staged) => normalizePath(staged) === normalized);
-      return exists ? current.filter((staged) => normalizePath(staged) !== normalized) : [...current, path];
-    });
-  };
-
-  const stagePath = (path: string) => {
-    const cleaned = cleanAddressInput(path);
-    if (!cleaned) {
-      setError("Enter a folder path first.");
-      return;
-    }
-
-    const normalized = normalizePath(cleaned);
-    if (libraryPaths.has(normalized)) {
-      setError("That folder is already in your library.");
-      return;
-    }
-    if (stagedSet.has(normalized)) {
-      setError("That folder is already selected.");
-      return;
-    }
-
-    setError(null);
-    setResults(null);
-    setStagedPaths((current) => [...current, cleaned]);
-  };
-
-  const navigateToAddress = () => {
-    const cleaned = cleanAddressInput(addressDraft);
-    setResults(null);
-    setError(null);
-    setCurrentPath(cleaned || null);
-  };
-
-  const beginAddressEdit = () => {
-    setAddressDraft(listing?.current ?? "");
-    setAddressEditing(true);
-  };
-
-  const removeStagedPath = (path: string) => {
-    const normalized = normalizePath(path);
-    setResults(null);
-    setStagedPaths((current) => current.filter((staged) => normalizePath(staged) !== normalized));
-  };
-
-  const clearStagedPaths = () => {
-    setResults(null);
-    setStagedPaths([]);
-  };
-
-  const confirmAdd = async () => {
-    if (stagedPaths.length === 0 || adding) return;
-    setAdding(true);
-    setError(null);
-    try {
-      const addResults = await addFolders(stagedPaths);
-      const failed = addResults.filter((result) => result.status === "error");
-      setResults(addResults);
-      if (failed.length > 0) {
-        setStagedPaths(stagedPaths.filter((_, i) => addResults[i]?.status === "error"));
-        setError(failed.map((failure) => failure.data).join("; "));
-        return;
-      }
-      setFolderPickerOpen(false);
-    } catch (addError) {
-      setError(addError instanceof Error ? addError.message : String(addError));
-    } finally {
-      setAdding(false);
-    }
-  };
+  if (!folderPicker.folderPickerOpen) return null
 
   return (
     <div
       className="fixed inset-0 z-[80] flex items-center justify-center bg-black/65 px-6 backdrop-blur-sm"
-      onClick={() => setFolderPickerOpen(false)}
+      onClick={() => folderPicker.setFolderPickerOpen(false)}
     >
       <div
-        className="relative flex h-[min(82vh,760px)] w-[min(90vw,1180px)] flex-col overflow-hidden rounded-lg border border-white/10 bg-gray-950 shadow-2xl shadow-black/60 light-theme:border-gray-300/70"
+        className="light-theme:border-gray-300/70 relative flex h-[min(82vh,760px)] w-[min(90vw,1180px)] flex-col overflow-hidden rounded-lg border border-white/10 bg-gray-950 shadow-2xl shadow-black/60"
         onClick={(event) => event.stopPropagation()}
       >
-        <header className="border-b border-white/[0.07] px-5 py-4 light-theme:border-gray-200">
+        <header className="light-theme:border-gray-200 border-b border-white/[0.07] px-5 py-4">
           <div className="flex items-start justify-between gap-6">
             <div className="min-w-0">
               <p className="text-base font-semibold text-white">Add media folders</p>
-              <p className="mt-1 text-xs text-gray-500 light-theme:text-gray-600">Choose folders from any location, then add them together.</p>
+              <p className="light-theme:text-gray-600 mt-1 text-xs text-gray-500">
+                Choose folders from any location, then add them together.
+              </p>
             </div>
             <Tooltip label="Close folder picker" anchorToCursor>
               <button
                 type="button"
-                className="rounded-md p-1.5 text-gray-500 transition-colors hover:bg-white/[0.06] hover:text-white light-theme:hover:bg-gray-900 light-theme:hover:text-white"
-                onClick={() => setFolderPickerOpen(false)}
+                className="light-theme:hover:bg-gray-900 light-theme:hover:text-white rounded-md p-1.5 text-gray-500 transition-colors hover:bg-white/[0.06] hover:text-white"
+                onClick={() => folderPicker.setFolderPickerOpen(false)}
               >
-                <svg className="h-4 w-4" fill="none" viewBox="0 0 24 24" stroke="currentColor">
-                  <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M6 18L18 6M6 6l12 12" />
-                </svg>
+                <CloseIcon className="h-4 w-4" />
               </button>
             </Tooltip>
           </div>
@@ -428,56 +53,58 @@ export function FolderPickerModal() {
             <div className="mb-4 flex items-center gap-2">
               <button
                 type="button"
-                className="rounded-md border border-white/10 bg-white/[0.035] px-2.5 py-1.5 text-xs text-gray-300 transition-colors hover:bg-white/[0.07] hover:text-white disabled:cursor-not-allowed disabled:opacity-40 light-theme:border-gray-700/50 light-theme:bg-gray-900 light-theme:text-white light-theme:hover:bg-gray-800"
-                onClick={() => setCurrentPath(listing?.parent ?? null)}
-                disabled={!listing?.current}
+                className="light-theme:border-gray-700/50 light-theme:bg-gray-900 light-theme:text-white light-theme:hover:bg-gray-800 rounded-md border border-white/10 bg-white/[0.035] px-2.5 py-1.5 text-xs text-gray-300 transition-colors hover:bg-white/[0.07] hover:text-white disabled:cursor-not-allowed disabled:opacity-40"
+                onClick={() => folderPicker.setCurrentPath(folderPicker.listing?.parent ?? null)}
+                disabled={!folderPicker.listing?.current}
               >
                 Up
               </button>
-              {addressEditing ? (
+              {folderPicker.addressEditing ? (
                 <form
                   className="flex min-w-0 flex-1 items-center gap-2"
                   onSubmit={(event) => {
-                    event.preventDefault();
-                    navigateToAddress();
+                    event.preventDefault()
+                    folderPicker.navigateToAddress()
                   }}
                 >
-                  <label className="sr-only" htmlFor="folder-picker-address">Folder path</label>
+                  <label className="sr-only" htmlFor="folder-picker-address">
+                    Folder path
+                  </label>
                   <input
-                    ref={addressInputRef}
+                    ref={folderPicker.addressInputRef}
                     id="folder-picker-address"
-                    className="min-w-0 flex-1 rounded-md border border-white/10 bg-white/[0.035] px-3 py-1.5 font-mono text-xs text-gray-200 placeholder-gray-600 outline-none transition-colors focus:border-white/25 focus:bg-white/[0.055] light-theme:border-gray-700/50 light-theme:bg-gray-900 light-theme:text-white light-theme:placeholder-gray-500 light-theme:focus:bg-gray-800"
-                    value={addressDraft}
-                    onChange={(event) => {
-                      setAddressDraft(event.target.value);
-                      setResults(null);
-                    }}
+                    className="light-theme:border-gray-700/50 light-theme:bg-gray-900 light-theme:text-white light-theme:placeholder-gray-500 light-theme:focus:bg-gray-800 min-w-0 flex-1 rounded-md border border-white/10 bg-white/[0.035] px-3 py-1.5 font-mono text-xs text-gray-200 placeholder-gray-600 transition-colors outline-none focus:border-white/25 focus:bg-white/[0.055]"
+                    value={folderPicker.addressDraft}
+                    onChange={(event) => folderPicker.updateAddressDraft(event.target.value)}
                     placeholder="Paste or type a folder path"
                     spellCheck={false}
                   />
                   <button
                     type="submit"
-                    className="rounded-md border border-white/10 bg-white/[0.035] px-2.5 py-1.5 text-xs text-gray-300 transition-colors hover:bg-white/[0.07] hover:text-white disabled:cursor-not-allowed disabled:opacity-40 light-theme:border-gray-700/50 light-theme:bg-gray-900 light-theme:text-white light-theme:hover:bg-gray-800"
-                    disabled={loading}
+                    className="light-theme:border-gray-700/50 light-theme:bg-gray-900 light-theme:text-white light-theme:hover:bg-gray-800 rounded-md border border-white/10 bg-white/[0.035] px-2.5 py-1.5 text-xs text-gray-300 transition-colors hover:bg-white/[0.07] hover:text-white disabled:cursor-not-allowed disabled:opacity-40"
+                    disabled={folderPicker.loading}
                   >
                     Go
                   </button>
                 </form>
               ) : (
-                <div
-                  className="flex min-w-0 flex-1 items-center gap-1 overflow-hidden rounded-md border border-white/10 bg-white/[0.025] px-2 py-1.5 light-theme:border-gray-300/70 light-theme:bg-gray-900"
-                >
+                <div className="light-theme:border-gray-300/70 light-theme:bg-gray-900 flex min-w-0 flex-1 items-center gap-1 overflow-hidden rounded-md border border-white/10 bg-white/[0.025] px-2 py-1.5">
                   <nav className="flex min-w-0 items-center gap-1 overflow-hidden">
-                    {breadcrumbs.map((crumb, index) => (
-                      <span key={`${crumb.path ?? "root"}-${index}`} className="flex min-w-0 items-center gap-1">
-                        {index > 0 ? <span className="text-gray-700 light-theme:text-gray-400">/</span> : null}
-                        <Tooltip label={crumb.path ?? "Roots"} anchorToCursor>
+                    {folderPicker.breadcrumbs.map((crumb, index) => (
+                      <span
+                        key={`${crumb.path ?? 'root'}-${index}`}
+                        className="flex min-w-0 items-center gap-1"
+                      >
+                        {index > 0 ? (
+                          <span className="light-theme:text-gray-400 text-gray-700">/</span>
+                        ) : null}
+                        <Tooltip label={crumb.path ?? 'Roots'} anchorToCursor>
                           <button
                             type="button"
-                            className="max-w-40 truncate rounded px-1.5 py-0.5 text-xs text-gray-400 transition-colors hover:bg-white/[0.06] hover:text-white light-theme:text-gray-500 light-theme:hover:bg-gray-800 light-theme:hover:text-white"
+                            className="light-theme:text-gray-500 light-theme:hover:bg-gray-800 light-theme:hover:text-white max-w-40 truncate rounded px-1.5 py-0.5 text-xs text-gray-400 transition-colors hover:bg-white/[0.06] hover:text-white"
                             onClick={(event) => {
-                              event.stopPropagation();
-                              setCurrentPath(crumb.path);
+                              event.stopPropagation()
+                              folderPicker.setCurrentPath(crumb.path)
                             }}
                           >
                             {crumb.label}
@@ -488,8 +115,8 @@ export function FolderPickerModal() {
                   </nav>
                   <button
                     type="button"
-                    className="min-w-10 flex-1 self-stretch cursor-text rounded px-1"
-                    onClick={beginAddressEdit}
+                    className="min-w-10 flex-1 cursor-text self-stretch rounded px-1"
+                    onClick={folderPicker.beginAddressEdit}
                     aria-label="Edit folder path"
                   />
                 </div>
@@ -497,36 +124,47 @@ export function FolderPickerModal() {
               <button
                 type="button"
                 className="rounded-md border border-emerald-400/35 bg-emerald-500/15 px-2.5 py-1.5 text-xs text-emerald-200 transition-colors hover:bg-emerald-500/25 disabled:cursor-not-allowed disabled:opacity-45"
-                onClick={() => stagePath(addressPath)}
-                disabled={!addressPath || addressAlreadyAdded || addressAlreadyStaged}
+                onClick={() => folderPicker.stagePath(folderPicker.addressPath)}
+                disabled={
+                  !folderPicker.addressPath ||
+                  folderPicker.addressAlreadyAdded ||
+                  folderPicker.addressAlreadyStaged
+                }
               >
                 Select
               </button>
             </div>
 
-            {error ? (
-              <div className="mb-3 rounded-md border border-amber-400/25 bg-amber-500/10 px-3 py-2 text-xs text-amber-200 light-theme:border-amber-600/40 light-theme:bg-amber-100 light-theme:text-amber-800">
-                {error}
+            {folderPicker.error ? (
+              <div className="light-theme:border-amber-600/40 light-theme:bg-amber-100 light-theme:text-amber-800 mb-3 rounded-md border border-amber-400/25 bg-amber-500/10 px-3 py-2 text-xs text-amber-200">
+                {folderPicker.error}
               </div>
             ) : null}
 
-            <div ref={scrollRef} className="min-h-0 flex-1 overflow-auto rounded-md border border-white/[0.07] bg-white/[0.018] p-2 light-theme:border-gray-300/70 light-theme:bg-gray-900/50">
-              {loading ? (
-                <div className="flex h-full items-center justify-center text-sm text-gray-500">Loading folders...</div>
-              ) : entries.length === 0 ? (
-                <div className="flex h-full items-center justify-center text-sm text-gray-500">No folders found here.</div>
+            <div
+              ref={folderPicker.scrollRef}
+              className="light-theme:border-gray-300/70 light-theme:bg-gray-900/50 min-h-0 flex-1 overflow-auto rounded-md border border-white/[0.07] bg-white/[0.018] p-2"
+            >
+              {folderPicker.loading ? (
+                <div className="flex h-full items-center justify-center text-sm text-gray-500">
+                  Loading folders...
+                </div>
+              ) : folderPicker.entries.length === 0 ? (
+                <div className="flex h-full items-center justify-center text-sm text-gray-500">
+                  No folders found here.
+                </div>
               ) : (
                 <div
                   className="relative w-full"
                   style={{ height: `${virtualizer.getTotalSize()}px` }}
                 >
                   {virtualizer.getVirtualItems().map((virtualItem) => {
-                    const entry = entries[virtualItem.index];
-                    const normalized = normalizePath(entry.path);
+                    const entry = folderPicker.entries[virtualItem.index]
+                    const normalized = normalizePath(entry.path)
                     return (
                       <div
                         key={virtualItem.key}
-                        className="absolute left-0 top-0 w-full px-0.5"
+                        className="absolute top-0 left-0 w-full px-0.5"
                         style={{
                           height: `${virtualItem.size}px`,
                           transform: `translateY(${virtualItem.start}px)`,
@@ -534,13 +172,13 @@ export function FolderPickerModal() {
                       >
                         <FolderRow
                           entry={entry}
-                          selected={stagedSet.has(normalized)}
-                          alreadyAdded={libraryPaths.has(normalized)}
-                          onToggle={() => togglePath(entry.path)}
-                          onNavigate={() => setCurrentPath(entry.path)}
+                          selected={folderPicker.stagedSet.has(normalized)}
+                          alreadyAdded={folderPicker.libraryPaths.has(normalized)}
+                          onToggle={() => folderPicker.togglePath(entry.path)}
+                          onNavigate={() => folderPicker.setCurrentPath(entry.path)}
                         />
                       </div>
-                    );
+                    )
                   })}
                 </div>
               )}
@@ -548,38 +186,38 @@ export function FolderPickerModal() {
           </main>
 
           <StagedFoldersPanel
-            stagedPaths={stagedPaths}
-            onRemove={removeStagedPath}
-            onClear={clearStagedPaths}
+            stagedPaths={folderPicker.stagedPaths}
+            onRemove={folderPicker.removeStagedPath}
+            onClear={folderPicker.clearStagedPaths}
           />
         </div>
 
-        <footer className="border-t border-white/[0.07] px-5 py-4 light-theme:border-gray-200">
+        <footer className="light-theme:border-gray-200 border-t border-white/[0.07] px-5 py-4">
           <div className="flex items-end justify-between gap-4">
             <div className="min-w-0 flex-1">
-              <StatusLine results={results} />
+              <StatusLine results={folderPicker.results} />
             </div>
 
             <div className="flex shrink-0 items-center gap-2">
               <button
                 type="button"
-                className="rounded-md border border-white/10 bg-white/[0.035] px-3 py-1.5 text-xs text-gray-300 transition-colors hover:bg-white/[0.07] hover:text-white light-theme:border-gray-700/50 light-theme:bg-gray-900 light-theme:text-white light-theme:hover:bg-gray-800"
-                onClick={() => setFolderPickerOpen(false)}
+                className="light-theme:border-gray-700/50 light-theme:bg-gray-900 light-theme:text-white light-theme:hover:bg-gray-800 rounded-md border border-white/10 bg-white/[0.035] px-3 py-1.5 text-xs text-gray-300 transition-colors hover:bg-white/[0.07] hover:text-white"
+                onClick={() => folderPicker.setFolderPickerOpen(false)}
               >
                 Cancel
               </button>
               <button
                 type="button"
-                className="rounded-md border border-white/15 bg-white/[0.08] px-3 py-1.5 text-xs text-white transition-colors hover:bg-white/[0.12] disabled:cursor-not-allowed disabled:opacity-45 light-theme:border-gray-700/50 light-theme:bg-gray-900 light-theme:text-white light-theme:hover:bg-gray-800"
-                onClick={() => void confirmAdd()}
-                disabled={stagedPaths.length === 0 || adding}
+                className="light-theme:border-gray-700/50 light-theme:bg-gray-900 light-theme:text-white light-theme:hover:bg-gray-800 rounded-md border border-white/15 bg-white/[0.08] px-3 py-1.5 text-xs text-white transition-colors hover:bg-white/[0.12] disabled:cursor-not-allowed disabled:opacity-45"
+                onClick={() => void folderPicker.confirmAdd()}
+                disabled={folderPicker.stagedPaths.length === 0 || folderPicker.adding}
               >
-                {adding ? "Adding..." : `Add ${stagedPaths.length}`}
+                {folderPicker.adding ? 'Adding...' : `Add ${folderPicker.stagedPaths.length}`}
               </button>
             </div>
           </div>
         </footer>
       </div>
     </div>
-  );
+  )
 }

src/components/FolderScopeDropdown.tsx

@@ -1,6 +1,6 @@
-import { useEffect, useRef, useState } from "react";
-import { useGalleryStore } from "../store";
-import { Tooltip } from "./Tooltip";
+import { useMemo } from 'react'
+import { useGalleryStore } from '../store'
+import { Dropdown, DropdownOption } from './menu'
 
 /**
  * In-view folder scope picker for feature views (Timeline / Explore /
@@ -8,93 +8,48 @@ import { Tooltip } from "./Tooltip";
  * current view active — unlike sidebar folder clicks, which jump to Gallery.
  */
 export function FolderScopeDropdown() {
-  const [open, setOpen] = useState(false);
-  const ref = useRef<HTMLDivElement>(null);
+  const folders = useGalleryStore((state) => state.folders)
+  const selectedFolderId = useGalleryStore((state) => state.selectedFolderId)
+  const setViewFolderScope = useGalleryStore((state) => state.setViewFolderScope)
 
-  const folders = useGalleryStore((state) => state.folders);
-  const selectedFolderId = useGalleryStore((state) => state.selectedFolderId);
-  const setViewFolderScope = useGalleryStore((state) => state.setViewFolderScope);
-
-  useEffect(() => {
-    const close = (e: MouseEvent) => {
-      if (!ref.current?.contains(e.target as Node)) setOpen(false);
-    };
-    window.addEventListener("pointerdown", close);
-    return () => window.removeEventListener("pointerdown", close);
-  }, []);
-
-  const currentLabel =
-    selectedFolderId === null
-      ? "All Media"
-      : folders.find((folder) => folder.id === selectedFolderId)?.name ?? "All Media";
-
-  const select = (folderId: number | null) => {
-    setViewFolderScope(folderId);
-    setOpen(false);
-  };
+  const options = useMemo<DropdownOption<number | null>[]>(
+    () => [
+      { value: null, label: 'All Media' },
+      ...folders.map((folder) => ({
+        value: folder.id,
+        label: folder.name,
+        hint: <span className="tabular-nums">{folder.image_count.toLocaleString()}</span>,
+      })),
+    ],
+    [folders]
+  )
 
   return (
-    <div ref={ref} className="feature-scope-dropdown relative">
-      <Tooltip label="Change folder scope" anchorToCursor>
-        <button
-          onClick={() => setOpen((v) => !v)}
-          className={`feature-scope-trigger flex max-w-56 items-center gap-1.5 rounded-lg border px-3 py-1.5 text-xs transition-colors ${
-            open
-              ? "border-white/15 bg-white/8 text-white light-theme:border-gray-700/50 light-theme:bg-gray-900 light-theme:text-white"
-              : "border-white/8 bg-transparent text-gray-400 hover:border-white/15 hover:text-gray-200 light-theme:border-gray-700/40 light-theme:text-gray-600 light-theme:hover:border-gray-700 light-theme:hover:bg-gray-900 light-theme:hover:text-white"
-          }`}
-        >
-          <svg className="h-3.5 w-3.5 shrink-0 text-gray-500" fill="none" viewBox="0 0 24 24" stroke="currentColor">
-            <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M3 7v10a2 2 0 002 2h14a2 2 0 002-2V9a2 2 0 00-2-2h-6l-2-2H5a2 2 0 00-2 2z" />
-          </svg>
-          <span className="truncate">{currentLabel}</span>
+    <Dropdown
+      value={selectedFolderId}
+      options={options}
+      onChange={setViewFolderScope}
+      ariaLabel="Folder scope"
+      trigger="ghost"
+      size="md"
+      triggerTooltip="Change folder scope"
+      triggerClassName="max-w-56"
+      panelClassName="min-w-52 max-h-80 overflow-y-auto"
+      triggerIcon={
         <svg
-            className={`h-3 w-3 shrink-0 text-gray-500 transition-transform duration-150 ${open ? "rotate-180" : ""}`}
-            fill="none" viewBox="0 0 24 24" stroke="currentColor"
+          className="h-3.5 w-3.5 shrink-0 text-gray-500"
+          fill="none"
+          viewBox="0 0 24 24"
+          stroke="currentColor"
         >
-            <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M19 9l-7 7-7-7" />
+          <path
+            strokeLinecap="round"
+            strokeLinejoin="round"
+            strokeWidth={2}
+            d="M3 7v10a2 2 0 002 2h14a2 2 0 002-2V9a2 2 0 00-2-2h-6l-2-2H5a2 2 0 00-2 2z"
+          />
         </svg>
-        </button>
-      </Tooltip>
-      {open ? (
-        <div className="feature-scope-menu absolute right-0 top-full z-30 mt-1.5 max-h-80 min-w-52 overflow-y-auto rounded-xl border border-white/10 bg-gray-950/98 p-1 shadow-2xl backdrop-blur light-theme:border-gray-700/50">
-          <button
-            className={`feature-scope-option flex w-full items-center justify-between gap-3 rounded-lg px-3 py-2 text-left text-sm transition-colors ${
-              selectedFolderId === null ? "bg-white/6 text-white light-theme:bg-gray-900 light-theme:text-white" : "text-gray-400 hover:bg-white/5 hover:text-white light-theme:text-gray-600 light-theme:hover:bg-gray-900 light-theme:hover:text-white"
-            }`}
-            onClick={() => select(null)}
-          >
-            All Media
-            {selectedFolderId === null ? (
-              <svg className="h-3.5 w-3.5 shrink-0 text-blue-400" fill="none" viewBox="0 0 24 24" stroke="currentColor">
-                <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2.5} d="M5 13l4 4L19 7" />
-              </svg>
-            ) : null}
-          </button>
-          {folders.map((folder) => {
-            const active = selectedFolderId === folder.id;
-            return (
-              <button
-                key={folder.id}
-                className={`feature-scope-option flex w-full items-center justify-between gap-3 rounded-lg px-3 py-2 text-left text-sm transition-colors ${
-                  active ? "bg-white/6 text-white light-theme:bg-gray-900 light-theme:text-white" : "text-gray-400 hover:bg-white/5 hover:text-white light-theme:text-gray-600 light-theme:hover:bg-gray-900 light-theme:hover:text-white"
-                }`}
-                onClick={() => select(folder.id)}
-              >
-                <span className="min-w-0 truncate">{folder.name}</span>
-                <span className="flex shrink-0 items-center gap-2">
-                  <span className="text-[11px] tabular-nums text-gray-600">{folder.image_count.toLocaleString()}</span>
-                  {active ? (
-                    <svg className="h-3.5 w-3.5 text-blue-400" fill="none" viewBox="0 0 24 24" stroke="currentColor">
-                      <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2.5} d="M5 13l4 4L19 7" />
-                    </svg>
-                  ) : null}
-                </span>
-              </button>
-            );
-          })}
-        </div>
-      ) : null}
-    </div>
-  );
+      }
+    />
+  )
 }

src/components/Gallery.tsx

@@ -1,366 +1,54 @@
-import { useEffect, useLayoutEffect, useRef, useCallback, useMemo, useState } from "react";
-import { useVirtualizer } from "@tanstack/react-virtual";
-import { ImageRecord, parseSearchValue, tileSizeForZoom, useGalleryStore } from "../store";
-import { BulkActionBar } from "./BulkActionBar";
-import { Tooltip } from "./Tooltip";
-import { mediaSrc } from "../lib/mediaSrc";
+import { useEffect, useLayoutEffect, useRef, useCallback, useMemo, useState } from 'react'
+import { useVirtualizer } from '@tanstack/react-virtual'
+import { ImageRecord, parseSearchValue, tileSizeForZoom, useGalleryStore } from '../store'
+import { BulkActionBar } from './BulkActionBar'
+import { ImageContextMenu } from './ImageContextMenu'
+import { GalleryEmptyState, GalleryLoadingState } from './gallery/GalleryEmptyState'
+import { ImageTile } from './gallery/ImageTile'
 
-const GAP = 6;
-
-function formatDuration(durationMs: number | null): string | null {
-  if (!durationMs || durationMs <= 0) return null;
-  const totalSeconds = Math.floor(durationMs / 1000);
-  const seconds = totalSeconds % 60;
-  const minutes = Math.floor(totalSeconds / 60) % 60;
-  const hours = Math.floor(totalSeconds / 3600);
-  if (hours > 0) {
-    return `${hours}:${minutes.toString().padStart(2, "0")}:${seconds.toString().padStart(2, "0")}`;
-  }
-  return `${minutes}:${seconds.toString().padStart(2, "0")}`;
-}
-
-export function ContextMenu({
-  x,
-  y,
-  image,
-  onClose,
-}: {
-  x: number;
-  y: number;
-  image: ImageRecord;
-  onClose: () => void;
-}) {
-  const openImage = useGalleryStore((state) => state.openImage);
-  const updateImageDetails = useGalleryStore((state) => state.updateImageDetails);
-  const findSimilar = useGalleryStore((state) => state.findSimilar);
-  const canFindSimilar = image.embedding_status === "ready";
-
-  return (
-    <div
-      data-gallery-context-menu
-      className="fixed z-40 min-w-52 rounded-xl border border-white/10 bg-gray-950/98 p-1 shadow-2xl backdrop-blur"
-      style={{ left: x, top: y }}
-      onClick={(event) => event.stopPropagation()}
-    >
-      <button
-        className="w-full rounded-lg px-3 py-2 text-left text-sm text-gray-200 hover:bg-white/5 hover:text-white transition-colors"
-        onClick={() => { openImage(image); onClose(); }}
-      >
-        Open Preview
-      </button>
-      <button
-        className="w-full rounded-lg px-3 py-2 text-left text-sm text-gray-200 hover:bg-white/5 hover:text-white transition-colors"
-        onClick={async () => { await updateImageDetails(image.id, { favorite: !image.favorite }); onClose(); }}
-      >
-        {image.favorite ? "Remove Favorite" : "Add to Favorites"}
-      </button>
-      <button
-        className={`w-full rounded-lg px-3 py-2 text-left text-sm transition-colors ${
-          canFindSimilar
-            ? "text-gray-200 hover:bg-white/5 hover:text-white"
-            : "text-gray-600 cursor-not-allowed"
-        }`}
-        onClick={() => {
-          if (!canFindSimilar) return;
-          findSimilar(image.id, image.folder_id);
-          onClose();
-        }}
-        disabled={!canFindSimilar}
-      >
-        {canFindSimilar ? "Find Similar" : "Embeddings not ready"}
-      </button>
-      <div className="my-1 h-px bg-white/[0.06]" />
-      <div className="px-3 py-1 text-[10px] uppercase tracking-[0.18em] text-gray-600">Rating</div>
-      <div className="flex items-center gap-0.5 px-2 pb-1.5">
-        {Array.from({ length: 5 }, (_, index) => {
-          const rating = index + 1;
-          return (
-            <Tooltip key={rating} label={`Set ${rating} star rating`} followCursor>
-              <button
-                className="rounded-md p-1 transition-colors hover:bg-white/5"
-                onClick={async () => { await updateImageDetails(image.id, { rating }); onClose(); }}
-              >
-                <svg
-                  className={`h-4 w-4 ${rating <= image.rating ? "text-amber-300" : "text-white/20 hover:text-white/40"}`}
-                  fill="currentColor" viewBox="0 0 20 20"
-                >
-                  <path d="M9.049 2.927c.3-.921 1.603-.921 1.902 0l1.07 3.292a1 1 0 00.95.69h3.462c.969 0 1.371 1.24.588 1.81l-2.8 2.034a1 1 0 00-.364 1.118l1.07 3.292c.3.921-.755 1.688-1.54 1.118l-2.8-2.034a1 1 0 00-1.176 0l-2.8 2.034c-.784.57-1.838-.197-1.539-1.118l1.07-3.292a1 1 0 00-.364-1.118L2.98 8.72c-.783-.57-.38-1.81.588-1.81H7.03a1 1 0 00.951-.69l1.07-3.292z" />
-                </svg>
-              </button>
-            </Tooltip>
-          );
-        })}
-        {image.rating > 0 ? (
-          <Tooltip label="Remove rating" followCursor>
-            <button
-              className="ml-1 rounded-md p-1 text-gray-600 hover:bg-white/5 hover:text-gray-300 transition-colors"
-              onClick={async () => { await updateImageDetails(image.id, { rating: 0 }); onClose(); }}
-            >
-              <svg className="h-3 w-3" fill="none" viewBox="0 0 24 24" stroke="currentColor">
-                <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M6 18L18 6M6 6l12 12" />
-              </svg>
-            </button>
-          </Tooltip>
-        ) : null}
-      </div>
-    </div>
-  );
-}
-
-export function ImageTile({
-  image,
-  onClick,
-  onContextMenu,
-}: {
-  image: ImageRecord;
-  onClick: () => void;
-  onContextMenu: (event: React.MouseEvent<HTMLDivElement>) => void;
-}) {
-  const [loaded, setLoaded] = useState(false);
-  const [errored, setErrored] = useState(false);
-  const findSimilar = useGalleryStore((state) => state.findSimilar);
-  const selected = useGalleryStore((state) => state.gallerySelectedIds.has(image.id));
-  const selectionActive = useGalleryStore((state) => state.gallerySelectedIds.size > 0);
-  const toggleGallerySelected = useGalleryStore((state) => state.toggleGallerySelected);
-  const canFindSimilar = image.embedding_status === "ready";
-
-  const src = mediaSrc(image.thumbnail_path);
-
-  return (
-    <div
-      className={`media-dark-surface group relative overflow-hidden rounded-xl bg-white/[0.04] text-left focus:outline-none transition-shadow ${
-        selected ? "ring-2 ring-inset ring-blue-400/80" : ""
-      }`}
-      style={{ width: "100%", aspectRatio: "1 / 1" }}
-      onContextMenu={onContextMenu}
-    >
-      {/* Full-tile click target — opens, or toggles selection while selecting.
-          A real button (over the non-interactive tile div) keeps it keyboard-
-          accessible without nesting buttons. */}
-      <button
-        type="button"
-        className="absolute inset-0 z-10 cursor-pointer focus:outline-none focus-visible:ring-2 focus-visible:ring-blue-400/80"
-        aria-label={`Open ${image.filename}`}
-        onClick={(event) => {
-          event.stopPropagation();
-          if (selectionActive) toggleGallerySelected(image.id);
-          else onClick();
-        }}
-        onDoubleClick={(event) => {
-          event.stopPropagation();
-          onClick();
-        }}
-      />
-      {/* Selection corner — a top-left zone that reveals the checkbox only when
-          hovered (not the whole tile) and toggles selection on click. The
-          checkbox stays visible once the item is selected. */}
-      <button
-        type="button"
-        role="checkbox"
-        aria-checked={selected}
-        aria-label={selected ? "Deselect" : "Select"}
-        className="group/cb absolute top-0 left-0 z-20 h-11 w-11 cursor-pointer"
-        onClick={(event) => {
-          event.stopPropagation();
-          toggleGallerySelected(image.id);
-        }}
-      >
-        <div
-          className={`absolute top-2 left-2 flex h-5 w-5 items-center justify-center rounded-full border transition-all duration-150 ${
-            selected
-              ? "border-blue-400 bg-blue-500 text-white opacity-100"
-              : "border-white/70 bg-black/40 text-transparent opacity-0 backdrop-blur-sm group-hover/cb:opacity-100"
-          }`}
-        >
-          <svg className="h-3 w-3" fill="none" viewBox="0 0 24 24" stroke="currentColor">
-            <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={3} d="M5 13l4 4L19 7" />
-          </svg>
-        </div>
-      </button>
-      {/* Image / placeholder */}
-      {src && !errored ? (
-        <>
-          {!loaded && <div className="absolute inset-0 animate-pulse bg-white/[0.04]" />}
-          <img
-            src={src}
-            alt={image.filename}
-            className={`h-full w-full object-cover transition-all duration-300 ${
-              loaded ? "opacity-100 scale-100" : "opacity-0 scale-[1.02]"
-            } group-hover:scale-[1.03]`}
-            loading="lazy"
-            onLoad={() => setLoaded(true)}
-            onError={() => setErrored(true)}
-          />
-        </>
-      ) : (
-        <div className="absolute inset-0 flex items-center justify-center bg-white/[0.03] text-white/20">
-          {image.media_kind === "video" ? (
-            <svg className="h-7 w-7" fill="currentColor" viewBox="0 0 24 24">
-              <path d="M8 5v14l11-7z" />
-            </svg>
-          ) : (
-            <svg className="h-7 w-7" fill="none" viewBox="0 0 24 24" stroke="currentColor">
-              <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={1}
-                d="M4 16l4.586-4.586a2 2 0 012.828 0L16 16m-2-2l1.586-1.586a2 2 0 012.828 0L20 14m-6-6h.01M6 20h12a2 2 0 002-2V6a2 2 0 00-2-2H6a2 2 0 00-2 2v12a2 2 0 002 2z" />
-            </svg>
-          )}
-        </div>
-      )}
-
-      {/* Video play icon — subtle at rest, visible on hover */}
-      {image.media_kind === "video" && (
-        <div className="absolute inset-0 flex items-center justify-center pointer-events-none">
-          <div className="rounded-full bg-black/40 p-3 text-white backdrop-blur-sm opacity-50 group-hover:opacity-90 transition-opacity duration-200">
-            <svg className="h-5 w-5" fill="currentColor" viewBox="0 0 24 24">
-              <path d="M8 5v14l11-7z" />
-            </svg>
-          </div>
-        </div>
-      )}
-
-      {/* Persistent badges — only shown when meaningful */}
-      <div className="absolute top-2 right-2 flex flex-col items-end gap-1 pointer-events-none">
-        {image.embedding_status === "failed" && (
-          <Tooltip label={image.embedding_error ?? "Embedding failed"} followCursor className="pointer-events-auto">
-            <div className="flex items-center gap-1 rounded-md bg-black/60 px-1.5 py-0.5 text-[10px] font-medium text-amber-400 backdrop-blur-sm">
-              <svg className="h-2.5 w-2.5 shrink-0" fill="none" viewBox="0 0 24 24" stroke="currentColor">
-                <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2.5}
-                  d="M12 9v2m0 4h.01M10.29 3.86L1.82 18a2 2 0 001.71 3h16.94a2 2 0 001.71-3L13.71 3.86a2 2 0 00-3.42 0z" />
-              </svg>
-            </div>
-          </Tooltip>
-        )}
-        {image.favorite && (
-          <div className="rounded-full bg-black/50 p-1 text-rose-400 backdrop-blur-sm">
-            <svg className="h-2.5 w-2.5" fill="currentColor" viewBox="0 0 20 20">
-              <path d="M3.172 5.172a4 4 0 015.656 0L10 6.343l1.172-1.171a4 4 0 115.656 5.656L10 17.657l-6.828-6.829a4 4 0 010-5.656z" />
-            </svg>
-          </div>
-        )}
-        {image.rating > 0 && (
-          <div className="flex items-center gap-0.5 rounded-md bg-black/60 px-1.5 py-1 text-amber-300 backdrop-blur-sm">
-            {Array.from({ length: image.rating }, (_, index) => (
-              <svg key={index} className="h-2.5 w-2.5" fill="currentColor" viewBox="0 0 20 20">
-                <path d="M9.049 2.927c.3-.921 1.603-.921 1.902 0l1.07 3.292a1 1 0 00.95.69h3.462c.969 0 1.371 1.24.588 1.81l-2.8 2.034a1 1 0 00-.364 1.118l1.07 3.292c.3.921-.755 1.688-1.54 1.118l-2.8-2.034a1 1 0 00-1.176 0l-2.8 2.034c-.784.57-1.838-.197-1.539-1.118l1.07-3.292a1 1 0 00-.364-1.118L2.98 8.72c-.783-.57-.38-1.81.588-1.81H7.03a1 1 0 00.951-.69l1.07-3.292z" />
-              </svg>
-            ))}
-          </div>
-        )}
-        {image.media_kind === "video" && image.duration_ms && (
-          <div className="rounded-md bg-black/60 px-1.5 py-0.5 text-[10px] font-medium text-white/80 backdrop-blur-sm">
-            {formatDuration(image.duration_ms)}
-          </div>
-        )}
-      </div>
-
-      {/* Hover overlay — slides up from bottom */}
-      <div className="absolute inset-0 bg-gradient-to-t from-black/85 via-black/30 to-transparent opacity-0 group-hover:opacity-100 transition-opacity duration-200 pointer-events-none" />
-
-      {/* Hover info — appears with overlay */}
-      <div className="absolute bottom-0 left-0 right-0 z-20 p-2.5 translate-y-1 group-hover:translate-y-0 opacity-0 group-hover:opacity-100 transition-all duration-200">
-        <TruncatedFilename filename={image.filename} />
-        <div className="mt-1.5 flex items-center justify-between gap-2">
-          {image.rating > 0 ? (
-            <div className="flex items-center gap-0.5">
-              {Array.from({ length: image.rating }, (_, i) => (
-                <svg key={i} className="h-2.5 w-2.5 text-amber-300" fill="currentColor" viewBox="0 0 20 20">
-                  <path d="M9.049 2.927c.3-.921 1.603-.921 1.902 0l1.07 3.292a1 1 0 00.95.69h3.462c.969 0 1.371 1.24.588 1.81l-2.8 2.034a1 1 0 00-.364 1.118l1.07 3.292c.3.921-.755 1.688-1.54 1.118l-2.8-2.034a1 1 0 00-1.176 0l-2.8 2.034c-.784.57-1.838-.197-1.539-1.118l1.07-3.292a1 1 0 00-.364-1.118L2.98 8.72c-.783-.57-.38-1.81.588-1.81H7.03a1 1 0 00.951-.69l1.07-3.292z" />
-                </svg>
-              ))}
-            </div>
-          ) : (
-            <span />
-          )}
-          <button
-            className={`relative z-20 rounded-md px-2 py-0.5 text-[10px] transition-colors pointer-events-auto backdrop-blur-sm focus:outline-none focus-visible:ring-2 focus-visible:ring-blue-400/80 ${
-              canFindSimilar
-                ? "bg-white/10 text-white/80 hover:bg-white/20 hover:text-white"
-                : "bg-white/5 text-white/30 cursor-not-allowed"
-            }`}
-            onClick={(event) => {
-              event.stopPropagation();
-              if (!canFindSimilar) return;
-              findSimilar(image.id, image.folder_id);
-            }}
-            disabled={!canFindSimilar}
-          >
-            Similar
-          </button>
-        </div>
-      </div>
-    </div>
-  );
-}
-
-function TruncatedFilename({ filename }: { filename: string }) {
-  const textRef = useRef<HTMLParagraphElement>(null);
-  const [isTruncated, setIsTruncated] = useState(false);
-
-  useLayoutEffect(() => {
-    const text = textRef.current;
-    if (!text) return;
-
-    const update = () => {
-      setIsTruncated(text.scrollWidth > text.clientWidth);
-    };
-
-    update();
-
-    const observer = new ResizeObserver(update);
-    observer.observe(text);
-    return () => observer.disconnect();
-  }, [filename]);
-
-  const label = (
-    <p ref={textRef} className="truncate text-[12px] font-medium leading-tight text-white">
-      {filename}
-    </p>
-  );
-
-  return (
-    <Tooltip label={filename} delay={500} block followCursor disabled={!isTruncated}>
-      {label}
-    </Tooltip>
-  );
-}
+const GAP = 6
 
 export function Gallery() {
-  const images = useGalleryStore((state) => state.images);
-  const loadMoreImages = useGalleryStore((state) => state.loadMoreImages);
-  const openImage = useGalleryStore((state) => state.openImage);
-  const totalImages = useGalleryStore((state) => state.totalImages);
-  const loadingImages = useGalleryStore((state) => state.loadingImages);
-  const zoomPreset = useGalleryStore((state) => state.zoomPreset);
-  const search = useGalleryStore((state) => state.search);
-  const collectionTitle = useGalleryStore((state) => state.collectionTitle);
-  const imageLoadError = useGalleryStore((state) => state.imageLoadError);
-  const galleryScrollResetKey = useGalleryStore((state) => state.galleryScrollResetKey);
-  const isSimilarResults = collectionTitle === "Similar Images";
-  const parsedSearch = parseSearchValue(search);
+  const images = useGalleryStore((state) => state.images)
+  const loadMoreImages = useGalleryStore((state) => state.loadMoreImages)
+  const openImage = useGalleryStore((state) => state.openImage)
+  const totalImages = useGalleryStore((state) => state.totalImages)
+  const loadingImages = useGalleryStore((state) => state.loadingImages)
+  const zoomPreset = useGalleryStore((state) => state.zoomPreset)
+  const search = useGalleryStore((state) => state.search)
+  const collectionTitle = useGalleryStore((state) => state.collectionTitle)
+  const imageLoadError = useGalleryStore((state) => state.imageLoadError)
+  const galleryScrollResetKey = useGalleryStore((state) => state.galleryScrollResetKey)
+  const isSimilarResults = collectionTitle === 'Similar Images'
+  const parsedSearch = parseSearchValue(search)
 
-  const parentRef = useRef<HTMLDivElement>(null);
-  const [containerWidth, setContainerWidth] = useState(0);
-  const [contextMenu, setContextMenu] = useState<{ x: number; y: number; image: ImageRecord } | null>(null);
+  const parentRef = useRef<HTMLDivElement>(null)
+  const [containerWidth, setContainerWidth] = useState(0)
+  const [contextMenu, setContextMenu] = useState<{
+    x: number
+    y: number
+    image: ImageRecord
+  } | null>(null)
 
   useLayoutEffect(() => {
-    const el = parentRef.current;
-    if (!el) return;
-    setContainerWidth(el.clientWidth);
+    const el = parentRef.current
+    if (!el) return
+    setContainerWidth(el.clientWidth)
     const ro = new ResizeObserver((entries) => {
-      setContainerWidth(entries[0].contentRect.width);
-    });
-    ro.observe(el);
-    return () => ro.disconnect();
-  }, []);
+      setContainerWidth(entries[0].contentRect.width)
+    })
+    ro.observe(el)
+    return () => ro.disconnect()
+  }, [])
 
-  const tileSize = tileSizeForZoom(zoomPreset);
+  const tileSize = tileSizeForZoom(zoomPreset)
   const cols = useMemo(
     () => Math.max(1, Math.floor((containerWidth - GAP) / (tileSize + GAP))),
-    [containerWidth, tileSize],
-  );
-  const rowCount = Math.ceil(images.length / cols);
+    [containerWidth, tileSize]
+  )
+  const rowCount = Math.ceil(images.length / cols)
 
-  const estimateSize = useCallback(() => tileSize + GAP, [tileSize]);
+  const estimateSize = useCallback(() => tileSize + GAP, [tileSize])
 
   const virtualizer = useVirtualizer({
     count: rowCount,
@@ -368,127 +56,67 @@ export function Gallery() {
     estimateSize,
     overscan: 3,
     paddingStart: GAP,
-  });
+  })
 
   useEffect(() => {
-    virtualizer.measure();
-  }, [cols, virtualizer]);
+    virtualizer.measure()
+  }, [cols, virtualizer])
 
   useEffect(() => {
-    parentRef.current?.scrollTo({ top: 0, left: 0 });
-  }, [galleryScrollResetKey]);
+    parentRef.current?.scrollTo({ top: 0, left: 0 })
+  }, [galleryScrollResetKey])
 
   const handleScroll = useCallback(() => {
-    const el = parentRef.current;
-    if (!el) return;
-    if (el.scrollTop < 24) return;
-    const nearBottom = el.scrollTop + el.clientHeight >= el.scrollHeight - 600;
+    const el = parentRef.current
+    if (!el) return
+    if (el.scrollTop < 24) return
+    const nearBottom = el.scrollTop + el.clientHeight >= el.scrollHeight - 600
     if (nearBottom && !loadingImages && images.length < totalImages) {
-      void loadMoreImages();
+      void loadMoreImages()
     }
-  }, [images.length, loadMoreImages, loadingImages, totalImages]);
+  }, [images.length, loadMoreImages, loadingImages, totalImages])
 
   useEffect(() => {
-    const el = parentRef.current;
-    if (!el) return;
-    el.addEventListener("scroll", handleScroll, { passive: true });
-    return () => el.removeEventListener("scroll", handleScroll);
-  }, [handleScroll]);
-
-  useEffect(() => {
-    const close = (event: PointerEvent) => {
-      if ((event.target as HTMLElement | null)?.closest("[data-gallery-context-menu]")) return;
-      setContextMenu(null);
-    };
-    const handleKeyDown = (event: KeyboardEvent) => {
-      if (event.key === "Escape") setContextMenu(null);
-    };
-    window.addEventListener("pointerdown", close);
-    window.addEventListener("keydown", handleKeyDown);
-    return () => {
-      window.removeEventListener("pointerdown", close);
-      window.removeEventListener("keydown", handleKeyDown);
-    };
-  }, []);
+    const el = parentRef.current
+    if (!el) return
+    el.addEventListener('scroll', handleScroll, { passive: true })
+    return () => el.removeEventListener('scroll', handleScroll)
+  }, [handleScroll])
 
   return (
-    <div className="relative flex-1 min-h-0">
-    <div ref={parentRef} className="absolute inset-0 overflow-y-auto overflow-x-hidden bg-gray-950">
+    <div className="relative min-h-0 flex-1">
+      <div
+        ref={parentRef}
+        className="absolute inset-0 overflow-x-hidden overflow-y-auto bg-gray-950"
+      >
         {images.length === 0 && loadingImages ? (
-        <div className="flex flex-1 flex-col items-center justify-center gap-4 text-center px-8 absolute inset-0">
-          <div className="rounded-2xl border border-white/[0.06] bg-white/[0.02] p-8 min-w-72">
-            <div className="h-5 w-5 mx-auto rounded-full border-2 border-white/20 border-t-white/60 animate-spin" />
-            <p className="mt-4 text-sm text-white/40 font-medium">
-              {isSimilarResults
-                ? "Finding similar images"
-                : parsedSearch.mode === "semantic" && parsedSearch.query.length > 0
-                ? `Searching for matches to "${parsedSearch.query}"`
-                : parsedSearch.mode === "tag" && parsedSearch.query.length > 0
-                ? `Searching tags for "${parsedSearch.query}"`
-                : "Loading media"}
-            </p>
-            <p className="text-xs text-white/20 mt-1">
-              {isSimilarResults
-                ? "Comparing visual embeddings"
-                : parsedSearch.mode === "semantic" && parsedSearch.query.length > 0
-                ? "Semantic search can take a little longer than filename search"
-                : parsedSearch.mode === "tag" && parsedSearch.query.length > 0
-                ? "Matching against AI and user tags"
-                : "Fetching results"}
-            </p>
-          </div>
-        </div>
+          <GalleryLoadingState isSimilarResults={isSimilarResults} parsedSearch={parsedSearch} />
         ) : images.length === 0 && !loadingImages ? (
-        <div className="flex flex-1 flex-col items-center justify-center gap-4 text-center px-8 absolute inset-0">
-          <div className="rounded-2xl border border-white/[0.06] bg-white/[0.02] p-8">
-            <svg className="h-12 w-12 mx-auto text-white/10 mb-4" fill="none" viewBox="0 0 24 24" stroke="currentColor">
-              <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={0.75}
-                d="M4 16l4.586-4.586a2 2 0 012.828 0L16 16m-2-2l1.586-1.586a2 2 0 012.828 0L20 14m-6-6h.01M6 20h12a2 2 0 002-2V6a2 2 0 00-2-2H6a2 2 0 00-2 2v12a2 2 0 002 2z" />
-            </svg>
-            <p className="text-sm text-white/30 font-medium">
-              {imageLoadError
-                ? "Could not load results"
-                : isSimilarResults
-                ? "No similar images found"
-                : parsedSearch.mode === "semantic" && parsedSearch.query.length > 0
-                ? "No semantic matches found"
-                : parsedSearch.mode === "tag" && parsedSearch.query.length > 0
-                ? "No tag matches found"
-                : "No media found"}
-            </p>
-            <p className="text-xs text-white/15 mt-1">
-              {imageLoadError
-                ? imageLoadError
-                : isSimilarResults
-                ? "This item may be visually isolated, or more embeddings may need to finish processing"
-                : parsedSearch.mode === "semantic" && parsedSearch.query.length > 0
-                ? "Try a broader phrase, or wait for more embeddings to finish processing"
-                : parsedSearch.mode === "tag" && parsedSearch.query.length > 0
-                ? "Try a shorter tag, or wait for more tagging jobs to finish"
-                : "Try adjusting your filters or add a new folder"}
-            </p>
-          </div>
-        </div>
+          <GalleryEmptyState
+            imageLoadError={imageLoadError}
+            isSimilarResults={isSimilarResults}
+            parsedSearch={parsedSearch}
+          />
         ) : (
-        <div style={{ height: virtualizer.getTotalSize(), position: "relative" }}>
+          <div style={{ height: virtualizer.getTotalSize(), position: 'relative' }}>
             {virtualizer.getVirtualItems().map((virtualRow) => {
-            const startIndex = virtualRow.index * cols;
-            const rowImages = images.slice(startIndex, startIndex + cols);
+              const startIndex = virtualRow.index * cols
+              const rowImages = images.slice(startIndex, startIndex + cols)
               return (
                 <div
                   key={virtualRow.key}
                   style={{
-                  position: "absolute",
+                    position: 'absolute',
                     top: virtualRow.start,
-                  width: "100%",
+                    width: '100%',
                     height: virtualRow.size,
-                  display: "grid",
+                    display: 'grid',
                     gridTemplateColumns: `repeat(${cols}, ${tileSize}px)`,
                     gap: GAP,
                     paddingLeft: GAP,
                     paddingRight: GAP,
                     paddingBottom: GAP,
-                  boxSizing: "border-box",
+                    boxSizing: 'border-box',
                   }}
                 >
                   {rowImages.map((image) => (
@@ -497,25 +125,25 @@ export function Gallery() {
                       image={image}
                       onClick={() => openImage(image)}
                       onContextMenu={(event) => {
-                      event.preventDefault();
-                      setContextMenu({ x: event.clientX, y: event.clientY, image });
+                        event.preventDefault()
+                        setContextMenu({ x: event.clientX, y: event.clientY, image })
                       }}
                     />
                   ))}
                 </div>
-            );
+              )
             })}
           </div>
         )}
 
         {images.length > 0 && loadingImages ? (
           <div className="flex justify-center py-8">
-          <div className="h-4 w-4 rounded-full border-2 border-white/20 border-t-white/60 animate-spin" />
+            <div className="h-4 w-4 animate-spin rounded-full border-2 border-white/20 border-t-white/60" />
           </div>
         ) : null}
 
         {contextMenu ? (
-        <ContextMenu
+          <ImageContextMenu
             x={contextMenu.x}
             y={contextMenu.y}
             image={contextMenu.image}
@@ -528,5 +156,5 @@ export function Gallery() {
           container so it stays put while the grid scrolls. */}
       <BulkActionBar />
     </div>
-  );
+  )
 }

src/components/ImageContextMenu.tsx

@@ -0,0 +1,88 @@
+import { ImageRecord, useGalleryStore } from '../store'
+import { ContextMenu, MenuItem, MenuLabel, MenuSeparator, SubMenu } from './menu'
+import { Tooltip } from './Tooltip'
+import { CloseIcon, StarIcon } from './icons'
+
+/** Right-click menu for an image tile. Shared by the Gallery grid and the Timeline. */
+export function ImageContextMenu({
+  x,
+  y,
+  image,
+  onClose,
+}: {
+  x: number
+  y: number
+  image: ImageRecord
+  onClose: () => void
+}) {
+  const openImage = useGalleryStore((state) => state.openImage)
+  const updateImageDetails = useGalleryStore((state) => state.updateImageDetails)
+  const findSimilar = useGalleryStore((state) => state.findSimilar)
+  const albums = useGalleryStore((state) => state.albums)
+  const addToAlbum = useGalleryStore((state) => state.addToAlbum)
+  const canFindSimilar = image.embedding_status === 'ready'
+
+  return (
+    <ContextMenu x={x} y={y} onClose={onClose}>
+      <MenuItem label="Open Preview" onSelect={() => openImage(image)} />
+      <MenuItem
+        label={image.favorite ? 'Remove Favorite' : 'Add to Favorites'}
+        onSelect={() => void updateImageDetails(image.id, { favorite: !image.favorite })}
+      />
+      <MenuItem
+        label={canFindSimilar ? 'Find Similar' : 'Embeddings not ready'}
+        disabled={!canFindSimilar}
+        onSelect={() => findSimilar(image.id, image.folder_id)}
+      />
+      <SubMenu label="Add to Album" panelClassName="max-h-64 overflow-y-auto">
+        {albums.length === 0 ? (
+          <MenuItem label="No albums yet" disabled />
+        ) : (
+          albums.map((album) => (
+            <MenuItem
+              key={album.id}
+              label={album.name}
+              hint={album.image_count.toLocaleString()}
+              onSelect={() => void addToAlbum(album.id, [image.id])}
+            />
+          ))
+        )}
+      </SubMenu>
+      <MenuSeparator />
+      <MenuLabel>Rating</MenuLabel>
+      <div className="flex items-center gap-0.5 px-2 pb-1.5">
+        {Array.from({ length: 5 }, (_, index) => {
+          const rating = index + 1
+          return (
+            <Tooltip key={rating} label={`Set ${rating} star rating`} followCursor>
+              <button
+                className="rounded-md p-1 transition-colors hover:bg-white/5"
+                onClick={async () => {
+                  await updateImageDetails(image.id, { rating })
+                  onClose()
+                }}
+              >
+                <StarIcon
+                  className={`h-4 w-4 ${rating <= image.rating ? 'text-amber-300' : 'text-white/20 hover:text-white/40'}`}
+                />
+              </button>
+            </Tooltip>
+          )
+        })}
+        {image.rating > 0 ? (
+          <Tooltip label="Remove rating" followCursor>
+            <button
+              className="ml-1 rounded-md p-1 text-gray-600 transition-colors hover:bg-white/5 hover:text-gray-300"
+              onClick={async () => {
+                await updateImageDetails(image.id, { rating: 0 })
+                onClose()
+              }}
+            >
+              <CloseIcon className="h-3 w-3" />
+            </button>
+          </Tooltip>
+        ) : null}
+      </div>
+    </ContextMenu>
+  )
+}

src/components/InlineConfirm.tsx

@@ -0,0 +1,28 @@
+/**
+ * Compact Confirm/Cancel pair for destructive row actions (remove folder,
+ * delete album). Swap it in where the hover actions normally sit.
+ */
+export function InlineConfirm({
+  onConfirm,
+  onCancel,
+}: {
+  onConfirm: () => void
+  onCancel: () => void
+}) {
+  return (
+    <div className="flex shrink-0 items-center gap-1" onClick={(event) => event.stopPropagation()}>
+      <button
+        className="rounded bg-red-500/20 px-1.5 py-0.5 text-[10px] text-red-400 transition-colors hover:bg-red-500/30 hover:text-red-300"
+        onClick={onConfirm}
+      >
+        Confirm
+      </button>
+      <button
+        className="rounded bg-white/5 px-1.5 py-0.5 text-[10px] text-gray-500 transition-colors hover:bg-white/10 hover:text-gray-300"
+        onClick={onCancel}
+      >
+        Cancel
+      </button>
+    </div>
+  )
+}

src/components/InlineRename.tsx

@@ -0,0 +1,50 @@
+import { useEffect, useRef, useState } from 'react'
+
+/**
+ * In-place rename input for sidebar rows (folders, albums). Mount it in
+ * place of the row label while renaming: commits on Enter or blur (only when
+ * the trimmed name is non-empty and actually changed), cancels on Escape.
+ */
+export function InlineRename({
+  name,
+  onRename,
+  onClose,
+}: {
+  name: string
+  onRename: (next: string) => Promise<void> | void
+  onClose: () => void
+}) {
+  const [value, setValue] = useState(name)
+  const inputRef = useRef<HTMLInputElement>(null)
+
+  useEffect(() => {
+    inputRef.current?.focus()
+    inputRef.current?.select()
+  }, [])
+
+  const commit = async () => {
+    const trimmed = value.trim()
+    if (trimmed && trimmed !== name) {
+      await onRename(trimmed)
+    }
+    onClose()
+  }
+
+  return (
+    <input
+      ref={inputRef}
+      className="w-full rounded bg-white/10 px-1 py-0 text-[13px] leading-tight font-medium text-white ring-1 ring-blue-500/60 outline-none"
+      value={value}
+      onChange={(event) => setValue(event.target.value)}
+      onKeyDown={(event) => {
+        if (event.key === 'Enter') {
+          event.preventDefault()
+          void commit()
+        }
+        if (event.key === 'Escape') onClose()
+      }}
+      onBlur={() => void commit()}
+      onClick={(event) => event.stopPropagation()}
+    />
+  )
+}

src/components/MenuBar.tsx

@@ -1,184 +0,0 @@
-import { useEffect, useRef, useState } from "react";
-import { MediaFilter, ZoomPreset, useGalleryStore } from "../store";
-
-type MenuKey = "library" | "view" | "filter";
-
-function MenuButton({
-  label,
-  active,
-  onClick,
-}: {
-  label: string;
-  active: boolean;
-  onClick: () => void;
-}) {
-  return (
-    <button
-      className={`rounded-md px-2.5 py-1 text-xs transition-colors ${
-        active ? "bg-white/10 text-white" : "text-gray-400 hover:bg-white/5 hover:text-white"
-      }`}
-      onClick={onClick}
-    >
-      {label}
-    </button>
-  );
-}
-
-function MenuPanel({ children }: { children: React.ReactNode }) {
-  return (
-    <div className="absolute left-0 top-full z-30 mt-2 min-w-56 rounded-xl border border-white/10 bg-gray-950/95 p-2 shadow-2xl backdrop-blur">
-      {children}
-    </div>
-  );
-}
-
-function MenuItem({
-  label,
-  hint,
-  active = false,
-  onClick,
-}: {
-  label: string;
-  hint?: string;
-  active?: boolean;
-  onClick: () => void;
-}) {
-  return (
-    <button
-      className={`flex w-full items-center justify-between rounded-lg px-3 py-2 text-left text-sm transition-colors ${
-        active ? "bg-blue-500/15 text-white" : "text-gray-300 hover:bg-white/5 hover:text-white"
-      }`}
-      onClick={onClick}
-    >
-      <span>{label}</span>
-      {hint ? <span className="text-xs text-gray-500">{hint}</span> : null}
-    </button>
-  );
-}
-
-const ZOOM_OPTIONS: { value: ZoomPreset; label: string }[] = [
-  { value: "compact", label: "Compact Grid" },
-  { value: "comfortable", label: "Comfortable Grid" },
-  { value: "detail", label: "Detail Grid" },
-];
-
-const FILTER_OPTIONS: { value: MediaFilter; label: string }[] = [
-  { value: "all", label: "All Media" },
-  { value: "image", label: "Images" },
-  { value: "video", label: "Videos" },
-];
-
-export function MenuBar() {
-  const [openMenu, setOpenMenu] = useState<MenuKey | null>(null);
-  const rootRef = useRef<HTMLDivElement>(null);
-  const setFolderPickerOpen = useGalleryStore((state) => state.setFolderPickerOpen);
-  const reindexFolder = useGalleryStore((state) => state.reindexFolder);
-  const selectedFolderId = useGalleryStore((state) => state.selectedFolderId);
-  const zoomPreset = useGalleryStore((state) => state.zoomPreset);
-  const setZoomPreset = useGalleryStore((state) => state.setZoomPreset);
-  const mediaFilter = useGalleryStore((state) => state.mediaFilter);
-  const setMediaFilter = useGalleryStore((state) => state.setMediaFilter);
-  const favoritesOnly = useGalleryStore((state) => state.favoritesOnly);
-  const setFavoritesOnly = useGalleryStore((state) => state.setFavoritesOnly);
-
-  useEffect(() => {
-    const handlePointerDown = (event: MouseEvent) => {
-      if (!rootRef.current?.contains(event.target as Node)) {
-        setOpenMenu(null);
-      }
-    };
-
-    window.addEventListener("pointerdown", handlePointerDown);
-    return () => window.removeEventListener("pointerdown", handlePointerDown);
-  }, []);
-
-  const handleAddFolder = () => {
-    setFolderPickerOpen(true);
-    setOpenMenu(null);
-  };
-
-  const handleReindex = async () => {
-    if (selectedFolderId !== null) {
-      await reindexFolder(selectedFolderId);
-    }
-    setOpenMenu(null);
-  };
-
-  return (
-    <div ref={rootRef} className="relative z-20 flex items-center gap-1 border-b border-white/5 bg-gray-950/90 px-4 py-2 backdrop-blur">
-      <div className="relative">
-        <MenuButton
-          label="Library"
-          active={openMenu === "library"}
-          onClick={() => setOpenMenu((current) => (current === "library" ? null : "library"))}
-        />
-        {openMenu === "library" ? (
-          <MenuPanel>
-            <MenuItem label="Add Folder" hint="Ctrl+O soon" onClick={handleAddFolder} />
-            <MenuItem
-              label="Re-index Current Folder"
-              hint={selectedFolderId === null ? "Select folder" : undefined}
-              onClick={handleReindex}
-              active={selectedFolderId !== null}
-            />
-          </MenuPanel>
-        ) : null}
-      </div>
-
-      <div className="relative">
-        <MenuButton
-          label="View"
-          active={openMenu === "view"}
-          onClick={() => setOpenMenu((current) => (current === "view" ? null : "view"))}
-        />
-        {openMenu === "view" ? (
-          <MenuPanel>
-            {ZOOM_OPTIONS.map((option) => (
-              <MenuItem
-                key={option.value}
-                label={option.label}
-                active={zoomPreset === option.value}
-                onClick={() => {
-                  setZoomPreset(option.value);
-                  setOpenMenu(null);
-                }}
-              />
-            ))}
-          </MenuPanel>
-        ) : null}
-      </div>
-
-      <div className="relative">
-        <MenuButton
-          label="Filter"
-          active={openMenu === "filter"}
-          onClick={() => setOpenMenu((current) => (current === "filter" ? null : "filter"))}
-        />
-        {openMenu === "filter" ? (
-          <MenuPanel>
-            {FILTER_OPTIONS.map((option) => (
-              <MenuItem
-                key={option.value}
-                label={option.label}
-                active={mediaFilter === option.value}
-                onClick={() => {
-                  setMediaFilter(option.value);
-                  setOpenMenu(null);
-                }}
-              />
-            ))}
-            <div className="my-2 h-px bg-white/5" />
-            <MenuItem
-              label={favoritesOnly ? "Hide Favorites Only" : "Show Favorites Only"}
-              active={favoritesOnly}
-              onClick={() => {
-                setFavoritesOnly(!favoritesOnly);
-                setOpenMenu(null);
-              }}
-            />
-          </MenuPanel>
-        ) : null}
-      </div>
-    </div>
-  );
-}

src/components/PhokusMark.tsx

@@ -6,14 +6,14 @@
 //
 // Pass dotClassName (e.g. "fill-amber-400") to light up the central focal point —
 // used in the titlebar as the "update available" indicator.
-const BLADE = "M0,-4.18 A10,10 0 0 1 6.43,-7.66";
+const BLADE = 'M0,-4.18 A10,10 0 0 1 6.43,-7.66'
 
 export function PhokusMark({
   className,
   dotClassName,
 }: {
-  className?: string;
-  dotClassName?: string;
+  className?: string
+  dotClassName?: string
 }) {
   return (
     <svg viewBox="0 0 24 24" fill="none" className={className}>
@@ -33,7 +33,9 @@ export function PhokusMark({
         <path d={BLADE} transform="rotate(240)" />
         <path d={BLADE} transform="rotate(300)" />
       </g>
-      {dotClassName ? <circle cx="12" cy="12" r="2.6" stroke="none" className={dotClassName} /> : null}
+      {dotClassName ? (
+        <circle cx="12" cy="12" r="2.6" stroke="none" className={dotClassName} />
+      ) : null}
     </svg>
-  );
+  )
 }

src/components/ThemedDropdown.tsx

@@ -1,106 +0,0 @@
-import { useEffect, useRef, useState } from "react";
-
-export interface DropdownOption {
-  value: string;
-  label: string;
-}
-
-export function ThemedDropdown({
-  value,
-  options,
-  onChange,
-  ariaLabel,
-  compact = false,
-  align = "right",
-}: {
-  value: string;
-  options: DropdownOption[];
-  onChange: (value: string) => void;
-  ariaLabel: string;
-  compact?: boolean;
-  align?: "left" | "right";
-}) {
-  const [open, setOpen] = useState(false);
-  const ref = useRef<HTMLDivElement>(null);
-  const current = options.find((option) => option.value === value) ?? options[0];
-
-  useEffect(() => {
-    const handlePointerDown = (event: PointerEvent) => {
-      if (!ref.current?.contains(event.target as Node)) setOpen(false);
-    };
-    const handleKeyDown = (event: KeyboardEvent) => {
-      if (event.key === "Escape") setOpen(false);
-    };
-    window.addEventListener("pointerdown", handlePointerDown);
-    window.addEventListener("keydown", handleKeyDown);
-    return () => {
-      window.removeEventListener("pointerdown", handlePointerDown);
-      window.removeEventListener("keydown", handleKeyDown);
-    };
-  }, []);
-
-  return (
-    <div ref={ref} className="relative">
-      <button
-        type="button"
-        aria-label={ariaLabel}
-        aria-haspopup="listbox"
-        aria-expanded={open}
-        onClick={() => setOpen((currentOpen) => !currentOpen)}
-        className={`flex items-center justify-between gap-2 rounded-md border transition-colors ${
-          compact
-            ? "border-white/10 bg-white/[0.04] px-1.5 py-0.5 text-[10px] font-medium light-theme:border-gray-700/50 light-theme:bg-gray-900"
-            : "min-w-40 border-white/10 bg-white/[0.055] px-3 py-1.5 text-xs light-theme:border-gray-700/50 light-theme:bg-gray-900"
-        } ${open ? "border-white/20 text-white light-theme:border-gray-700 light-theme:text-white" : "text-gray-400 hover:border-white/15 hover:text-gray-200 light-theme:text-white light-theme:hover:border-gray-700 light-theme:hover:bg-gray-800 light-theme:hover:text-white"}`}
-      >
-        <span>{current?.label}</span>
-        <svg
-          className={`h-3 w-3 shrink-0 text-gray-500 transition-transform duration-150 ${open ? "rotate-180" : ""}`}
-          fill="none"
-          viewBox="0 0 24 24"
-          stroke="currentColor"
-        >
-          <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M19 9l-7 7-7-7" />
-        </svg>
-      </button>
-
-      {open ? (
-        <div
-          role="listbox"
-          aria-label={ariaLabel}
-          className={`absolute top-full z-50 mt-1.5 min-w-full rounded-xl border border-white/10 bg-gray-950/98 p-1 shadow-2xl shadow-black/30 backdrop-blur-xl light-theme:border-gray-700/50 ${
-            align === "right" ? "right-0" : "left-0"
-          }`}
-        >
-          {options.map((option) => {
-            const selected = option.value === value;
-            return (
-              <button
-                key={option.value}
-                type="button"
-                role="option"
-                aria-selected={selected}
-                className={`flex w-full items-center justify-between gap-4 whitespace-nowrap rounded-lg px-3 py-2 text-left text-xs transition-colors ${
-                  selected
-                    ? "bg-white/[0.08] text-white light-theme:bg-gray-900 light-theme:text-white"
-                    : "text-gray-400 hover:bg-white/[0.055] hover:text-gray-200 light-theme:text-gray-600 light-theme:hover:bg-gray-900 light-theme:hover:text-white"
-                }`}
-                onClick={() => {
-                  onChange(option.value);
-                  setOpen(false);
-                }}
-              >
-                <span>{option.label}</span>
-                {selected ? (
-                  <svg className="h-3.5 w-3.5 text-blue-400" fill="none" viewBox="0 0 24 24" stroke="currentColor">
-                    <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2.5} d="M5 13l4 4L19 7" />
-                  </svg>
-                ) : null}
-              </button>
-            );
-          })}
-        </div>
-      ) : null}
-    </div>
-  );
-}

src/components/Timeline.tsx

@@ -1,160 +1,69 @@
-import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
-import { useVirtualizer } from "@tanstack/react-virtual";
-import { ImageRecord, tileSizeForZoom, useGalleryStore } from "../store";
-import { ContextMenu, ImageTile } from "./Gallery";
-import { Tooltip } from "./Tooltip";
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react'
+import { useVirtualizer } from '@tanstack/react-virtual'
+import { ImageRecord, tileSizeForZoom, useGalleryStore } from '../store'
+import { ImageTile } from './gallery/ImageTile'
+import { ImageContextMenu } from './ImageContextMenu'
+import { ScrubberYearBlock } from './timeline/ScrubberYearBlock'
+import { TimelineEmptyState, TimelineLoadingState } from './timeline/TimelineEmptyState'
+import { buildScrubberYears, buildTimelineRows, groupImages } from './timeline/timelineModel'
 
-const GAP = 6;
-const HEADER_HEIGHT = 52;
-const SCRUBBER_WIDTH = 48;
-const MONTH_SHORT = ["Jan","Feb","Mar","Apr","May","Jun","Jul","Aug","Sep","Oct","Nov","Dec"] as const;
-
-interface TimelineGroup {
-  key: string;
-  label: string;
-  images: ImageRecord[];
-}
-
-// One virtualized row: either a month header or a row of up to `cols` tiles.
-type TimelineRow =
-  | { type: "header"; group: TimelineGroup }
-  | { type: "tiles"; images: ImageRecord[] };
-
-interface ScrubberMonth {
-  monthNum: number;
-  label: string;
-  groupIndex: number;
-}
-
-interface ScrubberYear {
-  year: string;
-  firstGroupIndex: number;
-  months: ScrubberMonth[];
-}
-
-function buildLabel(key: string): string {
-  if (key === "unknown") return "Unknown Date";
-  const [yearStr, monthStr] = key.split("-");
-  const year = Number(yearStr);
-  const month = Number(monthStr);
-  if (!isFinite(year) || !isFinite(month) || month < 1 || month > 12) return "Unknown Date";
-  const date = new Date(year, month - 1);
-  if (isNaN(date.getTime())) return "Unknown Date";
-  return date.toLocaleDateString(undefined, { month: "long", year: "numeric" });
-}
-
-function groupImages(images: ImageRecord[]): TimelineGroup[] {
-  const map = new Map<string, ImageRecord[]>();
-  for (const img of images) {
-    const ds = img.taken_at ?? img.modified_at;
-    const key = ds ? ds.substring(0, 7) : "unknown";
-    let bucket = map.get(key);
-    if (bucket === undefined) {
-      bucket = [];
-      map.set(key, bucket);
-    }
-    bucket.push(img);
-  }
-  return Array.from(map.entries())
-    .sort(([a], [b]) => {
-      if (a === "unknown") return 1;
-      if (b === "unknown") return -1;
-      return a < b ? -1 : a > b ? 1 : 0;
-    })
-    .map(([key, imgs]) => ({ key, label: buildLabel(key), images: imgs }));
-}
-
-function buildScrubberYears(groups: TimelineGroup[]): ScrubberYear[] {
-  const byYear = new Map<string, ScrubberYear>();
-  for (let i = 0; i < groups.length; i++) {
-    const group = groups[i];
-    if (group.key === "unknown") continue;
-    const year = group.key.substring(0, 4);
-    const monthNum = Number(group.key.substring(5, 7));
-    if (!byYear.has(year)) {
-      byYear.set(year, { year, firstGroupIndex: i, months: [] });
-    }
-    byYear.get(year)!.months.push({
-      monthNum,
-      label: MONTH_SHORT[monthNum - 1] ?? "",
-      groupIndex: i,
-    });
-  }
-  // Keep insertion order so the scrubber runs the same direction as the scrolled
-  // content (oldest at top with taken_asc), keeping the active highlight aligned.
-  return Array.from(byYear.values());
-}
+const GAP = 6
+const HEADER_HEIGHT = 52
+const SCRUBBER_WIDTH = 48
 
 export function Timeline() {
-  const images = useGalleryStore((s) => s.images);
-  const loadMoreImages = useGalleryStore((s) => s.loadMoreImages);
-  const openImage = useGalleryStore((s) => s.openImage);
-  const totalImages = useGalleryStore((s) => s.totalImages);
-  const loadingImages = useGalleryStore((s) => s.loadingImages);
-  const imageLoadError = useGalleryStore((s) => s.imageLoadError);
-  const zoomPreset = useGalleryStore((s) => s.zoomPreset);
+  const images = useGalleryStore((s) => s.images)
+  const loadMoreImages = useGalleryStore((s) => s.loadMoreImages)
+  const openImage = useGalleryStore((s) => s.openImage)
+  const totalImages = useGalleryStore((s) => s.totalImages)
+  const loadingImages = useGalleryStore((s) => s.loadingImages)
+  const imageLoadError = useGalleryStore((s) => s.imageLoadError)
+  const zoomPreset = useGalleryStore((s) => s.zoomPreset)
 
-  const parentRef = useRef<HTMLDivElement>(null);
-  const [containerWidth, setContainerWidth] = useState(0);
-  const [activeGroupIndex, setActiveGroupIndex] = useState(0);
+  const parentRef = useRef<HTMLDivElement>(null)
+  const [containerWidth, setContainerWidth] = useState(0)
+  const [activeGroupIndex, setActiveGroupIndex] = useState(0)
   const [contextMenu, setContextMenu] = useState<{
-    x: number;
-    y: number;
-    image: ImageRecord;
-  } | null>(null);
+    x: number
+    y: number
+    image: ImageRecord
+  } | null>(null)
 
   // parentRef is the scroll container. Its clientWidth already excludes the
   // scrubber because they are flex siblings, so no further adjustment is needed.
   useLayoutEffect(() => {
-    const el = parentRef.current;
-    if (!el) return;
-    setContainerWidth(el.clientWidth);
+    const el = parentRef.current
+    if (!el) return
+    setContainerWidth(el.clientWidth)
     const ro = new ResizeObserver((entries) => {
-      setContainerWidth(entries[0].contentRect.width);
-    });
-    ro.observe(el);
-    return () => ro.disconnect();
-  }, []);
+      setContainerWidth(entries[0].contentRect.width)
+    })
+    ro.observe(el)
+    return () => ro.disconnect()
+  }, [])
 
-  const tileSize = tileSizeForZoom(zoomPreset);
-  const groups = useMemo(() => groupImages(images), [images]);
-  const scrubberYears = useMemo(() => buildScrubberYears(groups), [groups]);
+  const tileSize = tileSizeForZoom(zoomPreset)
+  const groups = useMemo(() => groupImages(images), [images])
+  const scrubberYears = useMemo(() => buildScrubberYears(groups), [groups])
   // Show as soon as there's more than one month to jump between — not gated on
   // a full year. With taken_asc sort the loaded set is oldest-first, so this
   // reflects whatever range is currently loaded.
-  const showScrubber = groups.length > 1;
+  const showScrubber = groups.length > 1
 
   const cols = useMemo(
     () => Math.max(1, Math.floor((containerWidth - GAP) / (tileSize + GAP))),
-    [containerWidth, tileSize],
-  );
+    [containerWidth, tileSize]
+  )
 
-  // Flatten the month groups into a single list of fixed-height rows — one
-  // header row per group, then one tile-row per `cols` images. This lets the
-  // virtualizer render only the on-screen rows, exactly like the Gallery.
-  // Previously each *group* was one virtual item that rendered ALL of its
-  // images, so scrolling into a busy month mounted thousands of tiles at once.
-  const { rows, rowToGroupIndex, groupFirstRow } = useMemo(() => {
-    const rows: TimelineRow[] = [];
-    const rowToGroupIndex: number[] = [];
-    const groupFirstRow: number[] = [];
-    groups.forEach((group, groupIndex) => {
-      groupFirstRow[groupIndex] = rows.length;
-      rows.push({ type: "header", group });
-      rowToGroupIndex.push(groupIndex);
-      for (let i = 0; i < group.images.length; i += cols) {
-        rows.push({ type: "tiles", images: group.images.slice(i, i + cols) });
-        rowToGroupIndex.push(groupIndex);
-      }
-    });
-    return { rows, rowToGroupIndex, groupFirstRow };
-  }, [groups, cols]);
+  const { rows, rowToGroupIndex, groupFirstRow } = useMemo(
+    () => buildTimelineRows(groups, cols),
+    [groups, cols]
+  )
 
   const estimateSize = useCallback(
-    (index: number): number =>
-      rows[index]?.type === "header" ? HEADER_HEIGHT : tileSize + GAP,
-    [rows, tileSize],
-  );
+    (index: number): number => (rows[index]?.type === 'header' ? HEADER_HEIGHT : tileSize + GAP),
+    [rows, tileSize]
+  )
 
   const virtualizer = useVirtualizer({
     count: rows.length,
@@ -162,151 +71,101 @@ export function Timeline() {
     estimateSize,
     overscan: 6,
     paddingStart: GAP,
-  });
+  })
 
   // Refs so the scroll handler can read the latest mappings without re-binding.
-  const rowToGroupIndexRef = useRef(rowToGroupIndex);
-  rowToGroupIndexRef.current = rowToGroupIndex;
-  const groupFirstRowRef = useRef(groupFirstRow);
-  groupFirstRowRef.current = groupFirstRow;
+  const rowToGroupIndexRef = useRef(rowToGroupIndex)
+  rowToGroupIndexRef.current = rowToGroupIndex
+  const groupFirstRowRef = useRef(groupFirstRow)
+  groupFirstRowRef.current = groupFirstRow
 
   useEffect(() => {
-    virtualizer.measure();
-  }, [cols, virtualizer]);
+    virtualizer.measure()
+  }, [cols, virtualizer])
 
   const handleScroll = useCallback(() => {
-    const el = parentRef.current;
-    if (!el) return;
+    const el = parentRef.current
+    if (!el) return
 
     // Active month = the group owning the first row still visible at the top.
-    const scrollTop = el.scrollTop;
-    const items = virtualizer.getVirtualItems();
-    let activeRow = items.length > 0 ? items[0].index : 0;
+    const scrollTop = el.scrollTop
+    const items = virtualizer.getVirtualItems()
+    let activeRow = items.length > 0 ? items[0].index : 0
     for (const item of items) {
       if (item.start + item.size > scrollTop + HEADER_HEIGHT / 2) {
-        activeRow = item.index;
-        break;
+        activeRow = item.index
+        break
       }
     }
-    setActiveGroupIndex(rowToGroupIndexRef.current[activeRow] ?? 0);
+    setActiveGroupIndex(rowToGroupIndexRef.current[activeRow] ?? 0)
 
-    if (scrollTop < 24) return;
-    const nearBottom = scrollTop + el.clientHeight >= el.scrollHeight - 600;
+    if (scrollTop < 24) return
+    const nearBottom = scrollTop + el.clientHeight >= el.scrollHeight - 600
     if (nearBottom && !loadingImages && images.length < totalImages) {
-      void loadMoreImages();
+      void loadMoreImages()
     }
-  }, [virtualizer, images.length, loadMoreImages, loadingImages, totalImages]);
+  }, [virtualizer, images.length, loadMoreImages, loadingImages, totalImages])
 
   useEffect(() => {
-    const el = parentRef.current;
-    if (!el) return;
-    el.addEventListener("scroll", handleScroll, { passive: true });
-    return () => el.removeEventListener("scroll", handleScroll);
-  }, [handleScroll]);
-
-  useEffect(() => {
-    const close = (e: PointerEvent) => {
-      if ((e.target as HTMLElement | null)?.closest("[data-gallery-context-menu]")) return;
-      setContextMenu(null);
-    };
-    const onKey = (e: KeyboardEvent) => {
-      if (e.key === "Escape") setContextMenu(null);
-    };
-    window.addEventListener("pointerdown", close);
-    window.addEventListener("keydown", onKey);
-    return () => {
-      window.removeEventListener("pointerdown", close);
-      window.removeEventListener("keydown", onKey);
-    };
-  }, []);
+    const el = parentRef.current
+    if (!el) return
+    el.addEventListener('scroll', handleScroll, { passive: true })
+    return () => el.removeEventListener('scroll', handleScroll)
+  }, [handleScroll])
 
   const scrollToGroup = useCallback(
     (groupIndex: number) => {
-      const row = groupFirstRowRef.current[groupIndex] ?? 0;
-      virtualizer.scrollToIndex(row, { align: "start" });
+      const row = groupFirstRowRef.current[groupIndex] ?? 0
+      virtualizer.scrollToIndex(row, { align: 'start' })
     },
-    [virtualizer],
-  );
+    [virtualizer]
+  )
 
   return (
     // Outer flex-row: fills remaining height in <main>'s flex-col, then
     // splits horizontally between the scroll area and the scrubber.
-    <div className="flex flex-1 min-h-0 bg-gray-950">
+    <div className="flex min-h-0 flex-1 bg-gray-950">
       {/* Scroll container — flex-1 takes all width except the scrubber */}
-      <div
-        ref={parentRef}
-        className="relative flex-1 overflow-y-auto overflow-x-hidden min-h-0"
-      >
+      <div ref={parentRef} className="relative min-h-0 flex-1 overflow-x-hidden overflow-y-auto">
         {images.length === 0 && loadingImages ? (
-          <div className="flex flex-1 flex-col items-center justify-center gap-4 text-center px-8 absolute inset-0">
-            <div className="rounded-2xl border border-white/[0.06] bg-white/[0.02] p-8 min-w-72">
-              <div className="h-5 w-5 mx-auto rounded-full border-2 border-white/20 border-t-white/60 animate-spin" />
-              <p className="mt-4 text-sm text-white/40 font-medium">Loading timeline</p>
-              <p className="text-xs text-white/20 mt-1">Fetching results</p>
-            </div>
-          </div>
+          <TimelineLoadingState />
         ) : images.length === 0 ? (
-          <div className="flex flex-1 flex-col items-center justify-center gap-4 text-center px-8 absolute inset-0">
-            <div className="rounded-2xl border border-white/[0.06] bg-white/[0.02] p-8">
-              <svg
-                className="h-12 w-12 mx-auto text-white/10 mb-4"
-                fill="none"
-                viewBox="0 0 24 24"
-                stroke="currentColor"
-              >
-                <path
-                  strokeLinecap="round"
-                  strokeLinejoin="round"
-                  strokeWidth={0.75}
-                  d="M8 7V3m8 4V3m-9 8h10M5 21h14a2 2 0 002-2V7a2 2 0 00-2-2H5a2 2 0 00-2 2v12a2 2 0 002 2z"
-                />
-              </svg>
-              <p className="text-sm text-white/30 font-medium">
-                {imageLoadError ? "Could not load timeline" : "No media found"}
-              </p>
-              <p className="text-xs text-white/15 mt-1">
-                {imageLoadError ?? "Add a folder to see your timeline"}
-              </p>
-            </div>
-          </div>
+          <TimelineEmptyState imageLoadError={imageLoadError} />
         ) : (
-          <div style={{ height: virtualizer.getTotalSize(), position: "relative" }}>
+          <div style={{ height: virtualizer.getTotalSize(), position: 'relative' }}>
             {virtualizer.getVirtualItems().map((virtualItem) => {
-              const row = rows[virtualItem.index];
-              if (!row) return null;
+              const row = rows[virtualItem.index]
+              if (!row) return null
               return (
                 <div
                   key={virtualItem.key}
                   style={{
-                    position: "absolute",
+                    position: 'absolute',
                     top: virtualItem.start,
-                    width: "100%",
+                    width: '100%',
                     height: virtualItem.size,
                   }}
                 >
-                  {row.type === "header" ? (
-                    <div
-                      className="flex items-center gap-3 px-4"
-                      style={{ height: HEADER_HEIGHT }}
-                    >
-                      <span className="text-sm font-semibold text-white/80 shrink-0">
+                  {row.type === 'header' ? (
+                    <div className="flex items-center gap-3 px-4" style={{ height: HEADER_HEIGHT }}>
+                      <span className="shrink-0 text-sm font-semibold text-white/80">
                         {row.group.label}
                       </span>
-                      <span className="text-xs text-white/25 shrink-0 tabular-nums">
+                      <span className="shrink-0 text-xs text-white/25 tabular-nums">
                         {row.group.images.length}
                       </span>
-                      <div className="flex-1 h-px bg-white/[0.06]" />
+                      <div className="h-px flex-1 bg-white/[0.06]" />
                     </div>
                   ) : (
                     <div
                       style={{
-                        display: "grid",
+                        display: 'grid',
                         gridTemplateColumns: `repeat(${cols}, ${tileSize}px)`,
                         gap: GAP,
                         paddingLeft: GAP,
                         paddingRight: GAP,
                         paddingBottom: GAP,
-                        boxSizing: "border-box",
+                        boxSizing: 'border-box',
                       }}
                     >
                       {row.images.map((image) => (
@@ -315,22 +174,22 @@ export function Timeline() {
                           image={image}
                           onClick={() => openImage(image)}
                           onContextMenu={(event) => {
-                            event.preventDefault();
-                            setContextMenu({ x: event.clientX, y: event.clientY, image });
+                            event.preventDefault()
+                            setContextMenu({ x: event.clientX, y: event.clientY, image })
                           }}
                         />
                       ))}
                     </div>
                   )}
                 </div>
-              );
+              )
             })}
           </div>
         )}
 
         {images.length > 0 && loadingImages ? (
           <div className="flex justify-center py-8">
-            <div className="h-4 w-4 rounded-full border-2 border-white/20 border-t-white/60 animate-spin" />
+            <div className="h-4 w-4 animate-spin rounded-full border-2 border-white/20 border-t-white/60" />
           </div>
         ) : null}
       </div>
@@ -338,7 +197,7 @@ export function Timeline() {
       {/* Scrubber — flex sibling so it stays visible while the left panel scrolls */}
       {showScrubber ? (
         <div
-          className="overflow-y-auto border-l border-white/[0.04] py-2 flex flex-col items-center gap-0.5"
+          className="flex flex-col items-center gap-0.5 overflow-y-auto border-l border-white/[0.04] py-2"
           style={{ width: SCRUBBER_WIDTH }}
         >
           {scrubberYears.map((yearEntry) => (
@@ -353,7 +212,7 @@ export function Timeline() {
       ) : null}
 
       {contextMenu ? (
-        <ContextMenu
+        <ImageContextMenu
           x={contextMenu.x}
           y={contextMenu.y}
           image={contextMenu.image}
@@ -361,53 +220,5 @@ export function Timeline() {
         />
       ) : null}
     </div>
-  );
-}
-
-interface ScrubberYearBlockProps {
-  yearEntry: ScrubberYear;
-  activeGroupIndex: number;
-  onScrollTo: (index: number) => void;
-}
-
-function ScrubberYearBlock({ yearEntry, activeGroupIndex, onScrollTo }: ScrubberYearBlockProps) {
-  const isYearActive = yearEntry.months.some((m) => m.groupIndex === activeGroupIndex);
-
-  return (
-    <div className="w-full flex flex-col items-center">
-      <Tooltip label={yearEntry.year} anchorToCursor>
-        <button
-          className={`w-full text-center py-0.5 text-[10px] font-semibold tracking-wide transition-colors ${
-            isYearActive ? "text-white/80" : "text-white/30 hover:text-white/55"
-          }`}
-          onClick={() => onScrollTo(yearEntry.firstGroupIndex)}
-        >
-          {yearEntry.year}
-        </button>
-      </Tooltip>
-      <div
-        className="grid gap-[3px] pb-1.5"
-        style={{ gridTemplateColumns: "repeat(3, 10px)" }}
-      >
-        {Array.from({ length: 12 }, (_, i) => {
-          const monthNum = i + 1;
-          const monthEntry = yearEntry.months.find((m) => m.monthNum === monthNum);
-          const isActive = monthEntry !== undefined && monthEntry.groupIndex === activeGroupIndex;
-          if (!monthEntry) {
-            return <span key={monthNum} className="h-[10px] w-[10px]" />;
-          }
-          return (
-            <Tooltip key={monthNum} label={`${monthEntry.label} ${yearEntry.year}`} anchorToCursor>
-              <button
-                onClick={() => onScrollTo(monthEntry.groupIndex)}
-                className={`h-[10px] w-[10px] rounded-full transition-colors ${
-                  isActive ? "bg-white/70" : "bg-white/15 hover:bg-white/40"
-                }`}
-              />
-            </Tooltip>
-          );
-        })}
-      </div>
-    </div>
-  );
+  )
 }

src/components/TitleBar.tsx

@@ -1,14 +1,19 @@
-import { useState, useEffect, useRef } from "react";
-import { getCurrentWindow } from "@tauri-apps/api/window";
-import { useGalleryStore, AppTheme } from "../store";
-import { PhokusMark } from "./PhokusMark";
-import { Tooltip } from "./Tooltip";
+import { useState, useEffect, useRef } from 'react'
+import { getCurrentWindow } from '@tauri-apps/api/window'
+import { useGalleryStore, AppTheme } from '../store'
+import { ContextMenu, MenuItem, MenuLabel } from './menu'
+import { PhokusMark } from './PhokusMark'
+import { Tooltip } from './Tooltip'
 
-const THEME_OPTIONS: { value: AppTheme; label: string }[] = [
-  { value: "phokus", label: "Phokus" },
-  { value: "subtle-light", label: "Subtle Light" },
-  { value: "conventional-dark", label: "Conventional Dark" },
-];
+const THEME_LABELS: Record<AppTheme, string> = {
+  phokus: 'Phokus',
+  'subtle-light': 'Subtle Light',
+  'conventional-dark': 'Conventional Dark',
+}
+const THEME_OPTIONS = (Object.keys(THEME_LABELS) as AppTheme[]).map((value) => ({
+  value,
+  label: THEME_LABELS[value],
+}))
 
 // SVG icons for window controls
 function MinimizeIcon() {
@@ -16,7 +21,7 @@ function MinimizeIcon() {
     <svg width="10" height="2" viewBox="0 0 10 2" fill="none">
       <rect y="0.5" width="10" height="1" rx="0.5" fill="currentColor" />
     </svg>
-  );
+  )
 }
 
 function MaximizeIcon() {
@@ -24,16 +29,25 @@ function MaximizeIcon() {
     <svg width="10" height="10" viewBox="0 0 10 10" fill="none">
       <rect x="0.5" y="0.5" width="9" height="9" rx="1.5" stroke="currentColor" strokeWidth="1" />
     </svg>
-  );
+  )
 }
 
 function RestoreIcon() {
   return (
     <svg width="10" height="10" viewBox="0 0 10 10" fill="none">
       <rect x="2.5" y="0.5" width="7" height="7" rx="1.5" stroke="currentColor" strokeWidth="1" />
-      <rect x="0.5" y="2.5" width="7" height="7" rx="1.5" stroke="currentColor" strokeWidth="1" fill="var(--color-gray-950)" />
+      <rect
+        x="0.5"
+        y="2.5"
+        width="7"
+        height="7"
+        rx="1.5"
+        stroke="currentColor"
+        strokeWidth="1"
+        fill="var(--color-gray-950)"
+      />
     </svg>
-  );
+  )
 }
 
 function CloseIcon() {
@@ -41,67 +55,52 @@ function CloseIcon() {
     <svg width="10" height="10" viewBox="0 0 10 10" fill="none">
       <path d="M1 1L9 9M9 1L1 9" stroke="currentColor" strokeWidth="1.25" strokeLinecap="round" />
     </svg>
-  );
+  )
 }
 
 export function TitleBar() {
-  const [isMaximized, setIsMaximized] = useState(false);
-  const setSettingsOpen = useGalleryStore((state) => state.setSettingsOpen);
-  const theme = useGalleryStore((state) => state.theme);
-  const setTheme = useGalleryStore((state) => state.setTheme);
-  const updateStatus = useGalleryStore((state) => state.updateStatus);
-  const updateVersion = useGalleryStore((state) => state.updateVersion);
-  const installUpdate = useGalleryStore((state) => state.installUpdate);
-  const appWindow = getCurrentWindow();
+  const [isMaximized, setIsMaximized] = useState(false)
+  const setSettingsOpen = useGalleryStore((state) => state.setSettingsOpen)
+  const theme = useGalleryStore((state) => state.theme)
+  const setTheme = useGalleryStore((state) => state.setTheme)
+  const updateStatus = useGalleryStore((state) => state.updateStatus)
+  const updateVersion = useGalleryStore((state) => state.updateVersion)
+  const installUpdate = useGalleryStore((state) => state.installUpdate)
+  const appWindow = getCurrentWindow()
 
   // Right-clicking the settings cog opens a quick theme switcher, anchored under
   // the cog so it never overflows the right edge of the window.
-  const settingsBtnRef = useRef<HTMLButtonElement>(null);
-  const themeMenuRef = useRef<HTMLDivElement>(null);
-  const [themeMenu, setThemeMenu] = useState<{ top: number; right: number } | null>(null);
-
-  useEffect(() => {
-    if (!themeMenu) return;
-    const handleDown = (e: MouseEvent) => {
-      if (themeMenuRef.current && !themeMenuRef.current.contains(e.target as Node)) setThemeMenu(null);
-    };
-    const handleKey = (e: KeyboardEvent) => { if (e.key === "Escape") setThemeMenu(null); };
-    document.addEventListener("mousedown", handleDown);
-    document.addEventListener("keydown", handleKey);
-    return () => {
-      document.removeEventListener("mousedown", handleDown);
-      document.removeEventListener("keydown", handleKey);
-    };
-  }, [themeMenu]);
+  const settingsBtnRef = useRef<HTMLButtonElement>(null)
+  const [themeMenu, setThemeMenu] = useState<{ x: number; y: number } | null>(null)
 
   const handleSettingsContextMenu = (e: React.MouseEvent) => {
-    e.preventDefault();
-    const rect = settingsBtnRef.current?.getBoundingClientRect();
-    if (!rect) return;
-    setThemeMenu({ top: rect.bottom + 4, right: window.innerWidth - rect.right });
-  };
+    e.preventDefault()
+    const rect = settingsBtnRef.current?.getBoundingClientRect()
+    if (!rect) return
+    setThemeMenu({ x: rect.right, y: rect.bottom + 4 })
+  }
 
   useEffect(() => {
     // Get initial maximized state
-    appWindow.isMaximized().then(setIsMaximized);
+    appWindow.isMaximized().then(setIsMaximized)
 
     // Listen for resize events to update maximized state
     const unlisten = appWindow.onResized(() => {
-      appWindow.isMaximized().then(setIsMaximized);
-    });
+      appWindow.isMaximized().then(setIsMaximized)
+    })
 
     return () => {
-      unlisten.then((fn) => fn());
-    };
-  }, []);
+      unlisten.then((fn) => fn())
+    }
+  }, [])
 
-  const handleMinimize = () => appWindow.minimize();
-  const handleMaximize = () => appWindow.toggleMaximize();
-  const handleClose = () => appWindow.close();
+  const handleMinimize = () => appWindow.minimize()
+  const handleMaximize = () => appWindow.toggleMaximize()
+  const handleClose = () => appWindow.close()
 
   // An update is waiting for the user to act. Covers the "clicked Later" case too,
   // since dismissing the toast doesn't change updateStatus.
-  const updatePending = updateStatus === "available";
+  const updatePending = updateStatus === 'available'
 
   return (
     // data-tauri-drag-region is the recommended Tauri approach for drag regions.
@@ -109,31 +108,34 @@ export function TitleBar() {
     <div
       data-tauri-drag-region
       className="titlebar relative z-50 flex h-9 shrink-0 items-center bg-gray-950 select-none"
-      style={{ WebkitAppRegion: "drag" } as React.CSSProperties}
+      style={{ WebkitAppRegion: 'drag' } as React.CSSProperties}
     >
       {/* App icon + name — left side. When an update is waiting, the iris lights
           up its focal point and the chip becomes a button that re-opens the prompt. */}
-      <div className="flex items-center gap-2 pl-3 pr-4">
+      <div className="flex items-center gap-2 pr-4 pl-3">
         {updatePending ? (
-          <div style={{ WebkitAppRegion: "no-drag" } as React.CSSProperties}>
+          <div
+            className="flex h-5 w-5 items-center justify-center"
+            style={{ WebkitAppRegion: 'no-drag' } as React.CSSProperties}
+          >
             {/* Instant tooltip (delay 0) — this affordance should read immediately. */}
             <Tooltip label={`Click to update — v${updateVersion}`} delay={0} align="start">
               <button
                 onClick={() => void installUpdate()}
                 aria-label={`Update available — click to update to Phokus v${updateVersion}`}
-                className="relative flex h-5 w-5 items-center justify-center rounded-md bg-white/8 overflow-hidden text-gray-300 transition-colors hover:bg-white/12"
+                className="relative flex h-5 w-5 items-center justify-center overflow-hidden rounded-md bg-white/8 text-gray-300 transition-colors hover:bg-white/12"
               >
-                <span className="pointer-events-none absolute left-1/2 top-1/2 h-3 w-3 -translate-x-1/2 -translate-y-1/2 rounded-full bg-amber-400/60 animate-ping" />
+                <span className="pointer-events-none absolute top-1/2 left-1/2 h-3 w-3 -translate-x-1/2 -translate-y-1/2 animate-ping rounded-full bg-amber-400/60" />
                 <PhokusMark className="relative h-4 w-4" dotClassName="fill-amber-400" />
               </button>
             </Tooltip>
           </div>
         ) : (
-          <div className="flex h-5 w-5 items-center justify-center rounded-md bg-white/8 overflow-hidden text-gray-300">
+          <div className="flex h-5 w-5 items-center justify-center overflow-hidden rounded-md bg-white/8 text-gray-300">
             <PhokusMark className="h-4 w-4" />
           </div>
         )}
-        <span className="text-[11px] font-semibold text-gray-400 tracking-wide">Phokus</span>
+        <span className="text-[11px] font-semibold tracking-wide text-gray-400">Phokus</span>
       </div>
 
       {/* Spacer — draggable region fills here */}
@@ -141,19 +143,30 @@ export function TitleBar() {
 
       {/* Window control buttons — right side, non-draggable */}
       <div
-        className="flex items-stretch h-full"
-        style={{ WebkitAppRegion: "no-drag" } as React.CSSProperties}
+        className="flex h-full items-stretch"
+        style={{ WebkitAppRegion: 'no-drag' } as React.CSSProperties}
       >
         <Tooltip label="Settings (right-click to switch theme)" anchorToCursor>
           <button
             ref={settingsBtnRef}
+            aria-label="Settings"
             onClick={() => setSettingsOpen(true)}
             onContextMenu={handleSettingsContextMenu}
             className="group flex h-full w-10 items-center justify-center text-gray-600 transition-colors duration-100 hover:bg-white/6 hover:text-gray-300"
           >
             <svg className="h-3.5 w-3.5" fill="none" viewBox="0 0 24 24" stroke="currentColor">
-            <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={1.8} d="M10.325 4.317c.426-1.756 2.924-1.756 3.35 0a1.724 1.724 0 002.573 1.066c1.543-.94 3.31.826 2.37 2.37a1.724 1.724 0 001.065 2.572c1.756.426 1.756 2.924 0 3.35a1.724 1.724 0 00-1.066 2.573c.94 1.543-.826 3.31-2.37 2.37a1.724 1.724 0 00-2.572 1.065c-.426 1.756-2.924 1.756-3.35 0a1.724 1.724 0 00-2.573-1.066c-1.543.94-3.31-.826-2.37-2.37a1.724 1.724 0 00-1.065-2.572c-1.756-.426-1.756-2.924 0-3.35a1.724 1.724 0 001.066-2.573c-.94-1.543.826-3.31 2.37-2.37.996.607 2.296.07 2.572-1.065z" />
-            <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={1.8} d="M15 12a3 3 0 11-6 0 3 3 0 016 0z" />
+              <path
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                strokeWidth={1.8}
+                d="M10.325 4.317c.426-1.756 2.924-1.756 3.35 0a1.724 1.724 0 002.573 1.066c1.543-.94 3.31.826 2.37 2.37a1.724 1.724 0 001.065 2.572c1.756.426 1.756 2.924 0 3.35a1.724 1.724 0 00-1.066 2.573c.94 1.543-.826 3.31-2.37 2.37a1.724 1.724 0 00-2.572 1.065c-.426 1.756-2.924 1.756-3.35 0a1.724 1.724 0 00-2.573-1.066c-1.543.94-3.31-.826-2.37-2.37a1.724 1.724 0 00-1.065-2.572c-1.756-.426-1.756-2.924 0-3.35a1.724 1.724 0 001.066-2.573c-.94-1.543.826-3.31 2.37-2.37.996.607 2.296.07 2.572-1.065z"
+              />
+              <path
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                strokeWidth={1.8}
+                d="M15 12a3 3 0 11-6 0 3 3 0 016 0z"
+              />
             </svg>
           </button>
         </Tooltip>
@@ -169,7 +182,7 @@ export function TitleBar() {
         {/* Maximize / Restore */}
         <button
           onClick={handleMaximize}
-          title={isMaximized ? "Restore" : "Maximize"}
+          title={isMaximized ? 'Restore' : 'Maximize'}
           className="group flex h-full w-10 items-center justify-center text-gray-600 transition-colors duration-100 hover:bg-white/6 hover:text-gray-300"
         >
           {isMaximized ? <RestoreIcon /> : <MaximizeIcon />}
@@ -187,33 +200,24 @@ export function TitleBar() {
 
       {/* Quick theme switcher — opened by right-clicking the settings cog. */}
       {themeMenu && (
-        <div
-          ref={themeMenuRef}
-          className="fixed z-50 min-w-[170px] py-1 px-1 rounded-lg bg-gray-900 border border-white/10 shadow-xl shadow-black/50"
-          style={{ top: themeMenu.top, right: themeMenu.right, WebkitAppRegion: "no-drag" } as React.CSSProperties}
+        <ContextMenu
+          x={themeMenu.x}
+          y={themeMenu.y}
+          size="sm"
+          align="end"
+          onClose={() => setThemeMenu(null)}
         >
-          <div className="px-3 pt-1 pb-1 text-[10px] font-semibold uppercase tracking-wide text-gray-500">Theme</div>
-          {THEME_OPTIONS.map((opt) => {
-            const active = theme === opt.value;
-            return (
-              <button
+          <MenuLabel>Theme</MenuLabel>
+          {THEME_OPTIONS.map((opt) => (
+            <MenuItem
               key={opt.value}
-                className={`flex w-full items-center justify-between gap-3 rounded-md px-3 py-1.5 text-left text-[12px] transition-colors ${
-                  active ? "bg-white/8 text-white" : "text-gray-300 hover:bg-white/8 hover:text-white"
-                }`}
-                onClick={() => { setTheme(opt.value); setThemeMenu(null); }}
-              >
-                {opt.label}
-                {active && (
-                  <svg className="h-3.5 w-3.5 text-sky-400" fill="none" viewBox="0 0 24 24" stroke="currentColor">
-                    <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2.5} d="M5 13l4 4L19 7" />
-                  </svg>
-                )}
-              </button>
-            );
-          })}
-        </div>
+              label={opt.label}
+              checked={theme === opt.value}
+              onSelect={() => setTheme(opt.value)}
+            />
+          ))}
+        </ContextMenu>
       )}
     </div>
-  );
+  )
 }

src/components/Toolbar.tsx

@@ -1,495 +1,24 @@
-import { useEffect, useRef, useState } from "react";
-import { invoke } from "@tauri-apps/api/core";
-import { tileSizeForZoom, useGalleryStore, SortOrder, MediaFilter, SearchCommand, parseSearchValue, searchModeLabel, ExploreTagEntry } from "../store";
-import { FolderScopeDropdown } from "./FolderScopeDropdown";
-import { ColorFilter } from "./ColorFilter";
-import { Tooltip } from "./Tooltip";
-
-const BASE_SORT_OPTIONS: { value: SortOrder; label: string }[] = [
-  { value: "date_desc", label: "Newest first" },
-  { value: "date_asc", label: "Oldest first" },
-  { value: "taken_desc", label: "Taken: newest" },
-  { value: "taken_asc", label: "Taken: oldest" },
-  { value: "name_asc", label: "Name A–Z" },
-  { value: "name_desc", label: "Name Z–A" },
-  { value: "rating_desc", label: "Highest rated" },
-  { value: "rating_asc", label: "Lowest rated" },
-  { value: "size_desc", label: "Largest first" },
-  { value: "size_asc", label: "Smallest first" },
-];
-
-const VIDEO_SORT_OPTIONS: { value: SortOrder; label: string }[] = [
-  { value: "duration_desc", label: "Longest first" },
-  { value: "duration_asc", label: "Shortest first" },
-];
-
-function getSortOptions(mediaFilter: MediaFilter) {
-  if (mediaFilter === "video") {
-    return [...BASE_SORT_OPTIONS, ...VIDEO_SORT_OPTIONS];
-  }
-  return BASE_SORT_OPTIONS;
-}
-
-function SortDropdown({
-  value,
-  onChange,
-  options,
-}: {
-  value: SortOrder;
-  onChange: (v: SortOrder) => void;
-  options: { value: SortOrder; label: string }[];
-}) {
-  const [open, setOpen] = useState(false);
-  const ref = useRef<HTMLDivElement>(null);
-  const current = options.find((o) => o.value === value) ?? BASE_SORT_OPTIONS[0];
-
-  useEffect(() => {
-    const close = (e: MouseEvent) => {
-      if (!ref.current?.contains(e.target as Node)) setOpen(false);
-    };
-    window.addEventListener("pointerdown", close);
-    return () => window.removeEventListener("pointerdown", close);
-  }, []);
-
-  return (
-    <div ref={ref} className="relative">
-      <button
-        onClick={() => setOpen((v) => !v)}
-        className={`flex items-center gap-1.5 rounded-lg border px-3 py-1.5 text-xs transition-colors ${
-          open
-            ? "border-white/15 bg-white/8 text-white light-theme:border-gray-700/50 light-theme:bg-gray-900 light-theme:text-white"
-            : "border-white/8 bg-transparent text-gray-400 hover:border-white/15 hover:text-gray-200 light-theme:border-gray-700/40 light-theme:text-gray-600 light-theme:hover:border-gray-700 light-theme:hover:bg-gray-900 light-theme:hover:text-white"
-        }`}
-      >
-        <span>{current?.label ?? "Sort"}</span>
-        <svg
-          className={`h-3 w-3 text-gray-500 transition-transform duration-150 ${open ? "rotate-180" : ""}`}
-          fill="none" viewBox="0 0 24 24" stroke="currentColor"
-        >
-          <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M19 9l-7 7-7-7" />
-        </svg>
-      </button>
-      {open ? (
-        <div className="absolute right-0 top-full z-30 mt-1.5 min-w-44 rounded-xl border border-white/10 bg-gray-950/98 p-1 shadow-2xl backdrop-blur light-theme:border-gray-700/50">
-          {options.map((option) => (
-            <button
-              key={option.value}
-              className={`flex w-full items-center justify-between rounded-lg px-3 py-2 text-left text-sm transition-colors ${
-                option.value === value
-                  ? "bg-white/6 text-white light-theme:bg-gray-900 light-theme:text-white"
-                  : "text-gray-400 hover:bg-white/5 hover:text-white light-theme:text-gray-600 light-theme:hover:bg-gray-900 light-theme:hover:text-white"
-              }`}
-              onClick={() => { onChange(option.value); setOpen(false); }}
-            >
-              {option.label}
-              {option.value === value ? (
-                <svg className="h-3.5 w-3.5 text-blue-400" fill="none" viewBox="0 0 24 24" stroke="currentColor">
-                  <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2.5} d="M5 13l4 4L19 7" />
-                </svg>
-              ) : null}
-            </button>
-          ))}
-        </div>
-      ) : null}
-    </div>
-  );
-}
-
-function FilterPill({
-  label,
-  active,
-  onClick,
-  variant = "default",
-}: {
-  label: string;
-  active: boolean;
-  onClick: () => void;
-  variant?: "default" | "amber";
-}) {
-  const activeClass =
-    variant === "amber"
-      ? "bg-amber-500/15 text-amber-300 border border-amber-500/30 light-theme:bg-amber-100 light-theme:text-amber-700 light-theme:border-amber-500/50"
-      : "bg-white/10 text-white light-theme:bg-gray-900 light-theme:text-white";
-  return (
-    <button
-      className={`shrink-0 whitespace-nowrap rounded-lg px-3 py-1.5 text-xs font-medium transition-all duration-150 ${
-        active
-          ? activeClass
-          : "text-gray-500 hover:text-gray-200 hover:bg-white/5 light-theme:text-gray-600 light-theme:hover:bg-gray-900 light-theme:hover:text-white"
-      }`}
-      onClick={onClick}
-    >
-      {label}
-    </button>
-  );
-}
-
-function commandPrefix(command: SearchCommand | null): string | null {
-  switch (command) {
-    case "semantic":
-      return "/s";
-    case "tag":
-      return "/t";
-    default:
-      return null;
-  }
-}
-
-function composeSearchValue(command: SearchCommand | null, query: string): string {
-  const prefix = commandPrefix(command);
-  if (!prefix) return query;
-  return query.length > 0 ? `${prefix} ${query}` : prefix;
-}
+import { SortControl } from './toolbar/SortControl'
+import { ToolbarFilters } from './toolbar/ToolbarFilters'
+import { ToolbarSearch } from './toolbar/ToolbarSearch'
+import { ToolbarTitle } from './toolbar/ToolbarTitle'
+import { useToolbarSearch } from './toolbar/useToolbarSearch'
+import { ZoomControl } from './toolbar/ZoomControl'
 
 export function Toolbar() {
-  const search = useGalleryStore((state) => state.search);
-  const setSearch = useGalleryStore((state) => state.setSearch);
-  const clearSearch = useGalleryStore((state) => state.clearSearch);
-  const sort = useGalleryStore((state) => state.sort);
-  const setSort = useGalleryStore((state) => state.setSort);
-  const totalImages = useGalleryStore((state) => state.totalImages);
-  const loadedCount = useGalleryStore((state) => state.loadedCount);
-  const selectedFolderId = useGalleryStore((state) => state.selectedFolderId);
-  const collectionTitle = useGalleryStore((state) => state.collectionTitle);
-  const folders = useGalleryStore((state) => state.folders);
-  const mediaFilter = useGalleryStore((state) => state.mediaFilter);
-  const setMediaFilter = useGalleryStore((state) => state.setMediaFilter);
-  const favoritesOnly = useGalleryStore((state) => state.favoritesOnly);
-  const setFavoritesOnly = useGalleryStore((state) => state.setFavoritesOnly);
-  const minimumRating = useGalleryStore((state) => state.minimumRating);
-  const setMinimumRating = useGalleryStore((state) => state.setMinimumRating);
-  const failedEmbeddingsOnly = useGalleryStore((state) => state.failedEmbeddingsOnly);
-  const setFailedEmbeddingsOnly = useGalleryStore((state) => state.setFailedEmbeddingsOnly);
-  const failedTaggingOnly = useGalleryStore((state) => state.failedTaggingOnly);
-  const setFailedTaggingOnly = useGalleryStore((state) => state.setFailedTaggingOnly);
-  const colorFilter = useGalleryStore((state) => state.colorFilter);
-  const setColorFilter = useGalleryStore((state) => state.setColorFilter);
-  const similarScope = useGalleryStore((state) => state.similarScope);
-  const setSimilarScope = useGalleryStore((state) => state.setSimilarScope);
-  const similarSourceAlbumId = useGalleryStore((state) => state.similarSourceAlbumId);
-  const mediaJobProgress = useGalleryStore((state) => state.mediaJobProgress);
-  const zoomPreset = useGalleryStore((state) => state.zoomPreset);
-  const setZoomPreset = useGalleryStore((state) => state.setZoomPreset);
-  const activeView = useGalleryStore((state) => state.activeView);
-
-  const hasAnyFailedEmbeddings = Object.values(mediaJobProgress).some((p) => p.embedding_failed > 0);
-  const hasAnyFailedTagging = Object.values(mediaJobProgress).some((p) => p.tagging_failed > 0);
-
-  const [searchCommand, setSearchCommand] = useState<SearchCommand | null>(null);
-  const [searchQuery, setSearchQuery] = useState(search);
-  const [searchPanelOpen, setSearchPanelOpen] = useState(false);
-  const [tagSuggestions, setTagSuggestions] = useState<ExploreTagEntry[]>([]);
-  const debounceRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-  const suggestDebounceRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-  const searchInputRef = useRef<HTMLInputElement>(null);
-  const searchShellRef = useRef<HTMLDivElement>(null);
-  const userHasTyped = useRef(false);
-
-  const selectedFolder = folders.find((folder) => folder.id === selectedFolderId);
-  const title = collectionTitle ?? (selectedFolder ? selectedFolder.name : "All Media");
-  const tileSize = tileSizeForZoom(zoomPreset);
-  const sortOptions = getSortOptions(mediaFilter);
-  const hasActiveSearch = search.trim().length > 0;
-  const parsedSearch = parseSearchValue(composeSearchValue(searchCommand, searchQuery));
-  const isSimilarResults = collectionTitle === "Similar Images";
-  // Album scope is offered while browsing an album (where it's the default) and
-  // while viewing similar/region results that were launched from an album.
-  const showAlbumScope =
-    activeView === "album" ||
-    (similarSourceAlbumId !== null &&
-      (collectionTitle === "Similar Images" || collectionTitle === "Region Search Results"));
-
-  // If current sort is video-only but we switched away from video filter, reset to date_desc
-  useEffect(() => {
-    if (mediaFilter !== "video" && (sort === "duration_asc" || sort === "duration_desc")) {
-      setSort("date_desc");
-    }
-  }, [mediaFilter, sort, setSort]);
-
-  useEffect(() => {
-    if (!userHasTyped.current) return;
-    if (debounceRef.current) clearTimeout(debounceRef.current);
-    debounceRef.current = setTimeout(() => { setSearch(composeSearchValue(searchCommand, searchQuery)); }, 200);
-    return () => { if (debounceRef.current) clearTimeout(debounceRef.current); };
-  }, [searchCommand, searchQuery, setSearch]);
-
-  useEffect(() => {
-    const parsed = parseSearchValue(search);
-    setSearchCommand(parsed.prefix && parsed.mode !== "filename" ? parsed.mode : null);
-    setSearchQuery(parsed.prefix ? parsed.query : search);
-  }, [search]);
-
-  // Fetch tag suggestions when in tag mode
-  useEffect(() => {
-    if (searchCommand !== "tag") {
-      setTagSuggestions([]);
-      return;
-    }
-    if (suggestDebounceRef.current) clearTimeout(suggestDebounceRef.current);
-    suggestDebounceRef.current = setTimeout(async () => {
-      try {
-        const results = await invoke<ExploreTagEntry[]>("search_tags_autocomplete", {
-          params: { query: searchQuery.trim(), folder_id: selectedFolderId ?? null, limit: 10 },
-        });
-        setTagSuggestions(Array.isArray(results) ? results : []);
-      } catch {
-        setTagSuggestions([]);
-      }
-    }, 120);
-    return () => { if (suggestDebounceRef.current) clearTimeout(suggestDebounceRef.current); };
-  }, [searchCommand, searchQuery, selectedFolderId]);
-
-  useEffect(() => {
-    const handleKeyDown = (event: KeyboardEvent) => {
-      const activeElement = document.activeElement;
-      const searchFocused = activeElement === searchInputRef.current;
-      if (event.key === "Escape" && (searchFocused || hasActiveSearch)) {
-        event.preventDefault();
-        setSearchCommand(null);
-        setSearchQuery("");
-        clearSearch();
-      }
-    };
-    window.addEventListener("keydown", handleKeyDown);
-    return () => window.removeEventListener("keydown", handleKeyDown);
-  }, [clearSearch, hasActiveSearch]);
-
-  useEffect(() => {
-    const close = (event: PointerEvent) => {
-      if (searchShellRef.current?.contains(event.target as Node)) return;
-      setSearchPanelOpen(false);
-    };
-    window.addEventListener("pointerdown", close);
-    return () => window.removeEventListener("pointerdown", close);
-  }, []);
-
-  const showTagSuggestions = searchCommand === "tag" && searchPanelOpen;
-  const showCommandHints = !searchCommand && searchPanelOpen;
+  const searchState = useToolbarSearch()
 
   return (
     <div className="relative z-40 shrink-0 border-b border-white/[0.06] bg-gray-950/80 backdrop-blur-xl">
-      {/* Primary row */}
-      <div className="flex items-center gap-2 px-3 h-12 lg:gap-3 lg:px-5">
-        {/* Title + count */}
-        <div className="flex items-baseline gap-2.5 min-w-0 shrink-0">
-          <h2 className="text-[15px] font-semibold text-white truncate max-w-32 lg:max-w-48">{title}</h2>
-          <span className="text-xs text-gray-600 shrink-0">
-            {loadedCount < totalImages
-              ? `${loadedCount.toLocaleString()} / ${totalImages.toLocaleString()}`
-              : totalImages.toLocaleString()}
-          </span>
-          {hasActiveSearch && (
-            <span className="rounded-md border border-blue-500/20 bg-blue-500/10 px-2 py-0.5 text-[10px] uppercase tracking-[0.14em] text-blue-300 shrink-0">
-              {searchModeLabel(parsedSearch.mode)}
-            </span>
-          )}
-        </div>
-
-        {activeView === "timeline" ? <FolderScopeDropdown /> : null}
-
+      <div className="flex h-12 items-center gap-2 px-3 lg:gap-3 lg:px-5">
+        <ToolbarTitle parsedSearch={searchState.parsedSearch} />
         <div className="flex-1" />
-
-        {/* Search */}
-        <div ref={searchShellRef} className="relative">
-          <div className="flex items-center rounded-lg border border-white/8 bg-white/5 overflow-hidden">
-            <div className="relative">
-              <svg className="pointer-events-none absolute left-2.5 top-1/2 h-3.5 w-3.5 -translate-y-1/2 text-gray-600"
-                fill="none" viewBox="0 0 24 24" stroke="currentColor">
-                <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2}
-                  d="M21 21l-4.35-4.35M17 11A6 6 0 115 11a6 6 0 0112 0z" />
-              </svg>
-              <input
-                ref={searchInputRef}
-                type="text"
-                value={searchQuery}
-                onChange={(event) => {
-                  userHasTyped.current = true;
-                  const nextValue = event.target.value;
-                  if (!searchCommand) {
-                    const parsed = parseSearchValue(nextValue);
-                    if (parsed.prefix) {
-                      setSearchCommand(parsed.mode === "filename" ? null : parsed.mode);
-                      setSearchQuery(parsed.query);
-                      return;
-                    }
-                  }
-                  setSearchQuery(nextValue);
-                }}
-                onKeyDown={(event) => {
-                  if (event.key === "Backspace" && searchQuery.length === 0 && searchCommand !== null) {
-                    event.preventDefault();
-                    setSearchCommand(null);
-                  }
-                }}
-                onFocus={() => setSearchPanelOpen(true)}
-                placeholder="Search files, or use /s /t"
-                className={`w-40 bg-transparent py-1.5 pr-9 text-sm text-white placeholder:text-gray-600 focus:outline-none transition-colors lg:w-52 xl:w-64 ${searchCommand !== null ? "pl-16" : "pl-8"}`}
-              />
-              {searchCommand !== null ? (
-                <div className="absolute left-8 top-1/2 -translate-y-1/2">
-                  <Tooltip label="Remove search command" anchorToCursor>
-                    <button
-                      type="button"
-                      className="rounded-md border border-white/10 bg-white/[0.05] px-1.5 py-0.5 font-mono text-[11px] text-gray-300 transition-colors hover:bg-white/[0.08] hover:text-white"
-                      onClick={() => { setSearchCommand(null); setTagSuggestions([]); }}
-                    >
-                      {commandPrefix(searchCommand)}
-                    </button>
-                  </Tooltip>
-                </div>
-              ) : null}
-              {searchQuery.trim().length > 0 || searchCommand !== null ? (
-                <Tooltip label="Clear search" anchorToCursor className="absolute right-2 top-1/2 -translate-y-1/2">
-                  <button
-                    className="rounded-md p-1 text-gray-500 hover:bg-white/5 hover:text-gray-200 transition-colors"
-                    onClick={() => {
-                      setSearchCommand(null);
-                      setSearchQuery("");
-                      setTagSuggestions([]);
-                      clearSearch();
-                    }}
-                  >
-                    <svg className="h-3.5 w-3.5" fill="none" viewBox="0 0 24 24" stroke="currentColor">
-                      <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M6 18L18 6M6 6l12 12" />
-                    </svg>
-                  </button>
-                </Tooltip>
-              ) : null}
-            </div>
-          </div>
-
-          {/* Tag autocomplete suggestions */}
-          {showTagSuggestions && tagSuggestions.length > 0 ? (
-            <div className="absolute left-0 top-full z-50 mt-1.5 w-72 rounded-xl border border-white/10 bg-gray-950/98 py-1 shadow-2xl backdrop-blur">
-              {tagSuggestions.map((entry) => (
-                <button
-                  key={entry.tag}
-                  className="flex w-full items-center justify-between gap-3 px-3 py-2 text-left transition-colors hover:bg-white/[0.05]"
-                  onMouseDown={(e) => {
-                    // mousedown fires before input blur, so we prevent losing focus
-                    e.preventDefault();
-                    userHasTyped.current = true;
-                    setSearchQuery(entry.tag);
-                    setSearch(`/t ${entry.tag}`);
-                    setSearchPanelOpen(false);
-                    searchInputRef.current?.blur();
-                  }}
-                >
-                  <span className="text-sm text-white/88">{entry.tag}</span>
-                  <span className="shrink-0 text-[11px] tabular-nums text-white/30">{entry.count.toLocaleString()}</span>
-                </button>
-              ))}
-            </div>
-          ) : null}
-
-          {/* Tag mode with no suggestions yet — show a brief hint */}
-          {showTagSuggestions && tagSuggestions.length === 0 && searchQuery.trim().length > 0 ? (
-            <div className="absolute left-0 top-full z-50 mt-1.5 w-72 rounded-xl border border-white/10 bg-gray-950/98 px-3 py-2.5 shadow-2xl backdrop-blur">
-              <p className="text-xs text-white/25">No matching tags</p>
-            </div>
-          ) : null}
-
-          {/* Semantic mode hint */}
-          {searchCommand === "semantic" && searchPanelOpen ? (
-            <div className="absolute left-0 top-full z-50 mt-1.5 w-72 rounded-xl border border-white/10 bg-gray-950/98 px-3 py-2.5 shadow-2xl backdrop-blur">
-              <p className="text-xs text-white/40">Search by meaning and visual concepts</p>
-            </div>
-          ) : null}
-
-          {/* Command hints — only shown when no command is active */}
-          {showCommandHints ? (
-            <div className="absolute left-0 top-full z-50 mt-1.5 w-64 rounded-xl border border-white/10 bg-gray-950/98 py-1 shadow-2xl backdrop-blur">
-              {(
-                [
-                  { command: "tag" as SearchCommand, prefix: "/t", label: "Tags", description: "Search user and AI tags" },
-                  { command: "semantic" as SearchCommand, prefix: "/s", label: "Semantic", description: "Search by meaning, object, mood" },
-                ] as const
-              ).map((option) => (
-                <button
-                  key={option.prefix}
-                  className="flex w-full items-center gap-3 px-3 py-2 text-left transition-colors hover:bg-white/[0.05]"
-                  onMouseDown={(e) => {
-                    e.preventDefault();
-                    userHasTyped.current = true;
-                    setSearchCommand(option.command);
-                    searchInputRef.current?.focus();
-                  }}
-                >
-                  <span className="rounded border border-white/10 bg-white/[0.04] px-1.5 py-0.5 font-mono text-[11px] text-gray-400">
-                    {option.prefix}
-                  </span>
-                  <div>
-                    <p className="text-sm text-gray-200">{option.label}</p>
-                    <p className="text-xs text-gray-500">{option.description}</p>
-                  </div>
-                </button>
-              ))}
-            </div>
-          ) : null}
-        </div>
-
-        {/* Sort */}
-        <SortDropdown value={sort} onChange={setSort} options={sortOptions} />
-
-        {/* Divider */}
-        <div className="h-4 w-px bg-white/10 shrink-0" />
-
-        {/* Zoom */}
-        <div className="flex items-center rounded-lg border border-white/8 overflow-hidden light-theme:border-gray-700/40">
-          {(["compact", "comfortable", "detail"] as const).map((preset, i) => (
-            <Tooltip key={preset} label={`${tileSize}px tiles`} followCursor>
-              <button
-                className={`px-2.5 py-1.5 text-xs font-medium transition-colors ${
-                  i > 0 ? "border-l border-white/8" : ""
-                } ${
-                  zoomPreset === preset
-                    ? "bg-white/10 text-white light-theme:bg-gray-900 light-theme:text-white"
-                    : "text-gray-500 hover:text-gray-200 hover:bg-white/5 light-theme:text-gray-600 light-theme:hover:bg-gray-900 light-theme:hover:text-white"
-                }`}
-                onClick={() => setZoomPreset(preset)}
-              >
-                {preset === "compact" ? "S" : preset === "comfortable" ? "M" : "L"}
-              </button>
-            </Tooltip>
-          ))}
-        </div>
-      </div>
-
-      {/* Filter row — pills scroll horizontally on narrow widths so they never
-          squash or stack; the color filter stays pinned to the right. */}
-      <div className="flex items-center gap-1 px-4 pb-1.5">
-        <div className="flex min-w-0 flex-1 items-center gap-1 overflow-x-auto [scrollbar-width:none] [&::-webkit-scrollbar]:hidden">
-        <FilterPill label="All" active={mediaFilter === "all" && !favoritesOnly && !failedEmbeddingsOnly && !failedTaggingOnly && minimumRating === 0 && colorFilter === null} onClick={() => { setMediaFilter("all"); setFavoritesOnly(false); setMinimumRating(0); setFailedEmbeddingsOnly(false); setFailedTaggingOnly(false); setColorFilter(null); }} />
-        <FilterPill label="Images" active={mediaFilter === "image" && !favoritesOnly && !failedEmbeddingsOnly && !failedTaggingOnly} onClick={() => { setMediaFilter("image"); setFavoritesOnly(false); setFailedEmbeddingsOnly(false); setFailedTaggingOnly(false); }} />
-        <FilterPill label="Videos" active={mediaFilter === "video" && !favoritesOnly && !failedEmbeddingsOnly && !failedTaggingOnly} onClick={() => { setMediaFilter("video"); setFavoritesOnly(false); setFailedEmbeddingsOnly(false); setFailedTaggingOnly(false); }} />
-        <FilterPill label="Favorites" active={favoritesOnly} onClick={() => { setFavoritesOnly(!favoritesOnly); setFailedEmbeddingsOnly(false); setFailedTaggingOnly(false); }} />
-        <FilterPill label="Rated" active={minimumRating === 1} onClick={() => { setMinimumRating(minimumRating === 1 ? 0 : 1); setFailedEmbeddingsOnly(false); setFailedTaggingOnly(false); }} />
-        <FilterPill label="4★+" active={minimumRating === 4} onClick={() => { setMinimumRating(minimumRating === 4 ? 0 : 4); setFailedEmbeddingsOnly(false); setFailedTaggingOnly(false); }} />
-        {showAlbumScope ? (
-          <FilterPill label="Similar: Album" active={similarScope === "current_album"} onClick={() => setSimilarScope("current_album")} />
-        ) : null}
-        <FilterPill label="Similar: Folder" active={similarScope === "current_folder"} onClick={() => setSimilarScope("current_folder")} />
-        <FilterPill label="Similar: All" active={similarScope === "all_media"} onClick={() => setSimilarScope("all_media")} />
-        {hasAnyFailedEmbeddings ? (
-          <FilterPill
-            label="Failed Embeddings"
-            active={failedEmbeddingsOnly}
-            variant="amber"
-            onClick={() => setFailedEmbeddingsOnly(!failedEmbeddingsOnly)}
-          />
-        ) : null}
-        {hasAnyFailedTagging ? (
-          <FilterPill
-            label="Failed Tags"
-            active={failedTaggingOnly}
-            variant="amber"
-            onClick={() => setFailedTaggingOnly(!failedTaggingOnly)}
-          />
-        ) : null}
-        {isSimilarResults ? <span className="ml-2 shrink-0 whitespace-nowrap text-[11px] text-gray-500">Current similar scope: {similarScope === "current_album" ? "this album" : similarScope === "current_folder" ? "current folder" : "all media"}</span> : null}
-        </div>
-        <ColorFilter />
-      </div>
-    </div>
-  );
+        <ToolbarSearch searchState={searchState} />
+        <SortControl />
+        <div className="h-4 w-px shrink-0 bg-white/10" />
+        <ZoomControl />
+      </div>
+      <ToolbarFilters />
+    </div>
+  )
 }

src/components/Tooltip.tsx

@@ -1,22 +1,23 @@
-import { MouseEvent, ReactNode, useEffect, useRef, useState } from "react";
-import { createPortal } from "react-dom";
-import { motion } from "framer-motion";
+import { MouseEvent, ReactNode, useEffect, useRef, useState } from 'react'
+import { createPortal } from 'react-dom'
+import { motion } from 'framer-motion'
 
-type TooltipSide = "top" | "bottom" | "left" | "right";
-type TooltipAlign = "center" | "start" | "end";
+type TooltipSide = 'top' | 'bottom' | 'left' | 'right'
+type TooltipAlign = 'center' | 'start' | 'end'
 
 // Horizontal alignment only applies to top/bottom; left/right center vertically.
 function positionClasses(side: TooltipSide, align: TooltipAlign): string {
-  if (side === "left") return "right-full top-1/2 mr-1.5 -translate-y-1/2";
-  if (side === "right") return "left-full top-1/2 ml-1.5 -translate-y-1/2";
-  const vertical = side === "top" ? "bottom-full mb-1.5" : "top-full mt-1.5";
-  const horizontal = align === "start" ? "left-0" : align === "end" ? "right-0" : "left-1/2 -translate-x-1/2";
-  return `${vertical} ${horizontal}`;
+  if (side === 'left') return 'right-full top-1/2 mr-1.5 -translate-y-1/2'
+  if (side === 'right') return 'left-full top-1/2 ml-1.5 -translate-y-1/2'
+  const vertical = side === 'top' ? 'bottom-full mb-1.5' : 'top-full mt-1.5'
+  const horizontal =
+    align === 'start' ? 'left-0' : align === 'end' ? 'right-0' : 'left-1/2 -translate-x-1/2'
+  return `${vertical} ${horizontal}`
 }
 
 const BASE_CLASSES =
-  "pointer-events-none z-50 whitespace-nowrap rounded-md border border-white/10 bg-gray-800 px-2 py-1 text-[11px] text-gray-200 shadow-lg";
-const STATIC_CLASSES = `${BASE_CLASSES} transition-opacity duration-100`;
+  'pointer-events-none z-50 whitespace-nowrap rounded-md border border-white/10 bg-gray-800 px-2 py-1 text-[11px] text-gray-200 shadow-lg'
+const STATIC_CLASSES = `${BASE_CLASSES} transition-opacity duration-100`
 
 /**
  * Lightweight custom tooltip — fades in (faster than the native one) after a
@@ -27,98 +28,98 @@ const STATIC_CLASSES = `${BASE_CLASSES} transition-opacity duration-100`;
 export function Tooltip({
   label,
   delay = 400,
-  side = "bottom",
-  align = "center",
+  side = 'bottom',
+  align = 'center',
   block = false,
   anchorToCursor = false,
   followCursor = false,
   disabled = false,
-  className = "",
+  className = '',
   children,
 }: {
-  label: ReactNode;
+  label: ReactNode
   /** Milliseconds the pointer must hover before the tooltip appears (0 = instant). */
-  delay?: number;
-  side?: TooltipSide;
+  delay?: number
+  side?: TooltipSide
   /** Horizontal alignment for top/bottom tooltips. */
-  align?: TooltipAlign;
+  align?: TooltipAlign
   /** Full-width block wrapper (e.g. wrapping a grid cell) instead of inline. */
-  block?: boolean;
+  block?: boolean
   /** Position at the cursor when shown, without following subsequent movement. */
-  anchorToCursor?: boolean;
+  anchorToCursor?: boolean
   /** Track the cursor (fixed position) instead of anchoring to a side. */
-  followCursor?: boolean;
+  followCursor?: boolean
   /** Render the wrapper but suppress tooltip display. */
-  disabled?: boolean;
+  disabled?: boolean
   /** Extra classes for the wrapper (e.g. layout). */
-  className?: string;
-  children: ReactNode;
+  className?: string
+  children: ReactNode
 }) {
-  const [visible, setVisible] = useState(false);
-  const [coords, setCoords] = useState({ x: 0, y: 0 });
-  const [mounted, setMounted] = useState(false);
-  const timer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
-  const frame = useRef<number | undefined>(undefined);
-  const tooltipRef = useRef<HTMLSpanElement>(null);
+  const [visible, setVisible] = useState(false)
+  const [coords, setCoords] = useState({ x: 0, y: 0 })
+  const [mounted, setMounted] = useState(false)
+  const timer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined)
+  const frame = useRef<number | undefined>(undefined)
+  const tooltipRef = useRef<HTMLSpanElement>(null)
 
   // Resolve a viewport-safe position near the cursor: below-right by default,
   // but flipped above the cursor if it would overflow the bottom edge, and
   // clamped so it never runs off the right/left.
   const place = (clientX: number, clientY: number) => {
-    const tip = tooltipRef.current;
-    const tipWidth = tip?.offsetWidth ?? 0;
-    const tipHeight = tip?.offsetHeight ?? 24;
-    const gap = 16;
-    let top = clientY + gap;
+    const tip = tooltipRef.current
+    const tipWidth = tip?.offsetWidth ?? 0
+    const tipHeight = tip?.offsetHeight ?? 24
+    const gap = 16
+    let top = clientY + gap
     if (top + tipHeight > window.innerHeight - 4) {
-      top = clientY - gap - tipHeight;
+      top = clientY - gap - tipHeight
+    }
+    let left = clientX + 14
+    if (left + tipWidth > window.innerWidth - 4) left = window.innerWidth - 4 - tipWidth
+    if (left < 4) left = 4
+    setCoords({ x: left, y: top })
   }
-    let left = clientX + 14;
-    if (left + tipWidth > window.innerWidth - 4) left = window.innerWidth - 4 - tipWidth;
-    if (left < 4) left = 4;
-    setCoords({ x: left, y: top });
-  };
 
   const clear = () => {
-    if (timer.current) clearTimeout(timer.current);
-    timer.current = undefined;
-    if (frame.current !== undefined) cancelAnimationFrame(frame.current);
-    frame.current = undefined;
-  };
-  const show = (event: MouseEvent<HTMLElement>) => {
-    if (disabled) return;
-    clear();
-    if (anchorToCursor || followCursor) place(event.clientX, event.clientY);
-    if (delay <= 0) {
-      setVisible(true);
-      return;
+    if (timer.current) clearTimeout(timer.current)
+    timer.current = undefined
+    if (frame.current !== undefined) cancelAnimationFrame(frame.current)
+    frame.current = undefined
+  }
+  const show = (event: MouseEvent<HTMLElement>) => {
+    if (disabled) return
+    clear()
+    if (anchorToCursor || followCursor) place(event.clientX, event.clientY)
+    if (delay <= 0) {
+      setVisible(true)
+      return
+    }
+    timer.current = setTimeout(() => setVisible(true), delay)
   }
-    timer.current = setTimeout(() => setVisible(true), delay);
-  };
   const hide = () => {
-    clear();
-    setVisible(false);
-  };
+    clear()
+    setVisible(false)
+  }
   const move = (event: MouseEvent<HTMLElement>) => {
-    if (!followCursor) return;
-    const { clientX, clientY } = event;
-    if (frame.current !== undefined) cancelAnimationFrame(frame.current);
+    if (!followCursor) return
+    const { clientX, clientY } = event
+    if (frame.current !== undefined) cancelAnimationFrame(frame.current)
     frame.current = requestAnimationFrame(() => {
-      frame.current = undefined;
-      place(clientX, clientY);
-    });
-  };
+      frame.current = undefined
+      place(clientX, clientY)
+    })
+  }
 
   useEffect(() => {
-    setMounted(true);
-    return clear;
-  }, []);
+    setMounted(true)
+    return clear
+  }, [])
 
   useEffect(() => {
-    if (disabled) hide();
-  }, [disabled]);
+    if (disabled) hide()
+  }, [disabled])
 
-  const Wrapper = block ? "div" : "span";
+  const Wrapper = block ? 'div' : 'span'
   const cursorTooltip = (
     <motion.span
       ref={tooltipRef}
@@ -130,18 +131,22 @@ export function Tooltip({
       initial={false}
       animate={{ left: coords.x, top: coords.y, opacity: visible ? 1 : 0 }}
       transition={{
-        left: followCursor ? { type: "spring", stiffness: 700, damping: 45, mass: 0.35 } : { duration: 0 },
-        top: followCursor ? { type: "spring", stiffness: 520, damping: 34, mass: 0.45 } : { duration: 0 },
+        left: followCursor
+          ? { type: 'spring', stiffness: 700, damping: 45, mass: 0.35 }
+          : { duration: 0 },
+        top: followCursor
+          ? { type: 'spring', stiffness: 520, damping: 34, mass: 0.45 }
+          : { duration: 0 },
         opacity: { duration: visible ? 0.1 : 0.05 },
       }}
     >
       {label}
     </motion.span>
-  );
+  )
 
   return (
     <Wrapper
-      className={`${block ? "relative block w-full" : "relative inline-flex"} ${className}`}
+      className={`${block ? 'relative block w-full' : 'relative inline-flex'} ${className}`}
       onMouseEnter={show}
       onMouseMove={followCursor ? move : undefined}
       onMouseLeave={hide}
@@ -149,16 +154,18 @@ export function Tooltip({
     >
       {children}
       {disabled ? null : anchorToCursor || followCursor ? (
-        mounted ? createPortal(cursorTooltip, document.body) : null
+        mounted ? (
+          createPortal(cursorTooltip, document.body)
+        ) : null
       ) : (
         <span
           role="tooltip"
           aria-hidden={!visible}
-          className={`absolute ${STATIC_CLASSES} ${positionClasses(side, align)} ${visible ? "opacity-100" : "opacity-0"}`}
+          className={`absolute ${STATIC_CLASSES} ${positionClasses(side, align)} ${visible ? 'opacity-100' : 'opacity-0'}`}
         >
           {label}
         </span>
       )}
     </Wrapper>
-  );
+  )
 }

src/components/UpdateToast.tsx

@@ -1,17 +1,19 @@
-import { AnimatePresence, motion } from "framer-motion";
-import { useGalleryStore } from "../store";
+import { AnimatePresence, motion } from 'framer-motion'
+import { useGalleryStore } from '../store'
 
 export function UpdateToast() {
-  const updateStatus = useGalleryStore((s) => s.updateStatus);
-  const updateVersion = useGalleryStore((s) => s.updateVersion);
-  const updateProgress = useGalleryStore((s) => s.updateProgress);
-  const updateDismissed = useGalleryStore((s) => s.updateDismissed);
-  const installUpdate = useGalleryStore((s) => s.installUpdate);
-  const dismissUpdate = useGalleryStore((s) => s.dismissUpdate);
+  const updateStatus = useGalleryStore((s) => s.updateStatus)
+  const updateVersion = useGalleryStore((s) => s.updateVersion)
+  const updateProgress = useGalleryStore((s) => s.updateProgress)
+  const updateDismissed = useGalleryStore((s) => s.updateDismissed)
+  const installUpdate = useGalleryStore((s) => s.installUpdate)
+  const dismissUpdate = useGalleryStore((s) => s.dismissUpdate)
 
   const visible =
     !updateDismissed &&
-    (updateStatus === "available" || updateStatus === "downloading" || updateStatus === "installing");
+    (updateStatus === 'available' ||
+      updateStatus === 'downloading' ||
+      updateStatus === 'installing')
 
   return (
     <AnimatePresence>
@@ -21,9 +23,9 @@ export function UpdateToast() {
           animate={{ opacity: 1, y: 0 }}
           exit={{ opacity: 0, y: 12 }}
           transition={{ duration: 0.18 }}
-          className="fixed bottom-4 right-4 z-50 w-80 rounded-lg border border-white/10 bg-gray-900 p-4 shadow-xl"
+          className="fixed right-4 bottom-4 z-50 w-80 rounded-lg border border-white/10 bg-gray-900 p-4 shadow-xl"
         >
-          {updateStatus === "available" ? (
+          {updateStatus === 'available' ? (
             <>
               <p className="text-sm font-medium text-white">Update available</p>
               <p className="mt-1 text-xs text-gray-500">
@@ -47,14 +49,18 @@ export function UpdateToast() {
           ) : (
             <>
               <p className="text-sm font-medium text-white">
-                {updateStatus === "installing" ? "Installing update..." : "Downloading update..."}
+                {updateStatus === 'installing' ? 'Installing update...' : 'Downloading update...'}
               </p>
               <div className="mt-3 h-1 overflow-hidden rounded-full bg-white/10">
                 <div
                   className={`h-full rounded-full bg-emerald-400/80 transition-[width] duration-200 ${
-                    updateProgress === null ? "w-full animate-pulse" : ""
+                    updateProgress === null ? 'w-full animate-pulse' : ''
                   }`}
-                  style={updateProgress !== null ? { width: `${Math.round(updateProgress * 100)}%` } : undefined}
+                  style={
+                    updateProgress !== null
+                      ? { width: `${Math.round(updateProgress * 100)}%` }
+                      : undefined
+                  }
                 />
               </div>
               <p className="mt-2 text-xs text-gray-600">The app will restart when it finishes.</p>
@@ -63,5 +69,5 @@ export function UpdateToast() {
         </motion.div>
       ) : null}
     </AnimatePresence>
-  );
+  )
 }

src/components/VideoPlayer.tsx

@@ -1,460 +1,64 @@
-import { useCallback, useEffect, useRef, useState } from "react";
-import { AnimatePresence, motion } from "framer-motion";
-import { useGalleryStore } from "../store";
-import { Tooltip } from "./Tooltip";
-
-const SPEED_OPTIONS = [0.25, 0.5, 0.75, 1, 1.25, 1.5, 2];
-const CONTROLS_HIDE_DELAY_MS = 2500;
-const SEEK_STEP_SECONDS = 5;
-const VOLUME_STEP = 0.1;
-
-// Session-wide playback preferences shared across player instances.
-let persistedVolume = 1;
-let persistedMuted = false;
-
-function formatTime(seconds: number): string {
-  if (!Number.isFinite(seconds) || seconds < 0) return "0:00";
-  const total = Math.floor(seconds);
-  const s = total % 60;
-  const m = Math.floor(total / 60) % 60;
-  const h = Math.floor(total / 3600);
-  if (h > 0) return `${h}:${m.toString().padStart(2, "0")}:${s.toString().padStart(2, "0")}`;
-  return `${m}:${s.toString().padStart(2, "0")}`;
-}
-
-interface BufferedRange {
-  start: number;
-  end: number;
-}
-
-function ControlButton({ onClick, label, active = false, children }: {
-  onClick: () => void;
-  label: string;
-  active?: boolean;
-  children: React.ReactNode;
-}) {
-  return (
-    <Tooltip label={label} anchorToCursor>
-      <button
-        className={`rounded-md p-1.5 transition-colors ${active ? "text-white" : "text-gray-300 hover:text-white"} hover:bg-white/10`}
-        onClick={(event) => {
-          event.stopPropagation();
-          onClick();
-        }}
-      >
-        {children}
-      </button>
-    </Tooltip>
-  );
-}
+import { VideoControls } from './videoPlayer/VideoControls'
+import { useVideoPlayer } from './videoPlayer/useVideoPlayer'
 
 export function VideoPlayer({ src }: { src: string }) {
-  const containerRef = useRef<HTMLDivElement>(null);
-  const videoRef = useRef<HTMLVideoElement>(null);
-  const trackRef = useRef<HTMLDivElement>(null);
-  const hideTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-  const scrubbingRef = useRef(false);
-
-  const [playing, setPlaying] = useState(false);
-  const [currentTime, setCurrentTime] = useState(0);
-  const [duration, setDuration] = useState(0);
-  const [buffered, setBuffered] = useState<BufferedRange[]>([]);
-  const [volume, setVolume] = useState(persistedVolume);
-  const [muted, setMuted] = useState(
-    () => useGalleryStore.getState().lightboxAutoMute || persistedMuted,
-  );
-  const [playbackRate, setPlaybackRate] = useState(1);
-  const [loop, setLoop] = useState(false);
-  const [fullscreen, setFullscreen] = useState(false);
-  const [controlsVisible, setControlsVisible] = useState(true);
-  const [speedMenuOpen, setSpeedMenuOpen] = useState(false);
-
-  const speedMenuOpenRef = useRef(speedMenuOpen);
-  speedMenuOpenRef.current = speedMenuOpen;
-
-  // ── Controls visibility ────────────────────────────────────────────────────
-  const showControls = useCallback(() => {
-    setControlsVisible(true);
-    if (hideTimerRef.current) clearTimeout(hideTimerRef.current);
-    hideTimerRef.current = setTimeout(() => {
-      const video = videoRef.current;
-      if (video && !video.paused && !scrubbingRef.current && !speedMenuOpenRef.current) {
-        setControlsVisible(false);
-      }
-    }, CONTROLS_HIDE_DELAY_MS);
-  }, []);
-
-  useEffect(() => {
-    return () => {
-      if (hideTimerRef.current) clearTimeout(hideTimerRef.current);
-    };
-  }, []);
-
-  // ── Video element wiring ───────────────────────────────────────────────────
-  useEffect(() => {
-    const video = videoRef.current;
-    if (!video) return;
-    // Read playback prefs fresh for each opened video — not reactive, so a
-    // settings change applies to the next video rather than the current one.
-    const { lightboxAutoplay, lightboxAutoMute } = useGalleryStore.getState();
-    const startMuted = lightboxAutoMute || persistedMuted;
-    video.volume = persistedVolume;
-    video.muted = startMuted;
-    setMuted(startMuted);
-    // Autoplay when enabled; if the webview blocks it the catch leaves us paused
-    // with controls visible, which is a fine fallback.
-    if (lightboxAutoplay) video.play().catch(() => {});
-  }, [src]);
-
-  const readBuffered = useCallback(() => {
-    const video = videoRef.current;
-    if (!video || !Number.isFinite(video.duration) || video.duration <= 0) return;
-    const ranges: BufferedRange[] = [];
-    for (let i = 0; i < video.buffered.length; i++) {
-      ranges.push({
-        start: video.buffered.start(i) / video.duration,
-        end: video.buffered.end(i) / video.duration,
-      });
-    }
-    setBuffered(ranges);
-  }, []);
-
-  const togglePlay = useCallback(() => {
-    const video = videoRef.current;
-    if (!video) return;
-    if (video.paused) {
-      void video.play().catch(() => {});
-    } else {
-      video.pause();
-    }
-    showControls();
-  }, [showControls]);
-
-  const seekBy = useCallback(
-    (deltaSeconds: number) => {
-      const video = videoRef.current;
-      if (!video || !Number.isFinite(video.duration)) return;
-      video.currentTime = Math.min(video.duration, Math.max(0, video.currentTime + deltaSeconds));
-      showControls();
-    },
-    [showControls],
-  );
-
-  const applyVolume = useCallback(
-    (nextVolume: number, nextMuted?: boolean) => {
-      const video = videoRef.current;
-      const clamped = Math.min(1, Math.max(0, nextVolume));
-      setVolume(clamped);
-      persistedVolume = clamped;
-      if (nextMuted !== undefined) {
-        setMuted(nextMuted);
-        persistedMuted = nextMuted;
-        if (video) video.muted = nextMuted;
-      }
-      if (video) video.volume = clamped;
-      showControls();
-    },
-    [showControls],
-  );
-
-  const toggleMute = useCallback(() => {
-    const next = !muted;
-    setMuted(next);
-    persistedMuted = next;
-    const video = videoRef.current;
-    if (video) video.muted = next;
-    showControls();
-  }, [muted, showControls]);
-
-  const toggleLoop = useCallback(() => {
-    setLoop((value) => {
-      const video = videoRef.current;
-      if (video) video.loop = !value;
-      return !value;
-    });
-    showControls();
-  }, [showControls]);
-
-  const toggleFullscreen = useCallback(() => {
-    if (document.fullscreenElement) {
-      void document.exitFullscreen().catch(() => {});
-    } else {
-      void containerRef.current?.requestFullscreen().catch(() => {});
-    }
-    showControls();
-  }, [showControls]);
-
-  useEffect(() => {
-    const onChange = () => setFullscreen(document.fullscreenElement !== null);
-    document.addEventListener("fullscreenchange", onChange);
-    return () => document.removeEventListener("fullscreenchange", onChange);
-  }, []);
-
-  const setSpeed = useCallback(
-    (rate: number) => {
-      setPlaybackRate(rate);
-      const video = videoRef.current;
-      if (video) video.playbackRate = rate;
-      setSpeedMenuOpen(false);
-      showControls();
-    },
-    [showControls],
-  );
-
-  // ── Scrubber ───────────────────────────────────────────────────────────────
-  const seekToPointer = useCallback((clientX: number) => {
-    const video = videoRef.current;
-    const track = trackRef.current;
-    if (!video || !track || !Number.isFinite(video.duration) || video.duration <= 0) return;
-    const bounds = track.getBoundingClientRect();
-    const fraction = Math.min(1, Math.max(0, (clientX - bounds.left) / bounds.width));
-    video.currentTime = fraction * video.duration;
-    setCurrentTime(video.currentTime);
-  }, []);
-
-  const handleTrackPointerDown = useCallback(
-    (event: React.PointerEvent<HTMLDivElement>) => {
-      event.stopPropagation();
-      event.currentTarget.setPointerCapture(event.pointerId);
-      scrubbingRef.current = true;
-      seekToPointer(event.clientX);
-    },
-    [seekToPointer],
-  );
-
-  const handleTrackPointerMove = useCallback(
-    (event: React.PointerEvent<HTMLDivElement>) => {
-      if (!scrubbingRef.current) return;
-      seekToPointer(event.clientX);
-    },
-    [seekToPointer],
-  );
-
-  const handleTrackPointerUp = useCallback((event: React.PointerEvent<HTMLDivElement>) => {
-    event.currentTarget.releasePointerCapture(event.pointerId);
-    scrubbingRef.current = false;
-  }, []);
-
-  // ── Keyboard ───────────────────────────────────────────────────────────────
-  useEffect(() => {
-    const handler = (event: KeyboardEvent) => {
-      const target = event.target as HTMLElement | null;
-      if (target && (target.tagName === "INPUT" || target.tagName === "TEXTAREA" || target.isContentEditable)) {
-        return;
-      }
-      switch (event.key) {
-        case " ":
-          event.preventDefault();
-          togglePlay();
-          break;
-        case "m":
-        case "M":
-          toggleMute();
-          break;
-        case "f":
-        case "F":
-          toggleFullscreen();
-          break;
-        case "l":
-        case "L":
-          toggleLoop();
-          break;
-        case "ArrowLeft":
-          if (event.shiftKey) {
-            event.preventDefault();
-            seekBy(-SEEK_STEP_SECONDS);
-          }
-          break;
-        case "ArrowRight":
-          if (event.shiftKey) {
-            event.preventDefault();
-            seekBy(SEEK_STEP_SECONDS);
-          }
-          break;
-        case "ArrowUp":
-          event.preventDefault();
-          // Adjusting volume always unmutes, matching the slider behavior.
-          applyVolume(persistedVolume + VOLUME_STEP, false);
-          break;
-        case "ArrowDown":
-          event.preventDefault();
-          applyVolume(persistedVolume - VOLUME_STEP, false);
-          break;
-      }
-    };
-    window.addEventListener("keydown", handler);
-    return () => window.removeEventListener("keydown", handler);
-  }, [togglePlay, toggleMute, toggleFullscreen, toggleLoop, seekBy, applyVolume]);
-
-  const playedFraction = duration > 0 ? currentTime / duration : 0;
-  const effectiveVolume = muted ? 0 : volume;
+  const player = useVideoPlayer(src)
 
   return (
     <div
-      ref={containerRef}
-      className={`media-dark-surface relative flex h-full w-full items-center justify-center bg-black ${controlsVisible ? "" : "cursor-none"}`}
-      onPointerMove={showControls}
+      ref={player.containerRef}
+      className={`media-dark-surface relative flex h-full w-full items-center justify-center bg-black ${player.controlsVisible ? '' : 'cursor-none'}`}
+      onPointerMove={player.showControls}
       onClick={(event) => event.stopPropagation()}
     >
       <video
-        ref={videoRef}
+        ref={player.videoRef}
         src={src}
         className="h-full w-full object-contain"
-        onClick={togglePlay}
-        onDoubleClick={toggleFullscreen}
+        onClick={player.togglePlay}
+        onDoubleClick={player.toggleFullscreen}
         onPlay={() => {
-          setPlaying(true);
-          showControls();
+          player.setPlaying(true)
+          player.showControls()
         }}
         onPause={() => {
-          setPlaying(false);
-          setControlsVisible(true);
+          player.setPlaying(false)
+          player.setControlsVisible(true)
         }}
-        onTimeUpdate={(event) => setCurrentTime(event.currentTarget.currentTime)}
+        onTimeUpdate={(event) => player.setCurrentTime(event.currentTarget.currentTime)}
         onLoadedMetadata={(event) => {
-          setDuration(event.currentTarget.duration);
-          readBuffered();
+          player.setDuration(event.currentTarget.duration)
+          player.readBuffered()
         }}
-        onDurationChange={(event) => setDuration(event.currentTarget.duration)}
-        onProgress={readBuffered}
+        onDurationChange={(event) => player.setDuration(event.currentTarget.duration)}
+        onProgress={player.readBuffered}
       />
 
-      <AnimatePresence>
-        {controlsVisible ? (
-          <motion.div
-            className="absolute inset-x-0 bottom-0 z-10 bg-gradient-to-t from-black/80 via-black/40 to-transparent px-4 pb-2.5 pt-12"
-            initial={{ opacity: 0 }}
-            animate={{ opacity: 1 }}
-            exit={{ opacity: 0 }}
-            transition={{ duration: 0.15 }}
-          >
-            {/* Scrubber */}
-            <div
-              ref={trackRef}
-              className="group/track relative flex h-4 cursor-pointer items-center"
-              onPointerDown={handleTrackPointerDown}
-              onPointerMove={handleTrackPointerMove}
-              onPointerUp={handleTrackPointerUp}
-            >
-              <div className="relative h-1 w-full overflow-hidden rounded-full bg-white/15 transition-[height] group-hover/track:h-1.5">
-                {buffered.map((range, index) => (
-                  <div
-                    key={index}
-                    className="absolute inset-y-0 bg-white/20"
-                    style={{ left: `${range.start * 100}%`, width: `${(range.end - range.start) * 100}%` }}
-                  />
-                ))}
-                <div className="absolute inset-y-0 left-0 bg-white/90" style={{ width: `${playedFraction * 100}%` }} />
-              </div>
-              <div
-                className="pointer-events-none absolute h-3 w-3 -translate-x-1/2 rounded-full bg-white opacity-0 shadow transition-opacity group-hover/track:opacity-100"
-                style={{ left: `${playedFraction * 100}%` }}
+      <VideoControls
+        applyVolume={player.applyVolume}
+        buffered={player.buffered}
+        controlsVisible={player.controlsVisible}
+        currentTime={player.currentTime}
+        duration={player.duration}
+        effectiveVolume={player.effectiveVolume}
+        fullscreen={player.fullscreen}
+        handleTrackPointerDown={player.handleTrackPointerDown}
+        handleTrackPointerMove={player.handleTrackPointerMove}
+        handleTrackPointerUp={player.handleTrackPointerUp}
+        loop={player.loop}
+        muted={player.muted}
+        playbackRate={player.playbackRate}
+        playedFraction={player.playedFraction}
+        playing={player.playing}
+        setSpeed={player.setSpeed}
+        setSpeedMenuOpen={player.setSpeedMenuOpen}
+        speedMenuOpen={player.speedMenuOpen}
+        toggleFullscreen={player.toggleFullscreen}
+        toggleLoop={player.toggleLoop}
+        toggleMute={player.toggleMute}
+        togglePlay={player.togglePlay}
+        trackRef={player.trackRef}
       />
     </div>
-
-            {/* Control row */}
-            <div className="mt-1 flex items-center gap-1.5">
-              <ControlButton onClick={togglePlay} label={playing ? "Pause (Space)" : "Play (Space)"}>
-                {playing ? (
-                  <svg className="h-5 w-5" fill="currentColor" viewBox="0 0 24 24">
-                    <path d="M7 5h4v14H7zM13 5h4v14h-4z" />
-                  </svg>
-                ) : (
-                  <svg className="h-5 w-5" fill="currentColor" viewBox="0 0 24 24">
-                    <path d="M8 5.14v13.72L19 12 8 5.14z" />
-                  </svg>
-                )}
-              </ControlButton>
-
-              <span className="ml-1 text-xs tabular-nums text-gray-300">
-                {formatTime(currentTime)} <span className="text-gray-500">/ {formatTime(duration)}</span>
-              </span>
-
-              <div className="flex-1" />
-
-              {/* Volume */}
-              <ControlButton onClick={toggleMute} label={muted ? "Unmute (M)" : "Mute (M)"}>
-                {effectiveVolume === 0 ? (
-                  <svg className="h-4.5 w-4.5" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
-                    <path strokeLinecap="round" strokeLinejoin="round" d="M5.586 15H4a1 1 0 01-1-1v-4a1 1 0 011-1h1.586l4.707-4.707C10.923 3.663 12 4.109 12 5v14c0 .891-1.077 1.337-1.707.707L5.586 15z" />
-                    <path strokeLinecap="round" strokeLinejoin="round" d="M17 9l4 6m0-6l-4 6" />
-                  </svg>
-                ) : (
-                  <svg className="h-4.5 w-4.5" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
-                    <path strokeLinecap="round" strokeLinejoin="round" d="M5.586 15H4a1 1 0 01-1-1v-4a1 1 0 011-1h1.586l4.707-4.707C10.923 3.663 12 4.109 12 5v14c0 .891-1.077 1.337-1.707.707L5.586 15z" />
-                    <path strokeLinecap="round" strokeLinejoin="round" d="M15.536 8.464a5 5 0 010 7.072M18.364 5.636a9 9 0 010 12.728" />
-                  </svg>
-                )}
-              </ControlButton>
-              <Tooltip label="Volume (↑/↓)" anchorToCursor>
-                <input
-                  type="range"
-                  min={0}
-                  max={1}
-                  step={0.02}
-                  value={effectiveVolume}
-                  className="h-1 w-20 cursor-pointer accent-white"
-                  onChange={(event) => applyVolume(parseFloat(event.target.value), false)}
-                  onClick={(event) => event.stopPropagation()}
-                />
-              </Tooltip>
-
-              {/* Playback speed */}
-              <div className="relative">
-                <Tooltip label="Playback speed" anchorToCursor>
-                  <button
-                    className={`min-w-12 rounded-md px-2 py-1.5 text-xs tabular-nums transition-colors hover:bg-white/10 ${playbackRate !== 1 ? "text-white" : "text-gray-300 hover:text-white"}`}
-                    onClick={(event) => {
-                      event.stopPropagation();
-                      setSpeedMenuOpen((value) => !value);
-                    }}
-                  >
-                    {playbackRate}×
-                  </button>
-                </Tooltip>
-                {speedMenuOpen ? (
-                  <div className="absolute bottom-full right-0 z-20 mb-2 min-w-20 rounded-lg border border-white/10 bg-gray-950/95 p-1 shadow-2xl backdrop-blur">
-                    {SPEED_OPTIONS.map((rate) => (
-                      <button
-                        key={rate}
-                        className={`flex w-full items-center justify-between gap-2 rounded-md px-2.5 py-1.5 text-left text-xs tabular-nums transition-colors ${
-                          rate === playbackRate ? "bg-white/10 text-white" : "text-gray-400 hover:bg-white/5 hover:text-white"
-                        }`}
-                        onClick={(event) => {
-                          event.stopPropagation();
-                          setSpeed(rate);
-                        }}
-                      >
-                        {rate}×
-                      </button>
-                    ))}
-                  </div>
-                ) : null}
-              </div>
-
-              {/* Loop */}
-              <ControlButton onClick={toggleLoop} label={loop ? "Loop on (L)" : "Loop off (L)"} active={loop}>
-                <svg className={`h-4.5 w-4.5 ${loop ? "text-emerald-300" : ""}`} fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
-                  <path strokeLinecap="round" strokeLinejoin="round" d="M4 4v5h5M20 20v-5h-5M4 9a8 8 0 0114-3M20 15a8 8 0 01-14 3" />
-                </svg>
-              </ControlButton>
-
-              {/* Fullscreen */}
-              <ControlButton onClick={toggleFullscreen} label={fullscreen ? "Exit fullscreen (F)" : "Fullscreen (F)"}>
-                {fullscreen ? (
-                  <svg className="h-4.5 w-4.5" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
-                    <path strokeLinecap="round" strokeLinejoin="round" d="M9 9H4m5 0V4m6 5h5m-5 0V4M9 15H4m5 0v5m6-5h5m-5 0v5" />
-                  </svg>
-                ) : (
-                  <svg className="h-4.5 w-4.5" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
-                    <path strokeLinecap="round" strokeLinejoin="round" d="M4 8V4h4M20 8V4h-4M4 16v4h4M20 16v4h-4" />
-                  </svg>
-                )}
-              </ControlButton>
-            </div>
-          </motion.div>
-        ) : null}
-      </AnimatePresence>
-    </div>
-  );
+  )
 }

src/components/WhatsNewModal.tsx

@@ -1,13 +1,34 @@
-import { useEffect, useState, type ReactNode } from "react";
-import { AnimatePresence, motion } from "framer-motion";
-import { invoke } from "@tauri-apps/api/core";
-import { useGalleryStore } from "../store";
-import { getChangelogForVersion, type ChangelogSection } from "../changelog";
-import { Tooltip } from "./Tooltip";
+import { useEffect, useState, type ReactNode } from 'react'
+import { AnimatePresence, motion } from 'framer-motion'
+import { invoke } from '@tauri-apps/api/core'
+import { useGalleryStore } from '../store'
+import {
+  getChangelogForVersion,
+  type ChangelogEntry,
+  type ChangelogItem,
+  type ChangelogSection,
+} from '../changelog'
+import { Tooltip } from './Tooltip'
+import { ChevronRightIcon, CloseIcon } from './icons'
+
+// The modal adapts its layout to the size of the release: small releases keep
+// the compact single-column list, while big ones switch to a two-pane layout
+// with a section nav rail so no one pane is a marathon scroll. Preview both in
+// UI Lab via `?changelog=unreleased` + the demo panel's "Open What's new modal".
+type WhatsNewLayout = 'single' | 'rail'
+
+// Above this many total bullets, the single column gets unpleasantly long.
+const RAIL_THRESHOLD = 20
+
+function chooseLayout(entry: ChangelogEntry | null): WhatsNewLayout {
+  if (!entry || entry.sections.length < 2) return 'single'
+  const total = entry.sections.reduce((sum, section) => sum + section.items.length, 0)
+  return total > RAIL_THRESHOLD ? 'rail' : 'single'
+}
 
 // Shown in the tooltip so the user can see the link's destination before
 // clicking. The actual navigation is handled by the open_changelog_url command.
-const CHANGELOG_URL = "https://github.com/JezzWTF/phokus/blob/main/CHANGELOG.md";
+const CHANGELOG_URL = 'https://github.com/JezzWTF/phokus/blob/main/CHANGELOG.md'
 
 // Per-section accent. These all use the standard colour scale, which the
 // subtle-light theme re-maps to readable dark shades via CSS variables — so no
@@ -15,84 +36,56 @@ const CHANGELOG_URL = "https://github.com/JezzWTF/phokus/blob/main/CHANGELOG.md"
 // index.css: `bg-white`/`text-white` deliberately become *dark* in light mode,
 // so neutral surfaces must use the gray scale and trust the remap.
 const SECTION_STYLES: Record<string, { label: string; dot: string }> = {
-  Added: { label: "text-emerald-300", dot: "bg-emerald-400/80" },
-  Changed: { label: "text-sky-300", dot: "bg-sky-300/80" },
-  Fixed: { label: "text-amber-300", dot: "bg-amber-400/80" },
-  Removed: { label: "text-rose-300", dot: "bg-rose-400/80" },
-  Security: { label: "text-violet-300", dot: "bg-violet-400/80" },
-};
+  Added: { label: 'text-emerald-300', dot: 'bg-emerald-400/80' },
+  Changed: { label: 'text-sky-300', dot: 'bg-sky-300/80' },
+  Fixed: { label: 'text-amber-300', dot: 'bg-amber-400/80' },
+  Removed: { label: 'text-rose-300', dot: 'bg-rose-400/80' },
+  Security: { label: 'text-violet-300', dot: 'bg-violet-400/80' },
+}
 
-const NEUTRAL_STYLE = { label: "text-gray-300", dot: "bg-gray-400/70" };
+const NEUTRAL_STYLE = { label: 'text-gray-300', dot: 'bg-gray-400/70' }
+
+function sectionStyle(title: string) {
+  return SECTION_STYLES[title] ?? NEUTRAL_STYLE
+}
 
 // Render the small amount of inline markdown the changelog uses: **bold** and
 // `code`. Anything else passes through as plain text.
 function renderInline(text: string): ReactNode[] {
-  const nodes: ReactNode[] = [];
-  const regex = /\*\*(.+?)\*\*|`([^`]+)`/g;
-  let lastIndex = 0;
-  let key = 0;
-  let match: RegExpExecArray | null;
+  const nodes: ReactNode[] = []
+  const regex = /\*\*(.+?)\*\*|`([^`]+)`/g
+  let lastIndex = 0
+  let key = 0
+  let match: RegExpExecArray | null
   while ((match = regex.exec(text)) !== null) {
     if (match.index > lastIndex) {
-      nodes.push(text.slice(lastIndex, match.index));
+      nodes.push(text.slice(lastIndex, match.index))
     }
     if (match[1] !== undefined) {
       nodes.push(
         <strong key={key++} className="font-semibold text-white">
           {match[1]}
-        </strong>,
-      );
+        </strong>
+      )
     } else if (match[2] !== undefined) {
       nodes.push(
         <code key={key++} className="rounded bg-white/10 px-1 py-0.5 text-[12px] text-gray-200">
           {match[2]}
-        </code>,
-      );
+        </code>
+      )
     }
-    lastIndex = regex.lastIndex;
+    lastIndex = regex.lastIndex
   }
   if (lastIndex < text.length) {
-    nodes.push(text.slice(lastIndex));
+    nodes.push(text.slice(lastIndex))
   }
-  return nodes;
+  return nodes
 }
 
-function Section({ section }: { section: ChangelogSection }) {
-  const style = SECTION_STYLES[section.title] ?? NEUTRAL_STYLE;
-  const [open, setOpen] = useState(true);
-
+function Item({ item, dot }: { item: ChangelogItem; dot: string }) {
   return (
-    <section>
-      <button
-        type="button"
-        onClick={() => setOpen((value) => !value)}
-        className="flex w-full items-center gap-2 text-left"
-        aria-expanded={open}
-      >
-        <svg
-          className={`h-3 w-3 shrink-0 text-gray-600 transition-transform ${open ? "rotate-90" : ""}`}
-          fill="none"
-          viewBox="0 0 24 24"
-          stroke="currentColor"
-        >
-          <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2.5} d="M9 5l7 7-7 7" />
-        </svg>
-        <span className={`text-[11px] font-semibold uppercase tracking-[0.1em] ${style.label}`}>{section.title}</span>
-        <span className="text-[11px] font-medium text-gray-600">{section.items.length}</span>
-      </button>
-      <AnimatePresence initial={false}>
-        {open ? (
-          <motion.div
-            initial={{ height: 0, opacity: 0 }}
-            animate={{ height: "auto", opacity: 1 }}
-            exit={{ height: 0, opacity: 0 }}
-            transition={{ duration: 0.18 }}
-            className="overflow-hidden"
-          >
-            <ul className="mt-2.5 space-y-2.5 pl-5">
-              {section.items.map((item, index) => (
-                <li key={index} className="flex gap-3">
-                  <span className={`mt-[7px] h-1.5 w-1.5 shrink-0 rounded-full ${style.dot}`} />
+    <li className="flex gap-3">
+      <span className={`mt-[7px] h-1.5 w-1.5 shrink-0 rounded-full ${dot}`} />
       <p className="text-[13px] leading-relaxed text-gray-400">
         {item.lead ? (
           <>
@@ -104,30 +97,129 @@ function Section({ section }: { section: ChangelogSection }) {
         )}
       </p>
     </li>
+  )
+}
+
+function ItemList({
+  items,
+  dot,
+  className = '',
+}: {
+  items: ChangelogItem[]
+  dot: string
+  className?: string
+}) {
+  return (
+    <ul className={`space-y-2.5 ${className}`}>
+      {items.map((item, index) => (
+        <Item key={index} item={item} dot={dot} />
       ))}
     </ul>
+  )
+}
+
+function CollapsibleSection({ section }: { section: ChangelogSection }) {
+  const style = sectionStyle(section.title)
+  const [open, setOpen] = useState(true)
+
+  return (
+    <section>
+      <button
+        type="button"
+        onClick={() => setOpen((value) => !value)}
+        className="flex w-full items-center gap-2 text-left"
+        aria-expanded={open}
+      >
+        <ChevronRightIcon
+          className={`h-3 w-3 shrink-0 text-gray-600 transition-transform ${open ? 'rotate-90' : ''}`}
+          strokeWidth={2.5}
+        />
+        <span className={`text-[11px] font-semibold tracking-[0.1em] uppercase ${style.label}`}>
+          {section.title}
+        </span>
+        <span className="text-[11px] font-medium text-gray-600">{section.items.length}</span>
+      </button>
+      <AnimatePresence initial={false}>
+        {open ? (
+          <motion.div
+            initial={{ height: 0, opacity: 0 }}
+            animate={{ height: 'auto', opacity: 1 }}
+            exit={{ height: 0, opacity: 0 }}
+            transition={{ duration: 0.18 }}
+            className="overflow-hidden"
+          >
+            <ItemList items={section.items} dot={style.dot} className="mt-2.5 pl-5" />
           </motion.div>
         ) : null}
       </AnimatePresence>
     </section>
-  );
+  )
+}
+
+// 'rail' layout — a section nav rail on the left, the selected section's items
+// on the right.
+function RailSections({ sections }: { sections: ChangelogSection[] }) {
+  const [active, setActive] = useState(0)
+  const section = sections[Math.min(active, sections.length - 1)]
+  const style = sectionStyle(section.title)
+
+  return (
+    <div className="flex min-h-0 flex-1">
+      <nav className="flex w-44 shrink-0 flex-col gap-1 border-r border-white/[0.07] px-3 py-4">
+        {sections.map((s, index) => {
+          const navStyle = sectionStyle(s.title)
+          const isActive = index === active
+          return (
+            <button
+              key={s.title}
+              type="button"
+              onClick={() => setActive(index)}
+              className={`flex items-center gap-2.5 rounded-md px-3 py-2 text-left text-[12px] font-medium transition-colors ${
+                isActive
+                  ? 'bg-white/[0.07] text-white'
+                  : 'text-gray-500 hover:bg-white/[0.04] hover:text-gray-300'
+              }`}
+            >
+              <span className={`h-1.5 w-1.5 shrink-0 rounded-full ${navStyle.dot}`} />
+              <span className="flex-1">{s.title}</span>
+              <span className="text-[11px] font-medium text-gray-600">{s.items.length}</span>
+            </button>
+          )
+        })}
+      </nav>
+      <div className="min-h-0 flex-1 overflow-y-auto px-6 py-5">
+        <p className={`mb-3 text-[11px] font-semibold tracking-[0.1em] uppercase ${style.label}`}>
+          {section.title}
+        </p>
+        <ItemList items={section.items} dot={style.dot} />
+      </div>
+    </div>
+  )
+}
+
+const MODAL_WIDTHS: Record<WhatsNewLayout, string> = {
+  single: 'w-[min(88vw,560px)]',
+  rail: 'w-[min(90vw,780px)]',
 }
 
 export function WhatsNewModal() {
-  const whatsNewOpen = useGalleryStore((s) => s.whatsNewOpen);
-  const closeWhatsNew = useGalleryStore((s) => s.closeWhatsNew);
-  const appVersion = useGalleryStore((s) => s.appVersion);
+  const whatsNewOpen = useGalleryStore((s) => s.whatsNewOpen)
+  const closeWhatsNew = useGalleryStore((s) => s.closeWhatsNew)
+  const appVersion = useGalleryStore((s) => s.appVersion)
 
-  const entry = getChangelogForVersion(appVersion);
+  const entry = getChangelogForVersion(appVersion)
+  const layout = chooseLayout(entry)
 
   useEffect(() => {
-    if (!whatsNewOpen) return;
+    if (!whatsNewOpen) return
     const handleKeyDown = (event: KeyboardEvent) => {
-      if (event.key === "Escape") closeWhatsNew();
-    };
-    window.addEventListener("keydown", handleKeyDown);
-    return () => window.removeEventListener("keydown", handleKeyDown);
-  }, [whatsNewOpen, closeWhatsNew]);
+      if (event.key === 'Escape') closeWhatsNew()
+    }
+    window.addEventListener('keydown', handleKeyDown)
+    return () => window.removeEventListener('keydown', handleKeyDown)
+  }, [whatsNewOpen, closeWhatsNew])
+
+  const hasSections = entry !== null && entry.sections.length > 0
 
   return (
     <AnimatePresence>
@@ -141,7 +233,7 @@ export function WhatsNewModal() {
           transition={{ duration: 0.15 }}
         >
           <motion.div
-            className="relative flex max-h-[min(82vh,760px)] w-[min(88vw,560px)] flex-col overflow-hidden rounded-lg border border-white/10 bg-gray-950 shadow-2xl shadow-black/60"
+            className={`relative flex max-h-[min(82vh,760px)] ${MODAL_WIDTHS[layout]} flex-col overflow-hidden rounded-lg border border-white/10 bg-gray-950 shadow-2xl shadow-black/60`}
             onClick={(event) => event.stopPropagation()}
             initial={{ opacity: 0, scale: 0.97, y: 8 }}
             animate={{ opacity: 1, scale: 1, y: 0 }}
@@ -150,39 +242,48 @@ export function WhatsNewModal() {
           >
             <div className="flex items-start justify-between gap-4 border-b border-white/[0.07] px-6 py-5">
               <div>
-                <p className="text-[11px] font-semibold uppercase tracking-[0.12em] text-emerald-300">What's new</p>
+                <p className="text-[11px] font-semibold tracking-[0.12em] text-emerald-300 uppercase">
+                  What's new
+                </p>
                 <h3 className="mt-1 text-lg font-semibold text-white">
-                  Phokus v{entry?.version ?? appVersion ?? "—"}
+                  Phokus v{entry?.version ?? appVersion ?? '—'}
                 </h3>
-                {entry?.date ? <p className="mt-0.5 text-xs text-gray-600">Released {entry.date}</p> : null}
+                {entry?.date ? (
+                  <p className="mt-0.5 text-xs text-gray-600">Released {entry.date}</p>
+                ) : null}
               </div>
               <Tooltip label="Close" anchorToCursor>
                 <button
                   className="rounded-md p-1.5 text-gray-500 transition-colors hover:bg-white/[0.06] hover:text-white"
                   onClick={closeWhatsNew}
                 >
-                  <svg className="h-4 w-4" fill="none" viewBox="0 0 24 24" stroke="currentColor">
-                    <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M6 18L18 6M6 6l12 12" />
-                  </svg>
+                  <CloseIcon className="h-4 w-4" />
                 </button>
               </Tooltip>
             </div>
 
+            {hasSections && layout === 'rail' ? (
+              <RailSections sections={entry.sections} />
+            ) : (
               <div className="min-h-0 flex-1 space-y-6 overflow-y-auto px-6 py-5">
-              {entry && entry.sections.length > 0 ? (
-                entry.sections.map((section) => <Section key={section.title} section={section} />)
+                {hasSections ? (
+                  entry.sections.map((section) => (
+                    <CollapsibleSection key={section.title} section={section} />
+                  ))
                 ) : (
                   <p className="text-sm text-gray-500">
-                  Release notes for this version aren't available in-app. See the full changelog on GitHub.
+                    Release notes for this version aren't available in-app. See the full changelog
+                    on GitHub.
                   </p>
                 )}
               </div>
+            )}
 
             <div className="flex items-center justify-between gap-4 border-t border-white/[0.07] px-6 py-4">
               <Tooltip label={CHANGELOG_URL} side="top" align="start">
                 <button
                   type="button"
-                  onClick={() => void invoke("open_changelog_url")}
+                  onClick={() => void invoke('open_changelog_url')}
                   className="text-xs text-gray-500 transition-colors hover:text-gray-300"
                 >
                   Full changelog ↗
@@ -199,5 +300,5 @@ export function WhatsNewModal() {
         </motion.div>
       ) : null}
     </AnimatePresence>
-  );
+  )
 }

src/components/WhatsNewToast.tsx

@@ -1,15 +1,15 @@
-import { AnimatePresence, motion } from "framer-motion";
-import { useGalleryStore } from "../store";
+import { AnimatePresence, motion } from 'framer-motion'
+import { useGalleryStore } from '../store'
 
 // Shown once on the first launch after an update, inviting the user to read the
 // changelog. Distinct from UpdateToast (which drives the download/install flow).
 export function WhatsNewToast() {
-  const whatsNewToast = useGalleryStore((s) => s.whatsNewToast);
-  const whatsNewOpen = useGalleryStore((s) => s.whatsNewOpen);
-  const openWhatsNew = useGalleryStore((s) => s.openWhatsNew);
-  const dismissWhatsNewToast = useGalleryStore((s) => s.dismissWhatsNewToast);
+  const whatsNewToast = useGalleryStore((s) => s.whatsNewToast)
+  const whatsNewOpen = useGalleryStore((s) => s.whatsNewOpen)
+  const openWhatsNew = useGalleryStore((s) => s.openWhatsNew)
+  const dismissWhatsNewToast = useGalleryStore((s) => s.dismissWhatsNewToast)
 
-  const visible = whatsNewToast !== null && !whatsNewOpen;
+  const visible = whatsNewToast !== null && !whatsNewOpen
 
   return (
     <AnimatePresence>
@@ -19,7 +19,7 @@ export function WhatsNewToast() {
           animate={{ opacity: 1, y: 0 }}
           exit={{ opacity: 0, y: 12 }}
           transition={{ duration: 0.18 }}
-          className="fixed bottom-4 right-4 z-50 w-80 rounded-lg border border-emerald-400/20 bg-gray-900 p-4 shadow-xl"
+          className="fixed right-4 bottom-4 z-50 w-80 rounded-lg border border-emerald-400/20 bg-gray-900 p-4 shadow-xl"
         >
           <p className="text-sm font-medium text-white">What's new in Phokus v{whatsNewToast}</p>
           <p className="mt-1 text-xs text-gray-500">See what's changed in this version.</p>
@@ -40,5 +40,5 @@ export function WhatsNewToast() {
         </motion.div>
       ) : null}
     </AnimatePresence>
-  );
+  )
 }

src/components/backgroundTasks/BackgroundTaskActions.tsx

@@ -0,0 +1,67 @@
+import { Tooltip } from '../Tooltip'
+import { CloseIcon } from '../icons'
+import type { BackgroundTask } from './types'
+
+export function FailureActions({
+  onLocate,
+  onRetry,
+  task,
+}: {
+  onLocate: (folderId: number) => void
+  onRetry: (task: BackgroundTask) => void
+  task: BackgroundTask
+}) {
+  if (task.pendingMediaWork !== 0 || (!task.hasFailedEmbeddings && !task.hasFailedTagging))
+    return null
+
+  return (
+    <div className="flex shrink-0 items-center gap-1.5">
+      {task.hasFailedTagging ? (
+        <button
+          className="light-theme:border-amber-500/50 light-theme:bg-amber-100 light-theme:text-amber-700 light-theme:hover:bg-amber-200 rounded-lg border border-amber-500/20 bg-amber-500/10 px-2.5 py-1 text-[11px] text-amber-300 transition-colors hover:bg-amber-500/20"
+          onClick={(event) => {
+            event.stopPropagation()
+            onLocate(task.id)
+          }}
+        >
+          Locate
+        </button>
+      ) : null}
+      <button
+        className="light-theme:border-amber-500/50 light-theme:bg-amber-100 light-theme:text-amber-700 light-theme:hover:bg-amber-200 rounded-lg border border-amber-500/20 bg-amber-500/10 px-2.5 py-1 text-[11px] text-amber-300 transition-colors hover:bg-amber-500/20"
+        onClick={(event) => {
+          event.stopPropagation()
+          onRetry(task)
+        }}
+      >
+        Retry
+      </button>
+    </div>
+  )
+}
+
+export function DismissTaskButton({
+  onDismiss,
+  size = 'normal',
+  task,
+}: {
+  onDismiss: (task: BackgroundTask) => void
+  size?: 'normal' | 'small'
+  task: BackgroundTask
+}) {
+  if (task.id < 0) return null
+
+  return (
+    <Tooltip label="Dismiss" anchorToCursor>
+      <button
+        className="shrink-0 rounded-md p-1 text-gray-600 transition-colors hover:bg-white/8 hover:text-gray-300"
+        onClick={(event) => {
+          event.stopPropagation()
+          onDismiss(task)
+        }}
+      >
+        <CloseIcon className={size === 'small' ? 'h-3 w-3' : 'h-3.5 w-3.5'} />
+      </button>
+    </Tooltip>
+  )
+}

src/components/backgroundTasks/BackgroundTaskSummary.tsx

@@ -0,0 +1,82 @@
+import type { WorkerKey } from '../../store'
+import { ChevronDownIcon } from '../icons'
+import { DismissTaskButton, FailureActions } from './BackgroundTaskActions'
+import { TaskProgressBar } from './TaskProgressBar'
+import { TaskStagePill } from './TaskStagePill'
+import type { BackgroundTask } from './types'
+
+export function BackgroundTaskSummary({
+  expanded,
+  extraCount,
+  hasFailed,
+  isWorkerPaused,
+  onDismiss,
+  onLocate,
+  onRetry,
+  onToggleExpanded,
+  onToggleWorker,
+  primary,
+  progress,
+  taskCount,
+}: {
+  expanded: boolean
+  extraCount: number
+  hasFailed: boolean
+  isWorkerPaused: (folderId: number, worker: WorkerKey) => boolean
+  onDismiss: (task: BackgroundTask) => void
+  onLocate: (folderId: number) => void
+  onRetry: (task: BackgroundTask) => void
+  onToggleExpanded: () => void
+  onToggleWorker: (folderId: number, worker: WorkerKey) => void
+  primary: BackgroundTask
+  progress: number | null
+  taskCount: number
+}) {
+  return (
+    <div
+      className={`group flex h-11 cursor-pointer items-center gap-3 px-5 transition-colors select-none ${
+        expanded ? 'bg-white/[0.03]' : 'hover:bg-white/[0.02]'
+      }`}
+      onClick={onToggleExpanded}
+    >
+      <div className="relative shrink-0">
+        <div className={`h-1.5 w-1.5 rounded-full ${hasFailed ? 'bg-amber-400' : 'bg-blue-400'}`} />
+        <div
+          className={`absolute inset-0 h-1.5 w-1.5 animate-ping rounded-full opacity-60 ${hasFailed ? 'bg-amber-400' : 'bg-blue-400'}`}
+        />
+      </div>
+
+      <span className="shrink-0 text-[13px] font-medium text-white/60">{primary.name}</span>
+
+      <div className="flex min-w-0 flex-1 items-center gap-1.5 overflow-hidden">
+        {primary.stages.map((stage) => (
+          <TaskStagePill
+            key={stage.label}
+            folderId={primary.id}
+            isWorkerPaused={isWorkerPaused}
+            onToggleWorker={onToggleWorker}
+            stage={stage}
+          />
+        ))}
+      </div>
+
+      <TaskProgressBar failed={hasFailed} progress={progress} widthClass="w-24" />
+
+      {extraCount > 0 ? (
+        <span className="shrink-0 rounded-full bg-white/8 px-2 py-0.5 text-[10px] text-gray-500">
+          +{extraCount}
+        </span>
+      ) : null}
+
+      <FailureActions onLocate={onLocate} onRetry={onRetry} task={primary} />
+
+      {taskCount > 1 ? (
+        <ChevronDownIcon
+          className={`h-3.5 w-3.5 shrink-0 text-gray-600 transition-transform duration-200 ${expanded ? 'rotate-180' : ''}`}
+        />
+      ) : null}
+
+      <DismissTaskButton onDismiss={onDismiss} task={primary} />
+    </div>
+  )
+}

src/components/backgroundTasks/ExpandedTaskPanel.tsx

@@ -0,0 +1,84 @@
+import type { WorkerKey } from '../../store'
+import { DismissTaskButton, FailureActions } from './BackgroundTaskActions'
+import { FailedWorkerItemRow } from './FailedWorkerItemRow'
+import { taskHasTerminalFailure, taskProgress } from './taskModel'
+import { TaskProgressBar } from './TaskProgressBar'
+import { TaskStagePill } from './TaskStagePill'
+import type { BackgroundTask, FailedWorkerItem } from './types'
+
+export function ExpandedTaskPanel({
+  failedEmbeddingItems,
+  failedTaggingItems,
+  isWorkerPaused,
+  onDismiss,
+  onLocate,
+  onRetry,
+  onToggleWorker,
+  tasks,
+}: {
+  failedEmbeddingItems: Record<number, FailedWorkerItem[]>
+  failedTaggingItems: Record<number, FailedWorkerItem[]>
+  isWorkerPaused: (folderId: number, worker: WorkerKey) => boolean
+  onDismiss: (task: BackgroundTask) => void
+  onLocate: (folderId: number) => void
+  onRetry: (task: BackgroundTask) => void
+  onToggleWorker: (folderId: number, worker: WorkerKey) => void
+  tasks: BackgroundTask[]
+}) {
+  return (
+    <div className="space-y-3 border-t border-white/[0.06] bg-white/[0.02] px-5 py-3">
+      {tasks.map((task) => {
+        const progress = taskProgress(task)
+        const failed = taskHasTerminalFailure(task)
+
+        return (
+          <div key={task.id}>
+            <div className="flex items-center gap-3">
+              <span className="w-28 shrink-0 truncate text-[12px] text-white/50">{task.name}</span>
+
+              <div className="flex min-w-0 flex-1 items-center gap-1.5 overflow-hidden">
+                {task.stages.map((stage) => (
+                  <TaskStagePill
+                    key={stage.label}
+                    folderId={task.id}
+                    isWorkerPaused={isWorkerPaused}
+                    mutedWhenPaused
+                    onToggleWorker={onToggleWorker}
+                    stage={stage}
+                  />
+                ))}
+              </div>
+
+              <TaskProgressBar failed={failed} progress={progress} />
+
+              {failed ? <FailureActions onLocate={onLocate} onRetry={onRetry} task={task} /> : null}
+
+              <DismissTaskButton onDismiss={onDismiss} size="small" task={task} />
+            </div>
+
+            {task.currentFile ? (
+              <p className="mt-1 truncate pl-[calc(7rem+0.75rem)] text-[10px] text-gray-600">
+                {task.currentFile}
+              </p>
+            ) : null}
+
+            {failed && failedEmbeddingItems[task.id] && failedEmbeddingItems[task.id].length > 0 ? (
+              <div className="mt-2 space-y-0.5 pl-[calc(7rem+0.75rem)]">
+                {failedEmbeddingItems[task.id].map((item) => (
+                  <FailedWorkerItemRow key={item.image_id} item={item} />
+                ))}
+              </div>
+            ) : null}
+            {failed && failedTaggingItems[task.id] && failedTaggingItems[task.id].length > 0 ? (
+              <div className="mt-2 space-y-0.5 pl-[calc(7rem+0.75rem)]">
+                {failedTaggingItems[task.id].map((item) => (
+                  <FailedWorkerItemRow key={item.image_id} item={item} />
+                ))}
+              </div>
+            ) : null}
+          </div>
+        )
+      })}
+    </div>
+  )
+}

src/components/backgroundTasks/FailedWorkerItemRow.tsx

@@ -0,0 +1,36 @@
+import { revealItemInDir } from '@tauri-apps/plugin-opener'
+import { Tooltip } from '../Tooltip'
+import { WarningIcon } from '../icons'
+import type { FailedWorkerItem } from './types'
+
+export function FailedWorkerItemRow({ item }: { item: FailedWorkerItem }) {
+  return (
+    <div className="flex min-w-0 items-start gap-1.5">
+      <WarningIcon
+        className="light-theme:text-amber-700 mt-px h-2.5 w-2.5 shrink-0 text-amber-500"
+        strokeWidth={2.5}
+      />
+      <div className="min-w-0 flex-1">
+        <p className="light-theme:text-amber-700 truncate text-[10px] font-medium text-amber-400/80">
+          {item.filename}
+        </p>
+        {item.error ? <p className="truncate text-[9px] text-gray-600">{item.error}</p> : null}
+      </div>
+      <Tooltip label="Reveal in Explorer" anchorToCursor>
+        <button
+          className="light-theme:text-gray-600 light-theme:hover:text-gray-100 shrink-0 text-gray-700 transition-colors hover:text-gray-300"
+          onClick={() => void revealItemInDir(item.path)}
+        >
+          <svg className="h-3 w-3" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+            <path
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              strokeWidth={1.5}
+              d="M3 7a2 2 0 012-2h4l2 2h8a2 2 0 012 2v8a2 2 0 01-2 2H5a2 2 0 01-2-2V7z"
+            />
+          </svg>
+        </button>
+      </Tooltip>
+    </div>
+  )
+}

src/components/backgroundTasks/TaskProgressBar.tsx

@@ -0,0 +1,24 @@
+export function TaskProgressBar({
+  failed,
+  progress,
+  widthClass = 'w-20',
+}: {
+  failed: boolean
+  progress: number | null
+  widthClass?: string
+}) {
+  return (
+    <div className={`${widthClass} h-px shrink-0 overflow-hidden rounded-full bg-white/8`}>
+      <div
+        className={`h-full rounded-full transition-all duration-500 ${
+          failed
+            ? 'bg-amber-400/60'
+            : progress === null
+              ? 'w-full animate-pulse bg-blue-500/40'
+              : 'bg-blue-500'
+        }`}
+        style={progress !== null ? { width: `${progress}%` } : undefined}
+      />
+    </div>
+  )
+}

src/components/backgroundTasks/TaskStagePill.tsx

@@ -0,0 +1,71 @@
+import type { WorkerKey } from '../../store'
+import { Tooltip } from '../Tooltip'
+import { PlayIcon } from '../icons'
+import type { TaskStage } from './types'
+import { WORKER_FOR_STAGE } from './types'
+
+export function TaskStagePill({
+  folderId,
+  isWorkerPaused,
+  mutedWhenPaused = false,
+  onToggleWorker,
+  stage,
+}: {
+  folderId: number
+  isWorkerPaused: (folderId: number, worker: WorkerKey) => boolean
+  mutedWhenPaused?: boolean
+  onToggleWorker: (folderId: number, worker: WorkerKey) => void
+  stage: TaskStage
+}) {
+  const workerKey = WORKER_FOR_STAGE[stage.label]
+  const isPaused = workerKey ? isWorkerPaused(folderId, workerKey) : false
+
+  return (
+    <span
+      className={`flex shrink-0 items-center gap-1 rounded-md px-2 py-0.5 text-[11px] ${
+        stage.failed
+          ? 'light-theme:border light-theme:border-amber-500/40 light-theme:bg-amber-100 light-theme:text-amber-700 bg-amber-500/10 text-amber-400'
+          : isPaused
+            ? 'bg-white/4 text-gray-600'
+            : mutedWhenPaused
+              ? 'bg-white/5 text-gray-500'
+              : 'bg-white/5 text-gray-400'
+      }`}
+    >
+      {isPaused && mutedWhenPaused ? (
+        <svg className="h-2 w-2 text-gray-600" fill="currentColor" viewBox="0 0 24 24">
+          <path d="M6 19h4V5H6v14zm8-14v14h4V5h-4z" />
+        </svg>
+      ) : null}
+      <span>{stage.label}</span>
+      <span
+        className={`tabular-nums ${stage.failed ? 'light-theme:text-amber-700 text-amber-500' : isPaused && !mutedWhenPaused ? 'text-gray-700' : 'text-gray-600'}`}
+      >
+        {stage.detail}
+      </span>
+      {workerKey ? (
+        <Tooltip label={isPaused ? `Resume ${stage.label}` : `Pause ${stage.label}`} anchorToCursor>
+          <button
+            className={
+              mutedWhenPaused
+                ? 'ml-0.5 text-gray-600 transition-colors hover:text-white'
+                : 'ml-0.5 opacity-0 transition-opacity group-hover:opacity-100 hover:text-white'
+            }
+            onClick={(event) => {
+              event.stopPropagation()
+              onToggleWorker(folderId, workerKey)
+            }}
+          >
+            {isPaused ? (
+              <PlayIcon className="h-2.5 w-2.5" />
+            ) : (
+              <svg className="h-2.5 w-2.5" fill="currentColor" viewBox="0 0 24 24">
+                <path d="M6 19h4V5H6v14zm8-14v14h4V5h-4z" />
+              </svg>
+            )}
+          </button>
+        </Tooltip>
+      ) : null}
+    </span>
+  )
+}

src/components/backgroundTasks/taskModel.ts

@@ -0,0 +1,233 @@
+import type {
+  DuplicateScanProgress,
+  Folder,
+  FolderJobProgress,
+  IndexProgress,
+  WorkerKey,
+} from '../../store'
+import type { BackgroundTask, TaskStage } from './types'
+
+export function buildFolderTasks({
+  dismissed,
+  folders,
+  indexingProgress,
+  mediaJobProgress,
+  workerPaused,
+}: {
+  dismissed: Record<number, string>
+  folders: Folder[]
+  indexingProgress: Record<number, IndexProgress>
+  mediaJobProgress: Record<number, FolderJobProgress>
+  workerPaused: Record<number, Record<WorkerKey, boolean>>
+}): BackgroundTask[] {
+  return folders
+    .map((folder): BackgroundTask | null => {
+      const index = indexingProgress[folder.id]
+      const jobs = mediaJobProgress[folder.id]
+
+      const thumbnailPending = jobs?.thumbnail_pending ?? 0
+      const metadataPending = jobs?.metadata_pending ?? 0
+      const embeddingPending = jobs?.embedding_pending ?? 0
+      const embeddingReady = jobs?.embedding_ready ?? 0
+      const embeddingFailed = jobs?.embedding_failed ?? 0
+      const taggingPending = jobs?.tagging_pending ?? 0
+      const taggingReady = jobs?.tagging_ready ?? 0
+      const taggingFailed = jobs?.tagging_failed ?? 0
+      const captionPending = jobs?.caption_pending ?? 0
+      const captionReady = jobs?.caption_ready ?? 0
+      const captionFailed = jobs?.caption_failed ?? 0
+
+      const paused = workerPaused[folder.id]
+      const isActive =
+        (!!index && !index.done) ||
+        (thumbnailPending > 0 && !(paused?.thumbnail ?? false)) ||
+        (metadataPending > 0 && !(paused?.metadata ?? false)) ||
+        (embeddingPending > 0 && !(paused?.embedding ?? false)) ||
+        (taggingPending > 0 && !(paused?.tagging ?? false)) ||
+        captionPending > 0
+
+      const pendingMediaWork =
+        thumbnailPending + metadataPending + embeddingPending + taggingPending + captionPending
+      const embeddingProcessed = embeddingReady + embeddingFailed
+      const embeddingTotal = embeddingProcessed + embeddingPending
+      const taggingProcessed = taggingReady + taggingFailed
+      const taggingTotal = taggingProcessed + taggingPending
+      const captionProcessed = captionReady + captionFailed
+      const captionTotal = captionProcessed + captionPending
+      const hasFailedEmbeddings = embeddingFailed > 0
+      const hasFailedTagging = taggingFailed > 0
+      const hasFailedCaptions = captionFailed > 0
+
+      if (
+        !index &&
+        pendingMediaWork === 0 &&
+        !hasFailedEmbeddings &&
+        !hasFailedTagging &&
+        !hasFailedCaptions
+      )
+        return null
+
+      const stages: TaskStage[] = []
+
+      if (index && !index.done) {
+        stages.push({
+          label: 'Scanning',
+          detail: `${index.indexed.toLocaleString()} / ${index.total.toLocaleString()}`,
+          progress: index.total > 0 ? (index.indexed / index.total) * 100 : 0,
+          failed: false,
+        })
+      }
+
+      if (thumbnailPending > 0) {
+        stages.push({
+          label: 'Thumbnails',
+          detail: thumbnailPending.toLocaleString(),
+          progress: null,
+          failed: false,
+        })
+      }
+
+      if (metadataPending > 0) {
+        stages.push({
+          label: 'Metadata',
+          detail: metadataPending.toLocaleString(),
+          progress: null,
+          failed: false,
+        })
+      }
+
+      if (embeddingPending > 0) {
+        stages.push({
+          label: 'Embeddings',
+          detail: `${embeddingProcessed.toLocaleString()} / ${embeddingTotal.toLocaleString()}`,
+          progress: embeddingTotal > 0 ? (embeddingProcessed / embeddingTotal) * 100 : 0,
+          failed: false,
+        })
+      }
+
+      if (taggingPending > 0) {
+        stages.push({
+          label: 'Tags',
+          detail: `${taggingProcessed.toLocaleString()} / ${taggingTotal.toLocaleString()}`,
+          progress: taggingTotal > 0 ? (taggingProcessed / taggingTotal) * 100 : 0,
+          failed: false,
+        })
+      }
+
+      if (captionPending > 0) {
+        stages.push({
+          label: 'Captions',
+          detail: `${captionProcessed.toLocaleString()} / ${captionTotal.toLocaleString()}`,
+          progress: captionTotal > 0 ? (captionProcessed / captionTotal) * 100 : 0,
+          failed: false,
+        })
+      }
+
+      if (hasFailedEmbeddings && pendingMediaWork === 0) {
+        stages.push({
+          label: 'Failed',
+          detail: `${embeddingFailed.toLocaleString()} embeddings`,
+          progress: null,
+          failed: true,
+        })
+      }
+
+      if (hasFailedTagging && pendingMediaWork === 0) {
+        stages.push({
+          label: 'Failed',
+          detail: `${taggingFailed.toLocaleString()} tags`,
+          progress: null,
+          failed: true,
+        })
+      }
+
+      if (hasFailedCaptions && pendingMediaWork === 0) {
+        stages.push({
+          label: 'Failed',
+          detail: `${captionFailed.toLocaleString()} captions`,
+          progress: null,
+          failed: true,
+        })
+      }
+
+      const snapshot = `${pendingMediaWork}:${embeddingFailed}:${taggingFailed}:${captionFailed}`
+
+      return {
+        id: folder.id,
+        name: folder.name,
+        stages,
+        isActive,
+        hasFailedEmbeddings,
+        hasFailedTagging,
+        hasFailedCaptions,
+        pendingMediaWork,
+        embeddingProcessed,
+        embeddingTotal,
+        currentFile: index && !index.done ? index.current_file || null : null,
+        snapshot,
+      }
+    })
+    .filter((task): task is BackgroundTask => task !== null)
+    .filter((task) => dismissed[task.id] !== task.snapshot)
+    .sort((a, b) => Number(b.isActive) - Number(a.isActive))
+}
+
+export function buildDuplicateScanTask(
+  duplicateScanning: boolean,
+  duplicateScanProgress: DuplicateScanProgress | null
+): BackgroundTask | null {
+  if (!duplicateScanning) return null
+
+  return {
+    id: -1,
+    name: 'Duplicate Scan',
+    stages: [
+      {
+        label:
+          duplicateScanProgress?.phase === 'checking'
+            ? 'Checking'
+            : duplicateScanProgress?.phase === 'confirming'
+              ? 'Confirming'
+              : 'Hashing',
+        detail: duplicateScanProgress
+          ? `${duplicateScanProgress.processed.toLocaleString()} / ${duplicateScanProgress.total.toLocaleString()}${duplicateScanProgress.skipped > 0 ? ` · ${duplicateScanProgress.skipped.toLocaleString()} skipped` : ''}`
+          : 'Starting…',
+        progress:
+          duplicateScanProgress && duplicateScanProgress.total > 0
+            ? (duplicateScanProgress.processed / duplicateScanProgress.total) * 100
+            : null,
+        failed: false,
+      },
+    ],
+    isActive: true,
+    hasFailedEmbeddings: false,
+    hasFailedTagging: false,
+    hasFailedCaptions: false,
+    pendingMediaWork: 1,
+    embeddingProcessed: 0,
+    embeddingTotal: 0,
+    currentFile: null,
+    snapshot: '',
+  }
+}
+
+export function taskProgress(task: BackgroundTask): number | null {
+  const embeddingStage = task.stages.find((stage) => stage.label === 'Embeddings')
+  const taggingStage = task.stages.find((stage) => stage.label === 'Tags')
+  const scanningStage = task.stages.find((stage) => stage.label === 'Scanning')
+  const duplicateStage = task.id === -1 ? task.stages[0] : null
+  return (
+    embeddingStage?.progress ??
+    taggingStage?.progress ??
+    scanningStage?.progress ??
+    duplicateStage?.progress ??
+    null
+  )
+}
+
+export function taskHasTerminalFailure(task: BackgroundTask): boolean {
+  return (
+    (task.hasFailedEmbeddings || task.hasFailedTagging || task.hasFailedCaptions) &&
+    task.pendingMediaWork === 0
+  )
+}

src/components/backgroundTasks/types.ts

@@ -0,0 +1,37 @@
+import type { WorkerKey } from '../../store'
+
+export const WORKER_FOR_STAGE: Record<string, WorkerKey> = {
+  Thumbnails: 'thumbnail',
+  Metadata: 'metadata',
+  Embeddings: 'embedding',
+  Tags: 'tagging',
+}
+
+export interface TaskStage {
+  label: string
+  detail: string
+  progress: number | null
+  failed: boolean
+}
+
+export interface BackgroundTask {
+  id: number
+  name: string
+  stages: TaskStage[]
+  isActive: boolean
+  hasFailedEmbeddings: boolean
+  hasFailedTagging: boolean
+  hasFailedCaptions: boolean
+  pendingMediaWork: number
+  embeddingProcessed: number
+  embeddingTotal: number
+  currentFile: string | null
+  snapshot: string
+}
+
+export interface FailedWorkerItem {
+  image_id: number
+  filename: string
+  path: string
+  error: string | null
+}

src/components/bulk/BulkAlbumPopover.tsx

@@ -0,0 +1,16 @@
+import { AlbumPicker } from '../AlbumPicker'
+
+interface BulkAlbumPopoverProps {
+  onPick: (albumId: number) => Promise<void>
+}
+
+export function BulkAlbumPopover({ onPick }: BulkAlbumPopoverProps) {
+  return (
+    <div
+      data-bulk-popover
+      className="absolute bottom-full left-1/2 mb-2 w-60 -translate-x-1/2 rounded-xl border border-white/10 bg-gray-950/98 p-2 shadow-2xl backdrop-blur"
+    >
+      <AlbumPicker onPick={(albumId) => void onPick(albumId)} />
+    </div>
+  )
+}

src/components/bulk/BulkDeleteConfirm.tsx

@@ -0,0 +1,46 @@
+import { WarningIcon } from '../icons'
+
+interface BulkDeleteConfirmProps {
+  deleting: boolean
+  selectedCount: number
+  onCancel: () => void
+  onDelete: () => Promise<void>
+}
+
+export function BulkDeleteConfirm({
+  deleting,
+  selectedCount,
+  onCancel,
+  onDelete,
+}: BulkDeleteConfirmProps) {
+  return (
+    <div
+      data-bulk-popover
+      className="absolute bottom-full left-1/2 mb-2 w-64 -translate-x-1/2 rounded-xl border border-red-500/30 bg-gray-950/98 p-3 shadow-2xl backdrop-blur"
+    >
+      <div className="mb-1 flex items-center gap-1.5 text-red-300">
+        <WarningIcon className="h-3.5 w-3.5 shrink-0" />
+        <p className="text-xs font-semibold">Delete from disk</p>
+      </div>
+      <p className="mb-2.5 text-[11px] leading-relaxed text-gray-400">
+        Permanently delete {selectedCount} file{selectedCount === 1 ? '' : 's'} from your computer.
+        This removes the actual file{selectedCount === 1 ? '' : 's'} from disk and cannot be undone.
+      </p>
+      <div className="flex justify-end gap-1.5">
+        <button
+          className="rounded-md border border-white/10 bg-white/5 px-2.5 py-1 text-[11px] text-gray-300 transition-colors hover:bg-white/10 hover:text-white"
+          onClick={onCancel}
+        >
+          Cancel
+        </button>
+        <button
+          className="rounded-md bg-red-500/20 px-2.5 py-1 text-[11px] font-medium text-red-300 transition-colors hover:bg-red-500/30 hover:text-red-200 disabled:opacity-50"
+          onClick={() => void onDelete()}
+          disabled={deleting}
+        >
+          {deleting ? 'Deleting…' : `Delete ${selectedCount} from disk`}
+        </button>
+      </div>
+    </div>
+  )
+}

src/components/bulk/BulkRatingPopover.tsx

@@ -0,0 +1,41 @@
+import { Tooltip } from '../Tooltip'
+import { StarIcon } from '../icons'
+
+interface BulkRatingPopoverProps {
+  onClose: () => void
+  onSetRating: (rating: number) => Promise<void>
+}
+
+export function BulkRatingPopover({ onClose, onSetRating }: BulkRatingPopoverProps) {
+  const setRating = async (rating: number) => {
+    await onSetRating(rating)
+    onClose()
+  }
+
+  return (
+    <div
+      data-bulk-popover
+      className="absolute bottom-full left-1/2 mb-2 flex -translate-x-1/2 items-center gap-1 rounded-xl border border-white/10 bg-gray-950/98 p-2 shadow-2xl backdrop-blur"
+    >
+      {Array.from({ length: 5 }, (_, index) => {
+        const rating = index + 1
+        return (
+          <Tooltip key={rating} label={`Set ${rating} star${rating === 1 ? '' : 's'}`}>
+            <button
+              className="rounded-md p-1 text-white/25 transition-colors hover:bg-white/5 hover:text-amber-300"
+              onClick={() => void setRating(rating)}
+            >
+              <StarIcon className="h-4 w-4" />
+            </button>
+          </Tooltip>
+        )
+      })}
+      <button
+        className="ml-1 rounded-md border border-white/10 px-2 py-1 text-[11px] text-gray-400 transition-colors hover:bg-white/5 hover:text-white"
+        onClick={() => void setRating(0)}
+      >
+        Clear
+      </button>
+    </div>
+  )
+}

src/components/bulk/BulkSelectionSummary.tsx

@@ -0,0 +1,35 @@
+import { Tooltip } from '../Tooltip'
+
+interface BulkSelectionSummaryProps {
+  loadedCount: number
+  selectedCount: number
+  totalImages: number
+  onSelectAll: () => void
+}
+
+export function BulkSelectionSummary({
+  loadedCount,
+  selectedCount,
+  totalImages,
+  onSelectAll,
+}: BulkSelectionSummaryProps) {
+  const showSelectAll = loadedCount < totalImages || loadedCount > selectedCount
+
+  return (
+    <div className="flex items-center gap-2 px-1.5">
+      <span className="text-xs font-medium text-white">{selectedCount} selected</span>
+      {showSelectAll ? (
+        <Tooltip
+          label={loadedCount < totalImages ? 'Selects loaded items only' : 'Select all loaded'}
+        >
+          <button
+            className="text-[11px] text-gray-500 transition-colors hover:text-gray-300"
+            onClick={onSelectAll}
+          >
+            Select all{loadedCount < totalImages ? ' loaded' : ''}
+          </button>
+        </Tooltip>
+      ) : null}
+    </div>
+  )
+}

src/components/bulk/BulkTagFields.tsx

@@ -1,25 +1,26 @@
-import { useBulkTagEditor } from "./useBulkTagEditor";
-import { Tooltip } from "../Tooltip";
+import { useBulkTagEditor } from './useBulkTagEditor'
+import { Tooltip } from '../Tooltip'
+import { CloseIcon } from '../icons'
 
 // Presentational tag-editing fields shared by the popover and modal surfaces.
 export function BulkTagFields({ autoFocus = false }: { autoFocus?: boolean }) {
   const { selectedCount, input, setInput, suggestions, appliedTags, pending, addTag, removeTag } =
-    useBulkTagEditor();
+    useBulkTagEditor()
 
   return (
     <div className="space-y-2">
       <form
         className="flex gap-1.5"
         onSubmit={(event) => {
-          event.preventDefault();
-          void addTag(input);
+          event.preventDefault()
+          void addTag(input)
         }}
       >
         {/* eslint-disable-next-line jsx-a11y/no-autofocus */}
         <input
           autoFocus={autoFocus}
           className="min-w-0 flex-1 rounded-md border border-white/10 bg-white/5 px-2 py-1 text-xs text-white placeholder-gray-600 focus:border-white/20 focus:outline-none"
-          placeholder={`Add tag to ${selectedCount} item${selectedCount === 1 ? "" : "s"}…`}
+          placeholder={`Add tag to ${selectedCount} item${selectedCount === 1 ? '' : 's'}…`}
           value={input}
           onChange={(event) => setInput(event.target.value)}
           disabled={pending}
@@ -36,7 +37,11 @@ export function BulkTagFields({ autoFocus = false }: { autoFocus?: boolean }) {
       {suggestions.length > 0 ? (
         <div className="flex flex-wrap gap-1">
           {suggestions.map((suggestion) => (
-            <Tooltip key={suggestion.tag} label={`${suggestion.count.toLocaleString()} tagged`} anchorToCursor>
+            <Tooltip
+              key={suggestion.tag}
+              label={`${suggestion.count.toLocaleString()} tagged`}
+              anchorToCursor
+            >
               <button
                 className="rounded-md border border-white/10 bg-white/[0.03] px-2 py-0.5 text-[11px] text-gray-400 transition-colors hover:bg-white/10 hover:text-white"
                 onClick={() => void addTag(suggestion.tag)}
@@ -61,9 +66,7 @@ export function BulkTagFields({ autoFocus = false }: { autoFocus?: boolean }) {
                   className="text-gray-600 transition-colors hover:text-white"
                   onClick={() => void removeTag(tag)}
                 >
-                  <svg className="h-3 w-3" fill="none" viewBox="0 0 24 24" stroke="currentColor">
-                    <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M6 18L18 6M6 6l12 12" />
-                  </svg>
+                  <CloseIcon className="h-3 w-3" />
                 </button>
               </Tooltip>
             </span>
@@ -71,5 +74,5 @@ export function BulkTagFields({ autoFocus = false }: { autoFocus?: boolean }) {
         </div>
       ) : null}
     </div>
-  );
+  )
 }

src/components/bulk/BulkTagPopover.tsx

@@ -1,5 +1,6 @@
-import { BulkTagFields } from "./BulkTagFields";
-import { Tooltip } from "../Tooltip";
+import { BulkTagFields } from './BulkTagFields'
+import { Tooltip } from '../Tooltip'
+import { CloseIcon } from '../icons'
 
 // Inline popover surface for bulk tagging — the default editing surface.
 // Anchored above the bar by the parent; closes on outside click via the
@@ -12,19 +13,14 @@ export function BulkTagPopover({ onClose }: { onClose: () => void }) {
       onClick={(event) => event.stopPropagation()}
     >
       <div className="mb-2 flex items-center justify-between">
-        <p className="text-[11px] uppercase tracking-wider text-gray-500">Add tags</p>
+        <p className="text-[11px] tracking-wider text-gray-500 uppercase">Add tags</p>
         <Tooltip label="Close" anchorToCursor>
-          <button
-            className="text-gray-600 transition-colors hover:text-white"
-            onClick={onClose}
-          >
-            <svg className="h-3.5 w-3.5" fill="none" viewBox="0 0 24 24" stroke="currentColor">
-              <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M6 18L18 6M6 6l12 12" />
-            </svg>
+          <button className="text-gray-600 transition-colors hover:text-white" onClick={onClose}>
+            <CloseIcon className="h-3.5 w-3.5" />
           </button>
         </Tooltip>
       </div>
       <BulkTagFields autoFocus />
     </div>
-  );
+  )
 }

src/components/bulk/types.ts

@@ -0,0 +1 @@
+export type BulkPanel = 'tag' | 'rating' | 'album' | 'delete' | null

src/components/bulk/useBulkTagEditor.ts

@@ -1,73 +1,73 @@
-import { useCallback, useEffect, useRef, useState } from "react";
-import { invoke } from "@tauri-apps/api/core";
-import { ExploreTagEntry, useGalleryStore } from "../../store";
+import { useCallback, useEffect, useRef, useState } from 'react'
+import { invoke } from '@tauri-apps/api/core'
+import { ExploreTagEntry, useGalleryStore } from '../../store'
 
 // Shared logic for the bulk tag editor, consumed by both the inline popover and
 // the modal surface so they stay behaviorally identical.
 export function useBulkTagEditor() {
-  const selectedCount = useGalleryStore((state) => state.gallerySelectedIds.size);
-  const selectedFolderId = useGalleryStore((state) => state.selectedFolderId);
-  const bulkAddTags = useGalleryStore((state) => state.bulkAddTags);
-  const bulkRemoveTag = useGalleryStore((state) => state.bulkRemoveTag);
+  const selectedCount = useGalleryStore((state) => state.gallerySelectedIds.size)
+  const selectedFolderId = useGalleryStore((state) => state.selectedFolderId)
+  const bulkAddTags = useGalleryStore((state) => state.bulkAddTags)
+  const bulkRemoveTag = useGalleryStore((state) => state.bulkRemoveTag)
 
-  const [input, setInput] = useState("");
-  const [suggestions, setSuggestions] = useState<ExploreTagEntry[]>([]);
-  const [appliedTags, setAppliedTags] = useState<string[]>([]);
-  const [pending, setPending] = useState(false);
-  const debounceRef = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
-  const requestRef = useRef(0);
+  const [input, setInput] = useState('')
+  const [suggestions, setSuggestions] = useState<ExploreTagEntry[]>([])
+  const [appliedTags, setAppliedTags] = useState<string[]>([])
+  const [pending, setPending] = useState(false)
+  const debounceRef = useRef<ReturnType<typeof setTimeout> | undefined>(undefined)
+  const requestRef = useRef(0)
 
   useEffect(() => {
-    const query = input.trim();
+    const query = input.trim()
     if (!query) {
-      requestRef.current += 1;
-      setSuggestions([]);
-      return;
+      requestRef.current += 1
+      setSuggestions([])
+      return
     }
-    if (debounceRef.current) clearTimeout(debounceRef.current);
-    const requestId = ++requestRef.current;
+    if (debounceRef.current) clearTimeout(debounceRef.current)
+    const requestId = ++requestRef.current
     debounceRef.current = setTimeout(async () => {
       try {
-        const results = await invoke<ExploreTagEntry[]>("search_tags_autocomplete", {
+        const results = await invoke<ExploreTagEntry[]>('search_tags_autocomplete', {
           params: { query, folder_id: selectedFolderId ?? null, limit: 8 },
-        });
-        if (requestId !== requestRef.current) return;
-        setSuggestions(results);
+        })
+        if (requestId !== requestRef.current) return
+        setSuggestions(results)
       } catch {
-        if (requestId !== requestRef.current) return;
-        setSuggestions([]);
+        if (requestId !== requestRef.current) return
+        setSuggestions([])
       }
-    }, 120);
+    }, 120)
     return () => {
-      requestRef.current += 1;
-      if (debounceRef.current) clearTimeout(debounceRef.current);
-    };
-  }, [input, selectedFolderId]);
+      requestRef.current += 1
+      if (debounceRef.current) clearTimeout(debounceRef.current)
+    }
+  }, [input, selectedFolderId])
 
   const addTag = useCallback(
     async (raw: string) => {
-      const tag = raw.trim();
-      if (!tag || pending) return;
-      setPending(true);
+      const tag = raw.trim()
+      if (!tag || pending) return
+      setPending(true)
       try {
-        await bulkAddTags([tag]);
-        setAppliedTags((prev) => (prev.includes(tag) ? prev : [...prev, tag]));
-        setInput("");
-        setSuggestions([]);
+        await bulkAddTags([tag])
+        setAppliedTags((prev) => (prev.includes(tag) ? prev : [...prev, tag]))
+        setInput('')
+        setSuggestions([])
       } finally {
-        setPending(false);
+        setPending(false)
       }
     },
-    [bulkAddTags, pending],
-  );
+    [bulkAddTags, pending]
+  )
 
   const removeTag = useCallback(
     async (tag: string) => {
-      await bulkRemoveTag(tag);
-      setAppliedTags((prev) => prev.filter((entry) => entry !== tag));
+      await bulkRemoveTag(tag)
+      setAppliedTags((prev) => prev.filter((entry) => entry !== tag))
     },
-    [bulkRemoveTag],
-  );
+    [bulkRemoveTag]
+  )
 
-  return { selectedCount, input, setInput, suggestions, appliedTags, pending, addTag, removeTag };
+  return { selectedCount, input, setInput, suggestions, appliedTags, pending, addTag, removeTag }
 }

src/components/duplicateFinder/DuplicateFinderEmptyStates.tsx

@@ -0,0 +1,45 @@
+export function DuplicateScanLoadingState({ progressLabel }: { progressLabel: string | null }) {
+  return (
+    <div className="flex flex-1 items-center justify-center gap-3 text-white/25">
+      <div className="h-5 w-5 animate-spin rounded-full border-2 border-white/15 border-t-white/50" />
+      <span className="text-sm">{progressLabel ? `${progressLabel}…` : 'Preparing scan…'}</span>
+    </div>
+  )
+}
+
+export function DuplicateScanIntroState() {
+  return (
+    <div className="flex flex-1 items-center justify-center px-8">
+      <div className="max-w-sm text-center">
+        <svg
+          className="mx-auto mb-4 h-10 w-10 text-white/10"
+          fill="none"
+          viewBox="0 0 24 24"
+          stroke="currentColor"
+        >
+          <path
+            strokeLinecap="round"
+            strokeLinejoin="round"
+            strokeWidth={1}
+            d="M8 16H6a2 2 0 01-2-2V6a2 2 0 012-2h8a2 2 0 012 2v2m-6 12h8a2 2 0 002-2v-8a2 2 0 00-2-2h-8a2 2 0 00-2 2v8a2 2 0 002 2z"
+          />
+        </svg>
+        <p className="text-sm text-white/30">
+          Finds files with identical content regardless of filename or location. Click{' '}
+          <strong className="text-white/50">Scan for duplicates</strong> to begin.
+        </p>
+        <p className="mt-2 text-xs text-white/20">
+          Large libraries may take a minute — files are hashed from disk.
+        </p>
+      </div>
+    </div>
+  )
+}
+
+export function DuplicateScanEmptyState() {
+  return (
+    <div className="flex flex-1 items-center justify-center">
+      <p className="text-sm text-white/25">No duplicate files found.</p>
+    </div>
+  )
+}

src/components/duplicateFinder/DuplicateFinderHeader.tsx

@@ -0,0 +1,180 @@
+import { DuplicateGroup, DuplicateScanProgress } from '../../store'
+import { FolderScopeDropdown } from '../FolderScopeDropdown'
+import { Tooltip } from '../Tooltip'
+import { WarningIcon } from '../icons'
+import {
+  duplicateProgressLabel,
+  duplicateProgressPercent,
+  formatBytes,
+  formatRelativeTime,
+} from './format'
+
+export function DuplicateFinderHeader({
+  confirmingDelete,
+  deleteResult,
+  deleting,
+  duplicateGroups,
+  duplicateLastScanned,
+  duplicateScanError,
+  duplicateScanning,
+  duplicateScanProgress,
+  duplicateScanWarning,
+  hasResults,
+  hasScanned,
+  onClearSelection,
+  onConfirmDelete,
+  onDelete,
+  onScan,
+  onSelectKeepFirstAll,
+  selectedCount,
+  setConfirmingDelete,
+}: {
+  confirmingDelete: boolean
+  deleteResult: string | null
+  deleting: boolean
+  duplicateGroups: DuplicateGroup[]
+  duplicateLastScanned: number | null
+  duplicateScanError: string | null
+  duplicateScanning: boolean
+  duplicateScanProgress: DuplicateScanProgress | null
+  duplicateScanWarning: string | null
+  hasResults: boolean
+  hasScanned: boolean
+  onClearSelection: () => void
+  onConfirmDelete: () => void
+  onDelete: () => void
+  onScan: () => void
+  onSelectKeepFirstAll: () => void
+  selectedCount: number
+  setConfirmingDelete: (value: boolean | ((current: boolean) => boolean)) => void
+}) {
+  const totalWasted = duplicateGroups.reduce(
+    (sum, group) => sum + group.file_size * (group.images.length - 1),
+    0
+  )
+  const totalDuplicateImages = duplicateGroups.reduce(
+    (sum, group) => sum + group.images.length - 1,
+    0
+  )
+  const progressLabel = duplicateProgressLabel(duplicateScanProgress)
+  const progressPercent = duplicateProgressPercent(duplicateScanProgress)
+
+  return (
+    <div className="shrink-0 border-b border-white/[0.05] px-6 py-4">
+      <div className="flex items-center justify-between gap-4">
+        <div>
+          <h2 className="text-[15px] font-semibold text-white">Duplicate Finder</h2>
+          <p className="mt-0.5 text-[11px] text-white/30">
+            {duplicateScanning
+              ? duplicateScanProgress
+                ? `${progressLabel}… ${duplicateScanProgress.processed.toLocaleString()} / ${duplicateScanProgress.total.toLocaleString()}${duplicateScanProgress.skipped > 0 ? ` · ${duplicateScanProgress.skipped.toLocaleString()} skipped` : ''}`
+                : 'Starting scan…'
+              : hasResults
+                ? `${duplicateGroups.length} group${duplicateGroups.length === 1 ? '' : 's'} · ${formatBytes(totalWasted)} reclaimable`
+                : duplicateLastScanned !== null
+                  ? 'No duplicates found'
+                  : 'Scan your library for identical files'}
+          </p>
+          {!duplicateScanning && duplicateLastScanned !== null ? (
+            <p className="mt-0.5 text-[10px] text-white/20">
+              Last scanned {formatRelativeTime(duplicateLastScanned)}
+            </p>
+          ) : null}
+        </div>
+        <div className="flex items-center gap-2">
+          <FolderScopeDropdown />
+          {hasResults && selectedCount === 0 && !deleting ? (
+            <Tooltip
+              label={`Mark ${totalDuplicateImages} duplicate${totalDuplicateImages === 1 ? '' : 's'} for deletion across all groups (keeps first in each)`}
+              anchorToCursor
+            >
+              <button
+                className="light-theme:border-gray-700/50 light-theme:bg-gray-900 light-theme:text-white light-theme:hover:bg-gray-800 light-theme:hover:text-white rounded-lg border border-white/10 bg-white/[0.04] px-3 py-1.5 text-xs text-gray-400 transition-colors hover:bg-white/[0.07] hover:text-white"
+                onClick={onSelectKeepFirstAll}
+              >
+                Select all duplicates
+              </button>
+            </Tooltip>
+          ) : null}
+          {selectedCount > 0 ? (
+            <>
+              <span className="text-[11px] text-white/40">{selectedCount} marked for deletion</span>
+              <button
+                className="light-theme:border-gray-700/50 light-theme:bg-gray-900 light-theme:text-white light-theme:hover:bg-gray-800 light-theme:hover:text-white rounded-lg border border-white/10 bg-white/[0.04] px-3 py-1.5 text-xs text-gray-400 transition-colors hover:bg-white/[0.07] hover:text-white disabled:opacity-40"
+                onClick={onClearSelection}
+                disabled={deleting}
+              >
+                Deselect all
+              </button>
+              <div className="relative">
+                <button
+                  className="rounded-lg border border-red-400/25 bg-red-500/10 px-3 py-1.5 text-xs text-red-300 transition-colors hover:bg-red-500/15 disabled:cursor-not-allowed disabled:opacity-40"
+                  onClick={() => setConfirmingDelete((value) => !value)}
+                  disabled={deleting}
+                >
+                  {deleting
+                    ? 'Deleting…'
+                    : `Delete ${selectedCount} file${selectedCount === 1 ? '' : 's'}`}
+                </button>
+                {confirmingDelete && !deleting ? (
+                  <>
+                    <div className="fixed inset-0 z-40" onClick={onConfirmDelete} />
+                    <div className="absolute top-full right-0 z-50 mt-2 w-72 rounded-xl border border-red-500/30 bg-gray-950/98 p-3 text-left shadow-2xl backdrop-blur">
+                      <div className="mb-1 flex items-center gap-1.5 text-red-300">
+                        <WarningIcon className="h-3.5 w-3.5 shrink-0" />
+                        <p className="text-xs font-semibold">Delete from disk</p>
+                      </div>
+                      <p className="mb-2.5 text-[11px] leading-relaxed text-gray-400">
+                        Permanently delete {selectedCount} file{selectedCount === 1 ? '' : 's'} from
+                        your computer. This removes the actual file{selectedCount === 1 ? '' : 's'}{' '}
+                        from disk and cannot be undone.
+                      </p>
+                      <div className="flex justify-end gap-1.5">
+                        <button
+                          className="rounded-md border border-white/10 bg-white/5 px-2.5 py-1 text-[11px] text-gray-300 transition-colors hover:bg-white/10 hover:text-white"
+                          onClick={onConfirmDelete}
+                        >
+                          Cancel
+                        </button>
+                        <button
+                          className="rounded-md bg-red-500/20 px-2.5 py-1 text-[11px] font-medium text-red-300 transition-colors hover:bg-red-500/30 hover:text-red-200"
+                          onClick={onDelete}
+                        >
+                          Delete {selectedCount} from disk
+                        </button>
+                      </div>
+                    </div>
+                  </>
+                ) : null}
+              </div>
+            </>
+          ) : null}
+          <button
+            className="light-theme:border-gray-700/50 light-theme:bg-gray-900 light-theme:text-white light-theme:hover:bg-gray-800 light-theme:hover:text-white rounded-lg border border-white/10 bg-white/[0.055] px-3 py-1.5 text-xs text-gray-300 transition-colors hover:bg-white/10 hover:text-white disabled:cursor-not-allowed disabled:opacity-40"
+            onClick={onScan}
+            disabled={duplicateScanning}
+          >
+            {duplicateScanning ? 'Scanning…' : hasScanned ? 'Rescan' : 'Scan for duplicates'}
+          </button>
+        </div>
+      </div>
+
+      {duplicateScanning && duplicateScanProgress ? (
+        <div className="mt-3 h-px overflow-hidden rounded-full bg-white/[0.07]">
+          <div
+            className="h-full rounded-full bg-blue-500/60 transition-[width] duration-200"
+            style={{ width: `${progressPercent}%` }}
+          />
+        </div>
+      ) : null}
+
+      {duplicateScanError ? (
+        <p className="mt-2 text-[11px] text-red-400/80">{duplicateScanError}</p>
+      ) : null}
+      {duplicateScanWarning ? (
+        <p className="mt-2 text-[11px] text-amber-300/70">{duplicateScanWarning}</p>
+      ) : null}
+      {deleteResult ? <p className="mt-2 text-[11px] text-white/40">{deleteResult}</p> : null}
+    </div>
+  )
+}

src/components/duplicateFinder/DuplicateGroupCard.tsx

@@ -0,0 +1,107 @@
+import { DuplicateGroup, useGalleryStore } from '../../store'
+import { mediaSrc } from '../../lib/mediaSrc'
+import { Tooltip } from '../Tooltip'
+import { formatBytes } from './format'
+
+export function DuplicateGroupCard({ group }: { group: DuplicateGroup }) {
+  const selectedIds = useGalleryStore((state) => state.duplicateSelectedIds)
+  const toggleDuplicateSelected = useGalleryStore((state) => state.toggleDuplicateSelected)
+  const selectAllDuplicates = useGalleryStore((state) => state.selectAllDuplicates)
+  const groupSelectedCount = group.images.filter((image) => selectedIds.has(image.id)).length
+  const noneSelected = groupSelectedCount === 0
+
+  const handleKeepFirst = () => {
+    const toDelete = group.images.slice(1).map((image) => image.id)
+    for (const image of group.images) {
+      if (selectedIds.has(image.id)) toggleDuplicateSelected(image.id)
+    }
+    selectAllDuplicates(toDelete)
+  }
+
+  const handleDeselectGroup = () => {
+    for (const image of group.images) {
+      if (selectedIds.has(image.id)) toggleDuplicateSelected(image.id)
+    }
+  }
+
+  return (
+    <div className="rounded-2xl border border-white/[0.07] bg-white/[0.02] p-4">
+      <div className="mb-3 flex items-center justify-between gap-3">
+        <div className="flex items-center gap-2">
+          <span className="rounded-md border border-white/10 bg-white/[0.04] px-2 py-0.5 text-[11px] text-gray-400">
+            {group.images.length} copies
+          </span>
+          <span className="text-[11px] text-white/30">{formatBytes(group.file_size)} each</span>
+          <span className="text-[11px] text-white/20">
+            {formatBytes(group.file_size * (group.images.length - 1))} wasted
+          </span>
+        </div>
+        <div className="flex items-center gap-2">
+          {noneSelected ? (
+            <button
+              className="text-[11px] text-white/35 transition-colors hover:text-white/70"
+              onClick={handleKeepFirst}
+            >
+              Keep first
+            </button>
+          ) : (
+            <button
+              className="text-[11px] text-white/35 transition-colors hover:text-white/70"
+              onClick={handleDeselectGroup}
+            >
+              Deselect all
+            </button>
+          )}
+        </div>
+      </div>
+
+      <div className="flex flex-wrap gap-3">
+        {group.images.map((image) => {
+          const isSelected = selectedIds.has(image.id)
+          const src = mediaSrc(image.thumbnail_path)
+          return (
+            <Tooltip key={image.id} label={image.path} anchorToCursor>
+              <button
+                className={`media-dark-surface group relative overflow-hidden rounded-xl border transition-all ${
+                  isSelected
+                    ? 'border-red-400/50 ring-1 ring-red-400/30'
+                    : 'border-white/8 hover:border-white/20'
+                }`}
+                style={{ width: 140, height: 105 }}
+                onClick={() => toggleDuplicateSelected(image.id)}
+              >
+                {src ? (
+                  <img src={src} alt="" className="h-full w-full object-cover" draggable={false} />
+                ) : (
+                  <div className="h-full w-full bg-white/[0.03]" />
+                )}
+                {isSelected ? (
+                  <div className="absolute inset-0 flex items-center justify-center bg-red-950/60">
+                    <svg
+                      className="h-6 w-6 text-red-300"
+                      fill="none"
+                      viewBox="0 0 24 24"
+                      stroke="currentColor"
+                    >
+                      <path
+                        strokeLinecap="round"
+                        strokeLinejoin="round"
+                        strokeWidth={2}
+                        d="M19 7l-.867 12.142A2 2 0 0116.138 21H7.862a2 2 0 01-1.995-1.858L5 7m5 4v6m4-6v6m1-10V4a1 1 0 00-1-1h-4a1 1 0 00-1 1v3M4 7h16"
+                      />
+                    </svg>
+                  </div>
+                ) : null}
+                <div className="absolute inset-x-0 bottom-0 bg-gradient-to-t from-black/90 to-transparent px-2 pt-4 pb-1.5 opacity-0 transition-opacity group-hover:opacity-100">
+                  <p className="truncate text-[9px] text-white/60">
+                    {image.path.split(/[\\/]/).slice(-2).join('/')}
+                  </p>
+                </div>
+              </button>
+            </Tooltip>
+          )
+        })}
+      </div>
+    </div>
+  )
+}

src/components/duplicateFinder/format.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, it } from 'vitest'
+import type { DuplicateScanProgress } from '../../store'
+import {
+  duplicateProgressLabel,
+  duplicateProgressPercent,
+  formatBytes,
+  formatRelativeTime,
+} from './format'
+
+function progress(overrides: Partial<DuplicateScanProgress> = {}): DuplicateScanProgress {
+  return { phase: 'checking', processed: 0, total: 0, skipped: 0, ...overrides }
+}
+
+describe('formatBytes', () => {
+  it('formats each size tier', () => {
+    expect(formatBytes(0)).toBe('0 B')
+    expect(formatBytes(512)).toBe('512 B')
+    expect(formatBytes(2048)).toBe('2 KB')
+    expect(formatBytes(1_048_576)).toBe('1.0 MB')
+    expect(formatBytes(1_610_612_736)).toBe('1.5 GB')
+  })
+})
+
+describe('formatRelativeTime', () => {
+  const now = () => Math.floor(Date.now() / 1000)
+
+  it('formats each time bucket', () => {
+    expect(formatRelativeTime(now())).toBe('just now')
+    expect(formatRelativeTime(now() - 120)).toBe('2m ago')
+    expect(formatRelativeTime(now() - 7200)).toBe('2h ago')
+    expect(formatRelativeTime(now() - 172_800)).toBe('2d ago')
+  })
+})
+
+describe('duplicateProgressLabel', () => {
+  it('returns null without progress', () => {
+    expect(duplicateProgressLabel(null)).toBeNull()
+  })
+
+  it('labels each phase', () => {
+    expect(duplicateProgressLabel(progress({ phase: 'checking' }))).toBe('Checking file sizes')
+    expect(duplicateProgressLabel(progress({ phase: 'hashing' }))).toBe(
+      'Hashing duplicate candidates'
+    )
+    expect(duplicateProgressLabel(progress({ phase: 'confirming' }))).toBe(
+      'Confirming exact matches'
+    )
+  })
+})
+
+describe('duplicateProgressPercent', () => {
+  it('returns 0 for missing progress or zero totals', () => {
+    expect(duplicateProgressPercent(null)).toBe(0)
+    expect(duplicateProgressPercent(progress({ processed: 5, total: 0 }))).toBe(0)
+  })
+
+  it('rounds to whole percent', () => {
+    expect(duplicateProgressPercent(progress({ processed: 50, total: 200 }))).toBe(25)
+    expect(duplicateProgressPercent(progress({ processed: 1, total: 3 }))).toBe(33)
+  })
+})

src/components/duplicateFinder/format.ts

@@ -0,0 +1,29 @@
+import { DuplicateScanProgress } from '../../store'
+
+export function formatBytes(bytes: number): string {
+  if (bytes >= 1_073_741_824) return `${(bytes / 1_073_741_824).toFixed(1)} GB`
+  if (bytes >= 1_048_576) return `${(bytes / 1_048_576).toFixed(1)} MB`
+  if (bytes >= 1024) return `${(bytes / 1024).toFixed(0)} KB`
+  return `${bytes} B`
+}
+
+export function formatRelativeTime(unixSecs: number): string {
+  const diff = Math.floor(Date.now() / 1000) - unixSecs
+  if (diff < 60) return 'just now'
+  if (diff < 3600) return `${Math.floor(diff / 60)}m ago`
+  if (diff < 86400) return `${Math.floor(diff / 3600)}h ago`
+  return `${Math.floor(diff / 86400)}d ago`
+}
+
+export function duplicateProgressLabel(progress: DuplicateScanProgress | null): string | null {
+  if (!progress) return null
+  if (progress.phase === 'checking') return 'Checking file sizes'
+  if (progress.phase === 'hashing') return 'Hashing duplicate candidates'
+  return 'Confirming exact matches'
+}
+
+export function duplicateProgressPercent(progress: DuplicateScanProgress | null): number {
+  return progress && progress.total > 0
+    ? Math.round((progress.processed / progress.total) * 100)
+    : 0
+}

src/components/explore/ClusterCloud.tsx

@@ -0,0 +1,281 @@
+import { useLayoutEffect, useMemo, useRef, useState } from 'react'
+import { motion, useReducedMotion } from 'framer-motion'
+import type { VisualClusterEntry } from '../../store'
+import { mediaSrc } from '../../lib/mediaSrc'
+import { Tooltip } from '../Tooltip'
+import { ACCENTS, GOLDEN_ANGLE, seeded } from './layout'
+
+interface PlacedNode {
+  entry: VisualClusterEntry
+  index: number
+  x: number
+  y: number
+  w: number
+  h: number
+  zIndex: number
+  accent: string
+  driftX: number
+  driftY: number
+  driftDuration: number
+  rotateSeed: number
+}
+
+function buildCloud(
+  entries: VisualClusterEntry[],
+  containerW: number,
+  containerH: number
+): PlacedNode[] {
+  if (!entries.length || containerW <= 0 || containerH <= 0) return []
+
+  const maxCount = Math.max(...entries.map((e) => e.count))
+  const cx = containerW / 2
+  const cy = containerH / 2
+  const n = entries.length
+  const ASPECT = 0.72
+  const PAD = 18
+
+  // Card width scales with image count; the sub-linear exponent (< 1) widens the
+  // gap so the busiest clusters read as clearly larger and more prominent.
+  const rawWidth = (count: number) => {
+    const ratio = Math.max(count / maxCount, 0.05)
+    return 92 + Math.pow(ratio, 0.65) * 158 // ~92–250px before fit scaling
+  }
+
+  // Shrink every card uniformly when their padded footprint can't fit the
+  // canvas, so overlap resolution can actually pull them apart instead of
+  // settling into a pile. (0.6 leaves headroom for imperfect packing.)
+  const totalArea = entries.reduce((sum, e) => {
+    const w = rawWidth(e.count)
+    return sum + (w + PAD) * (w * ASPECT + PAD)
+  }, 0)
+  const usableArea = containerW * containerH * 0.6
+  const fit = totalArea > usableArea ? Math.sqrt(usableArea / totalArea) : 1
+
+  const spreadX = containerW * 0.44
+  const spreadY = containerH * 0.4
+
+  // 1. Seed positions on a phyllotaxis spiral, sized by count.
+  const nodes: PlacedNode[] = entries.map((entry, i) => {
+    const w = rawWidth(entry.count) * fit
+    const h = w * ASPECT
+    const radialRatio = Math.sqrt((i + 0.5) / n)
+    const angle = i * GOLDEN_ANGLE
+
+    return {
+      entry,
+      index: i,
+      x: cx + Math.cos(angle) * radialRatio * spreadX,
+      y: cy + Math.sin(angle) * radialRatio * spreadY,
+      w,
+      h,
+      // Bigger (busier) clusters stack above smaller ones, so they stay
+      // clickable even if a sliver of overlap survives.
+      zIndex: Math.round(w),
+      accent: ACCENTS[i % ACCENTS.length],
+      driftX: (seeded(i + 11) - 0.5) * 18,
+      driftY: (seeded(i + 17) - 0.5) * 14,
+      driftDuration: 8 + seeded(i + 23) * 7,
+      rotateSeed: (seeded(i + 31) - 0.5) * 4,
+    }
+  })
+
+  // 2. Resolve overlaps by pushing pairs apart, clamping inside the canvas every
+  //    pass so edge cards settle in-bounds instead of being shoved out and
+  //    re-overlapping there.
+  const marginX = 14
+  const marginY = 14
+  for (let iter = 0; iter < 160; iter++) {
+    for (let a = 0; a < nodes.length; a++) {
+      const na = nodes[a]
+      for (let b = a + 1; b < nodes.length; b++) {
+        const nb = nodes[b]
+        const dx = nb.x - na.x
+        const dy = nb.y - na.y
+        const overlapX = (na.w + nb.w) / 2 + PAD - Math.abs(dx)
+        const overlapY = (na.h + nb.h) / 2 + PAD - Math.abs(dy)
+        if (overlapX <= 0 || overlapY <= 0) continue
+        // Push along the smaller overlap axis (ternary yields ±1 so coincident
+        // cards still separate rather than stalling at a zero push).
+        if (overlapX < overlapY) {
+          const push = (overlapX / 2) * (dx >= 0 ? 1 : -1)
+          nb.x += push
+          na.x -= push
+        } else {
+          const push = (overlapY / 2) * (dy >= 0 ? 1 : -1)
+          nb.y += push
+          na.y -= push
+        }
+      }
+    }
+    for (const node of nodes) {
+      node.x = Math.min(Math.max(node.x, node.w / 2 + marginX), containerW - node.w / 2 - marginX)
+      node.y = Math.min(Math.max(node.y, node.h / 2 + marginY), containerH - node.h / 2 - marginY)
+    }
+  }
+
+  return nodes
+}
+
+function CloudCard({
+  node,
+  onOpen,
+  animated,
+}: {
+  node: PlacedNode
+  onOpen: (imageIds: number[]) => void
+  animated: boolean
+}) {
+  const src = mediaSrc(node.entry.thumbnail_path)
+  const { w, h, accent } = node
+  const driftTransition = {
+    duration: node.driftDuration,
+    ease: 'easeInOut' as const,
+    delay: seeded(node.index + 41) * 1.6,
+    repeat: 1,
+    repeatType: 'reverse' as const,
+  }
+
+  return (
+    <Tooltip
+      label={`Open cluster — ${node.entry.count.toLocaleString()} ${node.entry.count === 1 ? 'image' : 'images'}`}
+      followCursor
+    >
+      <motion.button
+        className="explore-cluster-card group absolute overflow-hidden rounded-2xl border border-white/8 bg-white/[0.04] text-left shadow-[0_8px_28px_rgba(0,0,0,0.38)] focus:outline-none focus-visible:ring-2 focus-visible:ring-white/30"
+        style={{
+          width: w,
+          height: h,
+          left: node.x - w / 2,
+          top: node.y - h / 2,
+          zIndex: node.zIndex,
+        }}
+        initial={
+          animated
+            ? { opacity: 0, scale: 0.82, rotate: node.rotateSeed }
+            : { opacity: 0, scale: 0.96 }
+        }
+        animate={
+          animated
+            ? {
+                opacity: 1,
+                scale: 1,
+                x: [0, node.driftX * 0.65, 0],
+                y: [0, node.driftY * 0.65, 0],
+                rotate: [node.rotateSeed, node.rotateSeed + 0.8, node.rotateSeed],
+              }
+            : { opacity: 1, scale: 1, rotate: node.rotateSeed }
+        }
+        transition={
+          animated
+            ? {
+                opacity: { duration: 0.24, delay: Math.min(node.index * 0.024, 0.45) },
+                scale: { duration: 0.24, delay: Math.min(node.index * 0.024, 0.45) },
+                x: driftTransition,
+                y: {
+                  ...driftTransition,
+                  duration: node.driftDuration + 1.2,
+                  delay: seeded(node.index + 51) * 1.6,
+                },
+                rotate: {
+                  ...driftTransition,
+                  duration: node.driftDuration + 0.8,
+                  delay: seeded(node.index + 61) * 1.2,
+                },
+              }
+            : {
+                opacity: { duration: 0.18, delay: Math.min(node.index * 0.016, 0.28) },
+                scale: { duration: 0.18, delay: Math.min(node.index * 0.016, 0.28) },
+              }
+        }
+        whileHover={{ scale: 1.06, rotate: 0, zIndex: 500, transition: { duration: 0.18 } }}
+        onClick={() => onOpen(node.entry.image_ids)}
+      >
+        {src ? (
+          <img
+            src={src}
+            alt=""
+            className="absolute inset-0 h-full w-full object-cover transition-transform duration-500 group-hover:scale-105"
+            draggable={false}
+            loading="lazy"
+            decoding="async"
+          />
+        ) : (
+          <div className="absolute inset-0 bg-gradient-to-br from-white/[0.07] to-transparent" />
+        )}
+        <div className="explore-cluster-overlay absolute inset-0 bg-gradient-to-t from-black/85 via-black/20 to-transparent" />
+        {/* Accent glow on hover */}
+        <div
+          className="absolute inset-0 opacity-0 transition-opacity duration-300 group-hover:opacity-100"
+          style={{ background: `radial-gradient(ellipse at bottom, ${accent}25, transparent 70%)` }}
+        />
+        <div className="absolute inset-x-0 bottom-0 p-3">
+          <div
+            className="explore-cluster-rule mb-2 h-px rounded-full"
+            style={{ background: `linear-gradient(to right, ${accent}80, transparent)` }}
+          />
+          <p className="explore-cluster-label text-[9px] tracking-[0.18em] text-white/35 uppercase">
+            Cluster
+          </p>
+          <p className="explore-cluster-count text-base leading-none font-semibold text-white">
+            {node.entry.count.toLocaleString()}
+          </p>
+        </div>
+        {/* Anchored to the card corner (not in the count's flex row) so a wide
+          count can't push it past the edge on small cards. */}
+        <span
+          className="explore-cluster-open absolute right-3 bottom-3 rounded-full border px-2 py-0.5 text-[9px] tracking-[0.1em] uppercase opacity-0 transition-opacity duration-200 group-hover:opacity-100"
+          style={{ borderColor: `${accent}50`, color: accent, backgroundColor: `${accent}12` }}
+        >
+          Open
+        </span>
+      </motion.button>
+    </Tooltip>
+  )
+}
+
+// Separate component so its useLayoutEffect fires when the canvas is actually
+// mounted, not at ExploreView mount time when the container may still be hidden
+// behind a loading state.
+export function ClusterCloud({
+  entries,
+  onOpen,
+}: {
+  entries: VisualClusterEntry[]
+  onOpen: (imageIds: number[]) => void
+}) {
+  const reducedMotion = useReducedMotion()
+  const canvasRef = useRef<HTMLDivElement>(null)
+  const [canvasSize, setCanvasSize] = useState({ w: 0, h: 0 })
+
+  useLayoutEffect(() => {
+    const el = canvasRef.current
+    if (!el) return
+    const update = () => {
+      const r = el.getBoundingClientRect()
+      setCanvasSize({ w: r.width, h: r.height })
+    }
+    update()
+    const ro = new ResizeObserver(update)
+    ro.observe(el)
+    return () => ro.disconnect()
+  }, [])
+
+  const nodes = useMemo(
+    () => buildCloud(entries, canvasSize.w, canvasSize.h),
+    [entries, canvasSize.w, canvasSize.h]
+  )
+
+  return (
+    <div ref={canvasRef} className="relative isolate min-h-0 flex-1 overflow-hidden">
+      <div className="explore-cluster-grid pointer-events-none absolute inset-0 [background-image:radial-gradient(circle,rgba(255,255,255,0.6)_1px,transparent_1px)] [background-size:28px_28px] opacity-[0.07]" />
+      {nodes.map((node) => (
+        <CloudCard
+          key={`${node.entry.representative_image_id}:${node.index}`}
+          node={node}
+          onOpen={onOpen}
+          animated={!reducedMotion && node.index < 12}
+        />
+      ))}
+    </div>
+  )
+}

src/components/explore/ExploreLoadingPanel.tsx

@@ -0,0 +1,39 @@
+import { motion } from 'framer-motion'
+import type { ExploreMode } from '../../store'
+
+function Spinner() {
+  return (
+    <motion.div
+      className="explore-spinner h-5 w-5 rounded-full border-2 border-white/15 border-t-white/50"
+      animate={{ rotate: 360 }}
+      transition={{ duration: 0.85, repeat: Infinity, ease: 'linear' }}
+    />
+  )
+}
+
+export function ExploreLoadingPanel({ mode }: { mode: ExploreMode }) {
+  const title = mode === 'visual' ? 'Building visual clusters' : 'Reading tag frequencies'
+  const subtitle =
+    mode === 'visual'
+      ? 'Grouping similar images into browsable clusters.'
+      : 'Collecting tags from the current library scope.'
+
+  return (
+    <div className="flex flex-1 items-center justify-center px-8">
+      <div className="flex max-w-sm flex-col items-center text-center">
+        <div className="mb-4 flex items-center justify-center gap-3 text-white/65">
+          <Spinner />
+          <span className="text-sm font-medium">{title}</span>
+        </div>
+        <p className="text-sm leading-relaxed text-white/25">{subtitle}</p>
+        <div className="mt-6 h-px w-40 overflow-hidden rounded-full bg-white/[0.06]">
+          <motion.div
+            className="h-full w-16 rounded-full bg-white/25"
+            animate={{ x: [-72, 184] }}
+            transition={{ duration: 1.4, repeat: Infinity, ease: 'easeInOut' }}
+          />
+        </div>
+      </div>
+    </div>
+  )
+}

src/components/explore/TagAtlas.tsx

@@ -0,0 +1,390 @@
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react'
+import { motion, useReducedMotion } from 'framer-motion'
+import type { ExploreTagEntry, RelatedTagEntry } from '../../store'
+import { useGalleryStore } from '../../store'
+import { Tooltip } from '../Tooltip'
+import { ACCENTS, GOLDEN_ANGLE, LIGHT_ACCENTS, seeded } from './layout'
+
+interface AtlasNode {
+  entry: ExploreTagEntry
+  index: number
+  x: number
+  y: number
+  w: number
+  h: number
+  fontSize: number
+  ratio: number
+  accent: string
+  driftX: number
+  driftY: number
+}
+
+interface TagAnchor {
+  x: number
+  y: number
+}
+
+export const TAG_ATLAS_MAX_VISIBLE = 132
+const TAG_ATLAS_DENSE_THRESHOLD = 120
+
+function buildTagAtlas(
+  entries: ExploreTagEntry[],
+  containerW: number,
+  containerH: number,
+  isLight: boolean
+): AtlasNode[] {
+  if (!entries.length || containerW <= 0 || containerH <= 0) return []
+
+  const logs = entries.map((entry) => Math.log(Math.max(entry.count, 1)))
+  const logMin = Math.min(...logs)
+  const logRange = Math.max(...logs) - logMin || 1
+  const cx = containerW / 2
+  const cy = containerH * 0.48
+  const spreadX = containerW * 0.47
+  const spreadY = containerH * 0.46
+  const accents = isLight ? LIGHT_ACCENTS : ACCENTS
+
+  const nodes = entries.map((entry, index) => {
+    const ratio = (Math.log(Math.max(entry.count, 1)) - logMin) / logRange
+    const densityScale = entries.length > TAG_ATLAS_DENSE_THRESHOLD ? 0.94 : 1
+    const fontSize = (9.75 + Math.pow(ratio, 0.92) * 19.5) * densityScale
+    const maxWidthRatio = index < 48 ? 0.32 : index < 100 ? 0.26 : 0.2
+    const textWidth = entry.tag.length * fontSize * 0.5 + (ratio > 0.55 ? 36 : 26)
+    const w = Math.min(containerW * maxWidthRatio, textWidth)
+    const h = fontSize * 1.18 + 14
+    const radialRatio = Math.sqrt((index + 0.5) / entries.length)
+    const angle = index * GOLDEN_ANGLE
+    return {
+      entry,
+      index,
+      x: cx + Math.cos(angle) * radialRatio * spreadX,
+      y: cy + Math.sin(angle) * radialRatio * spreadY,
+      w,
+      h,
+      fontSize,
+      ratio,
+      accent: accents[index % accents.length],
+      driftX: (seeded(index + 101) - 0.5) * 7,
+      driftY: (seeded(index + 113) - 0.5) * 6,
+    }
+  })
+
+  const padX = entries.length > TAG_ATLAS_DENSE_THRESHOLD ? 4 : 10
+  const padY = entries.length > TAG_ATLAS_DENSE_THRESHOLD ? 3 : 7
+  const margin = 28
+  for (let iter = 0; iter < 140; iter++) {
+    for (let a = 0; a < nodes.length; a++) {
+      const na = nodes[a]
+      for (let b = a + 1; b < nodes.length; b++) {
+        const nb = nodes[b]
+        const dx = nb.x - na.x
+        const dy = nb.y - na.y
+        const overlapX = (na.w + nb.w) / 2 + padX - Math.abs(dx)
+        const overlapY = (na.h + nb.h) / 2 + padY - Math.abs(dy)
+        if (overlapX <= 0 || overlapY <= 0) continue
+        if (overlapX < overlapY) {
+          const push = (overlapX / 2) * (dx >= 0 ? 1 : -1)
+          nb.x += push
+          na.x -= push
+        } else {
+          const push = (overlapY / 2) * (dy >= 0 ? 1 : -1)
+          nb.y += push
+          na.y -= push
+        }
+      }
+    }
+    for (const node of nodes) {
+      node.x = Math.min(Math.max(node.x, node.w / 2 + margin), containerW - node.w / 2 - margin)
+      node.y = Math.min(Math.max(node.y, node.h / 2 + margin), containerH - node.h / 2 - margin)
+      if (node.x <= node.w / 2 + margin || node.x >= containerW - node.w / 2 - margin) {
+        node.y += (seeded(node.index + iter + 211) - 0.5) * 2
+      }
+      if (node.y <= node.h / 2 + margin || node.y >= containerH - node.h / 2 - margin) {
+        node.x += (seeded(node.index + iter + 223) - 0.5) * 2
+      }
+    }
+  }
+
+  for (let iter = 0; iter < 5; iter++) {
+    const weighted = nodes.reduce(
+      (acc, node) => {
+        const weight = 1 + Math.pow(node.ratio, 1.35) * 9
+        return {
+          x: acc.x + node.x * weight,
+          y: acc.y + node.y * weight,
+          weight: acc.weight + weight,
+        }
+      },
+      { x: 0, y: 0, weight: 0 }
+    )
+    const offsetX = containerW * 0.48 - weighted.x / weighted.weight
+    const offsetY = containerH * 0.44 - weighted.y / weighted.weight
+    if (Math.abs(offsetX) < 0.5 && Math.abs(offsetY) < 0.5) break
+    for (const node of nodes) {
+      node.x = Math.min(
+        Math.max(node.x + offsetX, node.w / 2 + margin),
+        containerW - node.w / 2 - margin
+      )
+      node.y = Math.min(
+        Math.max(node.y + offsetY, node.h / 2 + margin),
+        containerH - node.h / 2 - margin
+      )
+    }
+  }
+
+  return nodes
+}
+
+export function TagAtlas({
+  entries,
+  onSearch,
+  loadRelatedTags,
+}: {
+  entries: ExploreTagEntry[]
+  onSearch: (tag: string) => void
+  loadRelatedTags: (tag: string) => Promise<RelatedTagEntry[]>
+}) {
+  const theme = useGalleryStore((state) => state.theme)
+  const isLight = theme === 'subtle-light'
+  const reducedMotion = useReducedMotion()
+  const canvasRef = useRef<HTMLDivElement>(null)
+  const buttonRefs = useRef(new Map<string, HTMLButtonElement>())
+  const [canvasSize, setCanvasSize] = useState({ w: 0, h: 0 })
+  const [activeTag, setActiveTag] = useState<string | null>(null)
+  const [relatedTags, setRelatedTags] = useState<RelatedTagEntry[]>([])
+  const [anchors, setAnchors] = useState<Record<string, TagAnchor>>({})
+  const visibleEntries = useMemo(
+    () =>
+      entries.length > TAG_ATLAS_MAX_VISIBLE ? entries.slice(0, TAG_ATLAS_MAX_VISIBLE) : entries,
+    [entries]
+  )
+
+  useLayoutEffect(() => {
+    const el = canvasRef.current
+    if (!el) return
+    const update = () => {
+      const r = el.getBoundingClientRect()
+      setCanvasSize({ w: r.width, h: r.height })
+    }
+    update()
+    const ro = new ResizeObserver(update)
+    ro.observe(el)
+    return () => ro.disconnect()
+  }, [])
+
+  useEffect(() => {
+    if (!activeTag) {
+      setRelatedTags([])
+      return
+    }
+    let cancelled = false
+    void loadRelatedTags(activeTag).then((entries) => {
+      if (!cancelled) setRelatedTags(entries)
+    })
+    return () => {
+      cancelled = true
+    }
+  }, [activeTag, loadRelatedTags])
+
+  const nodes = useMemo(
+    () => buildTagAtlas(visibleEntries, canvasSize.w, canvasSize.h, isLight),
+    [visibleEntries, canvasSize.w, canvasSize.h, isLight]
+  )
+  const nodeByTag = useMemo(() => new Map(nodes.map((node) => [node.entry.tag, node])), [nodes])
+  const activeNode = activeTag ? nodeByTag.get(activeTag) : undefined
+  const minOpacity = isLight ? 0.62 : 0.42
+  const visibleConnections = useMemo(
+    () =>
+      activeNode
+        ? relatedTags
+            .map((related) => {
+              const node = nodeByTag.get(related.tag)
+              return node ? { node, related } : null
+            })
+            .filter((item): item is { node: AtlasNode; related: RelatedTagEntry } => item !== null)
+            .slice(0, visibleEntries.length > TAG_ATLAS_DENSE_THRESHOLD ? 6 : 10)
+        : [],
+    [activeNode, nodeByTag, relatedTags, visibleEntries.length]
+  )
+  const activeAnchor = activeTag ? anchors[activeTag] : undefined
+  const maxShared = Math.max(1, ...visibleConnections.map(({ related }) => related.shared_count))
+  const connectedByTag = useMemo(
+    () => new Map(visibleConnections.map(({ node, related }) => [node.entry.tag, related])),
+    [visibleConnections]
+  )
+
+  const setButtonRef = useCallback((tag: string, element: HTMLButtonElement | null) => {
+    if (element) {
+      buttonRefs.current.set(tag, element)
+    } else {
+      buttonRefs.current.delete(tag)
+    }
+  }, [])
+
+  const measureAnchors = useCallback(() => {
+    const canvas = canvasRef.current
+    if (!canvas || !activeTag) {
+      setAnchors({})
+      return
+    }
+
+    const canvasRect = canvas.getBoundingClientRect()
+    const tagsToMeasure = [activeTag, ...visibleConnections.map(({ node }) => node.entry.tag)]
+    const nextAnchors: Record<string, TagAnchor> = {}
+    for (const tag of tagsToMeasure) {
+      const element = buttonRefs.current.get(tag)
+      if (!element) continue
+      const rect = element.getBoundingClientRect()
+      nextAnchors[tag] = {
+        x: rect.left - canvasRect.left + rect.width / 2,
+        y: rect.top - canvasRect.top + rect.height / 2,
+      }
+    }
+    setAnchors(nextAnchors)
+  }, [activeTag, visibleConnections])
+
+  useLayoutEffect(() => {
+    if (!activeTag) {
+      setAnchors({})
+      return
+    }
+
+    let firstFrame = 0
+    let secondFrame = 0
+    const settleTimer = window.setTimeout(measureAnchors, 180)
+    firstFrame = window.requestAnimationFrame(() => {
+      measureAnchors()
+      secondFrame = window.requestAnimationFrame(measureAnchors)
+    })
+    return () => {
+      window.cancelAnimationFrame(firstFrame)
+      window.cancelAnimationFrame(secondFrame)
+      window.clearTimeout(settleTimer)
+    }
+  }, [activeTag, canvasSize.w, canvasSize.h, measureAnchors])
+
+  return (
+    <div ref={canvasRef} className="relative min-h-0 flex-1 overflow-hidden px-8 py-8">
+      <svg className="pointer-events-none absolute inset-0 h-full w-full" aria-hidden="true">
+        <defs>
+          <radialGradient id="tag-atlas-glow" cx="50%" cy="50%" r="50%">
+            <stop
+              offset="0%"
+              stopColor={isLight ? 'rgba(60,50,30,0.18)' : 'rgba(255,255,255,0.2)'}
+            />
+            <stop offset="100%" stopColor="rgba(0,0,0,0)" />
+          </radialGradient>
+        </defs>
+        {activeNode && activeAnchor ? (
+          <circle
+            cx={activeAnchor.x}
+            cy={activeAnchor.y}
+            r={Math.max(activeNode.w, activeNode.h) * 0.62}
+            fill="url(#tag-atlas-glow)"
+            opacity="0.24"
+          />
+        ) : null}
+        {visibleConnections.map(({ node, related }) => {
+          const from = activeAnchor
+          const to = anchors[node.entry.tag]
+          if (!from || !to) return null
+          const strength = related.shared_count / maxShared
+          return (
+            <g key={`${activeTag}:${node.entry.tag}`}>
+              <motion.line
+                x1={from.x}
+                y1={from.y}
+                x2={to.x}
+                y2={to.y}
+                stroke={node.accent}
+                strokeWidth={0.35 + strength * 0.55}
+                strokeOpacity={0.05 + strength * 0.12}
+                strokeLinecap="round"
+                vectorEffect="non-scaling-stroke"
+                initial={reducedMotion ? undefined : { pathLength: 0, opacity: 0 }}
+                animate={reducedMotion ? undefined : { pathLength: 1, opacity: 1 }}
+                transition={{ duration: 0.32, ease: 'easeOut' }}
+              />
+              {!reducedMotion ? (
+                <motion.line
+                  x1={from.x}
+                  y1={from.y}
+                  x2={to.x}
+                  y2={to.y}
+                  stroke={node.accent}
+                  strokeWidth={0.65 + strength * 0.5}
+                  strokeOpacity={0.16 + strength * 0.1}
+                  strokeLinecap="round"
+                  pathLength={1}
+                  strokeDasharray="0.08 1"
+                  vectorEffect="non-scaling-stroke"
+                  initial={{ strokeDashoffset: 1.08, opacity: 0 }}
+                  animate={{ strokeDashoffset: [1.08, 0], opacity: [0, 0.65, 0] }}
+                  transition={{
+                    duration: 4.1 + seeded(node.index + 307) * 1.2,
+                    repeat: Infinity,
+                    ease: 'easeInOut',
+                    delay: seeded(node.index + 317) * 0.75,
+                  }}
+                />
+              ) : null}
+            </g>
+          )
+        })}
+      </svg>
+      {nodes.map((node) => {
+        const isActive = activeTag === node.entry.tag
+        const connectedRelated = connectedByTag.get(node.entry.tag)
+        const isRelated = connectedRelated !== undefined
+        const dimmed = activeTag !== null && !isActive && !isRelated
+        const opacity = dimmed ? 0.2 : minOpacity + node.ratio * (1 - minOpacity)
+        return (
+          <Tooltip
+            key={node.entry.tag}
+            label={`${node.entry.tag} — ${node.entry.count.toLocaleString()} ${node.entry.count === 1 ? 'image' : 'images'}`}
+            followCursor
+            delay={250}
+          >
+            <button
+              ref={(element) => setButtonRef(node.entry.tag, element)}
+              className={`explore-tag-word group absolute inline-flex items-center justify-center rounded-full px-2 py-1 text-center transition-[opacity,transform] duration-300 ease-out before:absolute before:inset-x-[-14px] before:inset-y-[-8px] before:rounded-full before:bg-[radial-gradient(ellipse_at_center,rgba(255,255,255,0.16),rgba(255,255,255,0.06)_46%,rgba(255,255,255,0)_72%)] before:opacity-0 before:blur-md before:transition-opacity before:duration-300 before:content-[''] hover:before:opacity-100 focus:outline-none focus-visible:ring-2 focus-visible:ring-white/25 ${
+                isActive ? 'before:opacity-100' : ''
+              }`}
+              style={{
+                left: node.x - node.w / 2,
+                top: node.y - node.h / 2,
+                width: node.w,
+                minHeight: node.h,
+                fontSize: node.fontSize,
+                color:
+                  node.ratio > 0.55 ? node.accent : isLight ? '#4b5563' : 'rgba(255,255,255,0.82)',
+                opacity,
+                transform: `translate3d(0, 0, 0) scale(${isActive ? 1.045 : isRelated ? 1.015 : 1})`,
+                zIndex: isActive ? 30 : isRelated ? 20 : Math.round(node.ratio * 10),
+              }}
+              onMouseEnter={() => setActiveTag(node.entry.tag)}
+              onFocus={() => setActiveTag(node.entry.tag)}
+              onMouseLeave={() => setActiveTag(null)}
+              onBlur={() => setActiveTag(null)}
+              onClick={() => onSearch(node.entry.tag)}
+            >
+              <span className="relative z-10 block w-full truncate text-center leading-none font-medium">
+                {node.entry.tag}
+              </span>
+              <span
+                className={`absolute top-full left-1/2 z-10 mt-1 shrink-0 -translate-x-1/2 rounded-full px-1.5 py-0.5 text-[9px] tabular-nums shadow-sm backdrop-blur-sm transition-opacity ${
+                  isActive || isRelated ? 'opacity-100' : 'opacity-0 group-hover:opacity-100'
+                }`}
+                style={{ backgroundColor: `${node.accent}1A`, color: node.accent }}
+              >
+                {connectedRelated
+                  ? connectedRelated.shared_count.toLocaleString()
+                  : node.entry.count.toLocaleString()}
+              </span>
+            </button>
+          </Tooltip>
+        )
+      })}
+    </div>
+  )
+}

src/components/explore/TagManageList.tsx

@@ -0,0 +1,471 @@
+import { useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react'
+import { useVirtualizer } from '@tanstack/react-virtual'
+import type { ExploreTagEntry } from '../../store'
+import { Dropdown } from '../menu'
+import { Tooltip } from '../Tooltip'
+
+type TagManageSort = 'count_desc' | 'count_asc' | 'az' | 'za'
+
+const TAG_MANAGE_SORTS: { value: TagManageSort; label: string }[] = [
+  { value: 'count_desc', label: 'Most used' },
+  { value: 'count_asc', label: 'Least used' },
+  { value: 'az', label: 'A-Z' },
+  { value: 'za', label: 'Z-A' },
+]
+
+function AiSourceGlyph({ className = '' }: { className?: string }) {
+  return (
+    <svg className={className} viewBox="0 0 16 16" fill="none" aria-hidden="true">
+      <path
+        d="M8 2.75l.82 2.42a2.1 2.1 0 0 0 1.32 1.32l2.41.81-2.41.82a2.1 2.1 0 0 0-1.32 1.32L8 11.85l-.82-2.41a2.1 2.1 0 0 0-1.32-1.32L3.45 7.3l2.41-.81a2.1 2.1 0 0 0 1.32-1.32L8 2.75Z"
+        stroke="currentColor"
+        strokeLinejoin="round"
+        strokeWidth="1.35"
+      />
+      <path
+        d="M12.25 11.15l.25.74.75.26-.75.25-.25.75-.26-.75-.74-.25.74-.26.26-.74Z"
+        fill="currentColor"
+      />
+    </svg>
+  )
+}
+
+function RenameGlyph({ className = '' }: { className?: string }) {
+  return (
+    <svg className={className} viewBox="0 0 16 16" fill="none" aria-hidden="true">
+      <path
+        d="M3.25 11.85l.45-2.14 5.95-5.95a1.33 1.33 0 0 1 1.88 0l.71.71a1.33 1.33 0 0 1 0 1.88L6.29 12.3l-2.14.45a.76.76 0 0 1-.9-.9Z"
+        stroke="currentColor"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        strokeWidth="1.35"
+      />
+      <path d="M8.75 4.65l2.6 2.6" stroke="currentColor" strokeLinecap="round" strokeWidth="1.35" />
+    </svg>
+  )
+}
+
+function DeleteGlyph({ className = '' }: { className?: string }) {
+  return (
+    <svg className={className} viewBox="0 0 16 16" fill="none" aria-hidden="true">
+      <path d="M3.25 4.65h9.5" stroke="currentColor" strokeLinecap="round" strokeWidth="1.35" />
+      <path
+        d="M6.35 4.55V3.7c0-.55.45-1 1-1h1.3c.55 0 1 .45 1 1v.85"
+        stroke="currentColor"
+        strokeLinecap="round"
+        strokeWidth="1.35"
+      />
+      <path
+        d="M5.1 6.2l.35 5.65c.04.63.56 1.12 1.19 1.12h2.72c.63 0 1.15-.49 1.19-1.12l.35-5.65"
+        stroke="currentColor"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        strokeWidth="1.35"
+      />
+    </svg>
+  )
+}
+
+// Compact management tile for a single tag. Rename doubles as merge when the new
+// name already exists, and delete applies across the scoped tag set.
+function TagManageTile({
+  entry,
+  onSearch,
+  onRename,
+  onDelete,
+}: {
+  entry: ExploreTagEntry
+  onSearch: (tag: string) => void
+  onRename: (from: string, to: string) => Promise<void>
+  onDelete: (tag: string) => Promise<void>
+}) {
+  const [editing, setEditing] = useState(false)
+  const [value, setValue] = useState(entry.tag)
+  const [confirming, setConfirming] = useState(false)
+  const [busy, setBusy] = useState(false)
+  const inputRef = useRef<HTMLInputElement>(null)
+
+  useEffect(() => {
+    if (editing) {
+      setValue(entry.tag)
+      setTimeout(() => inputRef.current?.select(), 0)
+    }
+  }, [editing, entry.tag])
+
+  const commitRename = async () => {
+    const next = value.trim()
+    if (!next || next === entry.tag) {
+      setEditing(false)
+      return
+    }
+    setBusy(true)
+    try {
+      await onRename(entry.tag, next)
+      setEditing(false)
+    } finally {
+      setBusy(false)
+    }
+  }
+
+  const sourceLabel = entry.has_ai_source
+    ? entry.has_user_source
+      ? 'Used by AI tags and user tags'
+      : 'AI-generated tag'
+    : 'User tag'
+
+  return (
+    <div
+      data-tag-manager-tile
+      className={`tag-manager-tile ${entry.has_ai_source ? 'tag-manager-tile-ai' : ''} group relative min-w-0 rounded-lg border bg-white/[0.018] px-3 py-2 transition-[background-color,border-color,transform] duration-150 focus-within:bg-white/[0.045] hover:bg-white/[0.04] ${
+        entry.has_ai_source
+          ? 'border-white/[0.08] shadow-[inset_0_1px_0_rgba(125,211,252,0.055)] focus-within:border-white/[0.15] hover:border-white/[0.13]'
+          : 'border-white/[0.06] focus-within:border-white/[0.14] hover:border-white/[0.12]'
+      } ${editing || confirming ? 'min-h-[82px]' : 'min-h-[46px]'}`}
+    >
+      <div className="flex min-w-0 items-start gap-2">
+        {editing ? (
+          <input
+            ref={inputRef}
+            className="tag-manager-edit-input min-w-0 flex-1 rounded-md border border-blue-400/35 bg-black/25 px-2 py-1 text-sm text-white ring-1 ring-blue-500/30 outline-none"
+            value={value}
+            onChange={(e) => setValue(e.target.value)}
+            onKeyDown={(e) => {
+              if (e.key === 'Enter') {
+                e.preventDefault()
+                void commitRename()
+              }
+              if (e.key === 'Escape') setEditing(false)
+            }}
+            disabled={busy}
+          />
+        ) : (
+          <Tooltip label="Search this tag" delay={500} anchorToCursor className="min-w-0 flex-1">
+            <button
+              className="tag-manager-name block w-full truncate pr-36 text-left text-sm font-medium text-white/85 transition-colors hover:text-white"
+              onClick={() => onSearch(entry.tag)}
+            >
+              {entry.tag}
+            </button>
+          </Tooltip>
+        )}
+        <div className="absolute top-2 right-2.5 shrink-0">
+          {entry.has_ai_source ? (
+            <Tooltip label={sourceLabel} delay={400} anchorToCursor>
+              <span className="tag-manager-count tag-manager-count-ai inline-flex h-5 items-center gap-1 rounded-full border border-sky-300/10 bg-sky-300/[0.075] px-1.5 text-[10px] text-sky-200/75 tabular-nums">
+                <AiSourceGlyph className="tag-manager-ai-glyph h-3 w-3" />
+                {entry.count.toLocaleString()}
+              </span>
+            </Tooltip>
+          ) : (
+            <span className="tag-manager-count rounded-full bg-white/[0.055] px-2 py-0.5 text-[10px] text-white/38 tabular-nums">
+              {entry.count.toLocaleString()}
+            </span>
+          )}
+        </div>
+      </div>
+
+      {editing ? (
+        <div className="mt-2 flex items-center gap-1">
+          <button
+            className="tag-manager-save rounded-md bg-blue-500/20 px-2 py-1 text-[11px] text-blue-200 transition-colors hover:bg-blue-500/30 disabled:opacity-50"
+            onClick={() => void commitRename()}
+            disabled={busy || !value.trim()}
+          >
+            Save
+          </button>
+          <button
+            className="tag-manager-secondary rounded-md border border-white/10 px-2 py-1 text-[11px] text-white/50 transition-colors hover:bg-white/5 hover:text-white/80"
+            onClick={() => setEditing(false)}
+            disabled={busy}
+          >
+            Cancel
+          </button>
+        </div>
+      ) : confirming ? (
+        <div className="mt-2 flex items-center gap-1">
+          <button
+            className="tag-manager-danger rounded-md bg-red-500/20 px-2 py-1 text-[11px] text-red-300 transition-colors hover:bg-red-500/30 disabled:opacity-50"
+            onClick={async () => {
+              setBusy(true)
+              try {
+                await onDelete(entry.tag)
+                setConfirming(false)
+              } finally {
+                setBusy(false)
+              }
+            }}
+            disabled={busy}
+          >
+            Delete
+          </button>
+          <button
+            className="tag-manager-secondary rounded-md border border-white/10 px-2 py-1 text-[11px] text-white/50 transition-colors hover:bg-white/5 hover:text-white/80"
+            onClick={() => setConfirming(false)}
+            disabled={busy}
+          >
+            Cancel
+          </button>
+        </div>
+      ) : (
+        <div className="pointer-events-none absolute top-1/2 right-[5rem] flex -translate-y-1/2 items-center gap-1 opacity-0 transition-opacity group-focus-within:pointer-events-auto group-focus-within:opacity-100 group-hover:pointer-events-auto group-hover:opacity-100">
+          <Tooltip label="Rename or merge into another tag" delay={400} anchorToCursor>
+            <button
+              className="tag-manager-action inline-flex h-6 w-6 items-center justify-center rounded-md border border-white/10 bg-gray-950/80 text-white/55 transition-colors hover:bg-white/8 hover:text-white focus:outline-none focus-visible:ring-2 focus-visible:ring-blue-400/80"
+              onClick={() => setEditing(true)}
+              aria-label={`Rename ${entry.tag}`}
+            >
+              <RenameGlyph className="h-3.5 w-3.5" />
+            </button>
+          </Tooltip>
+          <Tooltip label="Delete this tag in the current scope" delay={400} anchorToCursor>
+            <button
+              className="tag-manager-action tag-manager-action-danger inline-flex h-6 w-6 items-center justify-center rounded-md border border-white/10 bg-gray-950/80 text-white/55 transition-colors hover:bg-red-500/10 hover:text-red-300 focus:outline-none focus-visible:ring-2 focus-visible:ring-red-400/80"
+              onClick={() => setConfirming(true)}
+              aria-label={`Delete ${entry.tag}`}
+            >
+              <DeleteGlyph className="h-3.5 w-3.5" />
+            </button>
+          </Tooltip>
+        </div>
+      )}
+    </div>
+  )
+}
+
+export function TagManageList({
+  entries,
+  onSearch,
+  onRename,
+  onDelete,
+  onResetAiTags,
+  scopeLabel,
+}: {
+  entries: ExploreTagEntry[]
+  onSearch: (tag: string) => void
+  onRename: (from: string, to: string) => Promise<void>
+  onDelete: (tag: string) => Promise<void>
+  onResetAiTags: () => Promise<number>
+  scopeLabel: string
+}) {
+  const scrollRef = useRef<HTMLDivElement>(null)
+  const measureRef = useRef<HTMLDivElement>(null)
+  const [query, setQuery] = useState('')
+  const [sort, setSort] = useState<TagManageSort>('count_desc')
+  const [columns, setColumns] = useState(3)
+  const [resetConfirming, setResetConfirming] = useState(false)
+  const [resetting, setResetting] = useState(false)
+  const [resetStatus, setResetStatus] = useState<string | null>(null)
+
+  useLayoutEffect(() => {
+    const el = measureRef.current
+    if (!el) return
+    const update = () => {
+      const width = el.getBoundingClientRect().width
+      setColumns(width >= 1160 ? 4 : width >= 780 ? 3 : width >= 520 ? 2 : 1)
+    }
+    update()
+    const ro = new ResizeObserver(update)
+    ro.observe(el)
+    return () => ro.disconnect()
+  }, [])
+
+  const filteredEntries = useMemo(() => {
+    const needle = query.trim().toLowerCase()
+    const filtered = needle
+      ? entries.filter((entry) => entry.tag.toLowerCase().includes(needle))
+      : entries
+    return [...filtered].sort((left, right) => {
+      switch (sort) {
+        case 'count_asc':
+          return left.count - right.count || left.tag.localeCompare(right.tag)
+        case 'az':
+          return left.tag.localeCompare(right.tag)
+        case 'za':
+          return right.tag.localeCompare(left.tag)
+        case 'count_desc':
+        default:
+          return right.count - left.count || left.tag.localeCompare(right.tag)
+      }
+    })
+  }, [entries, query, sort])
+
+  const rowCount = Math.ceil(filteredEntries.length / columns)
+  const rowVirtualizer = useVirtualizer({
+    count: rowCount,
+    getScrollElement: () => scrollRef.current,
+    estimateSize: () => 54,
+    overscan: 7,
+  })
+  const visibleItems = rowVirtualizer.getVirtualItems()
+  const totalUses = useMemo(() => entries.reduce((sum, entry) => sum + entry.count, 0), [entries])
+
+  const runResetAiTags = async () => {
+    if (!resetConfirming) {
+      setResetConfirming(true)
+      setResetStatus(
+        `Reset AI tags for ${scopeLabel}? User tags are preserved, and retagging is not queued automatically.`
+      )
+      return
+    }
+
+    setResetting(true)
+    setResetStatus(null)
+    try {
+      const count = await onResetAiTags()
+      setResetStatus(
+        count === 0
+          ? 'No AI tag data found for this scope.'
+          : `Reset AI tags for ${count.toLocaleString()} image${count === 1 ? '' : 's'}. Queue tagging when you're ready to retag.`
+      )
+    } catch (error) {
+      setResetStatus(String(error))
+    } finally {
+      setResetting(false)
+      setResetConfirming(false)
+    }
+  }
+
+  return (
+    <div className="flex min-h-0 flex-1 flex-col overflow-hidden">
+      <div className="tag-manager-header shrink-0 border-b border-white/[0.05] bg-black/[0.08] px-6 py-4">
+        <div className="flex flex-wrap items-end justify-between gap-3">
+          <div className="min-w-0">
+            <div className="flex flex-wrap items-center gap-2 text-[11px] text-white/32">
+              <span className="tag-manager-stat rounded-full bg-white/[0.045] px-2 py-1 tabular-nums">
+                {entries.length.toLocaleString()} tags
+              </span>
+              <span className="tag-manager-stat rounded-full bg-white/[0.045] px-2 py-1 tabular-nums">
+                {totalUses.toLocaleString()} uses
+              </span>
+              {query.trim() ? (
+                <span className="tag-manager-match rounded-full bg-blue-500/10 px-2 py-1 text-blue-200/70 tabular-nums">
+                  {filteredEntries.length.toLocaleString()} matches
+                </span>
+              ) : null}
+            </div>
+            <p className="tag-manager-help mt-2 max-w-2xl text-[11px] leading-relaxed text-white/28">
+              Rename tags to clean them up, rename into an existing tag to merge, or delete a tag
+              everywhere in the current scope.
+            </p>
+            {resetStatus ? (
+              <p className="mt-2 text-[11px] leading-relaxed text-amber-200/80">{resetStatus}</p>
+            ) : null}
+          </div>
+
+          <div className="flex min-w-[320px] flex-1 flex-wrap justify-end gap-2">
+            <button
+              className={`tag-manager-reset-button h-9 rounded-lg border px-3 text-xs transition-colors disabled:cursor-not-allowed disabled:opacity-50 ${
+                resetConfirming
+                  ? 'tag-manager-reset-button-confirm border-red-400/30 bg-red-500/15 text-red-200 hover:bg-red-500/25'
+                  : 'border-white/8 bg-black/20 text-white/50 hover:bg-white/[0.06] hover:text-white/80'
+              }`}
+              onClick={() => void runResetAiTags()}
+              disabled={resetting}
+            >
+              {resetting ? 'Resetting...' : resetConfirming ? 'Confirm reset' : 'Reset AI tags'}
+            </button>
+            {resetConfirming ? (
+              <button
+                className="tag-manager-reset-cancel h-9 rounded-lg border border-white/8 bg-black/20 px-3 text-xs text-white/45 transition-colors hover:bg-white/[0.06] hover:text-white/75 disabled:opacity-50"
+                onClick={() => {
+                  setResetConfirming(false)
+                  setResetStatus(null)
+                }}
+                disabled={resetting}
+              >
+                Cancel
+              </button>
+            ) : null}
+            <div className="relative min-w-[220px] flex-1 sm:max-w-sm">
+              <input
+                className="tag-manager-filter h-9 w-full rounded-lg border border-white/8 bg-black/20 px-3 pr-8 text-sm text-white/85 transition-colors outline-none placeholder:text-white/22 focus:border-blue-400/35 focus:bg-black/28"
+                value={query}
+                onChange={(event) => setQuery(event.target.value)}
+                placeholder="Filter tags"
+              />
+              {query ? (
+                <span className="absolute top-2 right-2 z-10">
+                  <Tooltip label="Clear filter" delay={400} anchorToCursor>
+                    <button
+                      className="tag-manager-clear inline-flex h-5 w-5 items-center justify-center rounded-md text-white/35 transition-colors hover:bg-white/8 hover:text-white/75 focus:outline-none focus-visible:ring-2 focus-visible:ring-blue-400/70"
+                      onClick={() => setQuery('')}
+                      aria-label="Clear tag filter"
+                    >
+                      <svg
+                        className="h-3.5 w-3.5"
+                        fill="none"
+                        viewBox="0 0 24 24"
+                        stroke="currentColor"
+                        aria-hidden="true"
+                      >
+                        <path
+                          strokeLinecap="round"
+                          strokeLinejoin="round"
+                          strokeWidth={2.2}
+                          d="M6 6l12 12M18 6L6 18"
+                        />
+                      </svg>
+                    </button>
+                  </Tooltip>
+                </span>
+              ) : null}
+            </div>
+            <Dropdown
+              value={sort}
+              onChange={setSort}
+              options={TAG_MANAGE_SORTS}
+              ariaLabel="Sort managed tags"
+              align="right"
+            />
+          </div>
+        </div>
+      </div>
+
+      <div
+        ref={scrollRef}
+        data-tag-manager-scroll
+        className="min-h-0 flex-1 overflow-y-auto px-6 py-5"
+      >
+        <div ref={measureRef} className="mx-auto w-full max-w-7xl">
+          {filteredEntries.length === 0 ? (
+            <div className="tag-manager-empty flex h-48 items-center justify-center rounded-lg border border-white/[0.06] bg-white/[0.02] text-sm text-white/30">
+              No tags match that filter.
+            </div>
+          ) : (
+            <div
+              className="relative w-full"
+              style={{ height: `${rowVirtualizer.getTotalSize()}px` }}
+            >
+              {visibleItems.map((virtualRow) => {
+                const start = virtualRow.index * columns
+                const rowEntries = filteredEntries.slice(start, start + columns)
+                return (
+                  <div
+                    key={virtualRow.key}
+                    data-index={virtualRow.index}
+                    ref={rowVirtualizer.measureElement}
+                    className="absolute top-0 left-0 grid w-full gap-x-2 pb-2"
+                    style={{
+                      gridTemplateColumns: `repeat(${columns}, minmax(0, 1fr))`,
+                      transform: `translateY(${virtualRow.start}px)`,
+                    }}
+                  >
+                    {rowEntries.map((entry) => (
+                      <TagManageTile
+                        key={entry.tag}
+                        entry={entry}
+                        onSearch={onSearch}
+                        onRename={onRename}
+                        onDelete={onDelete}
+                      />
+                    ))}
+                  </div>
+                )
+              })}
+            </div>
+          )}
+        </div>
+      </div>
+    </div>
+  )
+}

src/components/explore/layout.ts

@@ -0,0 +1,34 @@
+export const ACCENTS = [
+  '#60a5fa',
+  '#c084fc',
+  '#4ade80',
+  '#fbbf24',
+  '#f472b4',
+  '#2dd4bf',
+  '#fb923c',
+  '#a78bfa',
+  '#34d399',
+  '#f87171',
+]
+
+// Darker variants of each accent for the light theme -- the bright originals are
+// tuned for dark cards and wash out on the cream background.
+export const LIGHT_ACCENTS = [
+  '#2563eb',
+  '#9333ea',
+  '#16a34a',
+  '#d97706',
+  '#db2777',
+  '#0d9488',
+  '#ea580c',
+  '#7c3aed',
+  '#059669',
+  '#dc2626',
+]
+
+export const GOLDEN_ANGLE = Math.PI * (3 - Math.sqrt(5))
+
+export function seeded(n: number): number {
+  const x = Math.sin(n * 9301 + 49297) * 233280
+  return x - Math.floor(x)
+}

src/components/folderPicker/FolderRow.tsx

@@ -0,0 +1,76 @@
+import { DirEntry } from '../../store'
+import { Tooltip } from '../Tooltip'
+import { CheckIcon, ChevronRightIcon } from '../icons'
+
+export function FolderRow({
+  entry,
+  selected,
+  alreadyAdded,
+  onToggle,
+  onNavigate,
+}: {
+  entry: DirEntry
+  selected: boolean
+  alreadyAdded: boolean
+  onToggle: () => void
+  onNavigate: () => void
+}) {
+  return (
+    <div
+      className={`group flex h-11 items-center gap-3 rounded-md border px-3 transition-colors ${
+        alreadyAdded
+          ? 'light-theme:bg-gray-900 light-theme:text-gray-500 border-transparent bg-white/[0.025] text-gray-600'
+          : selected
+            ? 'light-theme:border-gray-700/45 light-theme:bg-gray-800/55 light-theme:text-white border-white/15 bg-white/[0.085] text-white shadow-[inset_0_0_0_1px_rgb(255_255_255_/_0.035)]'
+            : 'light-theme:text-gray-500 light-theme:hover:bg-gray-900 light-theme:hover:text-white border-transparent text-gray-300 hover:bg-white/[0.055] hover:text-white'
+      }`}
+    >
+      <button
+        type="button"
+        className={`grid h-5 w-5 shrink-0 place-items-center rounded border transition-colors ${
+          selected
+            ? 'light-theme:border-gray-700/55 light-theme:bg-gray-700 light-theme:text-white border-white/30 bg-gray-200 text-gray-950'
+            : 'light-theme:border-gray-700/50 light-theme:bg-gray-950 border-white/15 bg-white/[0.035] text-transparent hover:border-white/30'
+        } ${alreadyAdded ? 'cursor-not-allowed opacity-40' : ''}`}
+        onClick={onToggle}
+        disabled={alreadyAdded}
+        aria-label={selected ? `Remove ${entry.name} from folders to add` : `Choose ${entry.name}`}
+      >
+        <CheckIcon className="h-3.5 w-3.5" />
+      </button>
+
+      <Tooltip label={entry.path} anchorToCursor className="min-w-0 flex-1">
+        <button
+          type="button"
+          className="flex w-full min-w-0 items-center gap-2 text-left"
+          onClick={onNavigate}
+        >
+          <svg
+            className="h-4 w-4 shrink-0 text-amber-300/90"
+            fill="currentColor"
+            viewBox="0 0 24 24"
+          >
+            <path d="M3 6.5A2.5 2.5 0 015.5 4h4.1l2 2H18.5A2.5 2.5 0 0121 8.5v9A2.5 2.5 0 0118.5 20h-13A2.5 2.5 0 013 17.5v-11z" />
+          </svg>
+          <span className="truncate text-sm">{entry.name}</span>
+        </button>
+      </Tooltip>
+
+      {alreadyAdded ? (
+        <span className="light-theme:border-gray-700/40 light-theme:bg-gray-950 rounded-md border border-white/10 bg-white/[0.04] px-2 py-0.5 text-[11px] text-gray-500">
+          Added
+        </span>
+      ) : null}
+
+      <Tooltip label={entry.has_children ? 'Open folder' : 'No subfolders'} anchorToCursor>
+        <button
+          type="button"
+          className="light-theme:hover:bg-gray-900 light-theme:hover:text-white rounded-md p-1 text-gray-500 transition-colors hover:bg-white/[0.06] hover:text-white"
+          onClick={onNavigate}
+        >
+          <ChevronRightIcon className={`h-4 w-4 ${entry.has_children ? '' : 'opacity-45'}`} />
+        </button>
+      </Tooltip>
+    </div>
+  )
+}

src/components/folderPicker/StagedFoldersPanel.tsx

@@ -0,0 +1,75 @@
+import { Tooltip } from '../Tooltip'
+import { CloseIcon } from '../icons'
+import { folderName } from './pathUtils'
+
+export function StagedFoldersPanel({
+  stagedPaths,
+  onRemove,
+  onClear,
+}: {
+  stagedPaths: string[]
+  onRemove: (path: string) => void
+  onClear: () => void
+}) {
+  return (
+    <aside className="light-theme:border-gray-300/70 light-theme:bg-gray-900/35 flex min-h-0 w-full flex-col border-t border-white/[0.07] bg-white/[0.018] lg:w-80 lg:border-t-0 lg:border-l">
+      <div className="light-theme:border-gray-300/70 flex items-center justify-between gap-3 border-b border-white/[0.07] px-5 py-4">
+        <p className="text-[11px] font-semibold tracking-[0.16em] text-gray-500 uppercase">
+          Folders to add ({stagedPaths.length})
+        </p>
+        {stagedPaths.length > 0 ? (
+          <button
+            type="button"
+            className="light-theme:text-gray-500 light-theme:hover:bg-gray-800 light-theme:hover:text-white rounded px-1.5 py-0.5 text-xs text-gray-400 transition-colors hover:bg-white/[0.06] hover:text-white"
+            onClick={onClear}
+          >
+            Clear all
+          </button>
+        ) : null}
+      </div>
+
+      <div className="min-h-0 flex-1 overflow-y-auto p-3">
+        {stagedPaths.length === 0 ? (
+          <div className="light-theme:border-gray-700/35 flex h-full min-h-40 flex-col items-center justify-center rounded-md border border-dashed border-white/[0.08] px-5 text-center">
+            <p className="text-sm text-gray-500">No folders selected.</p>
+            <p className="light-theme:text-gray-500 mt-1 max-w-52 text-xs leading-relaxed text-gray-600">
+              Choose folders on the left and they will collect here.
+            </p>
+          </div>
+        ) : (
+          <div className="space-y-2">
+            {stagedPaths.map((path) => (
+              <Tooltip key={path} label={path} anchorToCursor block>
+                <div className="group light-theme:border-gray-700/40 light-theme:bg-gray-900 light-theme:text-white light-theme:hover:bg-gray-800 flex min-h-12 items-center gap-2 rounded-md border border-white/[0.07] bg-white/[0.045] px-3 py-2 text-gray-200 transition-colors hover:border-white/15 hover:bg-white/[0.07]">
+                  <svg
+                    className="h-4 w-4 shrink-0 text-amber-300/90"
+                    fill="currentColor"
+                    viewBox="0 0 24 24"
+                  >
+                    <path d="M3 6.5A2.5 2.5 0 015.5 4h4.1l2 2H18.5A2.5 2.5 0 0121 8.5v9A2.5 2.5 0 0118.5 20h-13A2.5 2.5 0 013 17.5v-11z" />
+                  </svg>
+                  <div className="min-w-0 flex-1">
+                    <p className="truncate text-sm font-medium">{folderName(path)}</p>
+                    <p className="light-theme:text-gray-500 mt-0.5 truncate text-[11px] text-gray-600">
+                      {path}
+                    </p>
+                  </div>
+                  <Tooltip label="Remove from folders to add" anchorToCursor>
+                    <button
+                      type="button"
+                      className="light-theme:hover:bg-gray-700 rounded-md p-1 text-gray-500 opacity-80 transition-colors group-hover:opacity-100 hover:bg-white/[0.08] hover:text-white"
+                      onClick={() => onRemove(path)}
+                      aria-label={`Remove ${path} from folders to add`}
+                    >
+                      <CloseIcon className="h-3.5 w-3.5" />
+                    </button>
+                  </Tooltip>
+                </div>
+              </Tooltip>
+            ))}
+          </div>
+        )}
+      </div>
+    </aside>
+  )
+}

src/components/folderPicker/StatusLine.tsx

@@ -0,0 +1,13 @@
+import { FolderAddResult } from '../../store'
+
+export function StatusLine({ results }: { results: FolderAddResult[] | null }) {
+  if (!results) return null
+  const added = results.filter((result) => result.status === 'added').length
+  const skipped = results.filter((result) => result.status === 'skipped').length
+  const failed = results.filter((result) => result.status === 'error').length
+  return (
+    <p className="light-theme:text-gray-600 text-xs text-gray-500">
+      Added {added}, skipped {skipped}, failed {failed}.
+    </p>
+  )
+}

src/components/folderPicker/pathUtils.test.ts

@@ -0,0 +1,91 @@
+import { describe, expect, it } from 'vitest'
+import {
+  buildBreadcrumbs,
+  cleanAddressInput,
+  folderName,
+  friendlyDirectoryError,
+  normalizePath,
+} from './pathUtils'
+
+describe('normalizePath', () => {
+  it('converts backslashes, strips trailing slashes, and lowercases', () => {
+    expect(normalizePath('C:\\Users\\Me\\Pictures\\')).toBe('c:/users/me/pictures')
+    expect(normalizePath('/home/User/photos///')).toBe('/home/user/photos')
+    expect(normalizePath('relative/path')).toBe('relative/path')
+  })
+})
+
+describe('cleanAddressInput', () => {
+  it('strips matching surrounding quotes', () => {
+    expect(cleanAddressInput('"C:\\Photos"')).toBe('C:\\Photos')
+    expect(cleanAddressInput("'C:\\Photos'")).toBe('C:\\Photos')
+  })
+
+  it('leaves mismatched quotes alone', () => {
+    expect(cleanAddressInput('"C:\\Photos\'')).toBe('"C:\\Photos\'')
+  })
+
+  it('trims whitespace inside and outside quotes', () => {
+    expect(cleanAddressInput('  " C:\\Photos "  ')).toBe('C:\\Photos')
+    expect(cleanAddressInput('  C:\\Photos  ')).toBe('C:\\Photos')
+  })
+})
+
+describe('friendlyDirectoryError', () => {
+  it('maps not-found style errors to a friendly message', () => {
+    expect(friendlyDirectoryError(new Error('The system cannot find the path specified.'))).toBe(
+      'Folder not found. Check the path and try again.'
+    )
+    expect(friendlyDirectoryError(new Error('os error 3'))).toBe(
+      'Folder not found. Check the path and try again.'
+    )
+    expect(friendlyDirectoryError('No such file or directory')).toBe(
+      'Folder not found. Check the path and try again.'
+    )
+  })
+
+  it('passes other messages through', () => {
+    expect(friendlyDirectoryError(new Error('Access denied'))).toBe('Access denied')
+    expect(friendlyDirectoryError(42)).toBe('42')
+  })
+})
+
+describe('folderName', () => {
+  it('returns the final path component', () => {
+    expect(folderName('C:\\Users\\me\\Pictures')).toBe('Pictures')
+    expect(folderName('/home/user/photos/')).toBe('photos')
+  })
+
+  it('handles roots', () => {
+    expect(folderName('C:\\')).toBe('C:')
+    expect(folderName('/')).toBe('/')
+  })
+})
+
+describe('buildBreadcrumbs', () => {
+  it('returns the home crumb for null paths', () => {
+    expect(buildBreadcrumbs(null)).toEqual([{ label: 'This PC / Home', path: null }])
+  })
+
+  it('builds Windows drive breadcrumbs', () => {
+    expect(buildBreadcrumbs('C:\\Users\\me')).toEqual([
+      { label: 'This PC', path: null },
+      { label: 'C:', path: 'C:' },
+      { label: 'Users', path: 'C:\\Users' },
+      { label: 'me', path: 'C:\\Users\\me' },
+    ])
+  })
+
+  it('builds Unix breadcrumbs', () => {
+    expect(buildBreadcrumbs('/home/user')).toEqual([
+      { label: '/', path: null },
+      { label: 'home', path: '/home' },
+      { label: 'user', path: '/home/user' },
+    ])
+  })
+
+  it('ignores trailing separators', () => {
+    const crumbs = buildBreadcrumbs('C:\\Users\\')
+    expect(crumbs.map((c) => c.label)).toEqual(['This PC', 'C:', 'Users'])
+  })
+})

src/components/folderPicker/pathUtils.ts

@@ -0,0 +1,69 @@
+export interface Breadcrumb {
+  label: string
+  path: string | null
+}
+
+export function normalizePath(path: string): string {
+  return path.replace(/\\/g, '/').replace(/\/+$/, '').toLowerCase()
+}
+
+export function cleanAddressInput(path: string): string {
+  const trimmed = path.trim()
+  if (trimmed.length >= 2) {
+    const first = trimmed[0]
+    const last = trimmed[trimmed.length - 1]
+    if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+      return trimmed.slice(1, -1).trim()
+    }
+  }
+  return trimmed
+}
+
+export function friendlyDirectoryError(error: unknown): string {
+  const message = error instanceof Error ? error.message : String(error)
+  if (/cannot find the path|os error 3|not found|no such file/i.test(message)) {
+    return 'Folder not found. Check the path and try again.'
+  }
+  return message
+}
+
+export function folderName(path: string): string {
+  const trimmed = path.replace(/[\\/]+$/, '')
+  const parts = trimmed.split(/[\\/]+/).filter(Boolean)
+  return parts.length > 0 ? parts[parts.length - 1] : path
+}
+
+export function buildBreadcrumbs(path: string | null): Breadcrumb[] {
+  if (!path) return [{ label: 'This PC / Home', path: null }]
+
+  const separator = path.includes('\\') ? '\\' : '/'
+  const normalized = path.replace(/[\\/]+$/, '')
+  const windowsDrive = normalized.match(/^[A-Za-z]:/)
+
+  if (windowsDrive) {
+    const drive = windowsDrive[0]
+    const rest = normalized
+      .slice(2)
+      .split(/[\\/]+/)
+      .filter(Boolean)
+    let current = drive
+    return [
+      { label: 'This PC', path: null },
+      { label: drive, path: drive },
+      ...rest.map((part) => {
+        current = current.endsWith('\\') ? `${current}${part}` : `${current}\\${part}`
+        return { label: part, path: current }
+      }),
+    ]
+  }
+
+  const parts = normalized.split(/[\\/]+/).filter(Boolean)
+  let current = separator === '/' ? '' : ''
+  return [
+    { label: '/', path: null },
+    ...parts.map((part) => {
+      current = `${current}/${part}`
+      return { label: part, path: current }
+    }),
+  ]
+}

src/components/folderPicker/useFolderPicker.ts

@@ -0,0 +1,219 @@
+import { useEffect, useMemo, useRef, useState } from 'react'
+import { DirListing, FolderAddResult, useGalleryStore } from '../../store'
+import {
+  buildBreadcrumbs,
+  cleanAddressInput,
+  friendlyDirectoryError,
+  normalizePath,
+} from './pathUtils'
+
+export function useFolderPicker() {
+  const folderPickerOpen = useGalleryStore((state) => state.folderPickerOpen)
+  const setFolderPickerOpen = useGalleryStore((state) => state.setFolderPickerOpen)
+  const folders = useGalleryStore((state) => state.folders)
+  const listDirectories = useGalleryStore((state) => state.listDirectories)
+  const addFolders = useGalleryStore((state) => state.addFolders)
+
+  const [listing, setListing] = useState<DirListing | null>(null)
+  const [currentPath, setCurrentPath] = useState<string | null>(null)
+  const [addressDraft, setAddressDraft] = useState('')
+  const [addressEditing, setAddressEditing] = useState(false)
+  const [stagedPaths, setStagedPaths] = useState<string[]>([])
+  const [loading, setLoading] = useState(false)
+  const [adding, setAdding] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+  const [results, setResults] = useState<FolderAddResult[] | null>(null)
+  const scrollRef = useRef<HTMLDivElement>(null)
+  const addressInputRef = useRef<HTMLInputElement>(null)
+
+  const libraryPaths = useMemo(
+    () => new Set(folders.map((folder) => normalizePath(folder.path))),
+    [folders]
+  )
+  const stagedSet = useMemo(() => new Set(stagedPaths.map(normalizePath)), [stagedPaths])
+  const breadcrumbs = useMemo(() => buildBreadcrumbs(listing?.current ?? null), [listing?.current])
+
+  useEffect(() => {
+    if (!folderPickerOpen) return
+    let cancelled = false
+    setLoading(true)
+    setError(null)
+    void listDirectories(currentPath)
+      .then((nextListing) => {
+        if (cancelled) return
+        setListing(nextListing)
+        setAddressDraft(nextListing.current ?? '')
+        setAddressEditing(false)
+        scrollRef.current?.scrollTo({ top: 0, left: 0 })
+      })
+      .catch((loadError) => {
+        if (cancelled) return
+        setListing({ current: currentPath, parent: null, entries: [] })
+        setError(friendlyDirectoryError(loadError))
+      })
+      .finally(() => {
+        if (!cancelled) setLoading(false)
+      })
+    return () => {
+      cancelled = true
+    }
+  }, [currentPath, folderPickerOpen, listDirectories])
+
+  useEffect(() => {
+    if (!folderPickerOpen) return
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key === 'Escape') {
+        if (addressEditing) {
+          setAddressDraft(listing?.current ?? '')
+          setAddressEditing(false)
+          return
+        }
+        setFolderPickerOpen(false)
+      }
+    }
+    window.addEventListener('keydown', handleKeyDown)
+    return () => window.removeEventListener('keydown', handleKeyDown)
+  }, [addressEditing, folderPickerOpen, listing?.current, setFolderPickerOpen])
+
+  useEffect(() => {
+    if (!addressEditing) return
+    requestAnimationFrame(() => {
+      addressInputRef.current?.focus()
+      addressInputRef.current?.select()
+    })
+  }, [addressEditing])
+
+  useEffect(() => {
+    if (folderPickerOpen) return
+    setCurrentPath(null)
+    setAddressDraft('')
+    setAddressEditing(false)
+    setListing(null)
+    setStagedPaths([])
+    setError(null)
+    setResults(null)
+    setAdding(false)
+  }, [folderPickerOpen])
+
+  const entries = listing?.entries ?? []
+  const addressPath = cleanAddressInput(addressEditing ? addressDraft : (listing?.current ?? ''))
+  const normalizedAddressPath = addressPath ? normalizePath(addressPath) : ''
+  const addressAlreadyAdded = normalizedAddressPath
+    ? libraryPaths.has(normalizedAddressPath)
+    : false
+  const addressAlreadyStaged = normalizedAddressPath ? stagedSet.has(normalizedAddressPath) : false
+
+  const togglePath = (path: string) => {
+    const normalized = normalizePath(path)
+    if (libraryPaths.has(normalized)) return
+    setResults(null)
+    setStagedPaths((current) => {
+      const exists = current.some((staged) => normalizePath(staged) === normalized)
+      return exists
+        ? current.filter((staged) => normalizePath(staged) !== normalized)
+        : [...current, path]
+    })
+  }
+
+  const stagePath = (path: string) => {
+    const cleaned = cleanAddressInput(path)
+    if (!cleaned) {
+      setError('Enter a folder path first.')
+      return
+    }
+
+    const normalized = normalizePath(cleaned)
+    if (libraryPaths.has(normalized)) {
+      setError('That folder is already in your library.')
+      return
+    }
+    if (stagedSet.has(normalized)) {
+      setError('That folder is already selected.')
+      return
+    }
+
+    setError(null)
+    setResults(null)
+    setStagedPaths((current) => [...current, cleaned])
+  }
+
+  const navigateToAddress = () => {
+    const cleaned = cleanAddressInput(addressDraft)
+    setResults(null)
+    setError(null)
+    setCurrentPath(cleaned || null)
+  }
+
+  const updateAddressDraft = (nextDraft: string) => {
+    setAddressDraft(nextDraft)
+    setResults(null)
+  }
+
+  const beginAddressEdit = () => {
+    setAddressDraft(listing?.current ?? '')
+    setAddressEditing(true)
+  }
+
+  const removeStagedPath = (path: string) => {
+    const normalized = normalizePath(path)
+    setResults(null)
+    setStagedPaths((current) => current.filter((staged) => normalizePath(staged) !== normalized))
+  }
+
+  const clearStagedPaths = () => {
+    setResults(null)
+    setStagedPaths([])
+  }
+
+  const confirmAdd = async () => {
+    if (stagedPaths.length === 0 || adding) return
+    setAdding(true)
+    setError(null)
+    try {
+      const addResults = await addFolders(stagedPaths)
+      const failed = addResults.filter((result) => result.status === 'error')
+      setResults(addResults)
+      if (failed.length > 0) {
+        setStagedPaths(stagedPaths.filter((_, i) => addResults[i]?.status === 'error'))
+        setError(failed.map((failure) => failure.data).join('; '))
+        return
+      }
+      setFolderPickerOpen(false)
+    } catch (addError) {
+      setError(addError instanceof Error ? addError.message : String(addError))
+    } finally {
+      setAdding(false)
+    }
+  }
+
+  return {
+    adding,
+    addressAlreadyAdded,
+    addressAlreadyStaged,
+    addressDraft,
+    addressEditing,
+    addressInputRef,
+    addressPath,
+    beginAddressEdit,
+    breadcrumbs,
+    clearStagedPaths,
+    confirmAdd,
+    entries,
+    error,
+    folderPickerOpen,
+    libraryPaths,
+    listing,
+    loading,
+    navigateToAddress,
+    removeStagedPath,
+    results,
+    scrollRef,
+    setCurrentPath,
+    setFolderPickerOpen,
+    stagePath,
+    stagedPaths,
+    stagedSet,
+    togglePath,
+    updateAddressDraft,
+  }
+}

src/components/gallery/GalleryEmptyState.tsx

@@ -0,0 +1,76 @@
+import { ParsedSearch } from '../../store'
+import { PhotoIcon } from '../icons'
+
+export function GalleryLoadingState({
+  isSimilarResults,
+  parsedSearch,
+}: {
+  isSimilarResults: boolean
+  parsedSearch: ParsedSearch
+}) {
+  return (
+    <div className="absolute inset-0 flex flex-1 flex-col items-center justify-center gap-4 px-8 text-center">
+      <div className="min-w-72 rounded-2xl border border-white/[0.06] bg-white/[0.02] p-8">
+        <div className="mx-auto h-5 w-5 animate-spin rounded-full border-2 border-white/20 border-t-white/60" />
+        <p className="mt-4 text-sm font-medium text-white/40">
+          {isSimilarResults
+            ? 'Finding similar images'
+            : parsedSearch.mode === 'semantic' && parsedSearch.query.length > 0
+              ? `Searching for matches to "${parsedSearch.query}"`
+              : parsedSearch.mode === 'tag' && parsedSearch.query.length > 0
+                ? `Searching tags for "${parsedSearch.query}"`
+                : 'Loading media'}
+        </p>
+        <p className="mt-1 text-xs text-white/20">
+          {isSimilarResults
+            ? 'Comparing visual embeddings'
+            : parsedSearch.mode === 'semantic' && parsedSearch.query.length > 0
+              ? 'Semantic search can take a little longer than filename search'
+              : parsedSearch.mode === 'tag' && parsedSearch.query.length > 0
+                ? 'Matching against AI and user tags'
+                : 'Fetching results'}
+        </p>
+      </div>
+    </div>
+  )
+}
+
+export function GalleryEmptyState({
+  imageLoadError,
+  isSimilarResults,
+  parsedSearch,
+}: {
+  imageLoadError: string | null
+  isSimilarResults: boolean
+  parsedSearch: ParsedSearch
+}) {
+  return (
+    <div className="absolute inset-0 flex flex-1 flex-col items-center justify-center gap-4 px-8 text-center">
+      <div className="rounded-2xl border border-white/[0.06] bg-white/[0.02] p-8">
+        <PhotoIcon className="mx-auto mb-4 h-12 w-12 text-white/10" strokeWidth={0.75} />
+        <p className="text-sm font-medium text-white/30">
+          {imageLoadError
+            ? 'Could not load results'
+            : isSimilarResults
+              ? 'No similar images found'
+              : parsedSearch.mode === 'semantic' && parsedSearch.query.length > 0
+                ? 'No semantic matches found'
+                : parsedSearch.mode === 'tag' && parsedSearch.query.length > 0
+                  ? 'No tag matches found'
+                  : 'No media found'}
+        </p>
+        <p className="mt-1 text-xs text-white/15">
+          {imageLoadError
+            ? imageLoadError
+            : isSimilarResults
+              ? 'This item may be visually isolated, or more embeddings may need to finish processing'
+              : parsedSearch.mode === 'semantic' && parsedSearch.query.length > 0
+                ? 'Try a broader phrase, or wait for more embeddings to finish processing'
+                : parsedSearch.mode === 'tag' && parsedSearch.query.length > 0
+                  ? 'Try a shorter tag, or wait for more tagging jobs to finish'
+                  : 'Try adjusting your filters or add a new folder'}
+        </p>
+      </div>
+    </div>
+  )
+}

src/components/gallery/ImageTile.tsx

@@ -0,0 +1,170 @@
+import { useState } from 'react'
+import { ImageRecord, useGalleryStore } from '../../store'
+import { mediaSrc } from '../../lib/mediaSrc'
+import { Tooltip } from '../Tooltip'
+import { CheckIcon, PhotoIcon, PlayIcon, StarIcon, WarningIcon } from '../icons'
+import { formatDuration } from './format'
+import { TruncatedFilename } from './TruncatedFilename'
+
+export function ImageTile({
+  image,
+  onClick,
+  onContextMenu,
+}: {
+  image: ImageRecord
+  onClick: () => void
+  onContextMenu: (event: React.MouseEvent<HTMLDivElement>) => void
+}) {
+  const [loaded, setLoaded] = useState(false)
+  const [errored, setErrored] = useState(false)
+  const findSimilar = useGalleryStore((state) => state.findSimilar)
+  const selected = useGalleryStore((state) => state.gallerySelectedIds.has(image.id))
+  const selectionActive = useGalleryStore((state) => state.gallerySelectedIds.size > 0)
+  const toggleGallerySelected = useGalleryStore((state) => state.toggleGallerySelected)
+  const canFindSimilar = image.embedding_status === 'ready'
+
+  const src = mediaSrc(image.thumbnail_path)
+
+  return (
+    <div
+      className={`media-dark-surface group relative overflow-hidden rounded-xl bg-white/[0.04] text-left transition-shadow focus:outline-none ${
+        selected ? 'ring-2 ring-blue-400/80 ring-inset' : ''
+      }`}
+      style={{ width: '100%', aspectRatio: '1 / 1' }}
+      onContextMenu={onContextMenu}
+    >
+      <button
+        type="button"
+        className="absolute inset-0 z-10 cursor-pointer focus:outline-none focus-visible:ring-2 focus-visible:ring-blue-400/80"
+        aria-label={`Open ${image.filename}`}
+        onClick={(event) => {
+          event.stopPropagation()
+          if (selectionActive) toggleGallerySelected(image.id)
+          else onClick()
+        }}
+        onDoubleClick={(event) => {
+          event.stopPropagation()
+          onClick()
+        }}
+      />
+      <button
+        type="button"
+        role="checkbox"
+        aria-checked={selected}
+        aria-label={selected ? 'Deselect' : 'Select'}
+        className="group/cb absolute top-0 left-0 z-20 h-11 w-11 cursor-pointer"
+        onClick={(event) => {
+          event.stopPropagation()
+          toggleGallerySelected(image.id)
+        }}
+      >
+        <div
+          className={`absolute top-2 left-2 flex h-5 w-5 items-center justify-center rounded-full border transition-all duration-150 ${
+            selected
+              ? 'border-blue-400 bg-blue-500 text-white opacity-100'
+              : 'border-white/70 bg-black/40 text-transparent opacity-0 backdrop-blur-sm group-hover/cb:opacity-100'
+          }`}
+        >
+          <CheckIcon className="h-3 w-3" strokeWidth={3} />
+        </div>
+      </button>
+
+      {src && !errored ? (
+        <>
+          {!loaded ? <div className="absolute inset-0 animate-pulse bg-white/[0.04]" /> : null}
+          <img
+            src={src}
+            alt={image.filename}
+            className={`h-full w-full object-cover transition-all duration-300 ${
+              loaded ? 'scale-100 opacity-100' : 'scale-[1.02] opacity-0'
+            } group-hover:scale-[1.03]`}
+            loading="lazy"
+            onLoad={() => setLoaded(true)}
+            onError={() => setErrored(true)}
+          />
+        </>
+      ) : (
+        <div className="absolute inset-0 flex items-center justify-center bg-white/[0.03] text-white/20">
+          {image.media_kind === 'video' ? (
+            <PlayIcon className="h-7 w-7" />
+          ) : (
+            <PhotoIcon className="h-7 w-7" strokeWidth={1} />
+          )}
+        </div>
+      )}
+
+      {image.media_kind === 'video' ? (
+        <div className="pointer-events-none absolute inset-0 flex items-center justify-center">
+          <div className="rounded-full bg-black/40 p-3 text-white opacity-50 backdrop-blur-sm transition-opacity duration-200 group-hover:opacity-90">
+            <PlayIcon className="h-5 w-5" />
+          </div>
+        </div>
+      ) : null}
+
+      <div className="pointer-events-none absolute top-2 right-2 flex flex-col items-end gap-1">
+        {image.embedding_status === 'failed' ? (
+          <Tooltip
+            label={image.embedding_error ?? 'Embedding failed'}
+            followCursor
+            className="pointer-events-auto"
+          >
+            <div className="flex items-center gap-1 rounded-md bg-black/60 px-1.5 py-0.5 text-[10px] font-medium text-amber-400 backdrop-blur-sm">
+              <WarningIcon className="h-2.5 w-2.5 shrink-0" strokeWidth={2.5} />
+            </div>
+          </Tooltip>
+        ) : null}
+        {image.favorite ? (
+          <div className="rounded-full bg-black/50 p-1 text-rose-400 backdrop-blur-sm">
+            <svg className="h-2.5 w-2.5" fill="currentColor" viewBox="0 0 20 20">
+              <path d="M3.172 5.172a4 4 0 015.656 0L10 6.343l1.172-1.171a4 4 0 115.656 5.656L10 17.657l-6.828-6.829a4 4 0 010-5.656z" />
+            </svg>
+          </div>
+        ) : null}
+        {image.rating > 0 ? (
+          <div className="flex items-center gap-0.5 rounded-md bg-black/60 px-1.5 py-1 text-amber-300 backdrop-blur-sm">
+            {Array.from({ length: image.rating }, (_, index) => (
+              <StarIcon key={index} className="h-2.5 w-2.5" />
+            ))}
+          </div>
+        ) : null}
+        {image.media_kind === 'video' && image.duration_ms ? (
+          <div className="rounded-md bg-black/60 px-1.5 py-0.5 text-[10px] font-medium text-white/80 backdrop-blur-sm">
+            {formatDuration(image.duration_ms)}
+          </div>
+        ) : null}
+      </div>
+
+      <div className="pointer-events-none absolute inset-0 bg-gradient-to-t from-black/85 via-black/30 to-transparent opacity-0 transition-opacity duration-200 group-hover:opacity-100" />
+
+      <div className="absolute right-0 bottom-0 left-0 z-20 translate-y-1 p-2.5 opacity-0 transition-all duration-200 group-hover:translate-y-0 group-hover:opacity-100">
+        <TruncatedFilename filename={image.filename} />
+        <div className="mt-1.5 flex items-center justify-between gap-2">
+          {image.rating > 0 ? (
+            <div className="flex items-center gap-0.5">
+              {Array.from({ length: image.rating }, (_, index) => (
+                <StarIcon key={index} className="h-2.5 w-2.5 text-amber-300" />
+              ))}
+            </div>
+          ) : (
+            <span />
+          )}
+          <button
+            className={`pointer-events-auto relative z-20 rounded-md px-2 py-0.5 text-[10px] backdrop-blur-sm transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-blue-400/80 ${
+              canFindSimilar
+                ? 'bg-white/10 text-white/80 hover:bg-white/20 hover:text-white'
+                : 'cursor-not-allowed bg-white/5 text-white/30'
+            }`}
+            onClick={(event) => {
+              event.stopPropagation()
+              if (!canFindSimilar) return
+              findSimilar(image.id, image.folder_id)
+            }}
+            disabled={!canFindSimilar}
+          >
+            Similar
+          </button>
+        </div>
+      </div>
+    </div>
+  )
+}

src/components/gallery/TruncatedFilename.tsx

@@ -0,0 +1,34 @@
+import { useLayoutEffect, useRef, useState } from 'react'
+import { Tooltip } from '../Tooltip'
+
+export function TruncatedFilename({ filename }: { filename: string }) {
+  const textRef = useRef<HTMLParagraphElement>(null)
+  const [isTruncated, setIsTruncated] = useState(false)
+
+  useLayoutEffect(() => {
+    const text = textRef.current
+    if (!text) return
+
+    const update = () => {
+      setIsTruncated(text.scrollWidth > text.clientWidth)
+    }
+
+    update()
+
+    const observer = new ResizeObserver(update)
+    observer.observe(text)
+    return () => observer.disconnect()
+  }, [filename])
+
+  const label = (
+    <p ref={textRef} className="truncate text-[12px] leading-tight font-medium text-white">
+      {filename}
+    </p>
+  )
+
+  return (
+    <Tooltip label={filename} delay={500} block followCursor disabled={!isTruncated}>
+      {label}
+    </Tooltip>
+  )
+}

src/components/gallery/format.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'vitest'
+import { formatDuration } from './format'
+
+describe('formatDuration', () => {
+  it('returns null for missing or non-positive durations', () => {
+    expect(formatDuration(null)).toBeNull()
+    expect(formatDuration(0)).toBeNull()
+    expect(formatDuration(-100)).toBeNull()
+  })
+
+  it('formats sub-hour durations as M:SS', () => {
+    expect(formatDuration(1000)).toBe('0:01')
+    expect(formatDuration(59_999)).toBe('0:59')
+    expect(formatDuration(65_000)).toBe('1:05')
+  })
+
+  it('formats hour-plus durations as H:MM:SS', () => {
+    expect(formatDuration(3_600_000)).toBe('1:00:00')
+    expect(formatDuration(3_661_000)).toBe('1:01:01')
+  })
+})

src/components/gallery/format.ts

@@ -0,0 +1,11 @@
+export function formatDuration(durationMs: number | null): string | null {
+  if (!durationMs || durationMs <= 0) return null
+  const totalSeconds = Math.floor(durationMs / 1000)
+  const seconds = totalSeconds % 60
+  const minutes = Math.floor(totalSeconds / 60) % 60
+  const hours = Math.floor(totalSeconds / 3600)
+  if (hours > 0) {
+    return `${hours}:${minutes.toString().padStart(2, '0')}:${seconds.toString().padStart(2, '0')}`
+  }
+  return `${minutes}:${seconds.toString().padStart(2, '0')}`
+}

src/components/icons.tsx

@@ -0,0 +1,66 @@
+/**
+ * Shared icons for paths that repeat across the app. One-off icons stay
+ * inline at their call site — only extract here once a shape shows up in
+ * three or more places. Stroke icons take a per-site strokeWidth because
+ * weights legitimately differ by context (menus vs badges vs empty states).
+ */
+
+export interface IconProps {
+  className?: string
+  strokeWidth?: number
+}
+
+function strokeIcon(d: string, defaultStrokeWidth: number, displayName: string) {
+  function Icon({ className = '', strokeWidth = defaultStrokeWidth }: IconProps) {
+    return (
+      <svg
+        className={className}
+        fill="none"
+        viewBox="0 0 24 24"
+        stroke="currentColor"
+        aria-hidden="true"
+      >
+        <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={strokeWidth} d={d} />
+      </svg>
+    )
+  }
+  Icon.displayName = displayName
+  return Icon
+}
+
+export const CheckIcon = strokeIcon('M5 13l4 4L19 7', 2.5, 'CheckIcon')
+export const CloseIcon = strokeIcon('M6 18L18 6M6 6l12 12', 2, 'CloseIcon')
+export const ChevronDownIcon = strokeIcon('M19 9l-7 7-7-7', 2, 'ChevronDownIcon')
+export const ChevronRightIcon = strokeIcon('M9 5l7 7-7 7', 2, 'ChevronRightIcon')
+export const PlusIcon = strokeIcon('M12 4v16m8-8H4', 1.75, 'PlusIcon')
+export const PhotoIcon = strokeIcon(
+  'M4 16l4.586-4.586a2 2 0 012.828 0L16 16m-2-2l1.586-1.586a2 2 0 012.828 0L20 14m-6-6h.01M6 20h12a2 2 0 002-2V6a2 2 0 00-2-2H6a2 2 0 00-2 2v12a2 2 0 002 2z',
+  1.5,
+  'PhotoIcon'
+)
+export const FolderIcon = strokeIcon(
+  'M3 7a2 2 0 012-2h3.586a1 1 0 01.707.293l1.414 1.414A1 1 0 0011.414 7H19a2 2 0 012 2v9a2 2 0 01-2 2H5a2 2 0 01-2-2V7z',
+  1.5,
+  'FolderIcon'
+)
+export const WarningIcon = strokeIcon(
+  'M12 9v2m0 4h.01M10.29 3.86L1.82 18a2 2 0 001.71 3h16.94a2 2 0 001.71-3L13.71 3.86a2 2 0 00-3.42 0z',
+  2,
+  'WarningIcon'
+)
+
+export function StarIcon({ className = '' }: { className?: string }) {
+  return (
+    <svg className={className} fill="currentColor" viewBox="0 0 20 20" aria-hidden="true">
+      <path d="M9.049 2.927c.3-.921 1.603-.921 1.902 0l1.07 3.292a1 1 0 00.95.69h3.462c.969 0 1.371 1.24.588 1.81l-2.8 2.034a1 1 0 00-.364 1.118l1.07 3.292c.3.921-.755 1.688-1.54 1.118l-2.8-2.034a1 1 0 00-1.176 0l-2.8 2.034c-.784.57-1.838-.197-1.539-1.118l1.07-3.292a1 1 0 00-.364-1.118L2.98 8.72c-.783-.57-.38-1.81.588-1.81H7.03a1 1 0 00.951-.69l1.07-3.292z" />
+    </svg>
+  )
+}
+
+export function PlayIcon({ className = '' }: { className?: string }) {
+  return (
+    <svg className={className} fill="currentColor" viewBox="0 0 24 24" aria-hidden="true">
+      <path d="M8 5v14l11-7z" />
+    </svg>
+  )
+}

src/components/lightbox/LightboxAlbumMenu.tsx

@@ -0,0 +1,104 @@
+import { useState } from 'react'
+import { Album } from '../../store'
+
+interface LightboxAlbumMenuProps {
+  imageId: number
+  albums: Album[]
+  addToAlbum: (albumId: number, imageIds: number[]) => Promise<number>
+  createAlbum: (name: string) => Promise<Album>
+}
+
+export function LightboxAlbumMenu({
+  imageId,
+  albums,
+  addToAlbum,
+  createAlbum,
+}: LightboxAlbumMenuProps) {
+  const [albumMenuOpen, setAlbumMenuOpen] = useState(false)
+  const [albumAddedTo, setAlbumAddedTo] = useState<number | null>(null)
+  const [newAlbumName, setNewAlbumName] = useState('')
+  const [albumAdding, setAlbumAdding] = useState(false)
+
+  return (
+    <div className="relative">
+      <div className="mb-2 flex items-center justify-between">
+        <p className="text-xs tracking-wider text-gray-500 uppercase">Albums</p>
+        <button
+          className="rounded-md border border-white/10 bg-white/5 px-2 py-0.5 text-[10px] text-gray-400 transition-colors hover:bg-white/10 hover:text-white"
+          onClick={() => {
+            setAlbumMenuOpen((open) => !open)
+            setAlbumAddedTo(null)
+          }}
+        >
+          Add to album
+        </button>
+      </div>
+      {albumMenuOpen ? (
+        <div className="rounded-lg border border-white/10 bg-white/[0.03] p-1.5">
+          <div className="max-h-40 overflow-y-auto">
+            {albums.length === 0 ? (
+              <p className="px-2 py-1.5 text-[11px] text-gray-600">
+                No albums yet — create one below.
+              </p>
+            ) : (
+              albums.map((album) => (
+                <button
+                  key={album.id}
+                  className="flex w-full items-center justify-between gap-2 rounded-md px-2 py-1 text-left text-xs text-gray-300 transition-colors hover:bg-white/5 hover:text-white"
+                  onClick={() => {
+                    if (albumAdding) return
+                    setAlbumAdding(true)
+                    void addToAlbum(album.id, [imageId])
+                      .then(() => setAlbumAddedTo(album.id))
+                      .catch(() => undefined)
+                      .finally(() => setAlbumAdding(false))
+                  }}
+                  disabled={albumAdding}
+                >
+                  <span className="truncate">{album.name}</span>
+                  {albumAddedTo === album.id ? (
+                    <span className="shrink-0 text-[10px] text-emerald-400">Added</span>
+                  ) : (
+                    <span className="shrink-0 text-[10px] text-gray-600">{album.image_count}</span>
+                  )}
+                </button>
+              ))
+            )}
+          </div>
+          <form
+            className="mt-1 flex gap-1 border-t border-white/[0.06] pt-1.5"
+            onSubmit={(event) => {
+              event.preventDefault()
+              const name = newAlbumName.trim()
+              if (!name || albumAdding) return
+              setAlbumAdding(true)
+              void createAlbum(name)
+                .then(async (album) => {
+                  await addToAlbum(album.id, [imageId])
+                  setAlbumAddedTo(album.id)
+                  setNewAlbumName('')
+                })
+                .catch(() => undefined)
+                .finally(() => setAlbumAdding(false))
+            }}
+          >
+            <input
+              className="min-w-0 flex-1 rounded-md border border-white/10 bg-white/5 px-2 py-1 text-xs text-white placeholder-gray-600 focus:border-white/20 focus:outline-none"
+              placeholder="New album…"
+              value={newAlbumName}
+              onChange={(event) => setNewAlbumName(event.target.value)}
+              disabled={albumAdding}
+            />
+            <button
+              type="submit"
+              className="rounded-md border border-white/10 bg-white/5 px-2 py-1 text-xs text-gray-300 transition-colors hover:bg-white/10 hover:text-white disabled:opacity-50"
+              disabled={albumAdding || !newAlbumName.trim()}
+            >
+              Add
+            </button>
+          </form>
+        </div>
+      ) : null}
+    </div>
+  )
+}

src/components/lightbox/LightboxDetailsPanel.tsx

@@ -0,0 +1,509 @@
+import { MutableRefObject } from 'react'
+import { invoke } from '@tauri-apps/api/core'
+import { revealItemInDir } from '@tauri-apps/plugin-opener'
+import { Album, ImageExif, ImageRecord, ImageTag } from '../../store'
+import { Tooltip } from '../Tooltip'
+import { CloseIcon, StarIcon } from '../icons'
+import { embeddingLabel, formatBytes, formatDate, formatDuration, ratingPill } from './format'
+import { LightboxAlbumMenu } from './LightboxAlbumMenu'
+
+interface LightboxDetailsPanelProps {
+  selectedImage: ImageRecord
+  currentIndex: number
+  imageCount: number
+  imageTags: ImageTag[]
+  setImageTags: React.Dispatch<React.SetStateAction<ImageTag[]>>
+  imageExif: ImageExif | null
+  tagInput: string
+  setTagInput: React.Dispatch<React.SetStateAction<string>>
+  tagAdding: boolean
+  setTagAdding: React.Dispatch<React.SetStateAction<boolean>>
+  tagsExpanded: boolean
+  setTagsExpanded: React.Dispatch<React.SetStateAction<boolean>>
+  taggingQueued: boolean
+  setTaggingQueued: React.Dispatch<React.SetStateAction<boolean>>
+  currentImageIdRef: MutableRefObject<number | null>
+  albums: Album[]
+  canFindSimilar: boolean
+  canSearchRegion: boolean
+  regionSelectMode: boolean
+  regionSearching: boolean
+  taggerReady: boolean
+  taggerButtonTooltip: string
+  closeImage: () => void
+  findSimilar: (imageId: number, sourceFolderId: number | null) => Promise<void>
+  updateImageDetails: (
+    imageId: number,
+    updates: { favorite?: boolean; rating?: number }
+  ) => Promise<void>
+  addUserTag: (imageId: number, tag: string) => Promise<ImageTag>
+  removeTag: (tagId: number) => Promise<void>
+  queueTaggingForImage: (imageId: number) => Promise<number>
+  addToAlbum: (albumId: number, imageIds: number[]) => Promise<number>
+  createAlbum: (name: string) => Promise<Album>
+  onToggleRegionMode: () => void
+}
+
+export function LightboxDetailsPanel({
+  selectedImage,
+  currentIndex,
+  imageCount,
+  imageTags,
+  setImageTags,
+  imageExif,
+  tagInput,
+  setTagInput,
+  tagAdding,
+  setTagAdding,
+  tagsExpanded,
+  setTagsExpanded,
+  taggingQueued,
+  setTaggingQueued,
+  currentImageIdRef,
+  albums,
+  canFindSimilar,
+  canSearchRegion,
+  regionSelectMode,
+  regionSearching,
+  taggerReady,
+  taggerButtonTooltip,
+  closeImage,
+  findSimilar,
+  updateImageDetails,
+  addUserTag,
+  removeTag,
+  queueTaggingForImage,
+  addToAlbum,
+  createAlbum,
+  onToggleRegionMode,
+}: LightboxDetailsPanelProps) {
+  const aiRating = selectedImage.ai_rating ? ratingPill(selectedImage.ai_rating) : null
+  const hasCameraInfo =
+    imageExif &&
+    (imageExif.make ||
+      imageExif.model ||
+      imageExif.lens ||
+      imageExif.f_number ||
+      imageExif.exposure_time ||
+      imageExif.iso ||
+      imageExif.focal_length ||
+      (imageExif.gps_lat != null && imageExif.gps_lon != null))
+
+  return (
+    <div className="lightbox-panel flex w-64 shrink-0 flex-col border-l border-white/5 bg-gray-900/95 lg:w-72">
+      <div className="flex shrink-0 items-center justify-between px-5 pt-5 pb-4">
+        <div className="min-w-0">
+          <p className="truncate text-sm font-medium text-white">{selectedImage.filename}</p>
+          <p className="text-xs text-gray-500">Details</p>
+        </div>
+        <div className="flex items-center gap-2">
+          <Tooltip label={selectedImage.favorite ? 'Remove favorite' : 'Add favorite'} followCursor>
+            <button
+              className={`rounded-full border p-2 ${selectedImage.favorite ? 'border-rose-400/40 bg-rose-500/10 text-rose-300' : 'border-white/10 bg-white/5 text-gray-400 hover:text-white'}`}
+              onClick={() =>
+                void updateImageDetails(selectedImage.id, { favorite: !selectedImage.favorite })
+              }
+            >
+              <svg className="h-4 w-4" fill="currentColor" viewBox="0 0 20 20">
+                <path d="M3.172 5.172a4 4 0 015.656 0L10 6.343l1.172-1.171a4 4 0 115.656 5.656L10 17.657l-6.828-6.829a4 4 0 010-5.656z" />
+              </svg>
+            </button>
+          </Tooltip>
+          <Tooltip
+            label={canFindSimilar ? 'Find similar images' : 'Embeddings not ready'}
+            followCursor
+          >
+            <button
+              className={`flex items-center gap-1.5 rounded-full border px-2 py-1.5 text-xs lg:px-3 ${
+                canFindSimilar
+                  ? 'border-white/10 bg-white/5 text-gray-300 hover:text-white'
+                  : 'cursor-not-allowed border-white/5 bg-white/[0.03] text-gray-600'
+              }`}
+              onClick={() => {
+                if (!canFindSimilar) return
+                void findSimilar(selectedImage.id, selectedImage.folder_id)
+              }}
+              disabled={!canFindSimilar}
+            >
+              <svg
+                className="h-4 w-4 shrink-0"
+                fill="none"
+                viewBox="0 0 24 24"
+                stroke="currentColor"
+              >
+                <path
+                  strokeLinecap="round"
+                  strokeLinejoin="round"
+                  strokeWidth={1.6}
+                  d="M13 3l1.55 4.65L19 9.2l-4.45 1.55L13 15.4l-1.55-4.65L7 9.2l4.45-1.55L13 3z"
+                />
+                <path
+                  strokeLinecap="round"
+                  strokeLinejoin="round"
+                  strokeWidth={1.6}
+                  d="M5.5 14.5l.8 2.2 2.2.8-2.2.8-.8 2.2-.8-2.2L2.5 17.5l2.2-.8.8-2.2z"
+                />
+              </svg>
+              <span className="hidden lg:inline">
+                {canFindSimilar ? 'Similar' : 'Embeddings not ready'}
+              </span>
+            </button>
+          </Tooltip>
+        </div>
+        <button className="rounded p-1 text-gray-400 hover:text-white" onClick={closeImage}>
+          <CloseIcon className="h-4 w-4" />
+        </button>
+      </div>
+
+      {canSearchRegion && (
+        <div className="shrink-0 px-5 pb-3">
+          <Tooltip
+            label={
+              regionSelectMode
+                ? 'Cancel region selection'
+                : 'Draw a region on the image to search for similar content'
+            }
+            followCursor
+          >
+            <button
+              className={`w-full rounded-lg border px-3 py-2 text-xs transition-colors ${
+                regionSelectMode
+                  ? 'border-violet-400/40 bg-violet-500/15 text-violet-300 hover:bg-violet-500/20'
+                  : regionSearching
+                    ? 'cursor-not-allowed border-white/5 bg-white/[0.03] text-gray-500'
+                    : 'border-white/10 bg-white/5 text-gray-300 hover:bg-white/10 hover:text-white'
+              }`}
+              onClick={() => {
+                if (regionSearching) return
+                onToggleRegionMode()
+              }}
+              disabled={regionSearching}
+            >
+              {regionSearching ? (
+                <span className="flex items-center justify-center gap-1.5">
+                  <svg className="h-3 w-3 animate-spin" fill="none" viewBox="0 0 24 24">
+                    <circle
+                      className="opacity-25"
+                      cx="12"
+                      cy="12"
+                      r="10"
+                      stroke="currentColor"
+                      strokeWidth="4"
+                    />
+                    <path className="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8v8H4z" />
+                  </svg>
+                  Searching region…
+                </span>
+              ) : regionSelectMode ? (
+                <span className="flex items-center justify-center gap-1.5">
+                  <CloseIcon className="h-3 w-3" />
+                  Cancel selection
+                </span>
+              ) : (
+                <span className="flex items-center justify-center gap-1.5">
+                  <svg className="h-3 w-3" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                    <path
+                      strokeLinecap="round"
+                      strokeLinejoin="round"
+                      strokeWidth={2}
+                      d="M4 8V4m0 0h4M4 4l5 5m11-1V4m0 0h-4m4 0l-5 5M4 16v4m0 0h4m-4 0l5-5m11 5l-5-5m5 5v-4m0 4h-4"
+                    />
+                  </svg>
+                  Search within image
+                </span>
+              )}
+            </button>
+          </Tooltip>
+        </div>
+      )}
+
+      <div className="min-h-0 flex-1 space-y-4 overflow-y-auto px-5 pb-4 text-sm">
+        <div className="grid grid-cols-2 gap-x-6 gap-y-4">
+          <div className="col-span-2">
+            <p className="mb-1 text-xs tracking-wider text-gray-500 uppercase">Rating</p>
+            <div className="flex items-center gap-1">
+              {Array.from({ length: 5 }, (_, index) => {
+                const rating = index + 1
+                return (
+                  <Tooltip
+                    key={rating}
+                    label={`Set ${rating} star rating`}
+                    followCursor
+                    delay={750}
+                  >
+                    <button
+                      className="rounded-md p-1"
+                      onClick={() => void updateImageDetails(selectedImage.id, { rating })}
+                    >
+                      <StarIcon
+                        className={`h-5 w-5 ${rating <= selectedImage.rating ? 'text-amber-300' : 'text-white/20 hover:text-white/50'}`}
+                      />
+                    </button>
+                  </Tooltip>
+                )
+              })}
+              {selectedImage.rating > 0 ? (
+                <Tooltip label="Remove rating" followCursor>
+                  <button
+                    className="ml-2 rounded-md border border-white/10 p-1.5 text-gray-400 hover:bg-white/5 hover:text-white"
+                    onClick={() => void updateImageDetails(selectedImage.id, { rating: 0 })}
+                  >
+                    <CloseIcon className="h-3.5 w-3.5" />
+                  </button>
+                </Tooltip>
+              ) : null}
+            </div>
+          </div>
+
+          <div>
+            <p className="mb-1 text-xs tracking-wider text-gray-500 uppercase">Dimensions</p>
+            <p className="text-white">
+              {selectedImage.width && selectedImage.height
+                ? `${selectedImage.width} x ${selectedImage.height}px`
+                : 'Pending / unavailable'}
+            </p>
+          </div>
+
+          {selectedImage.media_kind === 'video' ? (
+            <>
+              <div>
+                <p className="mb-1 text-xs tracking-wider text-gray-500 uppercase">Duration</p>
+                <p className="text-white">{formatDuration(selectedImage.duration_ms)}</p>
+              </div>
+              <div>
+                <p className="mb-1 text-xs tracking-wider text-gray-500 uppercase">Video codec</p>
+                <p className="text-white">{selectedImage.video_codec ?? 'Pending / unavailable'}</p>
+              </div>
+              <div>
+                <p className="mb-1 text-xs tracking-wider text-gray-500 uppercase">Audio codec</p>
+                <p className="text-white">{selectedImage.audio_codec ?? 'None / unavailable'}</p>
+              </div>
+              {selectedImage.metadata_error ? (
+                <div className="col-span-2">
+                  <p className="mb-1 text-xs tracking-wider text-gray-500 uppercase">Metadata</p>
+                  <p className="text-amber-300">{selectedImage.metadata_error}</p>
+                </div>
+              ) : null}
+            </>
+          ) : null}
+
+          <div>
+            <p className="mb-1 text-xs tracking-wider text-gray-500 uppercase">Type</p>
+            <p className="text-white">{selectedImage.mime_type}</p>
+          </div>
+          <div>
+            <p className="mb-1 text-xs tracking-wider text-gray-500 uppercase">File size</p>
+            <p className="text-white">{formatBytes(selectedImage.file_size)}</p>
+          </div>
+          <div className="col-span-2">
+            <p className="mb-1 text-xs tracking-wider text-gray-500 uppercase">Modified</p>
+            <p className="text-white">{formatDate(selectedImage.modified_at)}</p>
+          </div>
+          <div className="col-span-2">
+            <p className="mb-1 text-xs tracking-wider text-gray-500 uppercase">Embedding</p>
+            <p className="text-white">
+              {embeddingLabel(selectedImage.embedding_status, selectedImage.embedding_model)}
+            </p>
+            {selectedImage.embedding_error ? (
+              <p className="mt-1 text-xs text-amber-300">{selectedImage.embedding_error}</p>
+            ) : null}
+          </div>
+        </div>
+
+        <div>
+          <div className="mb-2 flex items-center justify-between">
+            <p className="text-xs tracking-wider text-gray-500 uppercase">Tags</p>
+            <div className="flex items-center gap-1.5">
+              {aiRating ? (
+                <span
+                  className={`rounded-md border px-1.5 py-0.5 text-[10px] font-medium ${aiRating.className}`}
+                >
+                  {aiRating.label}
+                </span>
+              ) : null}
+              {selectedImage.media_kind === 'image' ? (
+                <Tooltip label={taggerButtonTooltip} followCursor>
+                  <button
+                    className="rounded-md border border-white/10 bg-white/5 px-2 py-0.5 text-[10px] text-gray-400 transition-colors hover:bg-white/10 hover:text-white disabled:cursor-not-allowed disabled:opacity-40"
+                    disabled={!taggerReady || taggingQueued}
+                    onClick={() => {
+                      setTaggingQueued(true)
+                      void queueTaggingForImage(selectedImage.id).catch(() => undefined)
+                    }}
+                  >
+                    {taggingQueued ? 'Queued' : 'AI tags'}
+                  </button>
+                </Tooltip>
+              ) : null}
+            </div>
+          </div>
+
+          {imageTags.length > 0 ? (
+            <>
+              <div className="flex flex-wrap gap-1.5">
+                {(tagsExpanded ? imageTags : imageTags.slice(0, 8)).map((tag) => (
+                  <Tooltip
+                    key={tag.id}
+                    label={
+                      tag.source === 'ai' && tag.confidence !== null
+                        ? `AI confidence: ${(tag.confidence * 100).toFixed(0)}%`
+                        : ''
+                    }
+                    followCursor
+                    disabled={tag.source !== 'ai' || tag.confidence === null}
+                  >
+                    <span
+                      className={`group flex items-center gap-1 rounded-md border px-2 py-0.5 text-xs ${
+                        tag.source === 'ai'
+                          ? 'border-sky-400/20 bg-sky-500/8 text-sky-300'
+                          : 'border-white/10 bg-white/5 text-gray-300'
+                      }`}
+                    >
+                      {tag.tag}
+                      <Tooltip label="Remove tag" followCursor>
+                        <button
+                          className="text-gray-600 opacity-0 transition-opacity group-hover:opacity-100 hover:text-white"
+                          onClick={() => {
+                            void removeTag(tag.id).then(() =>
+                              setImageTags((prev) => prev.filter((item) => item.id !== tag.id))
+                            )
+                          }}
+                        >
+                          <CloseIcon className="h-3 w-3" />
+                        </button>
+                      </Tooltip>
+                    </span>
+                  </Tooltip>
+                ))}
+              </div>
+              {imageTags.length > 8 && (
+                <button
+                  className="mt-1.5 text-xs text-gray-500 transition-colors hover:text-gray-300"
+                  onClick={() => setTagsExpanded((expanded) => !expanded)}
+                >
+                  {tagsExpanded ? 'Show less' : `+${imageTags.length - 8} more`}
+                </button>
+              )}
+            </>
+          ) : (
+            <p className="text-xs text-gray-600">No tags yet</p>
+          )}
+
+          <form
+            className="mt-2 flex gap-1.5"
+            onSubmit={(event) => {
+              event.preventDefault()
+              const raw = tagInput.trim()
+              if (!raw || tagAdding) return
+              setTagAdding(true)
+              const taggedImageId = selectedImage.id
+              void addUserTag(taggedImageId, raw)
+                .then((newTag) => {
+                  if (currentImageIdRef.current !== taggedImageId) return
+                  setImageTags((prev) => [...prev, newTag])
+                  setTagInput('')
+                })
+                .catch(() => undefined)
+                .finally(() => setTagAdding(false))
+            }}
+          >
+            <input
+              className="min-w-0 flex-1 rounded-md border border-white/10 bg-white/5 px-2 py-1 text-xs text-white placeholder-gray-600 focus:border-white/20 focus:outline-none"
+              placeholder="Add tag…"
+              value={tagInput}
+              onChange={(event) => setTagInput(event.target.value)}
+              disabled={tagAdding}
+            />
+            <button
+              type="submit"
+              className="rounded-md border border-white/10 bg-white/5 px-2.5 py-1 text-xs text-gray-300 transition-colors hover:bg-white/10 hover:text-white disabled:cursor-not-allowed disabled:opacity-50"
+              disabled={tagAdding || !tagInput.trim()}
+            >
+              Add
+            </button>
+          </form>
+        </div>
+
+        <LightboxAlbumMenu
+          imageId={selectedImage.id}
+          albums={albums}
+          addToAlbum={addToAlbum}
+          createAlbum={createAlbum}
+        />
+
+        {hasCameraInfo ? (
+          <div>
+            <p className="mb-2 text-xs tracking-wider text-gray-500 uppercase">Camera</p>
+            <div className="space-y-1.5">
+              {imageExif.make || imageExif.model ? (
+                <p className="text-sm text-white">
+                  {[imageExif.make, imageExif.model].filter(Boolean).join(' ')}
+                </p>
+              ) : null}
+              {imageExif.lens ? <p className="text-xs text-gray-400">{imageExif.lens}</p> : null}
+              {imageExif.f_number ||
+              imageExif.exposure_time ||
+              imageExif.iso ||
+              imageExif.focal_length ? (
+                <div className="flex flex-wrap gap-x-3 gap-y-1 text-xs text-gray-400">
+                  {imageExif.f_number ? <span>{imageExif.f_number}</span> : null}
+                  {imageExif.exposure_time ? <span>{imageExif.exposure_time}</span> : null}
+                  {imageExif.iso ? <span>ISO {imageExif.iso}</span> : null}
+                  {imageExif.focal_length ? <span>{imageExif.focal_length}</span> : null}
+                </div>
+              ) : null}
+              {imageExif.gps_lat != null && imageExif.gps_lon != null ? (
+                <Tooltip label="Open location in your browser" anchorToCursor>
+                  <button
+                    className="inline-flex items-center gap-1 text-xs text-sky-400 transition-colors hover:text-sky-300"
+                    onClick={() =>
+                      void invoke('open_map_location', {
+                        params: { lat: imageExif.gps_lat, lon: imageExif.gps_lon },
+                      })
+                    }
+                  >
+                    {imageExif.gps_lat.toFixed(5)}, {imageExif.gps_lon.toFixed(5)}
+                    <svg className="h-3 w-3" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                      <path
+                        strokeLinecap="round"
+                        strokeLinejoin="round"
+                        strokeWidth={2}
+                        d="M10 6H6a2 2 0 00-2 2v10a2 2 0 002 2h10a2 2 0 002-2v-4M14 4h6m0 0v6m0-6L10 14"
+                      />
+                    </svg>
+                  </button>
+                </Tooltip>
+              ) : null}
+            </div>
+          </div>
+        ) : null}
+
+        <div>
+          <div className="mb-1 flex items-center justify-between">
+            <p className="text-xs tracking-wider text-gray-500 uppercase">Path</p>
+            <Tooltip label="Reveal in Explorer" anchorToCursor>
+              <button
+                className="rounded p-0.5 text-gray-600 transition-colors hover:text-gray-300"
+                onClick={() => void revealItemInDir(selectedImage.path)}
+              >
+                <svg className="h-3.5 w-3.5" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                  <path
+                    strokeLinecap="round"
+                    strokeLinejoin="round"
+                    strokeWidth={1.5}
+                    d="M3 7a2 2 0 012-2h4l2 2h8a2 2 0 012 2v8a2 2 0 01-2 2H5a2 2 0 01-2-2V7z"
+                  />
+                </svg>
+              </button>
+            </Tooltip>
+          </div>
+          <p className="text-xs break-all text-gray-400">{selectedImage.path}</p>
+        </div>
+      </div>
+
+      <div className="mt-auto shrink-0 px-5 pt-2 pb-4 text-center text-xs text-gray-600">
+        {currentIndex + 1} / {imageCount}
+      </div>
+    </div>
+  )
+}

src/components/lightbox/LightboxNavButton.tsx

@@ -0,0 +1,33 @@
+import { ChevronRightIcon } from '../icons'
+
+interface LightboxNavButtonProps {
+  direction: 'previous' | 'next'
+  disabled: boolean
+  onClick: () => void
+}
+
+export function LightboxNavButton({ direction, disabled, onClick }: LightboxNavButtonProps) {
+  const isNext = direction === 'next'
+
+  return (
+    <button
+      className={`absolute top-1/2 z-10 -translate-y-1/2 rounded-full bg-white/10 p-3 text-white transition-colors hover:bg-white/20 disabled:opacity-20 ${
+        isNext ? 'right-72 lg:right-80' : 'left-4'
+      }`}
+      disabled={disabled}
+      onClick={(event) => {
+        event.stopPropagation()
+        onClick()
+      }}
+      aria-label={isNext ? 'Next image' : 'Previous image'}
+    >
+      {isNext ? (
+        <ChevronRightIcon className="h-5 w-5" />
+      ) : (
+        <svg className="h-5 w-5" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+          <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M15 19l-7-7 7-7" />
+        </svg>
+      )}
+    </button>
+  )
+}

src/components/lightbox/LightboxViewport.tsx

@@ -0,0 +1,200 @@
+import { AnimatePresence, motion } from 'framer-motion'
+import { RefObject } from 'react'
+import { ImageRecord } from '../../store'
+import { mediaSrc } from '../../lib/mediaSrc'
+import { VideoPlayer } from '../VideoPlayer'
+import { Tooltip } from '../Tooltip'
+import { SelectionOverlay, ViewTransform } from './types'
+import { MAX_ZOOM, MIN_ZOOM, zoomViewAt } from './viewTransform'
+
+interface LightboxViewportProps {
+  selectedImage: ImageRecord
+  imageViewportRef: RefObject<HTMLDivElement | null>
+  imgRef: RefObject<HTMLImageElement | null>
+  view: ViewTransform
+  zoom: number
+  regionSelectMode: boolean
+  isPanning: boolean
+  selectionOverlay: SelectionOverlay | null
+  canStartSlideshow: boolean
+  onStartSlideshow: () => void
+  onPointerDown: (event: React.PointerEvent<HTMLDivElement>) => void
+  onPointerMove: (event: React.PointerEvent<HTMLDivElement>) => void
+  onPointerUp: (event: React.PointerEvent<HTMLDivElement>) => void
+  setView: React.Dispatch<React.SetStateAction<ViewTransform>>
+  clampPan: (view: ViewTransform) => ViewTransform
+}
+
+export function LightboxViewport({
+  selectedImage,
+  imageViewportRef,
+  imgRef,
+  view,
+  zoom,
+  regionSelectMode,
+  isPanning,
+  selectionOverlay,
+  canStartSlideshow,
+  onStartSlideshow,
+  onPointerDown,
+  onPointerMove,
+  onPointerUp,
+  setView,
+  clampPan,
+}: LightboxViewportProps) {
+  return (
+    <div
+      ref={imageViewportRef}
+      className={`group relative flex flex-1 items-center justify-center overflow-hidden p-10 ${
+        regionSelectMode
+          ? 'cursor-crosshair select-none'
+          : isPanning
+            ? 'cursor-grabbing select-none'
+            : zoom > 1 && selectedImage.media_kind === 'image'
+              ? 'cursor-grab'
+              : ''
+      }`}
+      onPointerDown={onPointerDown}
+      onPointerMove={onPointerMove}
+      onPointerUp={onPointerUp}
+    >
+      {regionSelectMode && (
+        <div className="pointer-events-none absolute inset-x-0 top-4 z-20 flex justify-center">
+          <div className="flex items-center gap-2 rounded-full border border-white/15 bg-black/70 px-4 py-2 text-xs text-gray-300 backdrop-blur">
+            <svg
+              className="h-3.5 w-3.5 text-violet-400"
+              fill="none"
+              viewBox="0 0 24 24"
+              stroke="currentColor"
+            >
+              <path
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                strokeWidth={2}
+                d="M4 8V4m0 0h4M4 4l5 5m11-1V4m0 0h-4m4 0l-5 5M4 16v4m0 0h4m-4 0l5-5m11 5l-5-5m5 5v-4m0 4h-4"
+              />
+            </svg>
+            Draw a region to search —{' '}
+            <kbd className="ml-1 rounded border border-white/20 bg-white/10 px-1.5 py-0.5 font-mono text-[10px]">
+              Esc
+            </kbd>{' '}
+            to cancel
+          </div>
+        </div>
+      )}
+
+      {selectionOverlay && selectionOverlay.width > 4 && selectionOverlay.height > 4 && (
+        <div
+          className="pointer-events-none fixed z-30 rounded border-2 border-violet-400 bg-violet-400/15 shadow-[0_0_0_9999px_rgba(0,0,0,0.35)]"
+          style={{
+            left: selectionOverlay.left,
+            top: selectionOverlay.top,
+            width: selectionOverlay.width,
+            height: selectionOverlay.height,
+          }}
+        />
+      )}
+
+      <AnimatePresence mode="wait">
+        <motion.div
+          key={selectedImage.id}
+          className={
+            selectedImage.media_kind === 'video'
+              ? 'absolute inset-0'
+              : 'flex items-center justify-center'
+          }
+          initial={{ opacity: 0.3, scale: 0.985 }}
+          animate={{ opacity: 1, scale: 1 }}
+          exit={{ opacity: 0.3, scale: 0.985 }}
+          transition={{ duration: 0.12 }}
+        >
+          {selectedImage.media_kind === 'video' ? (
+            <VideoPlayer src={mediaSrc(selectedImage.path) ?? ''} />
+          ) : (
+            <img
+              ref={imgRef}
+              src={mediaSrc(selectedImage.path) ?? ''}
+              alt={selectedImage.filename}
+              className="max-w-full rounded-2xl shadow-2xl"
+              draggable={false}
+              style={{
+                maxHeight: 'calc(100vh - 10rem)',
+                transform: `translate(${view.panX}px, ${view.panY}px) scale(${zoom})`,
+                transformOrigin: 'center center',
+                ...(regionSelectMode ? { opacity: 0.85 } : {}),
+              }}
+            />
+          )}
+        </motion.div>
+      </AnimatePresence>
+
+      {!regionSelectMode && (
+        <div className="pointer-events-none absolute top-6 right-6 opacity-75 transition-opacity group-hover:opacity-100">
+          <div className="pointer-events-auto flex items-center gap-1 rounded-full border border-white/10 bg-black/55 p-1 shadow-2xl shadow-black/25 backdrop-blur">
+            <Tooltip
+              label={canStartSlideshow ? 'Start slideshow' : 'No images available for slideshow'}
+              followCursor
+            >
+              <button
+                aria-label="Start slideshow"
+                className={`rounded-full p-2 transition-colors ${
+                  canStartSlideshow
+                    ? 'text-gray-300 hover:bg-white/10 hover:text-white'
+                    : 'cursor-not-allowed text-gray-600'
+                }`}
+                disabled={!canStartSlideshow}
+                onClick={(event) => {
+                  event.stopPropagation()
+                  onStartSlideshow()
+                }}
+              >
+                <svg className="h-4 w-4" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                  <path
+                    strokeLinecap="round"
+                    strokeLinejoin="round"
+                    strokeWidth={1.8}
+                    d="M8 5.5v13l10-6.5-10-6.5z"
+                  />
+                </svg>
+              </button>
+            </Tooltip>
+            {selectedImage.media_kind === 'image' ? (
+              <>
+                <div className="mx-0.5 h-5 w-px bg-white/10" />
+                <button
+                  aria-label="Zoom out"
+                  className="rounded-full px-2 py-1 text-sm text-gray-300 transition-colors hover:bg-white/10 hover:text-white"
+                  onClick={() =>
+                    setView((currentView) =>
+                      clampPan(
+                        zoomViewAt(currentView, Math.max(MIN_ZOOM, currentView.zoom - 0.25), 0, 0)
+                      )
+                    )
+                  }
+                >
+                  -
+                </button>
+                <span className="min-w-14 text-center text-xs text-gray-300">
+                  {Math.round(zoom * 100)}%
+                </span>
+                <button
+                  aria-label="Zoom in"
+                  className="rounded-full px-2 py-1 text-sm text-gray-300 transition-colors hover:bg-white/10 hover:text-white"
+                  onClick={() =>
+                    setView((currentView) =>
+                      clampPan(
+                        zoomViewAt(currentView, Math.min(MAX_ZOOM, currentView.zoom + 0.25), 0, 0)
+                      )
+                    )
+                  }
+                >
+                  +
+                </button>
+              </>
+            ) : null}
+          </div>
+        </div>
+      )}
+    </div>
+  )
+}

src/components/lightbox/SlideshowView.tsx

@@ -0,0 +1,181 @@
+import { AnimatePresence, motion } from 'framer-motion'
+import { ImageRecord } from '../../store'
+import { mediaSrc } from '../../lib/mediaSrc'
+import { Tooltip } from '../Tooltip'
+import { ChevronRightIcon, CloseIcon } from '../icons'
+import { SlideshowMotion } from './useSlideshow'
+
+interface SlideshowViewProps {
+  selectedImage: ImageRecord
+  imageCount: number
+  position: number
+  controlsShown: boolean
+  paused: boolean
+  loadingMore: boolean
+  motionConfig: SlideshowMotion
+  onPointerMove: (event: React.PointerEvent<HTMLDivElement>) => void
+  onShowControls: () => void
+  onExit: () => void
+  onGo: (direction: -1 | 1) => void
+  onTogglePaused: () => void
+}
+
+export function SlideshowView({
+  selectedImage,
+  imageCount,
+  position,
+  controlsShown,
+  paused,
+  loadingMore,
+  motionConfig,
+  onPointerMove,
+  onShowControls,
+  onExit,
+  onGo,
+  onTogglePaused,
+}: SlideshowViewProps) {
+  return (
+    <div
+      className={`relative flex h-full w-full items-center justify-center overflow-hidden bg-black ${
+        controlsShown ? '' : 'cursor-none'
+      }`}
+      onClick={(event) => {
+        event.stopPropagation()
+        onShowControls()
+      }}
+      onPointerMove={onPointerMove}
+    >
+      <AnimatePresence initial={false}>
+        {selectedImage.media_kind === 'image' ? (
+          <motion.div
+            key={selectedImage.id}
+            className="absolute inset-0 flex items-center justify-center"
+            initial={motionConfig.imageInitial}
+            animate={motionConfig.imageAnimate}
+            exit={motionConfig.imageExit}
+            transition={motionConfig.imageTransition}
+          >
+            <motion.img
+              src={mediaSrc(selectedImage.path) ?? ''}
+              alt={selectedImage.filename}
+              className="max-h-full max-w-full object-contain"
+              draggable={false}
+              initial={motionConfig.contentInitial}
+              animate={motionConfig.contentAnimate}
+              transition={motionConfig.contentTransition}
+            />
+          </motion.div>
+        ) : (
+          <motion.div
+            key="slideshow-waiting"
+            className="text-sm text-gray-500"
+            initial={{ opacity: 0 }}
+            animate={{ opacity: 1 }}
+            exit={{ opacity: 0 }}
+          >
+            Finding next image…
+          </motion.div>
+        )}
+      </AnimatePresence>
+
+      <motion.div
+        className="pointer-events-none absolute inset-x-0 top-0 flex items-start justify-between p-5"
+        initial={false}
+        animate={{ opacity: controlsShown ? 1 : 0, y: controlsShown ? 0 : -6 }}
+        transition={{ duration: 0.24, ease: [0.22, 1, 0.36, 1] }}
+      >
+        <div className="max-w-[60vw] rounded-full border border-white/10 bg-black/45 px-3 py-1.5 text-xs whitespace-nowrap text-gray-300 shadow-2xl shadow-black/30 backdrop-blur-md">
+          <span className="font-medium text-white">{position}</span>
+          <span className="mx-1 text-gray-600">/</span>
+          <span>{imageCount}</span>
+          <span className="mx-2 text-gray-700">•</span>
+          <span className="inline-block max-w-[42vw] truncate align-bottom text-gray-400">
+            {selectedImage.filename}
+          </span>
+        </div>
+        <Tooltip label="Exit slideshow" followCursor>
+          <button
+            aria-label="Exit slideshow"
+            className="pointer-events-auto rounded-full border border-white/10 bg-black/45 p-2 text-gray-300 shadow-2xl shadow-black/30 backdrop-blur-md transition-colors hover:bg-white/10 hover:text-white"
+            onClick={(event) => {
+              event.stopPropagation()
+              onExit()
+            }}
+          >
+            <CloseIcon className="h-4 w-4" strokeWidth={1.8} />
+          </button>
+        </Tooltip>
+      </motion.div>
+
+      <motion.div
+        className="pointer-events-none absolute inset-x-0 bottom-0 flex items-end justify-center p-6"
+        initial={false}
+        animate={{ opacity: controlsShown ? 1 : 0, y: controlsShown ? 0 : 8 }}
+        transition={{ duration: 0.24, ease: [0.22, 1, 0.36, 1] }}
+      >
+        <div className="pointer-events-auto flex items-center gap-1 rounded-full border border-white/10 bg-black/50 p-1.5 shadow-2xl shadow-black/30 backdrop-blur-md">
+          <Tooltip label="Previous image" followCursor>
+            <button
+              aria-label="Previous image"
+              className="rounded-full p-2 text-gray-300 transition-colors hover:bg-white/10 hover:text-white disabled:cursor-not-allowed disabled:opacity-35"
+              disabled={imageCount <= 1}
+              onClick={(event) => {
+                event.stopPropagation()
+                onGo(-1)
+              }}
+            >
+              <svg className="h-5 w-5" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                <path
+                  strokeLinecap="round"
+                  strokeLinejoin="round"
+                  strokeWidth={1.8}
+                  d="M15 19l-7-7 7-7"
+                />
+              </svg>
+            </button>
+          </Tooltip>
+          <Tooltip label={paused ? 'Resume slideshow' : 'Pause slideshow'} followCursor>
+            <button
+              aria-label={paused ? 'Resume slideshow' : 'Pause slideshow'}
+              className="rounded-full border border-white/10 bg-white/10 p-2.5 text-white transition-colors hover:bg-white/15"
+              onClick={(event) => {
+                event.stopPropagation()
+                onTogglePaused()
+                onShowControls()
+              }}
+            >
+              {paused ? (
+                <svg className="h-5 w-5" fill="currentColor" viewBox="0 0 24 24">
+                  <path d="M8 5.14v13.72a1 1 0 001.52.86l10.55-6.86a1 1 0 000-1.72L9.52 4.28A1 1 0 008 5.14z" />
+                </svg>
+              ) : (
+                <svg className="h-5 w-5" fill="currentColor" viewBox="0 0 24 24">
+                  <path d="M7 5a1 1 0 00-1 1v12a1 1 0 001 1h2a1 1 0 001-1V6a1 1 0 00-1-1H7zM15 5a1 1 0 00-1 1v12a1 1 0 001 1h2a1 1 0 001-1V6a1 1 0 00-1-1h-2z" />
+                </svg>
+              )}
+            </button>
+          </Tooltip>
+          <Tooltip label="Next image" followCursor>
+            <button
+              aria-label="Next image"
+              className="rounded-full p-2 text-gray-300 transition-colors hover:bg-white/10 hover:text-white disabled:cursor-not-allowed disabled:opacity-35"
+              disabled={imageCount <= 1}
+              onClick={(event) => {
+                event.stopPropagation()
+                onGo(1)
+              }}
+            >
+              <ChevronRightIcon className="h-5 w-5" strokeWidth={1.8} />
+            </button>
+          </Tooltip>
+        </div>
+      </motion.div>
+
+      {loadingMore ? (
+        <div className="pointer-events-none absolute right-6 bottom-6 rounded-full border border-white/10 bg-black/45 px-3 py-1.5 text-xs text-gray-500 backdrop-blur-md">
+          Loading more…
+        </div>
+      ) : null}
+    </div>
+  )
+}

src/components/lightbox/format.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from 'vitest'
+import { embeddingLabel, formatBytes, formatDate, formatDuration, ratingPill } from './format'
+
+describe('formatBytes', () => {
+  it('formats each size tier', () => {
+    expect(formatBytes(512)).toBe('512 B')
+    expect(formatBytes(2048)).toBe('2.0 KB')
+    expect(formatBytes(5 * 1024 * 1024)).toBe('5.0 MB')
+  })
+})
+
+describe('formatDate', () => {
+  it('returns Unknown for null', () => {
+    expect(formatDate(null)).toBe('Unknown')
+  })
+
+  it('formats ISO dates with a full year', () => {
+    // Exact output is locale-dependent; assert the stable parts.
+    const formatted = formatDate('2024-03-15T12:00:00Z')
+    expect(formatted).toContain('2024')
+    expect(formatted).not.toBe('Unknown')
+  })
+})
+
+describe('formatDuration', () => {
+  it('reports pending for missing or zero durations', () => {
+    expect(formatDuration(null)).toBe('Pending / unavailable')
+    expect(formatDuration(0)).toBe('Pending / unavailable')
+    expect(formatDuration(-5)).toBe('Pending / unavailable')
+  })
+
+  it('formats minutes and hours', () => {
+    expect(formatDuration(65_000)).toBe('1:05')
+    expect(formatDuration(3_661_000)).toBe('1:01:01')
+  })
+})
+
+describe('embeddingLabel', () => {
+  it('labels each status', () => {
+    expect(embeddingLabel('ready', 'clip-vit')).toBe('Ready (clip-vit)')
+    expect(embeddingLabel('ready', null)).toBe('Ready')
+    expect(embeddingLabel('failed', null)).toBe('Failed')
+    expect(embeddingLabel('processing', null)).toBe('Processing')
+    expect(embeddingLabel('pending', null)).toBe('Queued')
+  })
+})
+
+describe('ratingPill', () => {
+  it('maps each AI rating to a label and tone', () => {
+    expect(ratingPill('general').label).toBe('General')
+    expect(ratingPill('general').className).toContain('emerald')
+    expect(ratingPill('sensitive').label).toBe('Sensitive')
+    expect(ratingPill('sensitive').className).toContain('sky')
+    expect(ratingPill('questionable').label).toBe('Questionable')
+    expect(ratingPill('questionable').className).toContain('amber')
+    expect(ratingPill('explicit').label).toBe('Explicit')
+    expect(ratingPill('explicit').className).toContain('red')
+  })
+})