chore(release): 0.2.0

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

.gitea/workflows/README.md

@@ -0,0 +1,20 @@
+# External CI
+
+CI and release builds run on the GitHub mirror because they require Windows
+runner capacity. The GitHub workflows report their state back to this Gitea
+repository through the commit status API.
+
+Keep this directory in the repository. Gitea checks `.gitea/workflows` before
+falling back to `.github/workflows`; an existing directory with no workflow
+files prevents the GitHub-only workflows from being queued by Gitea Actions.
+
+## Setup
+
+1. In Gitea, create an access token with `write:repository` permission for an
+   account that can update `JezzWTF/phokus`.
+2. In the GitHub repository, add that token as the Actions repository secret
+   `GITEA_STATUS_TOKEN`.
+
+The status steps are non-blocking. If Gitea is temporarily unavailable, the
+GitHub build result is preserved and the failed status update remains visible
+in the workflow log.

.github/workflows/ci.yml

@@ -0,0 +1,149 @@
+name: CI
+
+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: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  check:
+    # 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
+        if: github.event_name != 'pull_request' && env.GITEA_STATUS_TOKEN != ''
+        continue-on-error: true
+        shell: pwsh
+        env:
+          GITHUB_RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+        run: |
+          $headers = @{
+            Authorization = "token $env:GITEA_STATUS_TOKEN"
+            Accept = "application/json"
+          }
+          $body = @{
+            state = "pending"
+            context = "github/actions/ci"
+            description = "GitHub Actions CI is running"
+            target_url = $env:GITHUB_RUN_URL
+          } | ConvertTo-Json
+          Invoke-RestMethod `
+            -Method Post `
+            -Uri "https://git.jezz.wtf/api/v1/repos/JezzWTF/phokus/statuses/$env:GITHUB_SHA" `
+            -Headers $headers `
+            -ContentType "application/json" `
+            -Body $body
+
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 11
+
+      - uses: actions/setup-node@v4
+        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
+
+      - name: Install Rust stable
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          components: clippy, rustfmt
+
+      - uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: src-tauri
+
+      - name: Rustfmt
+        working-directory: src-tauri
+        run: cargo fmt --check
+
+      # --no-default-features: default enables candle-cuda for the main dev
+      # machine; CI runners have no CUDA toolkit and must build CPU-only.
+      - name: Clippy
+        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
+        shell: pwsh
+        env:
+          GITHUB_RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+          JOB_STATUS: ${{ job.status }}
+        run: |
+          $state = switch ($env:JOB_STATUS) {
+            "success" { "success" }
+            "failure" { "failure" }
+            default { "error" }
+          }
+          $headers = @{
+            Authorization = "token $env:GITEA_STATUS_TOKEN"
+            Accept = "application/json"
+          }
+          $body = @{
+            state = $state
+            context = "github/actions/ci"
+            description = "GitHub Actions CI finished: $env:JOB_STATUS"
+            target_url = $env:GITHUB_RUN_URL
+          } | ConvertTo-Json
+          Invoke-RestMethod `
+            -Method Post `
+            -Uri "https://git.jezz.wtf/api/v1/repos/JezzWTF/phokus/statuses/$env:GITHUB_SHA" `
+            -Headers $headers `
+            -ContentType "application/json" `
+            -Body $body

.github/workflows/release.yml

@@ -0,0 +1,158 @@
+name: Release
+
+# Tag pushes mirrored from Gitea (git.jezz.wtf) trigger this on the GitHub
+# mirror. Builds the NSIS installer and attaches it to a DRAFT GitHub Release —
+# review and publish manually.
+on:
+  push:
+    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
+        shell: pwsh
+        env:
+          GITHUB_RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+        run: |
+          $headers = @{
+            Authorization = "token $env:GITEA_STATUS_TOKEN"
+            Accept = "application/json"
+          }
+          $body = @{
+            state = "pending"
+            context = "github/actions/release"
+            description = "GitHub Actions release is running"
+            target_url = $env:GITHUB_RUN_URL
+          } | ConvertTo-Json
+          Invoke-RestMethod `
+            -Method Post `
+            -Uri "https://git.jezz.wtf/api/v1/repos/JezzWTF/phokus/statuses/$env:RELEASE_SHA" `
+            -Headers $headers `
+            -ContentType "application/json" `
+            -Body $body
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 11
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+          cache-dependency-path: pnpm-lock.yaml
+
+      - name: Install Rust stable
+        uses: dtolnay/rust-toolchain@stable
+
+      - uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: src-tauri
+
+      - name: Install frontend dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build and create draft release
+        uses: tauri-apps/tauri-action@v0.6.2
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          # Updater artifact signing (Phase 3) — set these repo secrets once
+          # the updater keypair exists; empty values are ignored until then.
+          TAURI_SIGNING_PRIVATE_KEY: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY }}
+          TAURI_SIGNING_PRIVATE_KEY_PASSWORD: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY_PASSWORD }}
+        with:
+          tagName: ${{ env.RELEASE_TAG }}
+          releaseName: 'Phokus v__VERSION__'
+          releaseBody: 'See the assets below to download and install this version.'
+          releaseDraft: true
+          prerelease: false
+          includeUpdaterJson: true
+          updaterJsonPreferNsis: true
+          # Cargo args after `--`: ship the CPU/DirectML build — default
+          # features enable candle-cuda, which runners (and most users) lack.
+          args: '-- --no-default-features'
+
+      - name: Report final status to Gitea
+        if: always() && env.GITEA_STATUS_TOKEN != ''
+        continue-on-error: true
+        shell: pwsh
+        env:
+          GITHUB_RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+          JOB_STATUS: ${{ job.status }}
+        run: |
+          $state = switch ($env:JOB_STATUS) {
+            "success" { "success" }
+            "failure" { "failure" }
+            default { "error" }
+          }
+          $headers = @{
+            Authorization = "token $env:GITEA_STATUS_TOKEN"
+            Accept = "application/json"
+          }
+          $body = @{
+            state = $state
+            context = "github/actions/release"
+            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/$sha" `
+            -Headers $headers `
+            -ContentType "application/json" `
+            -Body $body

.gitignore

@@ -32,6 +32,15 @@ dist-ssr
 
 # Misc
 *.py
-*.json
-
 *.pyc
+
+# Bundled CUDA runtime DLLs for the CUDA build (copied from the toolkit
+# locally; ~600 MB, never committed).
+src-tauri/cuda-redist/
+
+# Playwright
+/test-results/
+/playwright-report/
+/blob-report/
+/playwright/.cache/
+/playwright/.auth/

.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

@@ -0,0 +1,269 @@
+# Changelog
+
+All notable changes to Phokus are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
+(0.x: anything may change between minor versions).
+
+## [0.2.0] — 2026-07-11
+
+### Added
+
+- **What's New** — after updating, Phokus now greets you with a "What's new"
+  toast that opens a tidy in-app tour of the new version. Added, Changed, and
+  Fixed notes are grouped into collapsible sections, so you can skim the good
+  bits without playing "spot the difference".
+- **Quick theme switch** — right-click the settings cog in the title bar to
+  swap between Phokus, Subtle Light, and Conventional Dark instantly. No Settings
+  detour required.
+- **Albums** — make your own cross-folder collections without moving a single
+  file. Albums live in their own sidebar section with cover thumbnails, can be
+  created, renamed, reordered, opened, and cleaned up in Manage mode, and deleting
+  one only removes the grouping.
+- **Gallery multi-select** — hover a thumbnail's top-left corner to start
+  selecting, then use the floating action bar to tag, rate, favorite, add to an
+  album, or delete a whole batch at once. It also works in similar-image, region,
+  and album views, because bulk work should not disappear the moment you need it.
+- **Colour search** — narrow the Gallery, Timeline, or tag results by dominant
+  colour using toolbar swatches or a custom picker. Great for those "I know it
+  was mostly blue" moments.
+- **Album-aware similar search** — similar-image and region searches started from
+  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.
+- **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
+  do not need a re-index.
+- **Build badge in Settings** — Settings -> Updates now shows whether you are
+  running the CPU build or the CUDA build.
+- **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).
+  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.
+- **Pause workers for longer** — Settings -> General can now remember per-folder
+  worker pauses across app restarts, useful for folders you want to keep in the
+  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
+  (most-used, least-used, A-Z, and Z-A), smooth scrolling for huge tag lists, and
+  it keeps your filter/sort in place while you edit.
+- **Safer deletion** — deleting media now asks for confirmation and clearly says
+  the file is being removed from disk. This covers gallery bulk delete and the
+  Duplicate Finder.
+- **Clearer update progress** — Settings -> Updates now shows a real download
+  progress bar with a percentage instead of the old lonely "Downloading" label.
+- **Better narrow-window layout** — the toolbar, filters, search box, colour
+  picker, sidebar, and lightbox info panel now adapt more gracefully when the
+  window is short on space.
+- **Tidier Explore clusters** — busier clusters get more room, dense groups
+  overlap less, and everything should stay easier to read and click.
+- **Faster CPU tagging** — CPU-only AI tagging can now use multiple cores while
+  leaving some breathing room for the rest of the app. GPU tagging is unchanged.
+- **Smoother tooltips** — Phokus now uses its custom tooltip style across more of
+  the app instead of falling back to the native browser tooltip.
+
+### Fixed
+
+- **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** — 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** — 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** — 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** — 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
+
+### Added
+
+- **Custom multi-folder picker** — replaces the native OS dialog with an
+  in-app folder browser that lets you navigate, stage folders from multiple
+  locations, and add them all in one go. Duplicate roots are skipped
+  automatically; partially-failed batches remove successfully-added entries
+  from the staging panel so only failed folders remain to retry.
+- **Rebuild semantic index** maintenance action in Settings — drops and
+  recreates the vector tables at the current model dimension, then re-queues
+  every image for embedding. Fixes "dimension mismatch" search errors that
+  occur after switching between CLIP models with different output sizes.
+- **Video playback settings** — new Video Playback group in Settings with two
+  persisted toggles: "Autoplay in lightbox" (default on) and "Start muted"
+  (default off). Settings apply to the next opened video rather than the
+  current one.
+- **Timeline scrubber** — a year/month rail on the Timeline view that jumps to
+  any period in the library. Timeline now loads the full filtered set so the
+  scrubber spans the whole library instead of just the first page.
+- **Folder reordering** in the sidebar — drag-and-drop (with edge auto-scroll)
+  or keyboard (↑/↓ on the drag handle), with the custom order persisted across
+  sessions; the Libraries list also gains A–Z / Z–A / Custom sort.
+- Failed AI-tagging jobs can now be located from the background worker prompt,
+  including a gallery filter for images with failed tags and an expanded list
+  of failed filenames/errors.
+- A new theme system adds Phokus, Subtle Light, and Conventional Dark chrome
+  options across the app.
+- First-run onboarding now includes an inline theme picker so new users can
+  choose their preferred app chrome before continuing the tour.
+
+### Changed
+
+- Settings sections are reordered — General is now the first and default
+  section instead of AI Workspace.
+- The Duplicate Finder group list is now virtualised — only on-screen cards
+  mount, so large result sets (e.g. 5,000+ pairs) scroll without lag rather
+  than mounting every thumbnail at once.
+- The gallery grid is now row-virtualised, so very large libraries scroll
+  smoothly and only on-screen thumbnails are rendered.
+- Polished the new theme surfaces before release, including readable
+  subtle-light secondary buttons, failed-worker action buttons, and onboarding
+  controls.
+- Onboarding preview media keeps the dark gallery/media surface regardless of
+  the active chrome theme.
+
+### Fixed
+
+- **AVIF thumbnails** — AVIF files are now processed correctly by routing
+  thumbnail generation through the bundled FFmpeg path instead of the Rust
+  image decoder (which has no dav1d dependency). Previously-failed AVIF jobs
+  are requeued on startup; JPEG derivatives are fed to the embedding and
+  tagging pipeline while the lightbox continues to display the original file.
+- Accent text is now readable in the Subtle Light theme.
+- Folder picker chevron tooltip now correctly shows "No subfolders" for leaf
+  entries instead of "Open folder" in both branches.
+- Folder picker Unix breadcrumb root now shows "/" instead of always "Home"
+  for non-home paths such as `/mnt/data`.
+- Video embedding jobs are no longer claimed before their thumbnail exists, and
+  any that previously failed for that reason are requeued on startup — videos no
+  longer churn through failed embeddings.
+- Subtle Light theme consistency — the lightbox metadata panel now follows the
+  light chrome while the image canvas stays dark (matching Conventional Dark),
+  and gallery/timeline media badges, duplicate-finder thumbnails, and the window
+  restore icon now theme correctly instead of staying Phokus-dark.
+- Timeline scrolling is now smooth on large libraries — it virtualizes per row
+  of tiles instead of per month, so a month with thousands of photos no longer
+  mounts every tile at once (thumbnails now load in incrementally as you scroll,
+  matching the All Media grid).
+- Background worker updates (thumbnails, metadata, embeddings, tags) no longer
+  re-sort the entire loaded image set on every batch. In Timeline, which loads
+  the whole library, this re-sort caused severe lag and could crash the app
+  during background indexing.
+
+## [0.1.0] — 2026-06-14
+
+First public release. Windows desktop, distributed as an unsigned NSIS
+installer with a built-in updater.
+
+### Added
+
+- **Local media library** — add folders, recursive background indexing with
+  live progress, and a filesystem watcher that keeps the library in sync as
+  files are added, edited, moved, renamed, or removed (thumbnails and
+  embeddings are preserved across renames).
+- **Gallery** — virtualized grid (handles very large libraries), favorites,
+  star ratings, video durations; filter by folder, type, favorites, or
+  rating; sort by date added, date taken (EXIF), name, size, rating, or
+  duration; compact / comfortable / detail density.
+- **Search** — filename, semantic (`/s`, via CLIP visual embeddings), and tag
+  (`/t`) search from one prefix-aware search bar.
+- **Discovery** — similar-image search (by image or selected region), an
+  Explore view with a visual cluster map and tag cloud, and a Timeline grouped
+  by EXIF capture date. Explore, Timeline, and Duplicates are folder-scopable
+  from their headers.
+- **Lightbox** — keyboard navigation, zoom, pan, inline tag editing, and
+  rating controls, plus a custom edge-to-edge video player (scrubbing, volume,
+  speed, loop, fullscreen, keyboard support).
+- **AI tagging** — WD tagger (ONNX, CPU/DirectML) with adjustable confidence
+  threshold, batch size, and per-folder queue targeting. Optional.
+- **Duplicate finder** — three-phase exact-duplicate scan
+  (size → sample hash → full hash) with live progress and bulk delete.
+- **Background pipeline** — strict-priority workers (thumbnails → metadata →
+  embeddings → tags) with per-folder pausing from the sidebar context menu or
+  the background-tasks bar.
+- **Guided first-run onboarding** — background FFmpeg provisioning with live
+  progress and retry, a walkthrough of the library, pipeline, search modes,
+  views, and updates, plus an optional AI-tagger download. Re-runnable from
+  Settings.
+- **Updater** — checks GitHub Releases on launch and from Settings; a title-bar
+  indicator lights up when a new version is ready, and one click downloads,
+  installs the signed update, and relaunches.
+- **Maintenance** — database compaction and orphaned-thumbnail cleanup from
+  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,32 +15,67 @@ pnpm dev:app
 # Frontend only (no Tauri window)
 pnpm dev:vite
 
-# Production build
-pnpm build:app
+# 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
+
+# Production build (CUDA / GPU-accelerated)
+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
@@ -64,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 |
@@ -80,11 +117,11 @@ Database: SQLite with WAL mode, stored in the Tauri app data directory as `galle
 | `media-updated` | `ThumbnailBatch` |
 | `caption-model-progress` | `CaptionModelProgress` |
 | `tagger-model-progress` | `TaggerModelProgress` |
-| `duplicate_scan_progress` | `[scanned, total]` |
+| `duplicate_scan_progress` | `{ phase, processed, total, skipped }` |
 
 ### 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
 
@@ -92,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).

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 JezzWTF
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -4,31 +4,95 @@ A local-first desktop media library for browsing, filtering, and curating image
 
 ## Features
 
+### Library
 - Add and remove media folders; background indexing with live progress
+- **Live file tracking** — a filesystem watcher keeps the library in sync as files are added, changed, or removed; renames and moves are handled in place, preserving thumbnails and embeddings
 - Browse all media or filter by folder, type (image/video), favorites, or star rating
-- **Filename search**, **semantic search** (`/s query`), and **tag search** (`/t tag`)
-- **Similar image search** — find visually similar media by image or selected region
-- **AI tagging** via WD tagger (ONNX, CPU/DirectML) with confidence threshold control
-- **Explore view** — visual cluster map and tag cloud for browsing by theme
-- **Duplicate finder** — scan for exact duplicates by file hash with bulk delete
-- Lightbox preview with keyboard navigation, inline tag editing, and rating controls
-- Sort by date, name, size, rating, or duration
+- Sort by date added, date taken (EXIF), name, size, rating, or duration
 - Grid density controls (compact / comfortable / detail)
+- Desktop notifications, batched per folder, with per-folder mute and a global pause
+
+### Search & discovery
+- **Filename search**, **semantic search** (`/s query`), and **tag search** (`/t tag`)
+- **Similar image search** — find visually similar media by image or a selected region
+- **Explore view** — visual cluster map and tag cloud for browsing by theme
+- **Timeline view** — media grouped chronologically by capture date (EXIF)
+- **Duplicate finder** — three-phase exact-duplicate scan (size → sample hash → full hash) with live progress and bulk delete
+- Explore, Timeline, and Duplicates are folder-scopable directly from their headers — no need to bounce through the sidebar
+
+### Viewing & curation
+- Lightbox with keyboard navigation, zoom, inline tag editing, and rating controls
+- **Custom video player** — immersive edge-to-edge playback with scrubbing, volume, playback speed, loop, and fullscreen; auto-hiding controls and full keyboard support
+- **AI tagging** via WD tagger (ONNX, CPU/DirectML) with confidence threshold, batch size, and per-folder queue targeting
+
+### Maintenance
+- Database compaction and orphaned-thumbnail cleanup from Settings, with live size/reclaimable stats
+- Per-folder pausing of background work (thumbnails, metadata, embeddings, tagging)
 
 ## Supported formats
 
 | Images | Videos |
 |--------|--------|
 | jpg, jpeg, png, gif, bmp | mp4, mov, m4v |
-| tiff, tif, webp, avif, heic, heif | webm |
+| tiff, tif, webp, avif | webm |
+
+## Installation
+
+Phokus is a **Windows desktop app**. Download the latest installer from the
+[Releases page](https://github.com/JezzWTF/phokus/releases/latest) and run it.
+
+**Requirements:** Windows 10 or 11. The installer will fetch the WebView2
+runtime automatically if it isn't already present (it ships with Windows 11).
+
+### A note on the unsigned build
+
+Phokus 0.1.0 installers are **not code-signed**. Code-signing certificates are
+an ongoing expense that's hard to justify for an unfunded open-source project,
+so signing is on the roadmap rather than in place today.
+
+In practice this means Windows SmartScreen will show a blue
+**"Windows protected your PC"** warning the first time you run the installer.
+To proceed: click **More info → Run anyway**. If a release publishes a SHA-256
+checksum, you can verify the download against it first.
+
+### First run
+
+On first launch Phokus downloads a few tools and models — all one-time, and all
+processed on your machine:
+
+- **FFmpeg** (~tens of MB) for video thumbnails and metadata — downloaded in the
+  background; the guided first-run tour shows progress.
+- **WD tagger model** (~1.3 GB) — **optional**, only if you enable AI tagging.
+- **CLIP embedding model** (~580 MB) — downloaded automatically the first time
+  visual embeddings run (powers semantic search and similar images).
+
+## Privacy & local-first
+
+Phokus is local-first by design. **Your media and everything derived from it —
+thumbnails, embeddings, tags, ratings — never leave your machine.** There is no
+account, no telemetry, and no cloud sync.
+
+The only network activity is:
+
+- **One-time tool/model downloads** on first use (FFmpeg, the CLIP and WD
+  models, and the ONNX runtime), fetched from their official sources
+  (FFmpeg builds, Hugging Face, NuGet). These pull *tools to your machine* —
+  none of your images are uploaded.
+- **Update checks** against the GitHub Releases page, so the app can offer new
+  versions. This can be ignored if you never update.
+
+Everything Phokus stores lives in its app-data directory (`gallery.db`,
+`thumbnails/`, `models/`, `settings/`). Removing that directory resets the app
+completely; your original media folders are never modified.
 
 ## Stack
 
 - Tauri 2 + Rust backend
 - React 19 + TypeScript + Zustand
-- SQLite + `sqlite-vec` (vector search)
+- SQLite + `sqlite-vec` (vector search) + HNSW index
 - ONNX Runtime (`ort`) for AI tagging
-- Candle (Rust ML) for visual embeddings
+- Candle (Rust ML) for CLIP visual embeddings
+- mozjpeg for fast scaled JPEG decoding
 - FFmpeg sidecar for video thumbnails and metadata
 - Vite + Tailwind CSS v4
 
@@ -45,14 +109,27 @@ pnpm dev:app
 # Frontend only
 pnpm dev:vite
 
-# Production build
-pnpm build:app
+# Browser-only UI Lab with mocked Tauri APIs
+pnpm dev:ui
+
+# Production build (CPU)
+pnpm build:app:cpu
+
+# Production build (CUDA / GPU-accelerated)
+pnpm build:app:cuda
+
+# Type-check the frontend
+pnpm build:vite
 ```
 
+For visual frontend work without launching Tauri or the Rust backend, see
+[Phokus UI Lab](docs/ui-lab.md).
+
 ## How it works
 
 1. Add a folder from the sidebar — the Rust indexer walks it recursively.
-2. Supported files are written to SQLite with metadata (path, dimensions, media type, etc.).
-3. Background workers generate thumbnails, compute visual embeddings, and run AI tagging.
+2. Supported files are written to SQLite with metadata (path, dimensions, media type, EXIF capture date, etc.).
+3. Background workers process the queue as a strict priority pipeline — thumbnails first, then video metadata, then visual embeddings, then AI tags — so each stage runs at full speed instead of competing for CPU, disk, and the database.
 4. Progress events stream back to the UI while the gallery updates incrementally.
-5. Embeddings power semantic search and the similar images feature via an HNSW index.
+5. A filesystem watcher picks up later changes (new files, edits, deletions, renames) and keeps the index current without rescans.
+6. Embeddings power semantic search and the similar-images feature via an HNSW index.

branding/phokus-aperture.svg

@@ -0,0 +1,43 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256" width="256" height="256" role="img" aria-label="Phokus">
+  <title>Phokus</title>
+
+  <!--
+    Phokus app mark — a camera iris.
+    The hexagon in the middle is the lens OPENING; each blade edge sweeps from a
+    corner of the opening out to the rim, all leaning the same way (the pinwheel).
+
+    Tuning knobs (edit and re-open in any browser/Figma):
+      * opening roundness  -> the "52" radius in the opening <path> arcs.
+          smaller (toward 30) = rounder/softer hole; larger (toward 90) = flatter, sharper.
+      * blade curve         -> the "110" radius in each blade <path>.
+          smaller = more pronounced curve; larger = straighter blade.
+      * blade sweep amount  -> the +40deg baked into the blade endpoint (70.71,-84.27).
+      * curve DIRECTION     -> the final flag in each "A r r 0 0 X" command (0<->1 flips the bow).
+      * weight              -> stroke-width on the <g>.
+      * color               -> stroke on the <g>; swap "#e9e9ec" for currentColor to inherit.
+    A brand-accent focal dot is provided at the bottom (commented out).
+  -->
+
+  <rect x="8" y="8" width="240" height="240" rx="52" fill="#0e0f14"/>
+
+  <g transform="translate(128 128)" fill="none" stroke="#e9e9ec" stroke-width="9"
+     stroke-linecap="round" stroke-linejoin="round">
+
+    <!-- outer rim -->
+    <circle r="110"/>
+
+    <!-- lens opening: soft, arc-rounded hexagon -->
+    <path d="M0,-46 A52,52 0 0 0 39.84,-23 A52,52 0 0 0 39.84,23 A52,52 0 0 0 0,46 A52,52 0 0 0 -39.84,23 A52,52 0 0 0 -39.84,-23 A52,52 0 0 0 0,-46 Z"/>
+
+    <!-- blades: one curved edge, swept six times -->
+    <g transform="rotate(0)"><path d="M0,-46 A110,110 0 0 1 70.71,-84.27"/></g>
+    <g transform="rotate(60)"><path d="M0,-46 A110,110 0 0 1 70.71,-84.27"/></g>
+    <g transform="rotate(120)"><path d="M0,-46 A110,110 0 0 1 70.71,-84.27"/></g>
+    <g transform="rotate(180)"><path d="M0,-46 A110,110 0 0 1 70.71,-84.27"/></g>
+    <g transform="rotate(240)"><path d="M0,-46 A110,110 0 0 1 70.71,-84.27"/></g>
+    <g transform="rotate(300)"><path d="M0,-46 A110,110 0 0 1 70.71,-84.27"/></g>
+  </g>
+
+  <!-- optional brand focal point -->
+  <!-- <circle cx="128" cy="128" r="9" fill="#e6a23c"/> -->
+</svg>

docs/release-notes-0.1.0.md

@@ -0,0 +1,59 @@
+# Phokus v0.1.0
+
+> Draft for the GitHub Release body. Paste into the release, fill in the
+> checksum, 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.
+
+This is the **first public release**. Expect rough edges, and please file
+issues.
+
+## Install
+
+1. Download `Phokus_0.1.0_x64-setup.exe` below.
+2. Run it. **Windows SmartScreen will warn** that the publisher is
+   unrecognized — this build is **not code-signed** (cost; signing is on the
+   roadmap). Click **More info → Run anyway** to proceed.
+3. Requires **Windows 10/11**. The installer fetches the WebView2 runtime
+   automatically if needed.
+
+On first launch, Phokus runs a short guided tour and downloads FFmpeg in the
+background (one-time, ~tens of MB). AI tagging (~1.3 GB) is optional; the CLIP
+model for semantic search (~580 MB) downloads automatically the first time
+embeddings run. **All of this stays on your machine.**
+
+## Highlights
+
+- Virtualized gallery for very large libraries; favorites, ratings, filters, sorts
+- Filename, semantic (`/s`), and tag (`/t`) search
+- Similar-image search, Explore clusters + tag cloud, EXIF Timeline
+- Lightbox with zoom/pan and a custom video player
+- Optional on-device AI tagging (WD tagger)
+- Exact-duplicate finder with bulk delete
+- Built-in updater
+
+See the [changelog](https://github.com/JezzWTF/phokus/blob/main/CHANGELOG.md)
+for the full list.
+
+## Privacy
+
+Your media and all derived data (thumbnails, embeddings, tags, ratings) never
+leave your machine. No account, no telemetry, no cloud. The only network
+activity is the one-time tool/model downloads above and update checks against
+this Releases page.
+
+## Known limitations
+
+- **Unsigned installer** — SmartScreen warning as described above.
+- **Windows only** for now.
+- CPU/DirectML inference in the shipped build; very large libraries take time
+  to embed on first index.
+
+## Verify your download (optional)
+
+```
+SHA-256 (Phokus_0.1.0_x64-setup.exe) = <fill in at publish time>
+```

docs/release-notes-0.1.1.md

@@ -0,0 +1,64 @@
+# Phokus v0.1.1
+
+> 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.
+
+This is a quality-of-life release on top of 0.1.0: a new in-app folder
+picker, themes, smoother scrolling on large libraries, and a batch of fixes.
+If you're updating from 0.1.0, the built-in updater will fetch this for you.
+
+## Install / update
+
+- **Updating from 0.1.0:** the in-app updater will offer 0.1.1 on launch — one
+  click downloads, installs, and relaunches.
+- **Fresh install:** download `Phokus_0.1.1_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 speed can use the
+`Phokus_0.1.1_x64-cuda-setup.exe` variant instead (larger download; bundles the
+CUDA runtime DLLs).
+
+## Highlights
+
+### Added
+- **Custom multi-folder picker** — navigate and stage folders from multiple
+  locations and add them in one go, replacing the native OS dialog.
+- **Themes** — Phokus, Subtle Light, and Conventional Dark chrome, with an
+  inline theme picker in first-run onboarding.
+- **Timeline scrubber** — a year/month rail to jump anywhere in the library.
+- **Folder reordering** in the sidebar (drag-and-drop or keyboard), persisted,
+  plus A–Z / Z–A / Custom sort for the Libraries list.
+- **Video playback settings** — autoplay-in-lightbox and start-muted toggles.
+- **Rebuild semantic index** maintenance action — fixes "dimension mismatch"
+  search errors after switching CLIP models.
+- Locate and filter images with failed AI-tagging jobs.
+
+### Changed
+- Gallery grid and Duplicate Finder list are now row-virtualised — large
+  libraries and large result sets (5,000+ pairs) scroll without lag.
+- Settings now open on General by default.
+
+### Fixed
+- **AVIF thumbnails** now generate correctly (routed through bundled FFmpeg);
+  previously-failed AVIF jobs are requeued on startup.
+- Video embedding jobs no longer churn through failed states before their
+  thumbnail exists; previously-failed ones are requeued.
+- Timeline scrolling is smooth on large libraries (per-row virtualisation);
+  background batches no longer re-sort the whole loaded set.
+- Numerous Subtle Light theme readability/parity fixes.
+
+See the [changelog](https://github.com/JezzWTF/phokus/blob/main/CHANGELOG.md)
+for the full list.
+
+## Checksums
+
+```
+SHA-256 (Phokus_0.1.1_x64-setup.exe)      = 1c19cbeb77f38a44149380c42c76b633add65777d317e1f3ff7e45d96d12d287
+SHA-256 (Phokus_0.1.1_x64-cuda-setup.exe) = a7337ef5ee0478a785b48acc8012e8fc5c957341161d6103409213ad78eb845f
+```

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)      = TBD
+SHA-256 (Phokus_0.2.0_x64-cuda-setup.exe) = TBD
+```

docs/ui-lab.md

@@ -0,0 +1,201 @@
+# Phokus UI Lab
+
+Phokus UI Lab is a browser-only development mode for visual work on the real
+Phokus frontend. It runs the same `App.tsx`, Zustand store, components, and CSS
+as the Tauri app, but installs Tauri JavaScript mocks before the app imports.
+
+This gives UI agents and contributors a stable browser target without launching
+the Rust backend or a Tauri window.
+
+## Run It
+
+```bash
+pnpm dev:ui
+```
+
+Then open:
+
+```text
+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
+```
+
+The normal app development commands are unchanged:
+
+```bash
+pnpm dev:app   # Tauri app + Rust backend
+pnpm dev:vite  # frontend dev server for Tauri dev
+```
+
+## Scenarios
+
+UI Lab reads `?scenario=` from the URL. If no scenario is provided, it uses
+`rich`.
+
+| URL | Purpose |
+| --- | --- |
+| `/?scenario=rich` | Default realistic library with folders, albums, ratings, favorites, tags, images, and videos |
+| `/?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 |
+| `/?scenario=errors` | Broken thumbnails, folder scan errors, failed embeddings, failed tagging, and metadata issues |
+| `/?scenario=huge` | Large mock library for virtualization and layout checks |
+
+Examples:
+
+```text
+http://127.0.0.1:1422/?scenario=duplicates
+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
+`src/dev/setupMockTauri.ts` first, then imports the real `App`.
+
+That order matters because static imports are hoisted. The Tauri mocks must be
+installed before `App`, the store, the title bar, or visual components import
+Tauri APIs.
+
+The mock setup installs:
+
+- `mockWindows("main")` for window APIs used by the title bar
+- `mockConvertFileSrc("windows")` as a baseline Tauri file URL mock
+- `mockIPC(..., { shouldMockEvents: true })` for `invoke`, `listen`, and `emit`
+
+The in-memory backend lives in:
+
+```text
+src/dev/mockBackend.ts
+src/dev/mockFixtures.ts
+src/dev/mockScenarios.ts
+src/dev/applyMockScenario.ts
+```
+
+Happy-path fixture media is generated from existing onboarding images and
+website screenshots into:
+
+```text
+public/dev-media/fixture-*.webp
+```
+
+The pack is deliberately small and deterministic, but varied enough for browser
+screenshots: square, portrait, landscape, monochrome, tinted, framed, and
+interface-like crops. Synthetic or deliberately broken fixture paths can still
+use the `mock://` scheme described below.
+
+## Mock Media
+
+Visual components should use `mediaSrc(...)` instead of calling
+`convertFileSrc(...)` directly:
+
+```ts
+import { mediaSrc } from "../lib/mediaSrc";
+
+const src = mediaSrc(image.thumbnail_path);
+```
+
+In normal Tauri modes, `mediaSrc` delegates to `convertFileSrc`. In UI Lab,
+root-relative asset URLs such as `/dev-media/fixture-01.webp` are returned
+as-is. Paths beginning with `mock://` are also served from `public/dev-media`:
+
+```text
+mock://thumb-1.svg -> /dev-media/thumb-1.svg
+```
+
+Use `mediaSrc` when adding components that render thumbnails, album covers,
+preview images, or video posters.
+
+## Adding A Mock Command
+
+If the browser console logs an unmocked command, add it to
+`src/dev/mockBackend.ts`.
+
+Prefer returning realistic data for commands that affect visible UI. For actions
+that would touch the machine, return a safe no-op:
+
+```ts
+case "open_app_data_folder":
+  return null;
+```
+
+When adding fixture data, keep it shaped like the real store/Rust contracts.
+Most frontend-facing types are exported from `src/store.ts`, so the mocks can
+stay type-checked against the real UI.
+
+## Adding A Scenario
+
+1. Add the scenario name to `MockScenario` and `SCENARIOS` in
+   `src/dev/mockScenarios.ts`.
+2. Adjust fixture creation in `src/dev/mockFixtures.ts`.
+3. If the scenario should open a specific view, add that behavior in
+   `src/dev/applyMockScenario.ts`.
+4. Visit `http://127.0.0.1:1422/?scenario=your-scenario` and check for console
+   errors.
+
+## What UI Lab Is For
+
+UI Lab is intended for:
+
+- visual iteration on the real app shell
+- layout and responsive checks
+- state-heavy views like Explore, Timeline, Duplicates, albums, and Settings
+- AI-agent screenshot/browser inspection
+- safe UI work without filesystem or Rust-side effects
+
+It is not a replacement for Tauri app testing. Validate native behavior with
+`pnpm dev:app` when touching:
+
+- file or folder pickers
+- filesystem permissions
+- real thumbnail/video loading
+- window drag, minimize, maximize, or close behavior
+- Rust backend performance
+- updater installation
+- WebView2-specific behavior
+
+## Verification
+
+Useful checks after changing UI Lab:
+
+```bash
+pnpm exec tsc --noEmit
+pnpm build:vite
+pnpm dev:ui
+```
+
+Then smoke-test at least:
+
+```text
+http://127.0.0.1:1422/?scenario=rich
+http://127.0.0.1:1422/?scenario=empty
+http://127.0.0.1:1422/?scenario=duplicates
+http://127.0.0.1:1422/?scenario=errors
+http://127.0.0.1:1422/?scenario=huge
+```

package.json

@@ -1,15 +1,32 @@
 {
   "name": "phokus",
   "private": true,
-  "version": "0.1.0",
+  "version": "0.2.0",
+  "license": "MIT",
   "type": "module",
   "scripts": {
-    "build:app": "tauri build",
+    "build:app:cpu": "tauri build -- --no-default-features",
+    "build:app:cuda": "tauri build --config src-tauri/tauri.cuda.conf.json",
     "build:vite": "tsc && vite build",
+    "build:web": "cd website && tsc && vite build",
+    "changelog:add": "node tools/changelog-add.mjs",
+    "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",
     "dev:vite": "vite",
+    "dev:web": "cd website && pnpm dev",
+    "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",
@@ -18,6 +35,8 @@
     "@tauri-apps/plugin-fs": "^2.5.0",
     "@tauri-apps/plugin-notification": "^2.3.3",
     "@tauri-apps/plugin-opener": "^2",
+    "@tauri-apps/plugin-process": "^2.3.1",
+    "@tauri-apps/plugin-updater": "^2.10.1",
     "d3-force": "^3.0.0",
     "framer-motion": "^12.38.0",
     "react": "^19.1.0",
@@ -25,14 +44,19 @@
     "zustand": "^5.0.12"
   },
   "devDependencies": {
+    "@playwright/test": "^1.61.1",
     "@tailwindcss/vite": "^4.2.2",
     "@tauri-apps/cli": "^2",
     "@types/d3-force": "^3.0.10",
+    "@types/node": "^26.0.1",
     "@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

@@ -0,0 +1,75 @@
+import { defineConfig, devices } from '@playwright/test'
+
+/**
+ * Read environment variables from file.
+ * https://github.com/motdotla/dotenv
+ */
+// import dotenv from 'dotenv';
+// import path from 'path';
+// dotenv.config({ path: path.resolve(__dirname, '.env') });
+
+/**
+ * See https://playwright.dev/docs/test-configuration.
+ */
+export default defineConfig({
+  testDir: './tests',
+  /* Run tests in files in parallel */
+  fullyParallel: true,
+  /* Fail the build on CI if you accidentally left test.only in the source code. */
+  forbidOnly: !!process.env.CI,
+  /* Retry on CI only */
+  retries: process.env.CI ? 2 : 0,
+  /* Opt out of parallel tests on CI. */
+  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://127.0.0.1:1422',
+
+    /* Collect trace when retrying the failed test. See https://playwright.dev/docs/trace-viewer */
+    trace: 'on-first-retry',
+  },
+
+  /* Configure projects for major browsers */
+  projects: [
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] },
+    },
+
+    {
+      name: 'webkit',
+      use: { ...devices['Desktop Safari'] },
+    },
+
+    /* Test against mobile viewports. */
+    // {
+    //   name: 'Mobile Chrome',
+    //   use: { ...devices['Pixel 5'] },
+    // },
+    // {
+    //   name: 'Mobile Safari',
+    //   use: { ...devices['iPhone 12'] },
+    // },
+
+    /* Test against branded browsers. */
+    // {
+    //   name: 'Microsoft Edge',
+    //   use: { ...devices['Desktop Edge'], channel: 'msedge' },
+    // },
+    // {
+    //   name: 'Google Chrome',
+    //   use: { ...devices['Desktop Chrome'], channel: 'chrome' },
+    // },
+  ],
+
+  /* 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-workspace.yaml

@@ -0,0 +1,6 @@
+packages:
+  - website
+
+allowBuilds:
+  esbuild: true
+  sharp: true

public/phokus-aperture.svg

@@ -0,0 +1,43 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256" width="256" height="256" role="img" aria-label="Phokus">
+  <title>Phokus</title>
+
+  <!--
+    Phokus app mark — a camera iris.
+    The hexagon in the middle is the lens OPENING; each blade edge sweeps from a
+    corner of the opening out to the rim, all leaning the same way (the pinwheel).
+
+    Tuning knobs (edit and re-open in any browser/Figma):
+      * opening roundness  -> the "52" radius in the opening <path> arcs.
+          smaller (toward 30) = rounder/softer hole; larger (toward 90) = flatter, sharper.
+      * blade curve         -> the "110" radius in each blade <path>.
+          smaller = more pronounced curve; larger = straighter blade.
+      * blade sweep amount  -> the +40deg baked into the blade endpoint (70.71,-84.27).
+      * curve DIRECTION     -> the final flag in each "A r r 0 0 X" command (0<->1 flips the bow).
+      * weight              -> stroke-width on the <g>.
+      * color               -> stroke on the <g>; swap "#e9e9ec" for currentColor to inherit.
+    A brand-accent focal dot is provided at the bottom (commented out).
+  -->
+
+  <rect x="8" y="8" width="240" height="240" rx="52" fill="#0e0f14"/>
+
+  <g transform="translate(128 128)" fill="none" stroke="#e9e9ec" stroke-width="9"
+     stroke-linecap="round" stroke-linejoin="round">
+
+    <!-- outer rim -->
+    <circle r="110"/>
+
+    <!-- lens opening: soft, arc-rounded hexagon -->
+    <path d="M0,-46 A52,52 0 0 0 39.84,-23 A52,52 0 0 0 39.84,23 A52,52 0 0 0 0,46 A52,52 0 0 0 -39.84,23 A52,52 0 0 0 -39.84,-23 A52,52 0 0 0 0,-46 Z"/>
+
+    <!-- blades: one curved edge, swept six times -->
+    <g transform="rotate(0)"><path d="M0,-46 A110,110 0 0 1 70.71,-84.27"/></g>
+    <g transform="rotate(60)"><path d="M0,-46 A110,110 0 0 1 70.71,-84.27"/></g>
+    <g transform="rotate(120)"><path d="M0,-46 A110,110 0 0 1 70.71,-84.27"/></g>
+    <g transform="rotate(180)"><path d="M0,-46 A110,110 0 0 1 70.71,-84.27"/></g>
+    <g transform="rotate(240)"><path d="M0,-46 A110,110 0 0 1 70.71,-84.27"/></g>
+    <g transform="rotate(300)"><path d="M0,-46 A110,110 0 0 1 70.71,-84.27"/></g>
+  </g>
+
+  <!-- optional brand focal point -->
+  <!-- <circle cx="128" cy="128" r="9" fill="#e6a23c"/> -->
+</svg>

scripts/codex-cloud-setup.sh

@@ -0,0 +1,189 @@
+#!/usr/bin/env bash
+set -Eeuo pipefail
+
+# Codex Cloud setup for Phokus.
+# Paste this script into the Codex Cloud environment setup field, or run it from
+# the repo root with: bash scripts/codex-cloud-setup.sh
+#
+# Goals:
+# - install Linux packages needed by Tauri/WebKit and native Rust crates
+# - install JS dependencies with pnpm using the lockfile
+# - pre-fetch Rust dependencies while setup still has internet access
+# - keep the environment CPU-safe by avoiding Phokus' default CUDA feature set
+# - leave Codex with clear verification commands for UI and Rust work
+
+log() {
+  printf '\n\033[1;36m[phokus-codex]\033[0m %s\n' "$*"
+}
+
+warn() {
+  printf '\n\033[1;33m[phokus-codex warning]\033[0m %s\n' "$*" >&2
+}
+
+repo_root="$(pwd)"
+
+if [[ ! -f "package.json" || ! -d "src-tauri" ]]; then
+  warn "This script should be run from the Phokus repository root. Current directory: ${repo_root}"
+  exit 1
+fi
+
+export CI=1
+export PNPM_HOME="${PNPM_HOME:-$HOME/.local/share/pnpm}"
+export PATH="$PNPM_HOME:$HOME/.cargo/bin:$PATH"
+
+# Persist useful shell defaults for the later Codex agent phase. Codex setup runs
+# in a separate Bash session, so exports here alone would not survive.
+if ! grep -q "# Phokus Codex Cloud" "$HOME/.bashrc" 2>/dev/null; then
+  cat >> "$HOME/.bashrc" <<'BASHRC'
+
+# Phokus Codex Cloud
+export PNPM_HOME="${PNPM_HOME:-$HOME/.local/share/pnpm}"
+export PATH="$PNPM_HOME:$HOME/.cargo/bin:$PATH"
+export CI=1
+BASHRC
+fi
+
+install_apt_packages() {
+  if ! command -v apt-get >/dev/null 2>&1; then
+    warn "apt-get not found; skipping system package installation."
+    return 0
+  fi
+
+  log "Installing Linux system dependencies for Tauri, WebKit, SQLite/native crates, and browser tooling"
+
+  sudo apt-get update
+
+  # Tauri v2 Linux builds need the WebKitGTK/AppIndicator/Rsvg stack. Some base
+  # images expose either the 4.1 or 4.0 WebKit development package, so try the
+  # modern package first and gracefully fall back.
+  local common_packages=(
+    build-essential
+    curl
+    wget
+    file
+    pkg-config
+    libssl-dev
+    libgtk-3-dev
+    libayatana-appindicator3-dev
+    librsvg2-dev
+    patchelf
+    ca-certificates
+  )
+
+  if apt-cache show libwebkit2gtk-4.1-dev >/dev/null 2>&1; then
+    sudo apt-get install -y --no-install-recommends "${common_packages[@]}" libwebkit2gtk-4.1-dev
+  else
+    sudo apt-get install -y --no-install-recommends "${common_packages[@]}" libwebkit2gtk-4.0-dev
+  fi
+}
+
+ensure_node_and_pnpm() {
+  log "Preparing Node/pnpm"
+
+  if ! command -v node >/dev/null 2>&1; then
+    warn "Node.js is not available in this image. Pin Node.js 20+ in the Codex environment settings or use a Codex universal image with Node installed."
+    exit 1
+  fi
+
+  node_major="$(node -p "process.versions.node.split('.')[0]")"
+  if [[ "$node_major" -lt 20 ]]; then
+    warn "Phokus expects Node.js 20+. Current version: $(node --version). Pin Node.js 20+ in Codex environment settings."
+    exit 1
+  fi
+
+  mkdir -p "$PNPM_HOME"
+
+  if command -v corepack >/dev/null 2>&1; then
+    corepack enable
+    corepack prepare pnpm@latest --activate
+  fi
+
+  if ! command -v pnpm >/dev/null 2>&1; then
+    npm install -g pnpm
+  fi
+
+  log "Node: $(node --version)"
+  log "pnpm: $(pnpm --version)"
+}
+
+ensure_rust() {
+  log "Preparing Rust toolchain"
+
+  if ! command -v rustup >/dev/null 2>&1; then
+    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --profile minimal
+    # shellcheck source=/dev/null
+    source "$HOME/.cargo/env"
+  fi
+
+  rustup toolchain install stable --profile minimal
+  rustup default stable
+  rustup component add rustfmt clippy
+
+  log "rustc: $(rustc --version)"
+  log "cargo: $(cargo --version)"
+}
+
+install_js_dependencies() {
+  log "Installing frontend dependencies"
+  pnpm install --frozen-lockfile
+}
+
+prefetch_rust_dependencies() {
+  log "Pre-fetching Rust dependencies for CPU-safe Tauri checks"
+
+  # Phokus enables candle-cuda by default in Cargo.toml. Codex Cloud usually runs
+  # in a CPU Linux container, so use --no-default-features for checks/builds
+  # unless you intentionally configure a CUDA-capable environment.
+  cargo fetch --manifest-path src-tauri/Cargo.toml --locked
+
+  # This is intentionally a check, not a full release build. It warms the Cargo
+  # cache and catches missing native packages without making setup painfully slow.
+  cargo check --manifest-path src-tauri/Cargo.toml --locked --no-default-features
+}
+
+install_playwright_browsers() {
+  log "Installing Playwright Chromium dependencies for UI Lab/browser screenshots"
+
+  # Safe even if no Playwright tests are present yet. Useful for Codex browser
+  # inspection against `pnpm dev:ui`.
+  pnpm exec playwright install --with-deps chromium || warn "Playwright browser install failed; UI work may still run, but browser automation/screenshots may need manual setup."
+}
+
+print_next_steps() {
+  cat <<'EOF'
+
+[phokus-codex] Setup complete.
+
+Recommended Codex verification commands:
+  pnpm exec tsc --noEmit
+  pnpm build:vite
+  cargo check --manifest-path src-tauri/Cargo.toml --locked --no-default-features
+
+For visual UI work in Codex/browser environments:
+  pnpm dev:ui
+  open http://127.0.0.1:1422/?scenario=rich
+
+Other useful UI Lab scenarios:
+  http://127.0.0.1:1422/?scenario=empty
+  http://127.0.0.1:1422/?scenario=duplicates
+  http://127.0.0.1:1422/?scenario=errors
+  http://127.0.0.1:1422/?scenario=huge
+
+Avoid the below in standard CPU-only Codex Cloud unless you have configured CUDA:
+  pnpm dev:app
+  pnpm build:app:cuda
+  cargo check --manifest-path src-tauri/Cargo.toml
+EOF
+}
+
+main() {
+  install_apt_packages
+  ensure_node_and_pnpm
+  ensure_rust
+  install_js_dependencies
+  prefetch_rust_dependencies
+  install_playwright_browsers
+  print_next_steps
+}
+
+main "$@"

src-tauri/Cargo.lock

@@ -8,6 +8,17 @@ version = "2.0.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "320119579fcad9c21884f5c4861d16174d0e06250625266f50fe6898340abefa"
 
+[[package]]
+name = "ahash"
+version = "0.7.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "891477e0c6a8957309ee5c45a6368af3ae14bb510732d2684ffa19af310920f9"
+dependencies = [
+ "getrandom 0.2.17",
+ "once_cell",
+ "version_check",
+]
+
 [[package]]
 name = "ahash"
 version = "0.8.12"
@@ -52,6 +63,23 @@ version = "0.2.21"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "683d7910e743518b0e34f1186f92494becacb047c7b6bf616c96772180fef923"
 
+[[package]]
+name = "android_log-sys"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "84521a3cf562bc62942e294181d9eef17eb38ceb8c68677bc49f144e4c3d4f8d"
+
+[[package]]
+name = "android_logger"
+version = "0.15.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dbb4e440d04be07da1f1bf44fb4495ebd58669372fe0cffa6e48595ac5bd88a3"
+dependencies = [
+ "android_log-sys",
+ "env_filter 0.1.4",
+ "log",
+]
+
 [[package]]
 name = "android_system_properties"
 version = "0.1.5"
@@ -143,6 +171,12 @@ dependencies = [
  "derive_arbitrary",
 ]
 
+[[package]]
+name = "arrayvec"
+version = "0.7.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7c02d123df017efcdfbd739ef81735b36c5ba83ec3c59c80a9d7ecc718f92e50"
+
 [[package]]
 name = "async-broadcast"
 version = "0.7.2"
@@ -372,6 +406,18 @@ dependencies = [
  "serde_core",
 ]
 
+[[package]]
+name = "bitvec"
+version = "1.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1bc2832c24239b0141d5674bb9174f9d68a8b5b3f2753311927c172ca46f7e9c"
+dependencies = [
+ "funty",
+ "radium",
+ "tap",
+ "wyz",
+]
+
 [[package]]
 name = "block-buffer"
 version = "0.10.4"
@@ -403,6 +449,30 @@ dependencies = [
  "piper",
 ]
 
+[[package]]
+name = "borsh"
+version = "1.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cfd1e3f8955a5d7de9fab72fc8373fade9fb8a703968cb200ae3dc6cf08e185a"
+dependencies = [
+ "borsh-derive",
+ "bytes",
+ "cfg_aliases",
+]
+
+[[package]]
+name = "borsh-derive"
+version = "1.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bfcfdc083699101d5a7965e49925975f2f55060f94f9a05e7187be95d530ca59"
+dependencies = [
+ "once_cell",
+ "proc-macro-crate 3.5.0",
+ "proc-macro2",
+ "quote",
+ "syn 2.0.117",
+]
+
 [[package]]
 name = "brotli"
 version = "8.0.2"
@@ -430,6 +500,40 @@ version = "3.20.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "5d20789868f4b01b2f2caec9f5c4e0213b41e3e5702a50157d699ae31ced2fcb"
 
+[[package]]
+name = "byte-unit"
+version = "5.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8c6d47a4e2961fb8721bcfc54feae6455f2f64e7054f9bc67e875f0e77f4c58d"
+dependencies = [
+ "rust_decimal",
+ "schemars 1.2.1",
+ "serde",
+ "utf8-width",
+]
+
+[[package]]
+name = "bytecheck"
+version = "0.6.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "23cdc57ce23ac53c931e88a43d06d070a6fd142f2617be5855eb75efc9beb1c2"
+dependencies = [
+ "bytecheck_derive",
+ "ptr_meta",
+ "simdutf8",
+]
+
+[[package]]
+name = "bytecheck_derive"
+version = "0.6.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3db406d29fbcd95542e92559bed4d8ad92636d1ca8b3b72ede10b4bcc010e659"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 1.0.109",
+]
+
 [[package]]
 name = "bytemuck"
 version = "1.25.0"
@@ -635,6 +739,8 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b7a4d3ec6524d28a329fc53654bbadc9bdd7b0431f5d65f1a56ffb28a1ee5283"
 dependencies = [
  "find-msvc-tools",
+ "jobserver",
+ "libc",
  "shlex",
 ]
 
@@ -1450,6 +1556,16 @@ dependencies = [
  "syn 2.0.117",
 ]
 
+[[package]]
+name = "env_filter"
+version = "0.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1bf3c259d255ca70051b30e2e95b5446cdb8949ac4cd22c0d7fd634d89f568e2"
+dependencies = [
+ "log",
+ "regex",
+]
+
 [[package]]
 name = "env_filter"
 version = "1.0.1"
@@ -1474,7 +1590,7 @@ checksum = "0621c04f2196ac3f488dd583365b9c09be011a4ab8b9f37248ffcc8f6198b56a"
 dependencies = [
  "anstream",
  "anstyle",
- "env_filter",
+ "env_filter 1.0.1",
  "jiff",
  "log",
 ]
@@ -1608,6 +1724,15 @@ dependencies = [
  "simd-adler32",
 ]
 
+[[package]]
+name = "fern"
+version = "0.7.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4316185f709b23713e41e3195f90edef7fb00c3ed4adc79769cf09cc762a3b29"
+dependencies = [
+ "log",
+]
+
 [[package]]
 name = "ffmpeg-sidecar"
 version = "2.5.0"
@@ -1759,6 +1884,12 @@ dependencies = [
  "libc",
 ]
 
+[[package]]
+name = "funty"
+version = "2.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6d5a32815ae3f33302d95fdcb2ce17862f8c65363dcfd29360480ba1001fc9c"
+
 [[package]]
 name = "futf"
 version = "0.1.5"
@@ -2454,6 +2585,9 @@ name = "hashbrown"
 version = "0.12.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8a9ee70c43aaf417c914396645a0fa852624801b24ebb7ae78fe8272889ac888"
+dependencies = [
+ "ahash 0.7.8",
+]
 
 [[package]]
 name = "hashbrown"
@@ -2461,7 +2595,7 @@ version = "0.14.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e5274423e17b7c9fc20b6e7e208532f9b19825d82dfd615708b70edd83df41f1"
 dependencies = [
- "ahash",
+ "ahash 0.8.12",
 ]
 
 [[package]]
@@ -3108,6 +3242,16 @@ dependencies = [
  "syn 2.0.117",
 ]
 
+[[package]]
+name = "jobserver"
+version = "0.1.34"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9afb3de4395d6b3e67a780b6de64b51c978ecf11cb9a462c66be7d4ca9039d33"
+dependencies = [
+ "getrandom 0.3.4",
+ "libc",
+]
+
 [[package]]
 name = "js-sys"
 version = "0.3.94"
@@ -3327,6 +3471,9 @@ name = "log"
 version = "0.4.29"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "5e5032e24019045c762d3c0f28f5b6b8bbf38563a65908389bf7978758920897"
+dependencies = [
+ "value-bag",
+]
 
 [[package]]
 name = "lzma-rust2"
@@ -3477,6 +3624,12 @@ version = "0.2.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "68354c5c6bd36d73ff3feceb05efa59b6acb7626617f4962be322a825e61f79a"
 
+[[package]]
+name = "minisign-verify"
+version = "0.2.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "22f9645cb765ea72b8111f36c522475d2daa0d22c957a9826437e97534bc4e9e"
+
 [[package]]
 name = "miniz_oxide"
 version = "0.8.9"
@@ -3559,6 +3712,31 @@ dependencies = [
  "pxfm",
 ]
 
+[[package]]
+name = "mozjpeg"
+version = "0.10.13"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b7891b80aaa86097d38d276eb98b3805d6280708c4e0a1e6f6aed9380c51fec9"
+dependencies = [
+ "arrayvec",
+ "bytemuck",
+ "libc",
+ "mozjpeg-sys",
+ "rgb",
+]
+
+[[package]]
+name = "mozjpeg-sys"
+version = "2.2.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7f0dc668bf9bf888c88e2fb1ab16a406d2c380f1d082b20d51dd540ab2aa70c1"
+dependencies = [
+ "cc",
+ "dunce",
+ "libc",
+ "nasm-rs",
+]
+
 [[package]]
 name = "muda"
 version = "0.17.2"
@@ -3586,6 +3764,16 @@ version = "0.1.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "13d2233c9842d08cfe13f9eac96e207ca6a2ea10b80259ebe8ad0268be27d2af"
 
+[[package]]
+name = "nasm-rs"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "706bf8a5e8c8ddb99128c3291d31bd21f4bcde17f0f4c20ec678d85c74faa149"
+dependencies = [
+ "jobserver",
+ "log",
+]
+
 [[package]]
 name = "native-tls"
 version = "0.2.18"
@@ -3837,6 +4025,15 @@ dependencies = [
  "syn 2.0.117",
 ]
 
+[[package]]
+name = "num_threads"
+version = "0.1.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5c7398b9c8b70908f6371f47ed36737907c87c52af34c268fed0bf0ceb92ead9"
+dependencies = [
+ "libc",
+]
+
 [[package]]
 name = "objc2"
 version = "0.6.4"
@@ -3933,6 +4130,18 @@ dependencies = [
  "objc2-core-foundation",
 ]
 
+[[package]]
+name = "objc2-osa-kit"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f112d1746737b0da274ef79a23aac283376f335f4095a083a267a082f21db0c0"
+dependencies = [
+ "bitflags 2.11.0",
+ "objc2",
+ "objc2-app-kit",
+ "objc2-foundation",
+]
+
 [[package]]
 name = "objc2-quartz-core"
 version = "0.3.2"
@@ -4102,6 +4311,20 @@ dependencies = [
  "ureq",
 ]
 
+[[package]]
+name = "osakit"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "732c71caeaa72c065bb69d7ea08717bd3f4863a4f451402fc9513e29dbd5261b"
+dependencies = [
+ "objc2",
+ "objc2-foundation",
+ "objc2-osa-kit",
+ "serde",
+ "serde_json",
+ "thiserror 2.0.18",
+]
+
 [[package]]
 name = "pango"
 version = "0.18.3"
@@ -4372,7 +4595,7 @@ dependencies = [
 
 [[package]]
 name = "phokus"
-version = "0.1.0"
+version = "0.2.0"
 dependencies = [
  "anyhow",
  "candle-core",
@@ -4388,6 +4611,7 @@ dependencies = [
  "kamadak-exif",
  "log",
  "memmap2",
+ "mozjpeg",
  "notify",
  "ort",
  "r2d2",
@@ -4402,12 +4626,16 @@ dependencies = [
  "tauri-build",
  "tauri-plugin-dialog",
  "tauri-plugin-fs",
+ "tauri-plugin-log",
  "tauri-plugin-notification",
  "tauri-plugin-opener",
+ "tauri-plugin-process",
+ "tauri-plugin-single-instance",
+ "tauri-plugin-updater",
+ "tauri-plugin-window-state",
  "tokenizers",
  "tokio",
  "ureq",
- "uuid",
  "walkdir",
  "xxhash-rust",
  "zip 4.6.1",
@@ -4618,6 +4846,26 @@ dependencies = [
  "unicode-ident",
 ]
 
+[[package]]
+name = "ptr_meta"
+version = "0.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0738ccf7ea06b608c10564b31debd4f5bc5e197fc8bfe088f68ae5ce81e7a4f1"
+dependencies = [
+ "ptr_meta_derive",
+]
+
+[[package]]
+name = "ptr_meta_derive"
+version = "0.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "16b845dbfca988fa33db069c0e230574d15a3088f147a87b64c7589eb662c9ac"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 1.0.109",
+]
+
 [[package]]
 name = "pulp"
 version = "0.21.5"
@@ -4728,6 +4976,12 @@ dependencies = [
  "uuid",
 ]
 
+[[package]]
+name = "radium"
+version = "0.7.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dc33ff2d4973d518d823d61aa239014831e521c75da58e3df4840d3f47749d09"
+
 [[package]]
 name = "rand"
 version = "0.7.3"
@@ -5001,6 +5255,15 @@ version = "0.8.10"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "dc897dd8d9e8bd1ed8cdad82b5966c3e0ecae09fb1907d58efaa013543185d0a"
 
+[[package]]
+name = "rend"
+version = "0.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "71fe3824f5629716b1589be05dacd749f6aa084c87e00e016714a8cdfccc997c"
+dependencies = [
+ "bytecheck",
+]
+
 [[package]]
 name = "reqwest"
 version = "0.12.28"
@@ -5058,15 +5321,20 @@ dependencies = [
  "http-body",
  "http-body-util",
  "hyper",
+ "hyper-rustls",
  "hyper-util",
  "js-sys",
  "log",
  "percent-encoding",
  "pin-project-lite",
+ "rustls",
+ "rustls-pki-types",
+ "rustls-platform-verifier",
  "serde",
  "serde_json",
  "sync_wrapper",
  "tokio",
+ "tokio-rustls",
  "tokio-util",
  "tower",
  "tower-http",
@@ -5102,6 +5370,15 @@ dependencies = [
  "windows-sys 0.60.2",
 ]
 
+[[package]]
+name = "rgb"
+version = "0.8.53"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "47b34b781b31e5d73e9fbc8689c70551fd1ade9a19e3e28cfec8580a79290cc4"
+dependencies = [
+ "bytemuck",
+]
+
 [[package]]
 name = "ring"
 version = "0.17.14"
@@ -5116,6 +5393,35 @@ dependencies = [
  "windows-sys 0.52.0",
 ]
 
+[[package]]
+name = "rkyv"
+version = "0.7.46"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2297bf9c81a3f0dc96bc9521370b88f054168c29826a75e89c55ff196e7ed6a1"
+dependencies = [
+ "bitvec",
+ "bytecheck",
+ "bytes",
+ "hashbrown 0.12.3",
+ "ptr_meta",
+ "rend",
+ "rkyv_derive",
+ "seahash",
+ "tinyvec",
+ "uuid",
+]
+
+[[package]]
+name = "rkyv_derive"
+version = "0.7.46"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "84d7b42d4b8d06048d3ac8db0eb31bcb942cbeb709f0b5f2b2ebde398d3038f5"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 1.0.109",
+]
+
 [[package]]
 name = "rusqlite"
 version = "0.32.1"
@@ -5130,6 +5436,23 @@ dependencies = [
  "smallvec",
 ]
 
+[[package]]
+name = "rust_decimal"
+version = "1.42.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "be2a24f50780bc85f09cc6ac299bdf1424302742d77221106859c9d8b102126a"
+dependencies = [
+ "arrayvec",
+ "borsh",
+ "bytes",
+ "num-traits",
+ "rand 0.8.5",
+ "rkyv",
+ "serde",
+ "serde_json",
+ "wasm-bindgen",
+]
+
 [[package]]
 name = "rustc-hash"
 version = "2.1.2"
@@ -5173,6 +5496,18 @@ dependencies = [
  "zeroize",
 ]
 
+[[package]]
+name = "rustls-native-certs"
+version = "0.8.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dab5152771c58876a2146916e53e35057e1a4dfa2b9df0f0305b07f611fdea4d"
+dependencies = [
+ "openssl-probe",
+ "rustls-pki-types",
+ "schannel",
+ "security-framework",
+]
+
 [[package]]
 name = "rustls-pki-types"
 version = "1.14.0"
@@ -5182,6 +5517,33 @@ dependencies = [
  "zeroize",
 ]
 
+[[package]]
+name = "rustls-platform-verifier"
+version = "0.6.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1d99feebc72bae7ab76ba994bb5e121b8d83d910ca40b36e0921f53becc41784"
+dependencies = [
+ "core-foundation 0.10.1",
+ "core-foundation-sys",
+ "jni",
+ "log",
+ "once_cell",
+ "rustls",
+ "rustls-native-certs",
+ "rustls-platform-verifier-android",
+ "rustls-webpki",
+ "security-framework",
+ "security-framework-sys",
+ "webpki-root-certs",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "rustls-platform-verifier-android"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f87165f0995f63a9fbeea62b64d10b4d9d8e78ec6d7d51fb2125fda7bb36788f"
+
 [[package]]
 name = "rustls-webpki"
 version = "0.103.10"
@@ -5310,6 +5672,12 @@ version = "1.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "94143f37725109f92c262ed2cf5e59bce7498c01bcc1502d7b9afe439a4e9f49"
 
+[[package]]
+name = "seahash"
+version = "4.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1c107b6f4780854c8b126e228ea8869f4d7b71260f962fefb57b996b8959ba6b"
+
 [[package]]
 name = "security-framework"
 version = "3.7.0"
@@ -5607,6 +5975,12 @@ version = "0.3.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "703d5c7ef118737c72f1af64ad2f6f8c5e1921f818cdcb97b8fe6fc69bf66214"
 
+[[package]]
+name = "simdutf8"
+version = "0.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e3a9fe34e3e7a50316060351f37187a3f546bce95496156754b601a5fa71b76e"
+
 [[package]]
 name = "siphasher"
 version = "0.3.11"
@@ -5958,6 +6332,12 @@ dependencies = [
  "syn 2.0.117",
 ]
 
+[[package]]
+name = "tap"
+version = "1.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "55937e1799185b12863d447f42597ed69d9928686b8d88a1df17376a097d8369"
+
 [[package]]
 name = "tar"
 version = "0.4.45"
@@ -6149,6 +6529,28 @@ dependencies = [
  "url",
 ]
 
+[[package]]
+name = "tauri-plugin-log"
+version = "2.8.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7545bd67f070a4500432c826e2e0682146a1d6712aee22a2786490156b574d93"
+dependencies = [
+ "android_logger",
+ "byte-unit",
+ "fern",
+ "log",
+ "objc2",
+ "objc2-foundation",
+ "serde",
+ "serde_json",
+ "serde_repr",
+ "swift-rs",
+ "tauri",
+ "tauri-plugin",
+ "thiserror 2.0.18",
+ "time",
+]
+
 [[package]]
 name = "tauri-plugin-notification"
 version = "2.3.3"
@@ -6190,6 +6592,79 @@ dependencies = [
  "zbus",
 ]
 
+[[package]]
+name = "tauri-plugin-process"
+version = "2.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d55511a7bf6cd70c8767b02c97bf8134fa434daf3926cfc1be0a0f94132d165a"
+dependencies = [
+ "tauri",
+ "tauri-plugin",
+]
+
+[[package]]
+name = "tauri-plugin-single-instance"
+version = "2.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5c8f29386f5e9fdc699182388a33ee80a56de436d91b67459e86afef426282af"
+dependencies = [
+ "serde",
+ "serde_json",
+ "tauri",
+ "thiserror 2.0.18",
+ "tracing",
+ "windows-sys 0.60.2",
+ "zbus",
+]
+
+[[package]]
+name = "tauri-plugin-updater"
+version = "2.10.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "806d9dac662c2e4594ff03c647a552f2c9bd544e7d0f683ec58f872f952ce4af"
+dependencies = [
+ "base64 0.22.1",
+ "dirs",
+ "flate2",
+ "futures-util",
+ "http",
+ "infer",
+ "log",
+ "minisign-verify",
+ "osakit",
+ "percent-encoding",
+ "reqwest 0.13.2",
+ "rustls",
+ "semver",
+ "serde",
+ "serde_json",
+ "tar",
+ "tauri",
+ "tauri-plugin",
+ "tempfile",
+ "thiserror 2.0.18",
+ "time",
+ "tokio",
+ "url",
+ "windows-sys 0.60.2",
+ "zip 4.6.1",
+]
+
+[[package]]
+name = "tauri-plugin-window-state"
+version = "2.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "73736611e14142408d15353e21e3cca2f12a3cfb523ad0ce85999b6d2ef1a704"
+dependencies = [
+ "bitflags 2.11.0",
+ "log",
+ "serde",
+ "serde_json",
+ "tauri",
+ "tauri-plugin",
+ "thiserror 2.0.18",
+]
+
 [[package]]
 name = "tauri-runtime"
 version = "2.10.1"
@@ -6398,7 +6873,9 @@ checksum = "743bd48c283afc0388f9b8827b976905fb217ad9e647fae3a379a9283c4def2c"
 dependencies = [
  "deranged",
  "itoa",
+ "libc",
  "num-conv",
+ "num_threads",
  "powerfmt",
  "serde_core",
  "time-core",
@@ -6431,13 +6908,28 @@ dependencies = [
  "zerovec",
 ]
 
+[[package]]
+name = "tinyvec"
+version = "1.11.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3e61e67053d25a4e82c844e8424039d9745781b3fc4f32b8d55ed50f5f667ef3"
+dependencies = [
+ "tinyvec_macros",
+]
+
+[[package]]
+name = "tinyvec_macros"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1f3ccbac311fea05f86f61904b462b55fb3df8837a366dfc601a0161d0532f20"
+
 [[package]]
 name = "tokenizers"
 version = "0.22.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b238e22d44a15349529690fb07bd645cf58149a1b1e44d6cb5bd1641ff1a6223"
 dependencies = [
- "ahash",
+ "ahash 0.8.12",
  "aho-corasick",
  "compact_str",
  "dary_heap",
@@ -6474,25 +6966,11 @@ dependencies = [
  "bytes",
  "libc",
  "mio 1.2.0",
- "parking_lot",
  "pin-project-lite",
- "signal-hook-registry",
  "socket2",
- "tokio-macros",
  "windows-sys 0.61.2",
 ]
 
-[[package]]
-name = "tokio-macros"
-version = "2.7.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "385a6cb71ab9ab790c5fe8d67f1645e6c450a7ce006a33de03daa956cf70a496"
-dependencies = [
- "proc-macro2",
- "quote",
- "syn 2.0.117",
-]
-
 [[package]]
 name = "tokio-native-tls"
 version = "0.3.1"
@@ -6957,6 +7435,12 @@ version = "0.7.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "09cc8ee72d2a9becf2f2febe0205bbed8fc6615b7cb429ad062dc7b7ddd036a9"
 
+[[package]]
+name = "utf8-width"
+version = "0.1.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1292c0d970b54115d14f2492fe0170adf21d68a1de108eebc51c1df4f346a091"
+
 [[package]]
 name = "utf8-zero"
 version = "0.8.1"
@@ -6988,6 +7472,12 @@ dependencies = [
  "wasm-bindgen",
 ]
 
+[[package]]
+name = "value-bag"
+version = "1.12.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7ba6f5989077681266825251a52748b8c1d8a4ad098cc37e440103d0ea717fc0"
+
 [[package]]
 name = "vcpkg"
 version = "0.2.15"
@@ -8096,6 +8586,15 @@ dependencies = [
  "x11-dl",
 ]
 
+[[package]]
+name = "wyz"
+version = "0.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "05f360fc0b24296329c78fda852a1e9ae82de9cf7b27dae4b7f62f118f77b9ed"
+dependencies = [
+ "tap",
+]
+
 [[package]]
 name = "x11"
 version = "2.21.0"

src-tauri/Cargo.toml

@@ -1,8 +1,9 @@
 [package]
 name = "phokus"
-version = "0.1.0"
-description = "A performant image gallery application"
+version = "0.2.0"
+description = "Local-first desktop media library"
 authors = ["JezzWTF"]
+license = "MIT"
 edition = "2021"
 
 [lib]
@@ -13,7 +14,9 @@ crate-type = ["staticlib", "cdylib", "rlib"]
 tauri-build = { version = "2", features = [] }
 
 [features]
-default = []
+# CUDA is on by default for the main dev machine; build with
+# `--no-default-features` (pnpm dev:app:cpu) on machines without the toolkit.
+default = ["candle-cuda"]
 candle-cuda = ["candle-core/cuda", "candle-nn/cuda", "candle-transformers/cuda"]
 
 [dependencies]
@@ -32,18 +35,16 @@ image = { version = "0.25", default-features = false, features = ["jpeg", "png",
 fast_image_resize = { version = "6.0.0", features = ["image"] }
 walkdir = "2"
 rayon = "1"
-tokio = { version = "1", features = ["full"] }
-chrono = { version = "0.4", features = ["serde"] }
-uuid = { version = "1", features = ["v4"] }
+tokio = { version = "1", features = ["rt-multi-thread"] }
+chrono = "0.4"
 anyhow = "1"
-log = "0.4"
 ffmpeg-sidecar = "2.5.0"
 xxhash-rust = { version = "0.8", features = ["xxh3"] }
 memmap2 = "0.9"
 sysinfo = "0.38.4"
-candle-core = { version = "0.10.2", features = ["cuda"] }
-candle-nn = { version = "0.10.2", features = ["cuda"] }
-candle-transformers = { version = "0.10.2", features = ["cuda"] }
+candle-core = "0.10.2"
+candle-nn = "0.10.2"
+candle-transformers = "0.10.2"
 hf-hub = { version = "0.5.0", default-features = false, features = ["ureq", "native-tls"] }
 tokenizers = "0.22.1"
 ort = { version = "2.0.0-rc.12", default-features = false, features = ["std", "ndarray", "download-binaries", "copy-dylibs", "load-dynamic", "directml", "api-24", "tls-native"] }
@@ -53,6 +54,13 @@ csv = "1"
 kamadak-exif = "0.5"
 notify = "6"
 tauri-plugin-notification = "2"
+mozjpeg = "0.10.13"
+tauri-plugin-updater = "2"
+tauri-plugin-process = "2"
+tauri-plugin-log = "2"
+tauri-plugin-single-instance = "2"
+tauri-plugin-window-state = "2"
+log = "0.4"
 
 # ── Dev-mode performance ────────────────────────────────────────────────────
 # opt-level=1 on the main crate keeps incremental compile short.
@@ -81,6 +89,10 @@ opt-level = 3
 opt-level = 3
 [profile.dev.package.fast_image_resize]
 opt-level = 3
+[profile.dev.package.mozjpeg]
+opt-level = 3
+[profile.dev.package.mozjpeg-sys]
+opt-level = 3
 
 # Parallel work scheduler
 [profile.dev.package.rayon]

src-tauri/build.rs

@@ -15,13 +15,17 @@ fn main() {
             if let Ok(path) = &cuda_path {
                 println!("cargo:warning=CUDA Toolkit found at {path} — GPU acceleration enabled.");
             } else {
-                println!("cargo:warning=CUDA Toolkit (nvcc) found in PATH — GPU acceleration enabled.");
+                println!(
+                    "cargo:warning=CUDA Toolkit (nvcc) found in PATH — GPU acceleration enabled."
+                );
             }
         } else {
             println!("cargo:warning=━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
             println!("cargo:warning=  candle-cuda feature is enabled but no CUDA Toolkit found.");
             println!("cargo:warning=  Install CUDA Toolkit from https://developer.nvidia.com/cuda-downloads");
-            println!("cargo:warning=  Or build without GPU support: cargo build --no-default-features");
+            println!(
+                "cargo:warning=  Or build without GPU support: cargo build --no-default-features"
+            );
             println!("cargo:warning=━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
         }
     }

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",
@@ -14,9 +16,13 @@
     "fs:read-files",
     "fs:read-dirs",
     "notification:default",
+    "updater:default",
+    "process:allow-restart",
     "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

@@ -0,0 +1,54 @@
+/// AI-generated tags that are too broad/noisy to be useful in this gallery.
+/// Edit this list to change what the tagger removes. Manual user tags are not
+/// affected.
+pub const AI_TAG_REMOVAL_LIST: &[&str] = &["1girl", "1boy", "no humans", "2girls", "2boys"];
+
+fn normalize_tag_for_removal(tag: &str) -> String {
+    tag.trim()
+        .chars()
+        .filter(|c| !matches!(c, ' ' | '_' | '-'))
+        .flat_map(char::to_lowercase)
+        .collect()
+}
+
+pub fn is_removed_ai_tag(tag: &str) -> bool {
+    let normalized = normalize_tag_for_removal(tag);
+    AI_TAG_REMOVAL_LIST
+        .iter()
+        .any(|blocked| normalize_tag_for_removal(blocked) == normalized)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn removed_ai_tags_match_common_spellings() {
+        for tag in [
+            "1girl",
+            "1 girl",
+            "1_girl",
+            "1-girl",
+            "NO_HUMANS",
+            "no humans",
+        ] {
+            assert!(is_removed_ai_tag(tag), "{tag} should be removed");
+        }
+    }
+
+    #[test]
+    fn removed_ai_tags_do_not_match_unrelated_tags() {
+        for tag in ["girl", "boy", "humans", "solo", "landscape"] {
+            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,43 +11,16 @@ use ort::session::{builder::GraphOptimizationLevel, Session};
 use ort::value::{Shape, Tensor};
 use serde::{Deserialize, Serialize};
 use std::borrow::Cow;
-use std::io::{Cursor, Read};
 use std::path::{Path, PathBuf};
 use std::sync::atomic::{AtomicBool, Ordering};
-use std::sync::OnceLock;
 use std::time::Instant;
 use tokenizers::Tokenizer;
 
 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,
@@ -62,15 +38,14 @@ const REQUIRED_FILES: &[&str] = &[
     "onnx/embed_tokens_fp16.onnx",
 ];
 
-static ORT_RUNTIME_INIT: OnceLock<std::result::Result<(), String>> = OnceLock::new();
-
 /// 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);
 
-#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[derive(Clone, Copy, Debug, Default, Deserialize, Eq, PartialEq, Serialize)]
 #[serde(rename_all = "lowercase")]
 pub enum CaptionAcceleration {
+    #[default]
     Auto,
     Cpu,
     Directml,
@@ -86,17 +61,12 @@ impl CaptionAcceleration {
     }
 }
 
-impl Default for CaptionAcceleration {
-    fn default() -> Self {
-        Self::Auto
-    }
-}
-
-#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[derive(Clone, Copy, Debug, Default, Deserialize, Eq, PartialEq, Serialize)]
 #[serde(rename_all = "lowercase")]
 pub enum CaptionDetail {
     Short,
     Detailed,
+    #[default]
     Paragraph,
 }
 
@@ -126,12 +96,6 @@ impl CaptionDetail {
     }
 }
 
-impl Default for CaptionDetail {
-    fn default() -> Self {
-        Self::Paragraph
-    }
-}
-
 #[derive(Serialize)]
 pub struct CaptionModelStatus {
     pub model_id: &'static str,
@@ -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);
@@ -470,7 +434,7 @@ impl FlorenceCaptioner {
             acceleration,
             false,
         )?;
-        println!(
+        log::info!(
             "Florence sessions loaded in {:?} with {:?} acceleration (total init {:?})",
             sessions_started_at.elapsed(),
             acceleration,
@@ -490,9 +454,9 @@ impl FlorenceCaptioner {
 
     pub fn generate(&mut self, image_path: &Path) -> Result<String> {
         let started_at = Instant::now();
-        println!("Florence caption started: {}", image_path.display());
+        log::info!("Florence caption started: {}", image_path.display());
         let image_features = run_vision_encoder(&mut self.vision_session, image_path)?;
-        println!("Florence vision encoder done in {:?}", started_at.elapsed());
+        log::info!("Florence vision encoder done in {:?}", started_at.elapsed());
         let prompt_ids = self
             .tokenizer
             .encode(self.caption_detail.prompt(), false)
@@ -502,7 +466,7 @@ impl FlorenceCaptioner {
             .map(|id| i64::from(*id))
             .collect::<Vec<_>>();
         let prompt_embeds = run_token_embedder(&mut self.embed_session, &prompt_ids)?;
-        println!(
+        log::info!(
             "Florence token embeddings done in {:?}",
             started_at.elapsed()
         );
@@ -513,7 +477,7 @@ impl FlorenceCaptioner {
             &encoder_embeds,
             &encoder_attention_mask,
         )?;
-        println!("Florence encoder done in {:?}", started_at.elapsed());
+        log::info!("Florence encoder done in {:?}", started_at.elapsed());
 
         let generated_ids = run_decoder(
             &mut self.decoder_prefill_session,
@@ -523,7 +487,7 @@ impl FlorenceCaptioner {
             &encoder_attention_mask,
             self.caption_detail.max_new_tokens(),
         )?;
-        println!("Florence decoder done in {:?}", started_at.elapsed());
+        log::info!("Florence decoder done in {:?}", started_at.elapsed());
 
         let generated_u32 = generated_ids
             .into_iter()
@@ -647,67 +611,6 @@ fn probe_vision_session(
     })
 }
 
-pub fn ensure_onnx_runtime(local_dir: &Path) -> Result<()> {
-    let dll_path = local_dir.join(ONNX_RUNTIME_DLL_FILE);
-    ORT_RUNTIME_INIT
-        .get_or_init(|| {
-            if !dll_path.exists() {
-                return Err(format!(
-                    "ONNX Runtime DLL is missing: {}",
-                    dll_path.display()
-                ));
-            }
-            ort::environment::init_from(&dll_path)
-                .map_err(|error| error.to_string())?
-                .with_name("phokus-florence")
-                .commit();
-            Ok(())
-        })
-        .clone()
-        .map_err(anyhow::Error::msg)
-}
-
-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(())
-}
-
-fn download_nuget_file(source_url: &str, archive_path: &str, destination: &Path) -> Result<()> {
-    let mut response = ureq::get(source_url)
-        .call()
-        .map_err(|error| anyhow::anyhow!("{error}"))?;
-    let mut bytes = Vec::new();
-    response
-        .body_mut()
-        .as_reader()
-        .read_to_end(&mut bytes)
-        .map_err(|error| anyhow::anyhow!("{error}"))?;
-
-    let mut archive = zip::ZipArchive::new(Cursor::new(bytes))?;
-    let mut dll = archive.by_name(archive_path)?;
-    if let Some(parent) = destination.parent() {
-        std::fs::create_dir_all(parent)?;
-    }
-
-    let temp_destination = destination.with_extension("tmp");
-    {
-        let mut file = std::fs::File::create(&temp_destination)?;
-        std::io::copy(&mut dll, &mut file)?;
-    }
-    std::fs::rename(temp_destination, destination)?;
-    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()))
@@ -784,7 +687,7 @@ fn run_decoder(
             "inputs_embeds" => prefill_inputs_embeds_tensor
         })
         .map_err(|error| anyhow::anyhow!("{error}"))?;
-    println!(
+    log::info!(
         "Florence decoder prefill done in {:?}",
         prefill_started_at.elapsed()
     );
@@ -848,7 +751,7 @@ fn run_decoder(
         decoder_kv = collect_present_key_values(&outputs, DECODER_LAYERS)?;
     }
 
-    println!("Florence decoder produced {} token(s)", generated.len());
+    log::info!("Florence decoder produced {} token(s)", generated.len());
     Ok(generated)
 }
 
@@ -886,7 +789,7 @@ fn create_session(
         CaptionAcceleration::Auto | CaptionAcceleration::Directml => {
             // `allow_directml` is false for the 4 text/decoder sessions —
             // they intentionally run on CPU regardless of the setting.
-            println!(
+            log::info!(
                 "Florence: using CPU for {} (DirectML disabled for this session type)",
                 path.display()
             );

src-tauri/src/color.rs

@@ -0,0 +1,91 @@
+//! Dominant-color palette extraction for color search.
+//!
+//! Colors are sampled from the already-generated thumbnail (small, fast) rather
+//! than the full image. We coarse-quantize pixels into an RGB histogram, then
+//! return the most populated bins as representative colors with their weight
+//! (fraction of sampled pixels). Search then filters images whose palette has a
+//! color within a distance threshold of the query color.
+
+use image::RgbImage;
+use std::collections::HashMap;
+use std::path::Path;
+
+#[derive(Debug, Clone, Copy)]
+pub struct PaletteColor {
+    pub r: u8,
+    pub g: u8,
+    pub b: u8,
+    /// Fraction of sampled pixels (0.0–1.0) that fell in this color's bin.
+    pub weight: f32,
+}
+
+/// Bits kept per channel when binning. 4 bits → 16 levels/channel → 4096 bins:
+/// coarse enough to group near-identical shades, fine enough to separate hues.
+const QUANT_BITS: u32 = 4;
+/// Cap on sampled pixels so very large frames stay cheap; thumbnails are tiny so
+/// this rarely bites, but the backfill may read arbitrary thumbnail sizes.
+const MAX_SAMPLES: usize = 50_000;
+
+/// Extract up to `k` dominant colors from an RGB image, most-common first.
+pub fn extract_palette(img: &RgbImage, k: usize) -> Vec<PaletteColor> {
+    let pixels = img.as_raw();
+    let pixel_count = pixels.len() / 3;
+    if pixel_count == 0 {
+        return Vec::new();
+    }
+    let step = (pixel_count / MAX_SAMPLES).max(1);
+    let shift = 8 - QUANT_BITS;
+
+    // bin key → (sum_r, sum_g, sum_b, count); summing lets us return the bin's
+    // average color rather than the quantized corner.
+    let mut bins: HashMap<u16, (u64, u64, u64, u64)> = HashMap::new();
+    let mut total: u64 = 0;
+    for pixel in pixels.chunks_exact(3).step_by(step) {
+        let (r, g, b) = (pixel[0], pixel[1], pixel[2]);
+        let key = (((r as u16) >> shift) << (QUANT_BITS * 2))
+            | (((g as u16) >> shift) << QUANT_BITS)
+            | ((b as u16) >> shift);
+        let entry = bins.entry(key).or_insert((0, 0, 0, 0));
+        entry.0 += r as u64;
+        entry.1 += g as u64;
+        entry.2 += b as u64;
+        entry.3 += 1;
+        total += 1;
+    }
+    if total == 0 {
+        return Vec::new();
+    }
+
+    let mut entries: Vec<(u64, u64, u64, u64)> = bins.into_values().collect();
+    entries.sort_unstable_by_key(|entry| std::cmp::Reverse(entry.3));
+    entries
+        .into_iter()
+        .take(k)
+        .map(|(sum_r, sum_g, sum_b, count)| PaletteColor {
+            r: (sum_r / count) as u8,
+            g: (sum_g / count) as u8,
+            b: (sum_b / count) as u8,
+            weight: count as f32 / total as f32,
+        })
+        .collect()
+}
+
+/// Decode a thumbnail file and extract its palette. Used by the backfill pass.
+pub fn extract_palette_from_file(thumbnail_path: &Path, k: usize) -> Option<Vec<PaletteColor>> {
+    let img = image::ImageReader::open(thumbnail_path)
+        .ok()?
+        .decode()
+        .ok()?;
+    Some(extract_palette(&img.into_rgb8(), k))
+}
+
+/// Number of palette colors stored per image.
+pub const PALETTE_SIZE: usize = 5;
+
+/// Max squared RGB distance for a palette color to count as matching a query
+/// color (~70 units in RGB space). Tunable feel/precision of color search.
+pub const MATCH_DISTANCE_SQ: i64 = 4900;
+
+/// Minimum weight (fraction of pixels) a palette color must have to match, so
+/// trivial specks of a color don't trigger a match.
+pub const MATCH_MIN_WEIGHT: f64 = 0.05;

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/embedder.rs

@@ -20,7 +20,7 @@ fn with_text_embedder<T>(f: impl FnOnce(&ClipImageEmbedder) -> Result<T>) -> Res
         .lock()
         .map_err(|_| anyhow::anyhow!("Text embedder lock poisoned"))?;
     if guard.is_none() {
-        println!("Initializing CLIP text embedder...");
+        log::info!("Initializing CLIP text embedder...");
         *guard = Some(ClipImageEmbedder::new()?);
     }
     f(guard.as_ref().unwrap())
@@ -35,13 +35,13 @@ pub struct ClipImageEmbedder {
 
 impl ClipImageEmbedder {
     pub fn new() -> Result<Self> {
-        println!("Initializing CLIP image embedder...");
+        log::info!("Initializing CLIP image embedder...");
         let api = Api::new()?;
         let repo = api.repo(Repo::new(
             "laion/CLIP-ViT-B-32-laion2B-s34B-b79K".to_string(),
             RepoType::Model,
         ));
-        println!("Resolving CLIP model weights from Hugging Face cache...");
+        log::info!("Resolving CLIP model weights from Hugging Face cache...");
         let model_path = repo.get("model.safetensors")?;
         let tokenizer_repo = api.repo(Repo::new(
             "openai/clip-vit-base-patch32".to_string(),
@@ -60,7 +60,7 @@ impl ClipImageEmbedder {
         };
         let model = ClipModel::new(vb, &config)?;
         let tokenizer = Tokenizer::from_file(tokenizer_path).map_err(anyhow::Error::msg)?;
-        println!("CLIP image embedder ready.");
+        log::info!("CLIP image embedder ready.");
 
         Ok(Self {
             model,
@@ -160,7 +160,7 @@ impl ClipImageEmbedder {
             let ids = enc.get_ids();
             let len = ids.len().min(max_len);
             for j in 0..len {
-                flat[i * max_len + j] = ids[j] as u32;
+                flat[i * max_len + j] = ids[j];
             }
         }
 
@@ -177,23 +177,25 @@ impl ClipImageEmbedder {
 fn resolve_device() -> Result<Device> {
     match Device::cuda_if_available(0) {
         Ok(device) if device.is_cuda() => {
-            println!("CLIP embedder: using CUDA GPU (device 0).");
+            log::info!("CLIP embedder: using CUDA GPU (device 0).");
             return Ok(device);
         }
         Ok(_) => {
-            println!("CLIP embedder: no compatible CUDA GPU found — using CPU.");
+            log::info!("CLIP embedder: no compatible CUDA GPU found — using CPU.");
         }
         Err(e) => {
-            println!("CLIP embedder: CUDA init failed ({e}) — using CPU.");
+            log::info!("CLIP embedder: CUDA init failed ({e}) — using CPU.");
         }
     }
     Ok(Device::Cpu)
 }
 
 fn load_image(path: &Path, image_size: usize) -> Result<Tensor> {
-    let image = image::ImageReader::open(path)?
-        .with_guessed_format()?
-        .decode()?;
+    // Scaled decode: CLIP only needs image_size² pixels, so decoding a large
+    // JPEG at full resolution is wasted work. Cover mode keeps the shortest
+    // side at or above image_size for the fill-crop below. Also applies EXIF
+    // orientation, so rotated photos embed the way they are displayed.
+    let image = crate::thumbnail::decode_image_scaled(path, image_size as u32, true)?;
     let image = image.resize_to_fill(
         image_size as u32,
         image_size as u32,
@@ -208,28 +210,29 @@ fn load_image(path: &Path, image_size: usize) -> Result<Tensor> {
 }
 
 fn load_images(paths: &[PathBuf], image_size: usize) -> Result<Tensor> {
-    let mut images = Vec::with_capacity(paths.len());
-    for path in paths {
-        images.push(load_image(path, image_size)?);
-    }
+    use rayon::prelude::*;
+    let images = paths
+        .par_iter()
+        .map(|path| load_image(path, image_size))
+        .collect::<Result<Vec<_>>>()?;
     Ok(Tensor::stack(&images, 0)?)
 }
 
 /// Returns the path that should be fed to the CLIP image embedder for a given media file.
 ///
-/// For videos the thumbnail image is used (because CLIP only understands still images).
-/// If a video has no thumbnail yet, an error is returned — the caller should mark the
-/// embedding job as failed rather than trying to decode the raw video file.
+/// For videos and AVIFs the thumbnail image is used because CLIP preprocessing
+/// only uses decoders from the `image` crate, while AVIF is decoded through
+/// FFmpeg into a JPEG thumbnail.
 pub fn embedding_source_path(
     path: &str,
     thumbnail_path: Option<&str>,
     media_kind: &str,
 ) -> Result<PathBuf> {
-    if media_kind == "video" {
+    if media_kind == "video" || is_avif_path(path) {
         match thumbnail_path {
             Some(thumb) => Ok(PathBuf::from(thumb)),
             None => Err(anyhow::anyhow!(
-                "No thumbnail available yet for video '{}' — embedding deferred until thumbnail is generated",
+                "No thumbnail available yet for '{}' — embedding deferred until thumbnail is generated",
                 std::path::Path::new(path)
                     .file_name()
                     .map(|n| n.to_string_lossy())
@@ -240,3 +243,10 @@ pub fn embedding_source_path(
         Ok(PathBuf::from(path))
     }
 }
+
+fn is_avif_path(path: &str) -> bool {
+    std::path::Path::new(path)
+        .extension()
+        .and_then(|ext| ext.to_str())
+        .is_some_and(|ext| ext.eq_ignore_ascii_case("avif"))
+}

src-tauri/src/hnsw_index.rs

@@ -92,6 +92,7 @@ pub fn find_similar_image_matches(
     conn: &Connection,
     image_id: i64,
     folder_id: Option<i64>,
+    album_id: Option<i64>,
     threshold: f32,
     offset: usize,
     limit: usize,
@@ -103,10 +104,17 @@ pub fn find_similar_image_matches(
         None => return Ok(Vec::new()),
     };
 
-    // Fetch folder image IDs *before* acquiring the read lock so we don't hold
+    // Build the allowed-id set *before* acquiring the read lock so we don't hold
     // the lock across a potentially slow SQLite query, which would delay any
-    // concurrent ensure_index call waiting for a write lock.
-    let folder_image_ids: Option<Vec<i64>> = if let Some(folder_id) = folder_id {
+    // concurrent ensure_index call waiting for a write lock. Album scope takes
+    // precedence over folder scope; both reuse the HNSW filtered search.
+    let allowed_image_ids: Option<Vec<i64>> = if let Some(album_id) = album_id {
+        let mut stmt = conn.prepare("SELECT image_id FROM album_images WHERE album_id = ?1")?;
+        let ids = stmt
+            .query_map([album_id], |row| row.get::<_, i64>(0))?
+            .collect::<rusqlite::Result<Vec<_>>>()?;
+        Some(ids)
+    } else if let Some(folder_id) = folder_id {
         let ids = vector::get_all_image_embeddings_with_ids(conn, Some(folder_id))?
             .into_iter()
             .map(|(id, _)| id)
@@ -122,7 +130,7 @@ pub fn find_similar_image_matches(
     };
 
     let knbn = (offset + limit).max(limit).saturating_add(32);
-    let neighbours: Vec<Neighbour> = if let Some(image_ids) = folder_image_ids {
+    let neighbours: Vec<Neighbour> = if let Some(image_ids) = allowed_image_ids {
         let mut allowed_ids = image_ids
             .into_iter()
             .filter_map(|allowed_image_id| {

src-tauri/src/lib.rs

@@ -1,10 +1,14 @@
+mod ai_tag_filter;
 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;
@@ -16,11 +20,61 @@ use tauri::Manager;
 #[cfg_attr(mobile, tauri::mobile_entry_point)]
 pub fn run() {
     tauri::Builder::default()
+        // Must be the first plugin: a second launch hands its args to the
+        // running instance and exits before anything else initializes.
+        .plugin(tauri_plugin_single_instance::init(|app, _args, _cwd| {
+            if let Some(window) = app.get_webview_window("main") {
+                let _ = window.unminimize();
+                let _ = window.set_focus();
+            }
+        }))
+        .plugin(
+            tauri_plugin_log::Builder::new()
+                .targets([
+                    tauri_plugin_log::Target::new(tauri_plugin_log::TargetKind::Stdout),
+                    tauri_plugin_log::Target::new(tauri_plugin_log::TargetKind::LogDir {
+                        file_name: Some("phokus".into()),
+                    }),
+                ])
+                .level(log::LevelFilter::Info)
+                .max_file_size(5 * 1024 * 1024)
+                .rotation_strategy(tauri_plugin_log::RotationStrategy::KeepOne)
+                .build(),
+        )
+        .plugin(tauri_plugin_window_state::Builder::new().build())
+        .plugin(tauri_plugin_updater::Builder::new().build())
+        .plugin(tauri_plugin_process::init())
         .plugin(tauri_plugin_opener::init())
         .plugin(tauri_plugin_dialog::init())
         .plugin(tauri_plugin_fs::init())
         .plugin(tauri_plugin_notification::init())
         .setup(|app| {
+            // Fresh installs open at the fixed config size (1280×800) because the
+            // window-state plugin has nothing saved yet — too tall for laptops
+            // like 1366×768. Clamp the window to the monitor's work area (which
+            // already excludes the taskbar) and re-center it there, but only when
+            // it actually overflows, so a restored size/position on a roomier
+            // display is left untouched. Sizes are physical pixels on both sides,
+            // so this stays correct across display scaling.
+            if let Some(window) = app.get_webview_window("main") {
+                if let Ok(Some(monitor)) = window.current_monitor() {
+                    let area = monitor.work_area();
+                    let max_w = area.size.width.saturating_sub(32);
+                    let max_h = area.size.height.saturating_sub(32);
+                    if let Ok(size) = window.outer_size() {
+                        if size.width > max_w || size.height > max_h {
+                            let new_w = size.width.min(max_w);
+                            let new_h = size.height.min(max_h);
+                            let _ = window.set_size(tauri::PhysicalSize::new(new_w, new_h));
+                            let _ = window.set_position(tauri::PhysicalPosition::new(
+                                area.position.x + (area.size.width as i32 - new_w as i32) / 2,
+                                area.position.y + (area.size.height as i32 - new_h as i32) / 2,
+                            ));
+                        }
+                    }
+                }
+            }
+
             let app_dir = app
                 .path()
                 .app_data_dir()
@@ -28,7 +82,10 @@ pub fn run() {
 
             std::fs::create_dir_all(&app_dir).expect("Failed to create app data dir");
 
-            media::MediaTools::ensure_installed().expect("Failed to provision FFmpeg sidecar");
+            // FFmpeg provisioning happens in the background so the window
+            // appears immediately; workers gate video/AVIF jobs on readiness and
+            // the onboarding/Settings UI shows progress and retry.
+            media::spawn_ffmpeg_provision(app.handle().clone());
 
             let db_path = app_dir.join("gallery.db");
             let pool = db::create_pool(&db_path).expect("Failed to create database pool");
@@ -38,23 +95,46 @@ pub fn run() {
                 let conn = pool.get().expect("Failed to get connection for migration");
                 db::migrate(&conn).expect("Failed to run migrations");
                 db::reset_inflight_jobs(&conn).expect("Failed to reset inflight jobs");
+                let repaired_deferred = db::repair_deferred_embedding_jobs(&conn)
+                    .expect("Failed to repair deferred embedding jobs");
+                if repaired_deferred > 0 {
+                    log::info!("Requeued {repaired_deferred} deferred embedding jobs.");
+                }
+                let repaired_avif =
+                    db::repair_avif_jobs(&conn).expect("Failed to repair AVIF jobs");
+                if repaired_avif > 0 {
+                    log::info!("Requeued {repaired_avif} AVIF jobs.");
+                }
                 let backfilled =
                     db::backfill_embedding_jobs(&conn).expect("Failed to backfill embedding jobs");
                 if backfilled > 0 {
-                    println!("Backfilled {} embedding jobs.", backfilled);
+                    log::info!("Backfilled {backfilled} embedding jobs.");
                 }
                 let (orphaned_vectors, missing_vectors) = db::repair_embedding_consistency(&conn)
                     .expect("Failed to repair embedding consistency");
                 if orphaned_vectors > 0 || missing_vectors > 0 {
-                    println!(
-                        "Repaired embedding consistency: removed {} orphaned vectors, requeued {} missing vectors.",
-                        orphaned_vectors, missing_vectors
+                    log::info!(
+                        "Repaired embedding consistency: removed {orphaned_vectors} orphaned vectors, requeued {missing_vectors} missing vectors."
                     );
                 }
             }
 
             let thumb_dir = app_dir.join("thumbnails");
             std::fs::create_dir_all(&thumb_dir).expect("Failed to create thumbnail dir");
+            commands::restore_persisted_worker_pauses(&app_dir);
+
+            // The asset protocol scope is no longer a blanket "**": thumbnails
+            // are allowed statically in tauri.conf.json, and each indexed
+            // folder is allowed here (and in add_folder/update_folder_path).
+            {
+                let scope = app.asset_protocol_scope();
+                let conn = pool.get().expect("Failed to get connection for asset scope");
+                for folder in db::get_folders(&conn).unwrap_or_default() {
+                    if let Err(error) = scope.allow_directory(&folder.path, true) {
+                        log::error!("Failed to allow asset scope for {}: {}", folder.path, error);
+                    }
+                }
+            }
 
             let thumbnail_worker_count = std::thread::available_parallelism()
                 .map(|parallelism| StorageProfile::Balanced.thumbnail_workers(parallelism.get()))
@@ -73,6 +153,8 @@ pub fn run() {
             // Caption worker disabled — UI removed; keeping backend code intact for future use.
             // indexer::start_caption_worker(app.handle().clone(), pool.clone(), app_dir.clone());
             indexer::start_tagging_worker(app.handle().clone(), pool.clone(), app_dir.clone());
+            // Backfill color palettes for images indexed before color search existed.
+            indexer::start_color_backfill(app.handle().clone(), pool.clone());
 
             let watcher_handle = indexer::start_watcher(app.handle().clone(), pool.clone(), thumb_dir.clone());
 
@@ -84,7 +166,10 @@ pub fn run() {
         })
         .invoke_handler(tauri::generate_handler![
             commands::add_folder,
+            commands::add_folders,
+            commands::list_directories,
             commands::get_folders,
+            commands::reorder_folders,
             commands::get_background_job_progress,
             commands::remove_folder,
             commands::get_images,
@@ -113,13 +198,19 @@ pub fn run() {
             commands::suggest_image_tags,
             commands::set_worker_paused,
             commands::get_worker_states,
-            commands::get_tag_cloud,
+            commands::get_worker_pauses_persist,
+            commands::set_worker_pauses_persist,
+            commands::get_visual_clusters,
             commands::get_explore_tags,
+            commands::get_related_tags,
             commands::get_images_by_ids,
             commands::get_failed_embedding_images,
+            commands::get_failed_tagging_images,
             commands::get_tagger_model_status,
             commands::get_tagger_acceleration,
             commands::set_tagger_acceleration,
+            commands::get_tagger_model,
+            commands::set_tagger_model,
             commands::probe_tagger_runtime,
             commands::get_tagger_threshold,
             commands::set_tagger_threshold,
@@ -129,9 +220,26 @@ pub fn run() {
             commands::delete_tagger_model,
             commands::queue_tagging_jobs,
             commands::clear_tagging_jobs,
+            commands::reset_ai_tags,
             commands::get_image_tags,
             commands::add_user_tag,
             commands::remove_tag,
+            commands::rename_tag,
+            commands::delete_tag,
+            commands::get_image_exif,
+            commands::list_albums,
+            commands::create_album,
+            commands::rename_album,
+            commands::delete_album,
+            commands::delete_albums,
+            commands::reorder_albums,
+            commands::add_images_to_album,
+            commands::remove_images_from_album,
+            commands::get_album_images,
+            commands::bulk_update_details,
+            commands::bulk_add_tags,
+            commands::bulk_remove_tag,
+            commands::get_build_variant,
             commands::search_tags_autocomplete,
             commands::find_duplicates,
             commands::load_duplicate_scan_cache,
@@ -144,12 +252,21 @@ pub fn run() {
             commands::get_tagging_queue_folder_ids,
             commands::set_tagging_queue_folder_ids,
             commands::open_app_data_folder,
+            commands::open_map_location,
+            commands::open_changelog_url,
             commands::get_database_info,
             commands::vacuum_database,
+            commands::rebuild_semantic_index,
             commands::get_orphaned_thumbnails_info,
             commands::cleanup_orphaned_thumbnails,
             commands::get_muted_folder_ids,
             commands::set_muted_folder_ids,
+            commands::get_ffmpeg_status,
+            commands::retry_ffmpeg_download,
+            commands::get_onboarding_completed,
+            commands::set_onboarding_completed,
+            commands::get_last_seen_version,
+            commands::set_last_seen_version,
             commands::get_notifications_paused,
             commands::set_notifications_paused,
         ])