release: Phokus 0.1.0 release preparation

Merge chore/release-prep into main for the first public release.

- Release pipeline: CI (fmt, clippy -D warnings, tsc) + tag-triggered
  GitHub Actions building the NSIS installer as a draft release.
- Self-updater via GitHub Releases — launch check, Settings UI, update
  toast, and a title-bar focal-point indicator that lights up when a new
  version is ready.
- Production hardening: real CSP, scoped asset protocol, rotating file
  logging, single-instance, window-state.
- Guided first-run onboarding with background FFmpeg provisioning and
  resilient (curl-based, resumable) model/DLL downloads.
- Branding: Phokus aperture mark across the icon set + title bar, with a
  reusable PhokusMark component.
- CUDA installer variant with bundled runtime DLLs (built locally).
- MIT license, bundle metadata, NSIS-only target, and docs (README
  install/privacy, CHANGELOG, 0.1.0 release notes).

.github/workflows/ci.yml

@@ -0,0 +1,54 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ci-${{ 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
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 11
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - name: Install frontend dependencies
+        run: pnpm install --frozen-lockfile
+
+      # 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

.github/workflows/release.yml

@@ -0,0 +1,57 @@
+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:
+
+jobs:
+  release:
+    permissions:
+      contents: write
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 11
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - 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@v1
+        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: ${{ github.ref_name }}
+          releaseName: 'Phokus v__VERSION__'
+          releaseBody: 'See the assets below to download and install this version.'
+          releaseDraft: true
+          prerelease: false
+          uploadUpdaterJson: 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'

.gitignore

@@ -35,3 +35,10 @@ dist-ssr
 *.json
 
 *.pyc
+
+# Bundled CUDA runtime DLLs for the CUDA build (copied from the toolkit
+# locally; ~600 MB, never committed). See RELEASE_PLAN.md "CUDA release variant".
+src-tauri/cuda-redist/
+
+# Keep the CUDA build config overlay tracked despite the *.json rule above.
+!src-tauri/tauri.cuda.conf.json

CHANGELOG.md

@@ -0,0 +1,50 @@
+# 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.1.0] — Unreleased
+
+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.1.0]: https://github.com/JezzWTF/phokus/releases/tag/v0.1.0

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

@@ -36,6 +36,55 @@ A local-first desktop media library for browsing, filtering, and curating image
 | jpg, jpeg, png, gif, bmp | mp4, mov, m4v |
 | tiff, tif, webp, avif, heic, heif | 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

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>
+```

package.json

@@ -2,12 +2,16 @@
   "name": "phokus",
   "private": true,
   "version": "0.1.0",
+  "license": "MIT",
   "type": "module",
   "scripts": {
     "build:app": "tauri build",
     "build:vite": "tsc && vite build",
     "clean:app": "cd src-tauri && cargo clean",
     "dev:app": "tauri dev",
+    "dev:app:cpu": "tauri dev -- --no-default-features",
+    "build:app:cpu": "tauri build -- --no-default-features",
+    "build:app:cuda": "tauri build --config src-tauri/tauri.cuda.conf.json",
     "dev:vite": "vite",
     "preview": "vite preview",
     "tauri": "tauri"
@@ -19,6 +23,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",

pnpm-lock.yaml

@@ -26,6 +26,12 @@ importers:
       '@tauri-apps/plugin-opener':
         specifier: ^2
         version: 2.5.3
+      '@tauri-apps/plugin-process':
+        specifier: ^2.3.1
+        version: 2.3.1
+      '@tauri-apps/plugin-updater':
+        specifier: ^2.10.1
+        version: 2.10.1
       d3-force:
         specifier: ^3.0.0
         version: 3.0.0
@@ -662,6 +668,12 @@ packages:
   '@tauri-apps/plugin-opener@2.5.3':
     resolution: {integrity: sha512-CCcUltXMOfUEArbf3db3kCE7Ggy1ExBEBl51Ko2ODJ6GDYHRp1nSNlQm5uNCFY5k7/ufaK5Ib3Du/Zir19IYQQ==}
 
+  '@tauri-apps/plugin-process@2.3.1':
+    resolution: {integrity: sha512-nCa4fGVaDL/B9ai03VyPOjfAHRHSBz5v6F/ObsB73r/dA3MHHhZtldaDMIc0V/pnUw9ehzr2iEG+XkSEyC0JJA==}
+
+  '@tauri-apps/plugin-updater@2.10.1':
+    resolution: {integrity: sha512-NFYMg+tWOZPJdzE/PpFj2qfqwAWwNS3kXrb1tm1gnBJ9mYzZ4WDRrwy8udzWoAnfGCHLuePNLY1WVCNHnh3eRA==}
+
   '@types/babel__core@7.20.5':
     resolution: {integrity: sha512-qoQprZvz5wQFJwMDqeseRXWv3rqMvhgpbXFfVyWhbx9X47POIA6i/+dXefEmZKoAgOaTdaIgNSMqMIU61yRyzA==}
 
@@ -1462,6 +1474,14 @@ snapshots:
     dependencies:
       '@tauri-apps/api': 2.10.1
 
+  '@tauri-apps/plugin-process@2.3.1':
+    dependencies:
+      '@tauri-apps/api': 2.10.1
+
+  '@tauri-apps/plugin-updater@2.10.1':
+    dependencies:
+      '@tauri-apps/api': 2.10.1
+
   '@types/babel__core@7.20.5':
     dependencies:
       '@babel/parser': 7.29.2

pnpm-workspace.yaml

@@ -0,0 +1,2 @@
+allowBuilds:
+  esbuild: true

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"
@@ -378,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"
@@ -409,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"
@@ -436,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"
@@ -1458,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"
@@ -1482,7 +1590,7 @@ checksum = "0621c04f2196ac3f488dd583365b9c09be011a4ab8b9f37248ffcc8f6198b56a"
 dependencies = [
  "anstream",
  "anstyle",
- "env_filter",
+ "env_filter 1.0.1",
  "jiff",
  "log",
 ]
@@ -1616,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"
@@ -1767,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"
@@ -2462,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"
@@ -2469,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]]
@@ -3345,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"
@@ -3495,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"
@@ -3890,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"
@@ -3986,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"
@@ -4155,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"
@@ -4456,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",
@@ -4672,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"
@@ -4782,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"
@@ -5055,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"
@@ -5112,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",
@@ -5179,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"
@@ -5193,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"
@@ -5236,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"
@@ -5245,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"
@@ -5373,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"
@@ -5670,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"
@@ -6021,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"
@@ -6212,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"
@@ -6253,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"
@@ -6461,7 +6873,9 @@ checksum = "743bd48c283afc0388f9b8827b976905fb217ad9e647fae3a379a9283c4def2c"
 dependencies = [
  "deranged",
  "itoa",
+ "libc",
  "num-conv",
+ "num_threads",
  "powerfmt",
  "serde_core",
  "time-core",
@@ -6494,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",
@@ -6537,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"
@@ -7020,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"
@@ -7051,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"
@@ -8159,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"
+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"] }
@@ -54,6 +55,12 @@ 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.

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

@@ -14,6 +14,8 @@
     "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",

src-tauri/src/captioner.rs

@@ -8,13 +8,20 @@ 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::io::Read;
 use std::path::{Path, PathBuf};
+use std::process::Command;
 use std::sync::atomic::{AtomicBool, Ordering};
-use std::sync::OnceLock;
+use std::sync::Mutex;
 use std::time::Instant;
 use tokenizers::Tokenizer;
 
+// Suppress the console window when spawning curl.exe from the GUI app.
+#[cfg(target_os = "windows")]
+use std::os::windows::process::CommandExt;
+#[cfg(target_os = "windows")]
+const CREATE_NO_WINDOW: u32 = 0x08000000;
+
 pub const FLORENCE_MODEL_ID: &str = "onnx-community/Florence-2-base-ft";
 pub const FLORENCE_CAPTION_MODEL_NAME: &str = "florence-2-base-ft-onnx-q4";
 const ONNX_RUNTIME_NUGET_URL: &str =
@@ -62,7 +69,10 @@ const REQUIRED_FILES: &[&str] = &[
     "onnx/embed_tokens_fp16.onnx",
 ];
 
-static ORT_RUNTIME_INIT: OnceLock<std::result::Result<(), String>> = OnceLock::new();
+// Mutex<bool> rather than OnceLock<Result>: a failed attempt (DLL not yet
+// downloaded) must NOT be cached, or a later successful download could never
+// recover within the same app session.
+static ORT_RUNTIME_INIT: Mutex<bool> = Mutex::new(false);
 
 /// Set to `true` by `set_caption_acceleration` so the caption worker loop
 /// knows to drop its cached `FlorenceCaptioner` and reload with the new EP.
@@ -470,7 +480,7 @@ impl FlorenceCaptioner {
             acceleration,
             false,
         )?;
-        println!(
+        log::info!(
             "Florence sessions loaded in {:?} with {:?} acceleration (total init {:?})",
             sessions_started_at.elapsed(),
             acceleration,
@@ -490,9 +500,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 +512,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 +523,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 +533,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()
@@ -648,23 +658,61 @@ fn probe_vision_session(
 }
 
 pub fn ensure_onnx_runtime(local_dir: &Path) -> Result<()> {
+    let mut initialized = ORT_RUNTIME_INIT
+        .lock()
+        .map_err(|_| anyhow::anyhow!("ONNX runtime init lock poisoned"))?;
+    if *initialized {
+        return Ok(());
+    }
     let dll_path = local_dir.join(ONNX_RUNTIME_DLL_FILE);
-    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)
+    if !dll_path.exists() {
+        anyhow::bail!("ONNX Runtime DLL is missing: {}", dll_path.display());
+    }
+    ort::environment::init_from(&dll_path)
+        .map_err(|error| anyhow::anyhow!(error.to_string()))?
+        .with_name("phokus-florence")
+        .commit();
+    *initialized = true;
+    Ok(())
+}
+
+/// Download any ONNX Runtime DLLs missing from `local_dir`, reporting per-file
+/// byte progress as `(short_label, downloaded_bytes, total_bytes)`.
+/// `total_bytes` is `None` when the server omits Content-Length. Unlike
+/// `ensure_onnx_runtime` (init only), this actually provisions the files —
+/// callers that can run on a clean install must call this first. The callback
+/// fires per chunk; callers should throttle.
+pub fn provision_onnx_runtime_with_progress(
+    local_dir: &Path,
+    mut on_progress: impl FnMut(&str, u64, Option<u64>),
+) -> Result<()> {
+    for (destination_file, source_url, archive_path) in ONNX_RUNTIME_FILES {
+        let destination = local_dir.join(destination_file);
+        if destination.exists() {
+            continue;
+        }
+        // Strip the "onnxruntime/" prefix for a clean label.
+        let label = destination_file
+            .rsplit('/')
+            .next()
+            .unwrap_or(destination_file);
+        download_nuget_file(
+            source_url,
+            archive_path,
+            &destination,
+            |downloaded, total| on_progress(label, downloaded, total),
+        )?;
+    }
+    Ok(())
+}
+
+/// Number of ONNX Runtime DLLs still missing from `local_dir` (for progress
+/// step counts before downloading).
+pub fn missing_onnx_runtime_count(local_dir: &Path) -> usize {
+    ONNX_RUNTIME_FILES
+        .iter()
+        .filter(|(destination_file, _, _)| !local_dir.join(destination_file).exists())
+        .count()
 }
 
 fn download_onnx_runtime_files(local_dir: &Path) -> Result<()> {
@@ -676,35 +724,218 @@ fn download_onnx_runtime_files(local_dir: &Path) -> Result<()> {
 
     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)?;
+        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}"))?;
+// 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;
 
-    let mut archive = zip::ZipArchive::new(Cursor::new(bytes))?;
-    let mut dll = archive.by_name(archive_path)?;
+/// Resiliently download `url` to `destination` using the system `curl.exe`.
+///
+/// ureq's read timeout does not fire on a stalled large transfer on Windows
+/// (schannel doesn't honor the socket read timeout), so a stall there hangs
+/// forever. curl detects an inactivity stall (`--speed-time`), resumes from
+/// the partial file (`-C -`), and retries internally — the same behavior a
+/// browser gets. We monitor the `.part` file's size for the progress bar and
+/// wrap curl in an outer progress-aware retry as a backstop. The partial file
+/// survives an app restart, so a later retry continues from disk.
+pub fn download_file_resilient(
+    url: &str,
+    destination: &Path,
+    mut on_progress: impl FnMut(u64, Option<u64>),
+) -> Result<()> {
     if let Some(parent) = destination.parent() {
         std::fs::create_dir_all(parent)?;
     }
+    let part = match destination.extension() {
+        Some(ext) => destination.with_extension(format!("{}.part", ext.to_string_lossy())),
+        None => destination.with_extension("part"),
+    };
+    let name = destination
+        .file_name()
+        .map(|n| n.to_string_lossy().into_owned())
+        .unwrap_or_else(|| url.to_string());
 
+    log::info!("{name}: resolving download size");
+    let total = remote_content_length(url);
+
+    // Reconcile any existing `.part` against the real size: exactly complete →
+    // finish; oversized (stale/corrupt) → discard so curl restarts cleanly
+    // (otherwise `curl -C -` would 416 forever).
+    if let Some(total) = total {
+        let size = std::fs::metadata(&part).map(|m| m.len()).unwrap_or(0);
+        if size == total {
+            std::fs::rename(&part, destination)?;
+            return Ok(());
+        }
+        if size > total {
+            let _ = std::fs::remove_file(&part);
+        }
+    }
+    log::info!(
+        "{name}: downloading via curl ({} bytes)",
+        total
+            .map(|t| t.to_string())
+            .unwrap_or_else(|| "unknown size".into())
+    );
+
+    let mut stalls = 0usize;
+    loop {
+        let before = std::fs::metadata(&part).map(|m| m.len()).unwrap_or(0);
+        match run_curl_download(url, &part, total, &mut on_progress) {
+            Ok(()) => break,
+            Err(error) => {
+                let after = std::fs::metadata(&part).map(|m| m.len()).unwrap_or(0);
+                if after > before {
+                    log::warn!("{name}: curl interrupted at {after} bytes, resuming: {error}");
+                    stalls = 0;
+                } else {
+                    stalls += 1;
+                    log::warn!(
+                        "{name}: curl made no progress ({stalls}/{MAX_STALL_RETRIES}): {error}"
+                    );
+                    if stalls >= MAX_STALL_RETRIES {
+                        // Discard the partial so a future attempt restarts clean
+                        // rather than getting stuck re-resuming a bad file.
+                        let _ = std::fs::remove_file(&part);
+                        return Err(error);
+                    }
+                }
+                std::thread::sleep(std::time::Duration::from_secs(2));
+            }
+        }
+    }
+
+    if let Some(total) = total {
+        let got = std::fs::metadata(&part).map(|m| m.len()).unwrap_or(0);
+        if got < total {
+            anyhow::bail!("{name}: incomplete after curl ({got}/{total} bytes)");
+        }
+    }
+    std::fs::rename(&part, destination)?;
+    Ok(())
+}
+
+/// Size probe via `curl -r 0-0` (a 1-byte Range request), parsing the total
+/// from the `Content-Range: bytes 0-0/<total>` header. Uses curl rather than
+/// ureq so no part of the download path depends on ureq (which hangs on this
+/// VM's TLS stack). Returns None if the server doesn't report a size.
+fn remote_content_length(url: &str) -> Option<u64> {
+    let mut command = Command::new("curl.exe");
+    command.args([
+        "-sL",
+        "-r",
+        "0-0",
+        "-D",
+        "-",
+        "-o",
+        "NUL",
+        "--connect-timeout",
+        "30",
+        "--max-time",
+        "30",
+        url,
+    ]);
+    #[cfg(target_os = "windows")]
+    command.creation_flags(CREATE_NO_WINDOW);
+    let output = command.output().ok()?;
+    let headers = String::from_utf8_lossy(&output.stdout);
+    for line in headers.lines() {
+        if let Some(rest) = line.to_ascii_lowercase().strip_prefix("content-range:") {
+            if let Some(total) = rest.rsplit('/').next().map(str::trim) {
+                if let Ok(n) = total.parse::<u64>() {
+                    return Some(n);
+                }
+            }
+        }
+    }
+    None
+}
+
+/// Run one `curl.exe` download to `dest`, resuming from any partial file, while
+/// reporting progress from the growing file size. Returns an error (leaving the
+/// partial in place) if curl exits non-zero.
+fn run_curl_download(
+    url: &str,
+    dest: &Path,
+    total: Option<u64>,
+    on_progress: &mut impl FnMut(u64, Option<u64>),
+) -> Result<()> {
+    let mut command = Command::new("curl.exe");
+    command
+        .arg("-fSL") // fail on HTTP errors, follow redirects, show errors
+        .args(["-C", "-"]) // resume from the existing output file
+        .args(["--retry", "3", "--retry-delay", "1", "--retry-connrefused"])
+        .args(["--connect-timeout", "30"])
+        // Abort (then --retry resumes) if under 1 KB/s for 30s — a real
+        // inactivity timeout, which is what ureq couldn't deliver here.
+        .args(["--speed-limit", "1024", "--speed-time", "30"])
+        .arg("-s") // no progress meter (we watch the file instead)
+        .arg("-o")
+        .arg(dest)
+        .arg(url)
+        .stdout(std::process::Stdio::null())
+        .stderr(std::process::Stdio::piped());
+    #[cfg(target_os = "windows")]
+    command.creation_flags(CREATE_NO_WINDOW);
+
+    let mut child = command
+        .spawn()
+        .map_err(|e| anyhow::anyhow!("failed to launch curl.exe (required for downloads): {e}"))?;
+
+    loop {
+        if let Some(status) = child.try_wait()? {
+            if status.success() {
+                return Ok(());
+            }
+            let mut stderr = String::new();
+            if let Some(mut pipe) = child.stderr.take() {
+                let _ = pipe.read_to_string(&mut stderr);
+            }
+            anyhow::bail!(
+                "curl exited with {}: {}",
+                status
+                    .code()
+                    .map(|c| c.to_string())
+                    .unwrap_or_else(|| "signal".into()),
+                stderr.trim()
+            );
+        }
+        let downloaded = std::fs::metadata(dest).map(|m| m.len()).unwrap_or(0);
+        on_progress(downloaded, total);
+        std::thread::sleep(std::time::Duration::from_millis(300));
+    }
+}
+
+fn download_nuget_file(
+    source_url: &str,
+    archive_path: &str,
+    destination: &Path,
+    on_progress: impl FnMut(u64, Option<u64>),
+) -> Result<()> {
+    // Download the .nupkg (a zip) resiliently, then extract the one DLL.
+    let package = destination.with_extension("nupkg");
+    download_file_resilient(source_url, &package, on_progress)?;
+
+    log::info!("extracting {archive_path} from package");
+    let file = std::fs::File::open(&package)?;
+    let mut archive = zip::ZipArchive::new(file)?;
+    let mut dll = archive.by_name(archive_path)?;
     let temp_destination = destination.with_extension("tmp");
     {
-        let mut file = std::fs::File::create(&temp_destination)?;
-        std::io::copy(&mut dll, &mut file)?;
+        let mut out = std::fs::File::create(&temp_destination)?;
+        std::io::copy(&mut dll, &mut out)?;
     }
-    std::fs::rename(temp_destination, destination)?;
+    std::fs::rename(&temp_destination, destination)?;
+    let _ = std::fs::remove_file(&package);
+    log::info!("extracted {archive_path}");
     Ok(())
 }
 
@@ -784,7 +1015,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 +1079,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 +1117,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/commands.rs

@@ -227,6 +227,14 @@ pub async fn add_folder(
         return Err("Path is not a valid directory".into());
     }
 
+    // Let the webview load media from this folder via the asset protocol.
+    if let Err(error) = app
+        .asset_protocol_scope()
+        .allow_directory(&folder_path, true)
+    {
+        log::error!("Failed to allow asset scope for {path}: {error}");
+    }
+
     let name = folder_path
         .file_name()
         .map(|n| n.to_string_lossy().to_string())
@@ -395,8 +403,17 @@ pub async fn update_folder_path(
 ) -> Result<(), String> {
     let new_path_buf = PathBuf::from(&new_path);
     if !new_path_buf.is_dir() {
-        return Err(format!("Path is not a valid directory: {}", new_path));
+        return Err(format!("Path is not a valid directory: {new_path}"));
     }
+
+    // Let the webview load media from the relocated folder via the asset protocol.
+    if let Err(error) = app
+        .asset_protocol_scope()
+        .allow_directory(&new_path_buf, true)
+    {
+        log::error!("Failed to allow asset scope for {new_path}: {error}");
+    }
+
     let new_name = new_path_buf
         .file_name()
         .map(|n| n.to_string_lossy().to_string())
@@ -445,7 +462,7 @@ pub async fn find_similar_images(
         offset,
         limit + 1,
     )
-        .map_err(|e| e.to_string())?;
+    .map_err(|e| e.to_string())?;
     let has_more = matches.len() > limit;
     let image_ids = matches
         .into_iter()
@@ -499,8 +516,9 @@ pub async fn find_similar_by_region(
         None => {
             // Fetch one extra candidate to compensate for the source image that
             // will be removed, so has_more is accurate and results span multiple pages.
-            let mut ids = vector::search_image_ids_by_embedding(&conn, &embedding, offset + limit + 2)
-                .map_err(|e| e.to_string())?;
+            let mut ids =
+                vector::search_image_ids_by_embedding(&conn, &embedding, offset + limit + 2)
+                    .map_err(|e| e.to_string())?;
             ids.retain(|&id| id != params.image_id);
             ids
         }
@@ -575,7 +593,7 @@ pub async fn semantic_search_images(
     let has_filters = params.folder_id.is_some()
         || params.media_kind.is_some()
         || params.favorites_only.unwrap_or(false)
-        || params.rating_min.map_or(false, |r| r > 0);
+        || params.rating_min.is_some_and(|r| r > 0);
 
     if !has_filters {
         // No post-query filtering — a single fetch of exactly `limit` results is optimal.
@@ -639,7 +657,12 @@ pub async fn search_images_by_tag(
         offset,
     )
     .map_err(|e| e.to_string())?;
-    Ok(TagSearchPage { images, total, offset, limit })
+    Ok(TagSearchPage {
+        images,
+        total,
+        offset,
+        limit,
+    })
 }
 
 #[tauri::command]
@@ -835,7 +858,6 @@ pub struct TagCloudEntry {
     pub image_ids: Vec<i64>,
 }
 
-
 /// Clusters the library's image embeddings with k-means and returns one representative
 /// image per cluster — the member whose embedding is closest to its cluster centroid.
 /// Results are cached in SQLite keyed by a hash of the embedded image IDs, so repeated
@@ -872,7 +894,7 @@ pub async fn get_tag_cloud(
         hasher.digest()
     };
     let folder_scope = match folder_id {
-        Some(id) => format!("folder_{}", id),
+        Some(id) => format!("folder_{id}"),
         None => "all".to_string(),
     };
 
@@ -957,7 +979,8 @@ pub async fn get_explore_tags(
     params: GetExploreTagsParams,
 ) -> Result<Vec<ExploreTagEntry>, String> {
     let conn = db.get().map_err(|e| e.to_string())?;
-    db::get_explore_tags(&conn, params.folder_id, params.limit.unwrap_or(48)).map_err(|e| e.to_string())
+    db::get_explore_tags(&conn, params.folder_id, params.limit.unwrap_or(48))
+        .map_err(|e| e.to_string())
 }
 
 #[tauri::command]
@@ -969,8 +992,13 @@ pub async fn search_tags_autocomplete(
         return Ok(vec![]);
     }
     let conn = db.get().map_err(|e| e.to_string())?;
-    db::search_tags_autocomplete(&conn, &params.query, params.folder_id, params.limit.unwrap_or(10))
-        .map_err(|e| e.to_string())
+    db::search_tags_autocomplete(
+        &conn,
+        &params.query,
+        params.folder_id,
+        params.limit.unwrap_or(10),
+    )
+    .map_err(|e| e.to_string())
 }
 
 #[tauri::command]
@@ -985,12 +1013,15 @@ pub async fn find_duplicates(
     };
 
     let total = records.len();
-    let _ = app.emit("duplicate_scan_progress", DuplicateScanProgress {
-        phase: "checking".to_string(),
-        processed: 0,
-        total,
-        skipped: 0,
-    });
+    let _ = app.emit(
+        "duplicate_scan_progress",
+        DuplicateScanProgress {
+            phase: "checking".to_string(),
+            processed: 0,
+            total,
+            skipped: 0,
+        },
+    );
 
     // Three-phase detection.
     //
@@ -1007,126 +1038,140 @@ pub async fn find_duplicates(
     //   For sample-hash groups that contain files > 64 KB, compute a full-file
     //   hash to confirm the match before presenting them as deletable duplicates.
     let app_hash = app.clone();
-    let (pairs, skipped_before_confirm, candidate_total):
-        (Vec<(u64, u64, i64, String)>, usize, usize) = tokio::task::spawn_blocking(move || {
-        use memmap2::Mmap;
-        use rayon::prelude::*;
-        use std::collections::HashMap;
-        use std::sync::atomic::{AtomicUsize, Ordering};
-        use xxhash_rust::xxh3::{xxh3_64, Xxh3};
+    // (size, sample/full hash, image_id, path) for each confirmed candidate.
+    type HashedCandidate = (u64, u64, i64, String);
+    let (pairs, skipped_before_confirm, candidate_total): (Vec<HashedCandidate>, usize, usize) =
+        tokio::task::spawn_blocking(move || {
+            use memmap2::Mmap;
+            use rayon::prelude::*;
+            use std::collections::HashMap;
+            use std::sync::atomic::{AtomicUsize, Ordering};
+            use xxhash_rust::xxh3::{xxh3_64, Xxh3};
 
-        const WINDOW: usize = 16 * 1024; // 16 KB per sample window
-        const N: usize = 4;              // windows at 0%, 33%, 66%, 100%
-        const COVERED: usize = WINDOW * N; // 64 KB total; also full-coverage threshold
+            const WINDOW: usize = 16 * 1024; // 16 KB per sample window
+            const N: usize = 4; // windows at 0%, 33%, 66%, 100%
+            const COVERED: usize = WINDOW * N; // 64 KB total; also full-coverage threshold
 
-        // Hash four evenly-spaced 16 KB windows. For files ≤ 64 KB this is
-        // equivalent to hashing the entire file.
-        fn sample(mmap: &[u8]) -> u64 {
-            if mmap.len() <= COVERED {
-                return xxh3_64(mmap);
+            // Hash four evenly-spaced 16 KB windows. For files ≤ 64 KB this is
+            // equivalent to hashing the entire file.
+            fn sample(mmap: &[u8]) -> u64 {
+                if mmap.len() <= COVERED {
+                    return xxh3_64(mmap);
+                }
+                let mut h = Xxh3::new();
+                for i in 0..N {
+                    let pos = (mmap.len() - WINDOW) * i / (N - 1);
+                    h.update(&mmap[pos..pos + WINDOW]);
+                }
+                h.digest()
             }
-            let mut h = Xxh3::new();
-            for i in 0..N {
-                let pos = (mmap.len() - WINDOW) * i / (N - 1);
-                h.update(&mmap[pos..pos + WINDOW]);
-            }
-            h.digest()
-        }
 
-        // ── Phase 1: stat ─────────────────────────────────────────────────
-        let stat_counter = AtomicUsize::new(0);
-        let stat_skipped = AtomicUsize::new(0);
-        let sized: Vec<(i64, String, u64)> = records
-            .par_iter()
-            .filter_map(|r| {
-                let result = match std::fs::metadata(&r.path) {
-                    Ok(metadata) => Some((r.id, r.path.clone(), metadata.len())),
-                    Err(_) => {
-                        stat_skipped.fetch_add(1, Ordering::Relaxed);
-                        None
+            // ── Phase 1: stat ─────────────────────────────────────────────────
+            let stat_counter = AtomicUsize::new(0);
+            let stat_skipped = AtomicUsize::new(0);
+            let sized: Vec<(i64, String, u64)> = records
+                .par_iter()
+                .filter_map(|r| {
+                    let result = match std::fs::metadata(&r.path) {
+                        Ok(metadata) => Some((r.id, r.path.clone(), metadata.len())),
+                        Err(_) => {
+                            stat_skipped.fetch_add(1, Ordering::Relaxed);
+                            None
+                        }
+                    };
+                    let done = stat_counter.fetch_add(1, Ordering::Relaxed) + 1;
+                    if done % 100 == 0 || done == total {
+                        let _ = app_hash.emit(
+                            "duplicate_scan_progress",
+                            DuplicateScanProgress {
+                                phase: "checking".to_string(),
+                                processed: done,
+                                total,
+                                skipped: stat_skipped.load(Ordering::Relaxed),
+                            },
+                        );
                     }
-                };
-                let done = stat_counter.fetch_add(1, Ordering::Relaxed) + 1;
-                if done % 100 == 0 || done == total {
-                    let _ = app_hash.emit("duplicate_scan_progress", DuplicateScanProgress {
-                        phase: "checking".to_string(),
-                        processed: done,
-                        total,
-                        skipped: stat_skipped.load(Ordering::Relaxed),
-                    });
-                }
-                result
-            })
-            .collect();
-        let stat_skipped = stat_skipped.load(Ordering::Relaxed);
+                    result
+                })
+                .collect();
+            let stat_skipped = stat_skipped.load(Ordering::Relaxed);
 
-        let mut by_size: HashMap<u64, Vec<usize>> = HashMap::new();
-        for (i, (_, _, size)) in sized.iter().enumerate() {
-            by_size.entry(*size).or_default().push(i);
-        }
-        let candidates: Vec<usize> = by_size
-            .into_values()
-            .filter(|g| g.len() > 1)
-            .flatten()
-            .collect();
+            let mut by_size: HashMap<u64, Vec<usize>> = HashMap::new();
+            for (i, (_, _, size)) in sized.iter().enumerate() {
+                by_size.entry(*size).or_default().push(i);
+            }
+            let candidates: Vec<usize> = by_size
+                .into_values()
+                .filter(|g| g.len() > 1)
+                .flatten()
+                .collect();
 
-        if candidates.is_empty() {
-            return (vec![], stat_skipped, 0);
-        }
+            if candidates.is_empty() {
+                return (vec![], stat_skipped, 0);
+            }
 
-        // ── Phase 2: sample hash ──────────────────────────────────────────
-        let c_total = candidates.len();
-        let _ = app_hash.emit("duplicate_scan_progress", DuplicateScanProgress {
-            phase: "hashing".to_string(),
-            processed: 0,
-            total: c_total,
-            skipped: stat_skipped,
-        });
-        let counter = AtomicUsize::new(0);
-        let hash_skipped = AtomicUsize::new(0);
+            // ── Phase 2: sample hash ──────────────────────────────────────────
+            let c_total = candidates.len();
+            let _ = app_hash.emit(
+                "duplicate_scan_progress",
+                DuplicateScanProgress {
+                    phase: "hashing".to_string(),
+                    processed: 0,
+                    total: c_total,
+                    skipped: stat_skipped,
+                },
+            );
+            let counter = AtomicUsize::new(0);
+            let hash_skipped = AtomicUsize::new(0);
 
-        let pairs = candidates
-            .par_iter()
-            .filter_map(|&idx| {
-                let (id, path, size) = &sized[idx];
-                let result = if *size == 0 {
-                    Some((xxh3_64(&[]), *size, *id, path.clone()))
-                } else {
-                    std::fs::File::open(path)
-                        .ok()
-                        // SAFETY: read-only; no external truncation expected during scan.
-                        .and_then(|file| unsafe { Mmap::map(&file).ok() })
-                        .map(|mmap| (sample(&mmap), *size, *id, path.clone()))
-                };
-                if result.is_none() {
-                    hash_skipped.fetch_add(1, Ordering::Relaxed);
-                }
-                let done = counter.fetch_add(1, Ordering::Relaxed) + 1;
-                if done % 100 == 0 || done == c_total {
-                    let _ = app_hash.emit("duplicate_scan_progress", DuplicateScanProgress {
-                        phase: "hashing".to_string(),
-                        processed: done,
-                        total: c_total,
-                        skipped: stat_skipped + hash_skipped.load(Ordering::Relaxed),
-                    });
-                }
-                result
-            })
-            .collect();
-        (
-            pairs,
-            stat_skipped + hash_skipped.load(Ordering::Relaxed),
-            c_total,
-        )
-    })
-    .await
-    .map_err(|e| e.to_string())?;
+            let pairs = candidates
+                .par_iter()
+                .filter_map(|&idx| {
+                    let (id, path, size) = &sized[idx];
+                    let result = if *size == 0 {
+                        Some((xxh3_64(&[]), *size, *id, path.clone()))
+                    } else {
+                        std::fs::File::open(path)
+                            .ok()
+                            // SAFETY: read-only; no external truncation expected during scan.
+                            .and_then(|file| unsafe { Mmap::map(&file).ok() })
+                            .map(|mmap| (sample(&mmap), *size, *id, path.clone()))
+                    };
+                    if result.is_none() {
+                        hash_skipped.fetch_add(1, Ordering::Relaxed);
+                    }
+                    let done = counter.fetch_add(1, Ordering::Relaxed) + 1;
+                    if done % 100 == 0 || done == c_total {
+                        let _ = app_hash.emit(
+                            "duplicate_scan_progress",
+                            DuplicateScanProgress {
+                                phase: "hashing".to_string(),
+                                processed: done,
+                                total: c_total,
+                                skipped: stat_skipped + hash_skipped.load(Ordering::Relaxed),
+                            },
+                        );
+                    }
+                    result
+                })
+                .collect();
+            (
+                pairs,
+                stat_skipped + hash_skipped.load(Ordering::Relaxed),
+                c_total,
+            )
+        })
+        .await
+        .map_err(|e| e.to_string())?;
 
     // Group by (sample_hash, file_size).
     let mut size_hash_map: std::collections::HashMap<(u64, u64), Vec<(i64, String)>> =
         std::collections::HashMap::new();
     for (hash, file_size, id, path) in pairs {
-        size_hash_map.entry((hash, file_size)).or_default().push((id, path));
+        size_hash_map
+            .entry((hash, file_size))
+            .or_default()
+            .push((id, path));
     }
 
     // Phase 3: for large-file groups (> 64 KB) the sample hash is not exact;
@@ -1140,12 +1185,15 @@ pub async fn find_duplicates(
         .map(|(_, entries)| entries.len())
         .sum();
     if confirming_total > 0 {
-        let _ = app.emit("duplicate_scan_progress", DuplicateScanProgress {
-            phase: "confirming".to_string(),
-            processed: 0,
-            total: confirming_total,
-            skipped: skipped_before_confirm,
-        });
+        let _ = app.emit(
+            "duplicate_scan_progress",
+            DuplicateScanProgress {
+                phase: "confirming".to_string(),
+                processed: 0,
+                total: confirming_total,
+                skipped: skipped_before_confirm,
+            },
+        );
     }
     let app_confirm = app.clone();
     let (confirmed, skipped_files): (Vec<(u64, u64, Vec<i64>)>, usize) =
@@ -1163,7 +1211,11 @@ pub async fn find_duplicates(
                 .flat_map(|((sample_hash, file_size), entries)| {
                     if file_size <= COVERED {
                         // Sample was already a full hash — one group, no re-read needed.
-                        return vec![(sample_hash, file_size, entries.into_iter().map(|(id, _)| id).collect())];
+                        return vec![(
+                            sample_hash,
+                            file_size,
+                            entries.into_iter().map(|(id, _)| id).collect(),
+                        )];
                     }
                     // Full-file hash pass. Group by full hash so that two sets of
                     // files that collide only in the sample produce separate groups.
@@ -1179,13 +1231,16 @@ pub async fn find_duplicates(
                             }
                             let done = counter.fetch_add(1, Ordering::Relaxed) + 1;
                             if done % 100 == 0 || done == confirming_total {
-                                let _ = app_confirm.emit("duplicate_scan_progress", DuplicateScanProgress {
-                                    phase: "confirming".to_string(),
-                                    processed: done,
-                                    total: confirming_total,
-                                    skipped: skipped_before_confirm
-                                        + confirm_skipped.load(Ordering::Relaxed),
-                                });
+                                let _ = app_confirm.emit(
+                                    "duplicate_scan_progress",
+                                    DuplicateScanProgress {
+                                        phase: "confirming".to_string(),
+                                        processed: done,
+                                        total: confirming_total,
+                                        skipped: skipped_before_confirm
+                                            + confirm_skipped.load(Ordering::Relaxed),
+                                    },
+                                );
                             }
                             (*id, hash)
                         })
@@ -1220,7 +1275,7 @@ pub async fn find_duplicates(
         .filter_map(|(hash, file_size, ids)| {
             let images = db::get_images_by_ids(&conn, &ids).ok()?;
             Some(DuplicateGroup {
-                file_hash: format!("{:016x}", hash),
+                file_hash: format!("{hash:016x}"),
                 file_size,
                 images,
             })
@@ -1232,7 +1287,7 @@ pub async fn find_duplicates(
 
     // Persist results so they survive restart — best-effort, ignore errors.
     let folder_scope = match folder_id {
-        Some(id) => format!("folder:{}", id),
+        Some(id) => format!("folder:{id}"),
         None => "all".to_string(),
     };
     if let Ok(json) = serde_json::to_string(&groups) {
@@ -1253,7 +1308,7 @@ pub async fn load_duplicate_scan_cache(
     folder_id: Option<i64>,
 ) -> Result<Option<DuplicateScanCache>, String> {
     let folder_scope = match folder_id {
-        Some(id) => format!("folder:{}", id),
+        Some(id) => format!("folder:{id}"),
         None => "all".to_string(),
     };
     let conn = db.get().map_err(|e| e.to_string())?;
@@ -1273,7 +1328,7 @@ pub async fn invalidate_duplicate_scan_cache(
     folder_id: Option<i64>,
 ) -> Result<(), String> {
     let folder_scope = match folder_id {
-        Some(id) => format!("folder:{}", id),
+        Some(id) => format!("folder:{id}"),
         None => "all".to_string(),
     };
     let conn = db.get().map_err(|e| e.to_string())?;
@@ -1326,7 +1381,7 @@ fn dot(a: &[f32], b: &[f32]) -> f32 {
     a.iter().zip(b.iter()).map(|(x, y)| x * y).sum()
 }
 
-fn normalize(v: &mut Vec<f32>) {
+fn normalize(v: &mut [f32]) {
     let norm: f32 = v.iter().map(|x| x * x).sum::<f32>().sqrt();
     if norm > 1e-10 {
         v.iter_mut().for_each(|x| *x /= norm);
@@ -1470,16 +1525,17 @@ pub async fn get_worker_states(folder_ids: Vec<i64>) -> Result<Vec<FolderWorkerS
     Ok(folder_ids
         .into_iter()
         .map(|folder_id| {
-            let state = states
-                .get(&folder_id)
-                .copied()
-                .unwrap_or(indexer::FolderWorkerPausedState {
-                    thumbnail: false,
-                    metadata: false,
-                    embedding: false,
-                    caption: false,
-                    tagging: false,
-                });
+            let state =
+                states
+                    .get(&folder_id)
+                    .copied()
+                    .unwrap_or(indexer::FolderWorkerPausedState {
+                        thumbnail: false,
+                        metadata: false,
+                        embedding: false,
+                        caption: false,
+                        tagging: false,
+                    });
             FolderWorkerStates {
                 folder_id,
                 thumbnail_paused: state.thumbnail,
@@ -1631,7 +1687,11 @@ pub async fn queue_tagging_jobs(
 ) -> Result<usize, String> {
     let conn = db.get().map_err(|e| e.to_string())?;
     let requested_folder_ids = params.folder_ids.unwrap_or_default();
-    let (total, folder_ids) = match (params.folder_id, params.image_id, requested_folder_ids.is_empty()) {
+    let (total, folder_ids) = match (
+        params.folder_id,
+        params.image_id,
+        requested_folder_ids.is_empty(),
+    ) {
         (_, Some(image_id), _) => {
             db::enqueue_tagging_job(&conn, image_id).map_err(|e| e.to_string())?;
             // Look up just this image's folder_id rather than fetching all folders
@@ -1675,27 +1735,29 @@ pub async fn clear_tagging_jobs(
 ) -> Result<usize, String> {
     let conn = db.get().map_err(|e| e.to_string())?;
     let requested_folder_ids = params.folder_ids.unwrap_or_default();
-    let (n, folder_ids): (usize, Vec<i64>) = match (params.folder_id, requested_folder_ids.is_empty()) {
-        (Some(id), _) => (
-            db::clear_tagging_jobs(&conn, Some(id)).map_err(|e| e.to_string())?,
-            vec![id],
-        ),
-        (None, false) => {
-            let mut total = 0usize;
-            for &folder_id in &requested_folder_ids {
-                total += db::clear_tagging_jobs(&conn, Some(folder_id)).map_err(|e| e.to_string())?;
+    let (n, folder_ids): (usize, Vec<i64>) =
+        match (params.folder_id, requested_folder_ids.is_empty()) {
+            (Some(id), _) => (
+                db::clear_tagging_jobs(&conn, Some(id)).map_err(|e| e.to_string())?,
+                vec![id],
+            ),
+            (None, false) => {
+                let mut total = 0usize;
+                for &folder_id in &requested_folder_ids {
+                    total += db::clear_tagging_jobs(&conn, Some(folder_id))
+                        .map_err(|e| e.to_string())?;
+                }
+                (total, requested_folder_ids)
             }
-            (total, requested_folder_ids)
-        }
-        (None, true) => (
-            db::clear_tagging_jobs(&conn, None).map_err(|e| e.to_string())?,
-            db::get_folders(&conn)
-            .map_err(|e| e.to_string())?
-            .into_iter()
-            .map(|f| f.id)
-            .collect(),
-        ),
-    };
+            (None, true) => (
+                db::clear_tagging_jobs(&conn, None).map_err(|e| e.to_string())?,
+                db::get_folders(&conn)
+                    .map_err(|e| e.to_string())?
+                    .into_iter()
+                    .map(|f| f.id)
+                    .collect(),
+            ),
+        };
     drop(conn);
     indexer::emit_folder_job_progress(&app, db.inner(), &folder_ids, true);
     Ok(n)
@@ -1747,7 +1809,11 @@ pub async fn get_tagging_queue_scope(app: AppHandle) -> Result<String, String> {
     let app_dir = app.path().app_data_dir().map_err(|e| e.to_string())?;
     let path = app_dir.join(TAGGING_QUEUE_SCOPE_FILE);
     let value = std::fs::read_to_string(path).unwrap_or_default();
-    Ok(if value.trim() == "selected" { "selected".to_string() } else { "all".to_string() })
+    Ok(if value.trim() == "selected" {
+        "selected".to_string()
+    } else {
+        "all".to_string()
+    })
 }
 
 #[tauri::command]
@@ -1760,7 +1826,11 @@ pub async fn set_tagging_queue_scope(
     if let Some(parent) = path.parent() {
         std::fs::create_dir_all(parent).map_err(|e| e.to_string())?;
     }
-    let value = if params.scope == "selected" { "selected" } else { "all" };
+    let value = if params.scope == "selected" {
+        "selected"
+    } else {
+        "all"
+    };
     std::fs::write(path, value).map_err(|e| e.to_string())?;
     Ok(value.to_string())
 }
@@ -1825,14 +1895,21 @@ pub struct VacuumResult {
 }
 
 #[tauri::command]
-pub async fn get_database_info(app: AppHandle, db: State<'_, DbState>) -> Result<DatabaseInfo, String> {
+pub async fn get_database_info(
+    app: AppHandle,
+    db: State<'_, DbState>,
+) -> Result<DatabaseInfo, String> {
     let app_dir = app.path().app_data_dir().map_err(|e| e.to_string())?;
     let db_path = app_dir.join("gallery.db");
     let size_bytes = std::fs::metadata(&db_path).map(|m| m.len()).unwrap_or(0);
 
     let conn = db.get().map_err(|e| e.to_string())?;
-    let page_size: i64 = conn.query_row("PRAGMA page_size", [], |r| r.get(0)).map_err(|e| e.to_string())?;
-    let freelist_count: i64 = conn.query_row("PRAGMA freelist_count", [], |r| r.get(0)).map_err(|e| e.to_string())?;
+    let page_size: i64 = conn
+        .query_row("PRAGMA page_size", [], |r| r.get(0))
+        .map_err(|e| e.to_string())?;
+    let freelist_count: i64 = conn
+        .query_row("PRAGMA freelist_count", [], |r| r.get(0))
+        .map_err(|e| e.to_string())?;
 
     Ok(DatabaseInfo {
         size_mb: size_bytes as f64 / 1_048_576.0,
@@ -1841,13 +1918,17 @@ pub async fn get_database_info(app: AppHandle, db: State<'_, DbState>) -> Result
 }
 
 #[tauri::command]
-pub async fn vacuum_database(app: AppHandle, db: State<'_, DbState>) -> Result<VacuumResult, String> {
+pub async fn vacuum_database(
+    app: AppHandle,
+    db: State<'_, DbState>,
+) -> Result<VacuumResult, String> {
     let app_dir = app.path().app_data_dir().map_err(|e| e.to_string())?;
     let db_path = app_dir.join("gallery.db");
     let before_bytes = std::fs::metadata(&db_path).map(|m| m.len()).unwrap_or(0);
 
     let conn = db.get().map_err(|e| e.to_string())?;
-    conn.execute_batch("PRAGMA wal_checkpoint(FULL); VACUUM;").map_err(|e| e.to_string())?;
+    conn.execute_batch("PRAGMA wal_checkpoint(FULL); VACUUM;")
+        .map_err(|e| e.to_string())?;
     drop(conn);
 
     let after_bytes = std::fs::metadata(&db_path).map(|m| m.len()).unwrap_or(0);
@@ -1870,7 +1951,9 @@ pub struct CleanupOrphanedThumbnailsResult {
     pub freed_mb: f64,
 }
 
-fn collect_db_thumbnail_filenames(conn: &rusqlite::Connection) -> Result<std::collections::HashSet<String>, String> {
+fn collect_db_thumbnail_filenames(
+    conn: &rusqlite::Connection,
+) -> Result<std::collections::HashSet<String>, String> {
     let mut stmt = conn
         .prepare("SELECT thumbnail_path FROM images WHERE thumbnail_path IS NOT NULL")
         .map_err(|e| e.to_string())?;
@@ -1993,8 +2076,7 @@ pub async fn set_muted_folder_ids(
         .map(|id| id.to_string())
         .collect::<Vec<_>>()
         .join(",");
-    std::fs::write(settings_dir.join("muted_folder_ids.txt"), content)
-        .map_err(|e| e.to_string())
+    std::fs::write(settings_dir.join("muted_folder_ids.txt"), content).map_err(|e| e.to_string())
 }
 
 #[tauri::command]
@@ -2019,3 +2101,50 @@ pub async fn set_notifications_paused(app: AppHandle, paused: bool) -> Result<()
     )
     .map_err(|e| e.to_string())
 }
+
+#[derive(Serialize)]
+pub struct FfmpegStatus {
+    pub installed: bool,
+    pub downloading: bool,
+    pub failed: bool,
+}
+
+#[tauri::command]
+pub async fn get_ffmpeg_status() -> Result<FfmpegStatus, String> {
+    Ok(FfmpegStatus {
+        installed: crate::media::ffmpeg_ready(),
+        downloading: crate::media::ffmpeg_downloading(),
+        failed: crate::media::ffmpeg_failed(),
+    })
+}
+
+#[tauri::command]
+pub async fn retry_ffmpeg_download(app: AppHandle) -> Result<(), String> {
+    crate::media::spawn_ffmpeg_provision(app);
+    Ok(())
+}
+
+const ONBOARDING_COMPLETED_FILE: &str = "settings/onboarding_completed.txt";
+
+#[tauri::command]
+pub async fn get_onboarding_completed(app: AppHandle) -> Result<bool, String> {
+    let app_dir = app.path().app_data_dir().map_err(|e| e.to_string())?;
+    let path = app_dir.join(ONBOARDING_COMPLETED_FILE);
+    if !path.exists() {
+        return Ok(false);
+    }
+    let content = std::fs::read_to_string(&path).map_err(|e| e.to_string())?;
+    Ok(content.trim() == "true")
+}
+
+#[tauri::command]
+pub async fn set_onboarding_completed(app: AppHandle, completed: bool) -> Result<(), String> {
+    let app_dir = app.path().app_data_dir().map_err(|e| e.to_string())?;
+    let settings_dir = app_dir.join("settings");
+    std::fs::create_dir_all(&settings_dir).map_err(|e| e.to_string())?;
+    std::fs::write(
+        settings_dir.join("onboarding_completed.txt"),
+        if completed { "true" } else { "false" },
+    )
+    .map_err(|e| e.to_string())
+}

src-tauri/src/db.rs

@@ -99,6 +99,8 @@ pub struct MetadataJob {
     pub path: String,
 }
 
+// Caption worker disabled (lib.rs) — kept for future re-enabling.
+#[allow(dead_code)]
 #[derive(Debug, Clone)]
 pub struct CaptionJob {
     pub image_id: i64,
@@ -318,9 +320,7 @@ pub fn migrate(conn: &Connection) -> Result<()> {
     // Index must be created after ensure_column adds the column; it cannot live
     // in the execute_batch above because that batch runs before the column exists
     // on databases that predate Phase 1.
-    conn.execute_batch(
-        "CREATE INDEX IF NOT EXISTS idx_images_taken_at ON images(taken_at);",
-    )?;
+    conn.execute_batch("CREATE INDEX IF NOT EXISTS idx_images_taken_at ON images(taken_at);")?;
     ensure_column(conn, "folders", "scan_error", "TEXT")?;
 
     vector::migrate(conn)?;
@@ -590,6 +590,7 @@ pub fn enqueue_caption_job(conn: &Connection, image_id: i64) -> Result<()> {
     Ok(())
 }
 
+#[allow(dead_code)] // caption worker disabled (lib.rs)
 pub fn requeue_caption_jobs(conn: &Connection, image_ids: &[i64]) -> Result<()> {
     for image_id in image_ids {
         conn.execute(
@@ -668,6 +669,7 @@ pub fn clear_caption_jobs(conn: &Connection, folder_id: Option<i64>) -> Result<u
     }
 }
 
+#[allow(dead_code)] // caption worker disabled (lib.rs)
 pub fn is_caption_job_cancelled(conn: &Connection, image_id: i64) -> Result<bool> {
     let count: i64 = conn.query_row(
         "SELECT COUNT(*) FROM caption_jobs WHERE image_id = ?1 AND status = 'cancelled'",
@@ -865,6 +867,7 @@ pub fn claim_embedding_jobs(
     Ok(claimed)
 }
 
+#[allow(dead_code)] // caption worker disabled (lib.rs)
 fn get_pending_caption_jobs_excluding(
     conn: &Connection,
     excluded_folder_ids: &std::collections::HashSet<i64>,
@@ -893,6 +896,7 @@ fn get_pending_caption_jobs_excluding(
     Ok(rows.collect::<rusqlite::Result<Vec<_>>>()?)
 }
 
+#[allow(dead_code)] // caption worker disabled (lib.rs)
 pub fn claim_caption_jobs(
     conn: &mut Connection,
     paused_folder_ids: &std::collections::HashSet<i64>,
@@ -1128,6 +1132,7 @@ pub fn get_all_folder_job_progress(conn: &Connection) -> Result<Vec<FolderJobPro
 fn get_pending_thumbnail_jobs_excluding(
     conn: &Connection,
     excluded_folder_ids: &std::collections::HashSet<i64>,
+    include_videos: bool,
     limit: usize,
 ) -> Result<Vec<ThumbnailJob>> {
     let sql = format!(
@@ -1136,8 +1141,10 @@ fn get_pending_thumbnail_jobs_excluding(
          JOIN images i ON i.id = j.image_id
          WHERE j.status = 'pending'
            {}
+           {}
          ORDER BY j.updated_at, j.image_id
          LIMIT ?1",
+        media_kind_clause(include_videos),
         folder_exclusion_clause("i", excluded_folder_ids)
     );
     let mut stmt = conn.prepare(&sql)?;
@@ -1152,6 +1159,17 @@ fn get_pending_thumbnail_jobs_excluding(
     Ok(rows.collect::<rusqlite::Result<Vec<_>>>()?)
 }
 
+/// Video jobs need FFmpeg; while it isn't provisioned they must be invisible
+/// to both claiming and the tier-priority checks, or pending video jobs would
+/// stall every lower tier indefinitely.
+fn media_kind_clause(include_videos: bool) -> &'static str {
+    if include_videos {
+        ""
+    } else {
+        "AND i.media_kind = 'image'"
+    }
+}
+
 /// True if any claimable (pending, non-excluded) jobs exist in `job_table`.
 /// Used by lower-priority workers to defer to higher-priority queues.
 /// `extra_predicate` narrows the image join (e.g. videos only for metadata).
@@ -1180,8 +1198,14 @@ fn has_claimable_jobs(
 pub fn has_claimable_thumbnail_jobs(
     conn: &Connection,
     excluded_folder_ids: &std::collections::HashSet<i64>,
+    include_videos: bool,
 ) -> Result<bool> {
-    has_claimable_jobs(conn, "thumbnail_jobs", "", excluded_folder_ids)
+    has_claimable_jobs(
+        conn,
+        "thumbnail_jobs",
+        media_kind_clause(include_videos),
+        excluded_folder_ids,
+    )
 }
 
 pub fn has_claimable_metadata_jobs(
@@ -1207,6 +1231,7 @@ pub fn claim_thumbnail_jobs(
     conn: &mut Connection,
     active_folder_ids: &std::collections::HashSet<i64>,
     paused_folder_ids: &std::collections::HashSet<i64>,
+    include_videos: bool,
     fetch_limit: usize,
     claim_limit: usize,
 ) -> Result<Vec<ThumbnailJob>> {
@@ -1215,7 +1240,12 @@ pub fn claim_thumbnail_jobs(
         .union(paused_folder_ids)
         .copied()
         .collect::<std::collections::HashSet<_>>();
-    let candidates = get_pending_thumbnail_jobs_excluding(&tx, &excluded_folder_ids, fetch_limit)?;
+    let candidates = get_pending_thumbnail_jobs_excluding(
+        &tx,
+        &excluded_folder_ids,
+        include_videos,
+        fetch_limit,
+    )?;
     let mut claimed = Vec::with_capacity(claim_limit);
 
     for job in candidates {
@@ -1410,7 +1440,10 @@ pub fn update_image_details(
 
 /// Look up the lightweight indexed-media entry for a single path.
 /// Used by the filesystem watcher to run change-detection before upserting.
-pub fn get_indexed_entry_by_path(conn: &Connection, path: &str) -> Result<Option<IndexedMediaEntry>> {
+pub fn get_indexed_entry_by_path(
+    conn: &Connection,
+    path: &str,
+) -> Result<Option<IndexedMediaEntry>> {
     let result = conn.query_row(
         "SELECT id, path, modified_at, file_size, media_kind FROM images WHERE path = ?1",
         [path],
@@ -1433,12 +1466,11 @@ pub fn get_indexed_entry_by_path(conn: &Connection, path: &str) -> Result<Option
 
 /// Look up just the image id for a path. Used by the filesystem watcher
 /// to find the DB row to delete when a file is removed from disk.
+#[allow(dead_code)] // only caller is the disabled caption worker path
 pub fn get_image_id_by_path(conn: &Connection, path: &str) -> Result<Option<i64>> {
-    let result = conn.query_row(
-        "SELECT id FROM images WHERE path = ?1",
-        [path],
-        |row| row.get(0),
-    );
+    let result = conn.query_row("SELECT id FROM images WHERE path = ?1", [path], |row| {
+        row.get(0)
+    });
     match result {
         Ok(id) => Ok(Some(id)),
         Err(rusqlite::Error::QueryReturnedNoRows) => Ok(None),
@@ -1474,8 +1506,9 @@ pub fn get_images_by_ids(conn: &Connection, image_ids: &[i64]) -> Result<Vec<Ima
 }
 
 pub fn get_folders(conn: &Connection) -> Result<Vec<Folder>> {
-    let mut stmt =
-        conn.prepare("SELECT id, path, name, image_count, indexed_at, scan_error FROM folders ORDER BY name")?;
+    let mut stmt = conn.prepare(
+        "SELECT id, path, name, image_count, indexed_at, scan_error FROM folders ORDER BY name",
+    )?;
     let rows = stmt.query_map([], |row| {
         Ok(Folder {
             id: row.get(0)?,
@@ -1497,7 +1530,13 @@ pub fn rename_folder(conn: &Connection, folder_id: i64, new_name: &str) -> Resul
     Ok(())
 }
 
-pub fn update_folder_path(conn: &Connection, folder_id: i64, old_path: &str, new_path: &str, new_name: &str) -> Result<()> {
+pub fn update_folder_path(
+    conn: &Connection,
+    folder_id: i64,
+    old_path: &str,
+    new_path: &str,
+    new_name: &str,
+) -> Result<()> {
     // Both updates must be atomic: if the image path rewrite fails (e.g. a
     // uniqueness collision) the folder row must not remain at the new location.
     let tx = conn.unchecked_transaction()?;
@@ -1533,6 +1572,7 @@ pub fn clear_folder_scan_error(conn: &Connection, folder_id: i64) -> Result<()>
     Ok(())
 }
 
+#[allow(clippy::too_many_arguments)] // mirrors the gallery query surface; a params struct adds noise for one caller
 pub fn get_images(
     conn: &Connection,
     folder_id: Option<i64>,
@@ -1561,7 +1601,7 @@ pub fn get_images(
         _ => "modified_at DESC NULLS LAST",
     };
 
-    let search_pattern = search.map(|value| format!("%{}%", value));
+    let search_pattern = search.map(|value| format!("%{value}%"));
     let favorites_flag = i64::from(favorites_only);
     let embedding_failed_flag = i64::from(embedding_failed_only);
     let sql = format!(
@@ -1577,9 +1617,8 @@ pub fn get_images(
            AND (?4 = 0 OR favorite = 1)
            AND rating >= ?5
            AND (?6 = 0 OR embedding_status = 'failed')
-         ORDER BY {}
-         LIMIT ?7 OFFSET ?8",
-        order
+         ORDER BY {order}
+         LIMIT ?7 OFFSET ?8"
     );
     let mut stmt = conn.prepare(&sql)?;
     let rows = stmt.query_map(
@@ -1607,7 +1646,7 @@ pub fn count_images(
     rating_min: i64,
     embedding_failed_only: bool,
 ) -> Result<i64> {
-    let search_pattern = search.map(|value| format!("%{}%", value));
+    let search_pattern = search.map(|value| format!("%{value}%"));
 
     let favorites_flag = i64::from(favorites_only);
     let embedding_failed_flag = i64::from(embedding_failed_only);
@@ -1633,6 +1672,7 @@ pub fn count_images(
     Ok(count)
 }
 
+#[allow(clippy::too_many_arguments)]
 pub fn search_images_by_tag(
     conn: &Connection,
     query: &str,
@@ -1659,7 +1699,13 @@ pub fn search_images_by_tag(
            AND (?3 = 0 OR i.favorite = 1)
            AND i.rating >= ?4
            AND LOWER(TRIM(t.tag)) = ?5",
-        params![folder_id, media_kind, favorites_flag, rating_min, normalized_query],
+        params![
+            folder_id,
+            media_kind,
+            favorites_flag,
+            rating_min,
+            normalized_query
+        ],
         |row| row.get::<_, i64>(0),
     )? as usize;
 
@@ -1769,10 +1815,7 @@ pub fn get_image_id_and_thumbnail_by_path(
 
 /// Returns all non-null thumbnail_path values for images in a folder.
 /// Called before folder deletion so callers can remove the files from disk.
-pub fn get_thumbnail_paths_for_folder(
-    conn: &Connection,
-    folder_id: i64,
-) -> Result<Vec<String>> {
+pub fn get_thumbnail_paths_for_folder(conn: &Connection, folder_id: i64) -> Result<Vec<String>> {
     let mut stmt = conn.prepare(
         "SELECT thumbnail_path FROM images WHERE folder_id = ?1 AND thumbnail_path IS NOT NULL",
     )?;
@@ -2054,7 +2097,10 @@ pub fn clear_tagging_jobs(conn: &Connection, folder_id: Option<i64>) -> Result<u
                  WHERE status = 'processing'",
                 [],
             )?;
-            let n = conn.execute("DELETE FROM tagging_jobs WHERE status NOT IN ('processing', 'cancelled')", [])?;
+            let n = conn.execute(
+                "DELETE FROM tagging_jobs WHERE status NOT IN ('processing', 'cancelled')",
+                [],
+            )?;
             conn.execute(
                 "UPDATE images SET ai_tagger_error = NULL WHERE ai_tagged_at IS NULL",
                 [],
@@ -2376,7 +2422,7 @@ pub fn set_duplicate_scan_cache(
 }
 
 fn ensure_column(conn: &Connection, table: &str, column: &str, definition: &str) -> Result<()> {
-    let mut stmt = conn.prepare(&format!("PRAGMA table_info({})", table))?;
+    let mut stmt = conn.prepare(&format!("PRAGMA table_info({table})"))?;
     let mut rows = stmt.query([])?;
     while let Some(row) = rows.next()? {
         let existing_name: String = row.get(1)?;
@@ -2386,7 +2432,7 @@ fn ensure_column(conn: &Connection, table: &str, column: &str, definition: &str)
     }
 
     conn.execute(
-        &format!("ALTER TABLE {} ADD COLUMN {} {}", table, column, definition),
+        &format!("ALTER TABLE {table} ADD COLUMN {column} {definition}"),
         [],
     )?;
     Ok(())
@@ -2413,5 +2459,5 @@ fn folder_exclusion_clause(
         .map(|id| id.to_string())
         .collect::<Vec<_>>()
         .join(",");
-    format!("AND {}.folder_id NOT IN ({})", image_alias, id_list)
+    format!("AND {image_alias}.folder_id NOT IN ({id_list})")
 }

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,14 +177,14 @@ 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)

src-tauri/src/indexer.rs

@@ -7,9 +7,9 @@ use crate::tagger::{self, WdTagger};
 use crate::thumbnail;
 use crate::vector;
 use anyhow::Result;
+use notify::{RecommendedWatcher, RecursiveMode, Watcher};
 use rayon::prelude::*;
 use serde::Serialize;
-use notify::{RecommendedWatcher, RecursiveMode, Watcher};
 use std::collections::{HashMap, HashSet};
 use std::path::{Path, PathBuf};
 use std::sync::{Arc, Mutex, OnceLock};
@@ -24,6 +24,7 @@ const IMAGE_EXTENSIONS: &[&str] = &[
 const VIDEO_EXTENSIONS: &[&str] = &["mp4", "mov", "m4v", "webm"];
 
 const JOB_PROGRESS_EMIT_INTERVAL: Duration = Duration::from_millis(750);
+#[allow(dead_code)] // caption worker disabled (lib.rs)
 const CAPTION_BATCH_SIZE: usize = 1;
 
 static LAST_JOB_PROGRESS_EMIT: OnceLock<Mutex<HashMap<i64, Instant>>> = OnceLock::new();
@@ -141,14 +142,18 @@ fn higher_priority_work_pending(pool: &DbPool, own_tier: WorkerTier) -> Result<b
     let conn = pool.get()?;
     let active_folders = active_indexing_folders();
 
+    // Video jobs are unclaimable until FFmpeg is provisioned; they must not
+    // count as pending higher-priority work or they'd stall lower tiers.
+    let ffmpeg_ready = crate::media::ffmpeg_ready();
+
     if own_tier > WorkerTier::Thumbnail {
         let mut excluded = paused_folder_ids("thumbnail");
         excluded.extend(active_folders.iter().copied());
-        if db::has_claimable_thumbnail_jobs(&conn, &excluded)? {
+        if db::has_claimable_thumbnail_jobs(&conn, &excluded, ffmpeg_ready)? {
             return Ok(true);
         }
     }
-    if own_tier > WorkerTier::Metadata {
+    if own_tier > WorkerTier::Metadata && ffmpeg_ready {
         let mut excluded = paused_folder_ids("metadata");
         excluded.extend(active_folders.iter().copied());
         if db::has_claimable_metadata_jobs(&conn, &excluded)? {
@@ -200,7 +205,7 @@ pub fn index_folder(app: AppHandle, pool: DbPool, folder_id: i64, folder_path: P
         // not be silently destroyed.
         if !folder_path.is_dir() {
             let error_msg = format!("Folder not found: {}", folder_path.display());
-            eprintln!("Indexing error for folder {}: {}", folder_id, error_msg);
+            log::error!("Indexing error for folder {folder_id}: {error_msg}");
             if let Ok(conn) = pool.get() {
                 let _ = db::set_folder_scan_error(&conn, folder_id, &error_msg);
             }
@@ -221,7 +226,7 @@ pub fn index_folder(app: AppHandle, pool: DbPool, folder_id: i64, folder_path: P
         let storage_profile = detect_storage_profile(&folder_path);
         set_folder_storage_profile(folder_id, RuntimeAdaptiveProfile::new(storage_profile));
         if let Err(error) = do_index(app.clone(), &pool, folder_id, folder_path) {
-            eprintln!("Indexing error for folder {}: {}", folder_id, error);
+            log::error!("Indexing error for folder {folder_id}: {error}");
             if let Ok(conn) = pool.get() {
                 let _ = db::set_folder_scan_error(&conn, folder_id, &error.to_string());
             }
@@ -254,7 +259,7 @@ pub fn start_thumbnail_worker(
             Ok(true) => {}
             Ok(false) => std::thread::sleep(std::time::Duration::from_millis(250)),
             Err(error) => {
-                eprintln!("Thumbnail worker error: {}", error);
+                log::error!("Thumbnail worker error: {error}");
                 std::thread::sleep(std::time::Duration::from_millis(250));
             }
         }
@@ -269,7 +274,7 @@ pub fn start_metadata_worker(app: AppHandle, pool: DbPool, media_tools: MediaToo
             Ok(true) => {}
             Ok(false) => std::thread::sleep(std::time::Duration::from_millis(250)),
             Err(error) => {
-                eprintln!("Metadata worker error: {}", error);
+                log::error!("Metadata worker error: {error}");
                 std::thread::sleep(std::time::Duration::from_millis(250));
             }
         }
@@ -279,7 +284,7 @@ pub fn start_metadata_worker(app: AppHandle, pool: DbPool, media_tools: MediaToo
 pub fn start_embedding_worker(app: AppHandle, pool: DbPool) {
     std::thread::spawn(move || {
         let mut embedder: Option<ClipImageEmbedder> = None;
-        println!("Embedding worker started.");
+        log::info!("Embedding worker started.");
         loop {
             // Only back off when the queue is empty (or errored); while jobs
             // are pending, claim the next batch immediately.
@@ -287,7 +292,7 @@ pub fn start_embedding_worker(app: AppHandle, pool: DbPool) {
                 Ok(true) => {}
                 Ok(false) => std::thread::sleep(std::time::Duration::from_millis(500)),
                 Err(error) => {
-                    eprintln!("Embedding worker error: {}", error);
+                    log::error!("Embedding worker error: {error}");
                     std::thread::sleep(std::time::Duration::from_millis(500));
                 }
             }
@@ -295,19 +300,20 @@ pub fn start_embedding_worker(app: AppHandle, pool: DbPool) {
     });
 }
 
+#[allow(dead_code)] // caption worker disabled (lib.rs)
 pub fn start_caption_worker(app: AppHandle, pool: DbPool, app_data_dir: PathBuf) {
     std::thread::spawn(move || {
         let mut captioner: Option<FlorenceCaptioner> = None;
-        println!("Caption worker started.");
+        log::info!("Caption worker started.");
         loop {
             // If the acceleration setting changed, drop the cached session so
             // the next batch picks it up with the new execution provider.
             if captioner::CAPTION_SESSION_DIRTY.swap(false, std::sync::atomic::Ordering::Relaxed) {
-                println!("Caption worker: acceleration setting changed — resetting session.");
+                log::info!("Caption worker: acceleration setting changed — resetting session.");
                 captioner = None;
             }
             if let Err(error) = process_caption_batch(&app, &pool, &app_data_dir, &mut captioner) {
-                eprintln!("Caption worker error: {}", error);
+                log::error!("Caption worker error: {error}");
                 captioner = None;
             }
             std::thread::sleep(std::time::Duration::from_millis(750));
@@ -318,12 +324,12 @@ pub fn start_caption_worker(app: AppHandle, pool: DbPool, app_data_dir: PathBuf)
 pub fn start_tagging_worker(app: AppHandle, pool: DbPool, app_data_dir: PathBuf) {
     std::thread::spawn(move || {
         let mut tagger_instance: Option<WdTagger> = None;
-        println!("Tagging worker started.");
+        log::info!("Tagging worker started.");
         loop {
             // If the acceleration setting changed, drop the cached session so
             // the next batch picks it up with the new execution provider.
             if tagger::TAGGER_SESSION_DIRTY.swap(false, std::sync::atomic::Ordering::Relaxed) {
-                println!("Tagging worker: acceleration setting changed — resetting session.");
+                log::info!("Tagging worker: acceleration setting changed — resetting session.");
                 tagger_instance = None;
             }
             // Only back off when the queue is empty (or errored); while jobs
@@ -332,7 +338,7 @@ pub fn start_tagging_worker(app: AppHandle, pool: DbPool, app_data_dir: PathBuf)
                 Ok(true) => {}
                 Ok(false) => std::thread::sleep(std::time::Duration::from_millis(750)),
                 Err(error) => {
-                    eprintln!("Tagging worker error: {}", error);
+                    log::error!("Tagging worker error: {error}");
                     tagger_instance = None;
                     std::thread::sleep(std::time::Duration::from_millis(750));
                 }
@@ -369,7 +375,7 @@ fn do_index(app: AppHandle, pool: &DbPool, folder_id: i64, folder_path: PathBuf)
                 if let Some(path) = err.path() {
                     unreadable_prefixes.push(path.to_string_lossy().into_owned());
                 }
-                eprintln!(
+                log::error!(
                     "WalkDir error while scanning folder {}: {}",
                     folder_path.display(),
                     err
@@ -414,7 +420,7 @@ fn do_index(app: AppHandle, pool: &DbPool, folder_id: i64, folder_path: PathBuf)
         }
 
         if !records.is_empty() {
-            let committed = commit_batch(&pool, &records)?;
+            let committed = commit_batch(pool, &records)?;
             emit_images(
                 &app,
                 &IndexedImagesBatch {
@@ -422,7 +428,7 @@ fn do_index(app: AppHandle, pool: &DbPool, folder_id: i64, folder_path: PathBuf)
                     images: committed,
                 },
             );
-            emit_folder_job_progress(&app, &pool, &[folder_id], false);
+            emit_folder_job_progress(&app, pool, &[folder_id], false);
         }
 
         processed += path_chunk.len();
@@ -473,7 +479,7 @@ fn do_index(app: AppHandle, pool: &DbPool, folder_id: i64, folder_path: PathBuf)
         let _ = db::clear_folder_scan_error(&conn, folder_id);
         // Invalidate duplicate scan cache — any reindex can change file contents
         // or the set of files, making cached duplicate groups stale.
-        let folder_scope = format!("folder:{}", folder_id);
+        let folder_scope = format!("folder:{folder_id}");
         let _ = db::clear_duplicate_scan_cache(&conn, &folder_scope);
         let _ = db::clear_duplicate_scan_cache(&conn, "all");
     }
@@ -488,7 +494,7 @@ fn do_index(app: AppHandle, pool: &DbPool, folder_id: i64, folder_path: PathBuf)
             done: true,
         },
     );
-    emit_folder_job_progress(&app, &pool, &[folder_id], true);
+    emit_folder_job_progress(&app, pool, &[folder_id], true);
     Ok(())
 }
 
@@ -639,6 +645,7 @@ fn process_thumbnail_batch(
                 &mut conn,
                 &active_folders,
                 &paused_folders,
+                crate::media::ffmpeg_ready(),
                 worker_fetch_size,
                 worker_batch_size,
             )
@@ -649,7 +656,7 @@ fn process_thumbnail_batch(
         return Ok(false);
     }
 
-    println!("Thumbnail batch claimed: {} items", jobs.len());
+    log::info!("Thumbnail batch claimed: {} items", jobs.len());
 
     let (image_jobs, video_jobs): (Vec<_>, Vec<_>) =
         jobs.into_iter().partition(|job| job.media_kind == "image");
@@ -746,6 +753,11 @@ fn process_metadata_batch(
     pool: &DbPool,
     media_tools: &MediaTools,
 ) -> Result<bool> {
+    // Metadata jobs are video-only and need ffprobe; leave them pending until
+    // FFmpeg is provisioned — the worker poll loop drains them once ready.
+    if !crate::media::ffmpeg_ready() {
+        return Ok(false);
+    }
     if higher_priority_work_pending(pool, WorkerTier::Metadata)? {
         return Ok(false);
     }
@@ -846,7 +858,7 @@ fn process_embedding_batch(
         *embedder = Some(ClipImageEmbedder::new()?);
     }
 
-    println!("Embedding batch claimed: {} items", jobs.len());
+    log::info!("Embedding batch claimed: {} items", jobs.len());
     let folder_ids = jobs.iter().map(|job| job.folder_id).collect::<HashSet<_>>();
     emit_folder_job_progress(
         app,
@@ -897,10 +909,7 @@ fn process_embedding_batch(
                 }
             }
             Err(batch_error) => {
-                eprintln!(
-                    "Embedding batch fallback to per-image mode: {}",
-                    batch_error
-                );
+                log::error!("Embedding batch fallback to per-image mode: {batch_error}");
                 for (job, source_path) in embeddable_jobs
                     .into_iter()
                     .zip(embeddable_paths.into_iter())
@@ -921,7 +930,7 @@ fn process_embedding_batch(
         for job in &jobs {
             let embedding_result: Result<Vec<f32>> =
                 if let Some(err) = pre_failed.remove(&job.image_id) {
-                    Err(anyhow::anyhow!("{}", err))
+                    Err(anyhow::anyhow!("{err}"))
                 } else if let Some(r) = embed_results.remove(&job.image_id) {
                     r
                 } else {
@@ -946,7 +955,7 @@ fn process_embedding_batch(
     })?;
 
     if !updated_images.is_empty() {
-        println!("Embedding batch completed: {} items", updated_images.len());
+        log::info!("Embedding batch completed: {} items", updated_images.len());
         let folder_ids = updated_images
             .iter()
             .map(|image| image.folder_id)
@@ -962,14 +971,14 @@ fn process_embedding_batch(
 
     let write_elapsed = write_started_at.elapsed();
     let batch_elapsed = batch_started_at.elapsed();
-    println!(
-        "Embedding batch timing: claimed {} in {:?}, infer {:?}, write {:?}, total {:?}",
-        EMBEDDING_BATCH_SIZE, claim_elapsed, infer_elapsed, write_elapsed, batch_elapsed
+    log::info!(
+        "Embedding batch timing: claimed {EMBEDDING_BATCH_SIZE} in {claim_elapsed:?}, infer {infer_elapsed:?}, write {write_elapsed:?}, total {batch_elapsed:?}"
     );
 
     Ok(true)
 }
 
+#[allow(dead_code)] // caption worker disabled (lib.rs)
 fn process_caption_batch(
     app: &AppHandle,
     pool: &DbPool,
@@ -1182,7 +1191,7 @@ fn process_tagging_batch(
         tx.commit()?;
         Ok(updated_images)
     })
-    .or_else(|db_err| {
+    .inspect_err(|_db_err| {
         // The DB write failed.  Try to requeue the claimed jobs so they aren't
         // left stuck in 'processing' until the next app restart.
         let image_ids: Vec<i64> = jobs.iter().map(|job| job.image_id).collect();
@@ -1190,7 +1199,6 @@ fn process_tagging_batch(
             let conn = pool.get()?;
             db::requeue_tagging_jobs(&conn, &image_ids)
         });
-        Err(db_err)
     })?;
 
     if !updated_images.is_empty() {
@@ -1296,7 +1304,7 @@ fn emit_media_updates(app: &AppHandle, batch: &MediaUpdateBatch) {
 }
 
 pub fn emit_folder_job_progress(app: &AppHandle, pool: &DbPool, folder_ids: &[i64], force: bool) {
-    let mut unique_folder_ids = folder_ids.iter().copied().collect::<Vec<_>>();
+    let mut unique_folder_ids = folder_ids.to_vec();
     unique_folder_ids.sort_unstable();
     unique_folder_ids.dedup();
 
@@ -1397,11 +1405,15 @@ impl WatcherHandle {
             let mut w = self.inner.watcher.lock().unwrap();
             if path.is_dir() {
                 if let Err(e) = w.watch(&path, RecursiveMode::Recursive) {
-                    eprintln!("Watcher: failed to watch {:?}: {}", path, e);
+                    log::error!("Watcher: failed to watch {path:?}: {e}");
                 }
             }
         }
-        self.inner.folder_map.lock().unwrap().insert(path, folder_id);
+        self.inner
+            .folder_map
+            .lock()
+            .unwrap()
+            .insert(path, folder_id);
     }
 
     pub fn remove_folder(&self, path: &Path) {
@@ -1418,7 +1430,7 @@ impl WatcherHandle {
             let _ = w.unwatch(old_path);
             if new_path.is_dir() {
                 if let Err(e) = w.watch(&new_path, RecursiveMode::Recursive) {
-                    eprintln!("Watcher: failed to watch {:?}: {}", new_path, e);
+                    log::error!("Watcher: failed to watch {new_path:?}: {e}");
                 }
             }
         }
@@ -1446,7 +1458,9 @@ pub fn start_watcher(app: AppHandle, pool: DbPool, thumb_dir: PathBuf) -> Watche
     // Seed the folder map from the DB so existing folders are watched on startup.
     let folder_map: Arc<Mutex<HashMap<PathBuf, i64>>> = Arc::new(Mutex::new(HashMap::new()));
     {
-        let conn = pool.get().expect("Watcher: failed to get DB connection for init");
+        let conn = pool
+            .get()
+            .expect("Watcher: failed to get DB connection for init");
         let folders = db::get_folders(&conn).unwrap_or_default();
         let mut map = folder_map.lock().unwrap();
         for f in folders {
@@ -1461,7 +1475,7 @@ pub fn start_watcher(app: AppHandle, pool: DbPool, thumb_dir: PathBuf) -> Watche
         for path in map.keys() {
             if path.is_dir() {
                 if let Err(e) = w.watch(path, RecursiveMode::Recursive) {
-                    eprintln!("Watcher: failed to watch {:?}: {}", path, e);
+                    log::error!("Watcher: failed to watch {path:?}: {e}");
                 }
             }
         }
@@ -1505,7 +1519,10 @@ pub fn start_watcher(app: AppHandle, pool: DbPool, thumb_dir: PathBuf) -> Watche
 
             // Absorb incoming event — coalesces rapid writes into one deadline.
             if let Some(Ok(event)) = received {
-                use notify::{EventKind, event::{ModifyKind, RenameMode}};
+                use notify::{
+                    event::{ModifyKind, RenameMode},
+                    EventKind,
+                };
                 if !matches!(event.kind, EventKind::Access(_)) {
                     // Intercept atomic rename events (old + new path in one event).
                     // Handle these separately to preserve embeddings and thumbnails.
@@ -1536,7 +1553,14 @@ pub fn start_watcher(app: AppHandle, pool: DbPool, thumb_dir: PathBuf) -> Watche
             // Process renames immediately — they are atomic filesystem operations
             // and do not benefit from debouncing.
             for (old_path, new_path) in pending_renames.drain(..) {
-                process_watcher_rename(&app, &pool, &folder_map_thread, &thumb_dir, &old_path, &new_path);
+                process_watcher_rename(
+                    &app,
+                    &pool,
+                    &folder_map_thread,
+                    &thumb_dir,
+                    &old_path,
+                    &new_path,
+                );
             }
 
             // Process all paths whose debounce window has expired.
@@ -1577,7 +1601,7 @@ fn process_watcher_path(
     let conn = match pool.get() {
         Ok(c) => c,
         Err(e) => {
-            eprintln!("Watcher: DB pool error: {}", e);
+            log::error!("Watcher: DB pool error: {e}");
             return;
         }
     };
@@ -1594,7 +1618,13 @@ fn process_watcher_path(
         match commit_batch(pool, &[record]) {
             Ok(committed) if !committed.is_empty() => {
                 // Always emit the images — they are committed to the DB.
-                emit_images(app, &IndexedImagesBatch { folder_id, images: committed });
+                emit_images(
+                    app,
+                    &IndexedImagesBatch {
+                        folder_id,
+                        images: committed,
+                    },
+                );
                 emit_folder_job_progress(app, pool, &[folder_id], false);
                 // Update the sidebar count only if we successfully write the new
                 // count; skip the frontend notification on pool/DB failure to
@@ -1606,7 +1636,7 @@ fn process_watcher_path(
                 }
             }
             Ok(_) => {}
-            Err(e) => eprintln!("Watcher: commit error for {:?}: {}", path, e),
+            Err(e) => log::error!("Watcher: commit error for {path:?}: {e}"),
         }
     } else {
         // File removed from disk — clean up DB row and thumbnail.
@@ -1623,7 +1653,7 @@ fn process_watcher_path(
                 }
             }
             Ok(None) => {} // never indexed or already removed
-            Err(e) => eprintln!("Watcher: lookup error for {:?}: {}", path, e),
+            Err(e) => log::error!("Watcher: lookup error for {path:?}: {e}"),
         }
     }
 }
@@ -1643,7 +1673,9 @@ fn process_watcher_rename(
     let folder_id = {
         let map = folder_map.lock().unwrap();
         map.iter()
-            .find(|(fp, _)| old_path.starts_with(fp.as_path()) || new_path.starts_with(fp.as_path()))
+            .find(|(fp, _)| {
+                old_path.starts_with(fp.as_path()) || new_path.starts_with(fp.as_path())
+            })
             .map(|(_, &id)| id)
     };
     let Some(folder_id) = folder_id else { return };
@@ -1651,7 +1683,7 @@ fn process_watcher_rename(
     let conn = match pool.get() {
         Ok(c) => c,
         Err(e) => {
-            eprintln!("Watcher rename: DB pool error: {}", e);
+            log::error!("Watcher rename: DB pool error: {e}");
             return;
         }
     };
@@ -1668,7 +1700,7 @@ fn process_watcher_rename(
             return;
         }
         Err(e) => {
-            eprintln!("Watcher rename: DB lookup error: {}", e);
+            log::error!("Watcher rename: DB lookup error: {e}");
             return;
         }
     };
@@ -1684,19 +1716,28 @@ fn process_watcher_rename(
     // the thumbnail worker regenerates it.
     let effective_thumb: Option<&str> = if thumb_ok { Some(&new_thumb_str) } else { None };
 
-    let new_filename = new_path
-        .file_name()
-        .and_then(|f| f.to_str())
-        .unwrap_or("");
+    let new_filename = new_path.file_name().and_then(|f| f.to_str()).unwrap_or("");
 
-    if let Err(e) = db::update_image_path(&conn, image_id, &new_path_str, new_filename, effective_thumb) {
-        eprintln!("Watcher rename: DB update error: {}", e);
+    if let Err(e) = db::update_image_path(
+        &conn,
+        image_id,
+        &new_path_str,
+        new_filename,
+        effective_thumb,
+    ) {
+        log::error!("Watcher rename: DB update error: {e}");
         return;
     }
 
     // Emit the updated record so the frontend refreshes without a full reload.
     match db::get_image_by_id(&conn, image_id) {
-        Ok(record) => emit_images(app, &IndexedImagesBatch { folder_id, images: vec![record] }),
-        Err(e) => eprintln!("Watcher rename: post-update fetch error: {}", e),
+        Ok(record) => emit_images(
+            app,
+            &IndexedImagesBatch {
+                folder_id,
+                images: vec![record],
+            },
+        ),
+        Err(e) => log::error!("Watcher rename: post-update fetch error: {e}"),
     }
 }

src-tauri/src/lib.rs

@@ -16,6 +16,30 @@ 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())
@@ -28,7 +52,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 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");
@@ -41,14 +68,13 @@ pub fn run() {
                 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."
                     );
                 }
             }
@@ -56,6 +82,19 @@ pub fn run() {
             let thumb_dir = app_dir.join("thumbnails");
             std::fs::create_dir_all(&thumb_dir).expect("Failed to create thumbnail 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()))
                 .unwrap_or(2);
@@ -150,6 +189,10 @@ pub fn run() {
             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_notifications_paused,
             commands::set_notifications_paused,
         ])

src-tauri/src/media.rs

@@ -2,9 +2,136 @@ use anyhow::{anyhow, Result};
 use ffmpeg_sidecar::download::{auto_download_with_progress, FfmpegDownloadProgressEvent};
 use ffmpeg_sidecar::ffprobe::ffprobe_path;
 use ffmpeg_sidecar::paths::ffmpeg_path;
-use serde::Deserialize;
+use serde::{Deserialize, Serialize};
 use std::path::{Path, PathBuf};
 use std::process::Command;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::time::{Duration, Instant};
+use tauri::{AppHandle, Emitter};
+
+static FFMPEG_READY: AtomicBool = AtomicBool::new(false);
+static FFMPEG_DOWNLOADING: AtomicBool = AtomicBool::new(false);
+// Set when a provision attempt fails, so the frontend can distinguish
+// "failed before the event listener attached" from "about to start".
+static FFMPEG_FAILED: AtomicBool = AtomicBool::new(false);
+
+/// True once both ffmpeg and ffprobe binaries are present on disk. Workers
+/// gate video jobs on this so a missing/in-flight download never fails jobs.
+pub fn ffmpeg_ready() -> bool {
+    FFMPEG_READY.load(Ordering::Relaxed)
+}
+
+pub fn ffmpeg_downloading() -> bool {
+    FFMPEG_DOWNLOADING.load(Ordering::Relaxed)
+}
+
+pub fn ffmpeg_failed() -> bool {
+    FFMPEG_FAILED.load(Ordering::Relaxed)
+}
+
+#[derive(Debug, Clone, Serialize)]
+pub struct FfmpegProgressPayload {
+    pub phase: String,
+    pub downloaded_bytes: Option<u64>,
+    pub total_bytes: Option<u64>,
+    pub error: Option<String>,
+}
+
+impl FfmpegProgressPayload {
+    fn phase(phase: &str) -> Self {
+        Self {
+            phase: phase.to_string(),
+            downloaded_bytes: None,
+            total_bytes: None,
+            error: None,
+        }
+    }
+}
+
+const FFMPEG_PROGRESS_EVENT: &str = "ffmpeg-progress";
+
+/// Provision FFmpeg in the background, streaming progress to the frontend as
+/// `ffmpeg-progress` events. Idempotent: re-invoking while a download is in
+/// flight is a no-op, and re-invoking after success only re-emits `done`.
+pub fn spawn_ffmpeg_provision(app: AppHandle) {
+    // Fast path: binaries already on disk (previous run, or a manual install).
+    if ffmpeg_path().exists() && ffprobe_path().exists() {
+        FFMPEG_READY.store(true, Ordering::Relaxed);
+        let _ = app.emit(FFMPEG_PROGRESS_EVENT, FfmpegProgressPayload::phase("done"));
+        return;
+    }
+
+    if FFMPEG_DOWNLOADING
+        .compare_exchange(false, true, Ordering::SeqCst, Ordering::SeqCst)
+        .is_err()
+    {
+        return; // a download is already running
+    }
+    FFMPEG_FAILED.store(false, Ordering::SeqCst);
+
+    std::thread::spawn(move || {
+        // The Downloading callback fires very frequently; throttle emissions.
+        // Cell because the download callback is Fn, not FnMut.
+        let last_emit = std::cell::Cell::new(Instant::now() - Duration::from_secs(1));
+        let result = auto_download_with_progress(|event| match event {
+            FfmpegDownloadProgressEvent::Starting => {
+                log::info!("Downloading bundled FFmpeg...");
+                let _ = app.emit(
+                    FFMPEG_PROGRESS_EVENT,
+                    FfmpegProgressPayload::phase("starting"),
+                );
+            }
+            FfmpegDownloadProgressEvent::Downloading {
+                total_bytes,
+                downloaded_bytes,
+            } => {
+                if last_emit.get().elapsed() >= Duration::from_millis(250) {
+                    last_emit.set(Instant::now());
+                    let _ = app.emit(
+                        FFMPEG_PROGRESS_EVENT,
+                        FfmpegProgressPayload {
+                            phase: "downloading".to_string(),
+                            downloaded_bytes: Some(downloaded_bytes),
+                            total_bytes: Some(total_bytes),
+                            error: None,
+                        },
+                    );
+                }
+            }
+            FfmpegDownloadProgressEvent::UnpackingArchive => {
+                log::info!("Unpacking bundled FFmpeg...");
+                let _ = app.emit(
+                    FFMPEG_PROGRESS_EVENT,
+                    FfmpegProgressPayload::phase("unpacking"),
+                );
+            }
+            FfmpegDownloadProgressEvent::Done => {
+                log::info!("Bundled FFmpeg ready.");
+            }
+        });
+
+        FFMPEG_DOWNLOADING.store(false, Ordering::SeqCst);
+        match result {
+            Ok(()) => {
+                FFMPEG_READY.store(true, Ordering::Relaxed);
+                let _ = app.emit(FFMPEG_PROGRESS_EVENT, FfmpegProgressPayload::phase("done"));
+            }
+            Err(error) => {
+                FFMPEG_FAILED.store(true, Ordering::SeqCst);
+                log::error!("FFmpeg provisioning failed: {error}");
+                let _ = app.emit(
+                    FFMPEG_PROGRESS_EVENT,
+                    FfmpegProgressPayload {
+                        phase: "error".to_string(),
+                        downloaded_bytes: None,
+                        total_bytes: None,
+                        error: Some(error.to_string()),
+                    },
+                );
+            }
+        }
+    });
+}
 
 // On Windows, GUI apps spawn subprocesses with a visible console window by default.
 // CREATE_NO_WINDOW suppresses that for every ffmpeg/ffprobe invocation.
@@ -36,33 +163,6 @@ impl MediaTools {
         }
     }
 
-    pub fn ensure_installed() -> Result<()> {
-        // Skip download entirely if both binaries are already present.
-        if ffmpeg_path().exists() && ffprobe_path().exists() {
-            return Ok(());
-        }
-        auto_download_with_progress(|event| match event {
-            FfmpegDownloadProgressEvent::Starting => {
-                println!("Downloading bundled FFmpeg...");
-            }
-            FfmpegDownloadProgressEvent::Downloading {
-                total_bytes,
-                downloaded_bytes,
-            } => {
-                println!(
-                    "Downloading bundled FFmpeg: {}/{} bytes",
-                    downloaded_bytes, total_bytes
-                );
-            }
-            FfmpegDownloadProgressEvent::UnpackingArchive => {
-                println!("Unpacking bundled FFmpeg...");
-            }
-            FfmpegDownloadProgressEvent::Done => {
-                println!("Bundled FFmpeg ready.");
-            }
-        })
-    }
-
     pub fn ffmpeg_command(&self) -> Command {
         let mut cmd = Command::new(&self.ffmpeg_path);
         #[cfg(target_os = "windows")]

src-tauri/src/storage.rs

@@ -1,4 +1,4 @@
-use std::path::{Path, PathBuf};
+use std::path::Path;
 use sysinfo::{DiskKind, Disks};
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
@@ -107,7 +107,7 @@ pub fn detect_storage_profile(path: &Path) -> StorageProfile {
     }
 }
 
-fn fallback_profile_for_path(path: &PathBuf) -> StorageProfile {
+fn fallback_profile_for_path(path: &Path) -> StorageProfile {
     let path_str = path.to_string_lossy().to_lowercase();
     if path_str.starts_with("\\\\") {
         return StorageProfile::Conservative;

src-tauri/src/tagger.rs

@@ -87,6 +87,10 @@ pub struct TaggerModelProgress {
     pub total_files: usize,
     pub completed_files: usize,
     pub current_file: Option<String>,
+    // Byte progress for the file currently downloading. None for files whose
+    // size isn't known up front (or between files).
+    pub downloaded_bytes: Option<u64>,
+    pub total_bytes: Option<u64>,
     pub done: bool,
 }
 
@@ -200,11 +204,7 @@ pub fn tagger_batch_size(app_data_dir: &Path) -> usize {
     let Ok(value) = std::fs::read_to_string(path) else {
         return 8;
     };
-    value
-        .trim()
-        .parse::<usize>()
-        .unwrap_or(8)
-        .clamp(1, 100)
+    value.trim().parse::<usize>().unwrap_or(8).clamp(1, 100)
 }
 
 pub fn set_tagger_batch_size(app_data_dir: &Path, batch_size: usize) -> Result<usize> {
@@ -254,58 +254,93 @@ pub fn prepare_tagger_model_with_progress(
     let local_dir = model_dir(app_data_dir);
     std::fs::create_dir_all(&local_dir)?;
 
-    // Ensure the shared ONNX runtime DLLs are present. The tagger shares
-    // them with the captioner; install them here so the tagger is fully
-    // functional even on a clean install where the caption model has never
-    // been downloaded.
+    // The tagger shares the ONNX runtime DLLs with the captioner; download
+    // them here so the tagger works even on a clean install where the caption
+    // model has never been fetched (ensure_onnx_runtime only initializes).
+    const DOWNLOAD_FILES: &[&str] = &["model.onnx", "selected_tags.csv"];
     let caption_model_dir = crate::captioner::model_dir(app_data_dir);
     std::fs::create_dir_all(&caption_model_dir)?;
-    crate::captioner::ensure_onnx_runtime(&caption_model_dir)?;
 
-    // Download the two tagger-specific files.
-    const DOWNLOAD_FILES: &[&str] = &["model.onnx", "selected_tags.csv"];
-
-    let api = Api::new()?;
-    let repo = api.repo(Repo::new(WD_TAGGER_MODEL_ID.to_string(), RepoType::Model));
-
-    let mut completed_files = DOWNLOAD_FILES
+    // Unified step count across DLLs and tagger files so the bar is coherent.
+    let dll_count = crate::captioner::missing_onnx_runtime_count(&caption_model_dir);
+    let model_pending = DOWNLOAD_FILES
         .iter()
-        .filter(|file| local_dir.join(file).exists())
+        .filter(|file| !local_dir.join(file).exists())
         .count();
+    let total_files = dll_count + model_pending;
+    let mut completed_files = 0usize;
 
     emit_progress(TaggerModelProgress {
-        total_files: DOWNLOAD_FILES.len(),
+        total_files,
         completed_files,
         current_file: None,
-        done: completed_files == DOWNLOAD_FILES.len(),
+        downloaded_bytes: None,
+        total_bytes: None,
+        done: total_files == 0,
     });
 
+    // ── ONNX runtime DLLs (small, but non-trivial on a slow link) ──
+    {
+        let mut last_emit = Instant::now() - std::time::Duration::from_secs(1);
+        crate::captioner::provision_onnx_runtime_with_progress(
+            &caption_model_dir,
+            |label, downloaded, total| {
+                if last_emit.elapsed() >= std::time::Duration::from_millis(200) {
+                    last_emit = Instant::now();
+                    emit_progress(TaggerModelProgress {
+                        total_files,
+                        completed_files,
+                        current_file: Some(format!("ONNX Runtime: {label}")),
+                        downloaded_bytes: Some(downloaded),
+                        total_bytes: total,
+                        done: false,
+                    });
+                }
+            },
+        )?;
+        completed_files += dll_count;
+    }
+    log::info!("Tagger: ONNX runtime DLLs ready; initializing runtime");
+    crate::captioner::ensure_onnx_runtime(&caption_model_dir)?;
+    log::info!("Tagger: runtime initialized; downloading model files");
+
+    // ── Tagger model files (model.onnx is ~446 MB) ──
+    // Download directly from the resolved URL with our resilient downloader
+    // (timeout + resume), rather than hf-hub's download_with_progress, whose
+    // agent has no read timeout and would hang on a stalled connection.
+    let api = Api::new()?;
+    let repo = api.repo(Repo::new(WD_TAGGER_MODEL_ID.to_string(), RepoType::Model));
+
     for file in DOWNLOAD_FILES {
         let destination = local_dir.join(file);
         if destination.exists() {
             continue;
         }
-        emit_progress(TaggerModelProgress {
-            total_files: DOWNLOAD_FILES.len(),
-            completed_files,
-            current_file: Some((*file).to_string()),
-            done: false,
-        });
-        let cached = repo.get(file)?;
-        std::fs::copy(cached, destination)?;
+        let url = repo.url(file);
+        let label = (*file).to_string();
+        let mut last_emit = Instant::now() - std::time::Duration::from_secs(1);
+        crate::captioner::download_file_resilient(&url, &destination, |downloaded, total| {
+            if last_emit.elapsed() >= std::time::Duration::from_millis(200) {
+                last_emit = Instant::now();
+                emit_progress(TaggerModelProgress {
+                    total_files,
+                    completed_files,
+                    current_file: Some(label.clone()),
+                    downloaded_bytes: Some(downloaded),
+                    total_bytes: total,
+                    done: false,
+                });
+            }
+        })?;
         completed_files += 1;
-        emit_progress(TaggerModelProgress {
-            total_files: DOWNLOAD_FILES.len(),
-            completed_files,
-            current_file: Some((*file).to_string()),
-            done: completed_files == DOWNLOAD_FILES.len(),
-        });
     }
 
     emit_progress(TaggerModelProgress {
-        total_files: DOWNLOAD_FILES.len(),
+        total_files,
         completed_files,
         current_file: None,
+        downloaded_bytes: None,
+        total_bytes: None,
         done: true,
     });
 
@@ -447,7 +482,7 @@ impl WdTagger {
 
         let labels = load_labels(&labels_path)?;
 
-        println!(
+        log::info!(
             "WD tagger loaded in {:?} ({} labels, input {}x{}, {:?} acceleration)",
             started_at.elapsed(),
             labels.len(),
@@ -485,7 +520,7 @@ impl WdTagger {
             .try_extract_tensor::<f32>()
             .map_err(|error| anyhow::anyhow!("{error}"))?;
 
-        let probs: &[f32] = &probabilities;
+        let probs: &[f32] = probabilities;
 
         if probs.len() != self.labels.len() {
             anyhow::bail!(
@@ -523,7 +558,7 @@ impl WdTagger {
         tags.sort_by(|a, b| b.confidence.total_cmp(&a.confidence));
         tags.truncate(max_tags);
 
-        println!(
+        log::info!(
             "WD tagger: {} tags (threshold={}, rating={}) in {:?} for {}",
             tags.len(),
             self.threshold,
@@ -563,13 +598,13 @@ fn create_tagger_session(path: &Path, acceleration: TaggerAcceleration) -> Resul
 
     let mut builder = match acceleration {
         TaggerAcceleration::Cpu => {
-            println!("WD tagger: using CPU execution provider");
+            log::info!("WD tagger: using CPU execution provider");
             builder
         }
         TaggerAcceleration::Auto => builder
             .with_execution_providers([ep::DirectML::default().build().fail_silently()])
             .unwrap_or_else(|error| {
-                println!("WD tagger: DirectML unavailable, falling back to CPU");
+                log::info!("WD tagger: DirectML unavailable, falling back to CPU");
                 error.recover()
             }),
         TaggerAcceleration::Directml => builder

src-tauri/src/thumbnail.rs

@@ -237,9 +237,7 @@ pub fn generate_video_thumbnail(
     }
 
     Err(anyhow!(
-        "ffmpeg failed generating poster for {}: {}",
-        path_str,
-        last_error
+        "ffmpeg failed generating poster for {path_str}: {last_error}"
     ))
 }
 
@@ -253,13 +251,27 @@ pub fn video_poster_path(cache_dir: &Path, video_path: &str) -> PathBuf {
 
 fn thumb_path_with_ext(cache_dir: &Path, input_path: &str, extension: &str) -> PathBuf {
     let hash = hash_path(input_path);
-    cache_dir.join(format!("{}.{}", hash, extension))
+    cache_dir.join(format!("{hash}.{extension}"))
 }
 
 fn hash_path(s: &str) -> String {
     format!("{:016x}", xxhash_rust::xxh3::xxh3_64(s.as_bytes()))
 }
 
+fn fit_dimensions(width: u32, height: u32, max_size: u32) -> (u32, u32) {
+    if width <= max_size && height <= max_size {
+        return (width.max(1), height.max(1));
+    }
+
+    if width >= height {
+        let scaled_height = ((height as f64 / width as f64) * max_size as f64).round() as u32;
+        (max_size, scaled_height.max(1))
+    } else {
+        let scaled_width = ((width as f64 / height as f64) * max_size as f64).round() as u32;
+        (scaled_width.max(1), max_size)
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -289,8 +301,8 @@ mod tests {
         assert_eq!((decoded.width(), decoded.height()), (400, 300));
 
         // Cover mode: shortest side (1200) must stay >= 224 -> numerator 2
-        let covered = decode_jpeg_scaled(&src_path, 224, true)
-            .expect("fast path should handle plain JPEG");
+        let covered =
+            decode_jpeg_scaled(&src_path, 224, true).expect("fast path should handle plain JPEG");
         assert_eq!((covered.width(), covered.height()), (400, 300));
 
         let cache = dir.join("cache");
@@ -302,17 +314,3 @@ mod tests {
         assert_eq!((thumb_w, thumb_h), (320, 240));
     }
 }
-
-fn fit_dimensions(width: u32, height: u32, max_size: u32) -> (u32, u32) {
-    if width <= max_size && height <= max_size {
-        return (width.max(1), height.max(1));
-    }
-
-    if width >= height {
-        let scaled_height = ((height as f64 / width as f64) * max_size as f64).round() as u32;
-        (max_size, scaled_height.max(1))
-    } else {
-        let scaled_width = ((width as f64 / height as f64) * max_size as f64).round() as u32;
-        (scaled_width.max(1), max_size)
-    }
-}

src-tauri/src/vector.rs

@@ -10,7 +10,14 @@ static SQLITE_VEC_INIT: Once = Once::new();
 
 pub fn register_sqlite_vec() {
     SQLITE_VEC_INIT.call_once(|| unsafe {
-        sqlite3_auto_extension(Some(std::mem::transmute(sqlite3_vec_init as *const ())));
+        sqlite3_auto_extension(Some(std::mem::transmute::<
+            *const (),
+            unsafe extern "C" fn(
+                *mut rusqlite::ffi::sqlite3,
+                *mut *mut std::os::raw::c_char,
+                *const rusqlite::ffi::sqlite3_api_routines,
+            ) -> i32,
+        >(sqlite3_vec_init as *const ())));
     });
 }
 
@@ -18,14 +25,13 @@ pub fn migrate(conn: &Connection) -> Result<()> {
     conn.execute_batch(&format!(
         "CREATE VIRTUAL TABLE IF NOT EXISTS image_vec USING vec0(
             image_id INTEGER PRIMARY KEY,
-            embedding FLOAT[{}] distance_metric=cosine
+            embedding FLOAT[{CLIP_VECTOR_DIM}] distance_metric=cosine
         );
 
         CREATE VIRTUAL TABLE IF NOT EXISTS caption_vec USING vec0(
             image_id INTEGER PRIMARY KEY,
-            embedding FLOAT[{}] distance_metric=cosine
-        );",
-        CLIP_VECTOR_DIM, CLIP_VECTOR_DIM
+            embedding FLOAT[{CLIP_VECTOR_DIM}] distance_metric=cosine
+        );"
     ))?;
     Ok(())
 }
@@ -465,7 +471,7 @@ pub fn has_image_vector(conn: &Connection, image_id: i64) -> Result<bool> {
 
 #[allow(dead_code)]
 fn pack_f32(values: &[f32]) -> Vec<u8> {
-    let mut out = Vec::with_capacity(values.len() * std::mem::size_of::<f32>());
+    let mut out = Vec::with_capacity(std::mem::size_of_val(values));
     for value in values {
         out.extend_from_slice(&value.to_le_bytes());
     }

src-tauri/tauri.conf.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://schema.tauri.app/config/2",
   "productName": "Phokus",
-  "version": "0.1.0",
+  "version": null,
   "identifier": "wtf.jezz.phokus",
   "build": {
     "beforeDevCommand": "pnpm dev:vite",
@@ -22,18 +22,34 @@
       }
     ],
     "security": {
-      "csp": null,
+      "csp": "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' asset: http://asset.localhost data: blob:; media-src 'self' asset: http://asset.localhost; connect-src 'self' ipc: http://ipc.localhost; font-src 'self' data:; object-src 'none'",
+      "devCsp": "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' asset: http://asset.localhost data: blob:; media-src 'self' asset: http://asset.localhost; connect-src 'self' ipc: http://ipc.localhost ws://localhost:1420 http://localhost:1420; font-src 'self' data:; object-src 'none'",
       "assetProtocol": {
         "enable": true,
         "scope": [
-          "**"
+          "$APPDATA/thumbnails/**"
         ]
       }
     }
   },
+  "plugins": {
+    "updater": {
+      "pubkey": "dW50cnVzdGVkIGNvbW1lbnQ6IG1pbmlzaWduIHB1YmxpYyBrZXk6IDYyMDVBQzkyOENENjYzOTUKUldTVlk5YU1rcXdGWW9JRklYdHpOVXA1MDNMVEpyell6cVlma0VGS3pYaUVBLzJydy9nNUtJdlUK",
+      "endpoints": [
+        "https://github.com/JezzWTF/phokus/releases/latest/download/latest.json"
+      ]
+    }
+  },
   "bundle": {
     "active": true,
-    "targets": "all",
+    "targets": ["nsis"],
+    "createUpdaterArtifacts": true,
+    "publisher": "JezzWTF",
+    "license": "MIT",
+    "copyright": "Copyright © 2026 JezzWTF",
+    "shortDescription": "Local-first desktop media library",
+    "longDescription": "A local-first desktop media library for browsing, filtering, and curating image and video folders, with AI tagging, semantic search, and duplicate detection — all processed on-device.",
+    "homepage": "https://git.jezz.wtf/jezzwtf/phokus",
     "icon": [
       "icons/32x32.png",
       "icons/128x128.png",

src-tauri/tauri.cuda.conf.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://schema.tauri.app/config/2",
+  "plugins": {
+    "updater": {
+      "endpoints": [
+        "https://github.com/JezzWTF/phokus/releases/latest/download/latest-cuda.json"
+      ]
+    }
+  },
+  "bundle": {
+    "windows": {
+      "nsis": {
+        "installerHooks": "./windows/cuda-hooks.nsh"
+      }
+    }
+  }
+}

src-tauri/windows/cuda-hooks.nsh

@@ -0,0 +1,35 @@
+; NSIS hooks for the CUDA build variant.
+;
+; The CUDA exe load-time-imports the CUDA runtime DLLs, so they must sit next
+; to phokus.exe ($INSTDIR) where the Windows loader searches. Rather than
+; bundling them as Tauri "resources" (which land in $INSTDIR\resources\) and
+; then relocating them — a move that proved unreliable in the elevated/silent
+; installer (CopyFiles via SHFileOperation, and even Rename, failed) — we embed
+; them directly into the installer with NSIS `File` and extract them straight
+; to $INSTDIR. `File` is the standard, reliable install primitive.
+;
+; This hook is !included from its original location, and ${__FILEDIR__} in this
+; top-level !define expands at *include* time to this file's own directory,
+; src-tauri\windows. cuda-redist is its sibling under src-tauri, so one level
+; up. (Caveat that bit us: ${__FILEDIR__} used inline *inside the macro* would
+; instead expand at insertion time to Tauri's generated nsis dir — hence the
+; !define here.) The 4 DLLs must be present in src-tauri\cuda-redist at build
+; time (see RELEASE_PLAN.md).
+
+!define CUDA_REDIST "${__FILEDIR__}\..\cuda-redist"
+
+!macro NSIS_HOOK_POSTINSTALL
+  DetailPrint "Phokus: installing bundled CUDA runtime libraries..."
+  SetOutPath "$INSTDIR"
+  File "${CUDA_REDIST}\cudart64_12.dll"
+  File "${CUDA_REDIST}\cublas64_12.dll"
+  File "${CUDA_REDIST}\cublasLt64_12.dll"
+  File "${CUDA_REDIST}\curand64_10.dll"
+!macroend
+
+!macro NSIS_HOOK_POSTUNINSTALL
+  Delete "$INSTDIR\cudart64_12.dll"
+  Delete "$INSTDIR\cublas64_12.dll"
+  Delete "$INSTDIR\cublasLt64_12.dll"
+  Delete "$INSTDIR\curand64_10.dll"
+!macroend

src/App.tsx

@@ -10,6 +10,9 @@ import { DuplicateFinder } from "./components/DuplicateFinder";
 import { Timeline } from "./components/Timeline";
 import { TitleBar } from "./components/TitleBar";
 import { SettingsModal } from "./components/SettingsModal";
+import { UpdateToast } from "./components/UpdateToast";
+import { OnboardingOverlay } from "./components/onboarding/OnboardingOverlay";
+import { DemoPanel } from "./components/DemoPanel";
 import { initializeNotifications } from "./notifications";
 
 export default function App() {
@@ -21,12 +24,23 @@ export default function App() {
   const loadMutedFolderIds = useGalleryStore((state) => state.loadMutedFolderIds);
   const loadNotificationsPaused = useGalleryStore((state) => state.loadNotificationsPaused);
   const subscribeToProgress = useGalleryStore((state) => state.subscribeToProgress);
+  const loadAppVersion = useGalleryStore((state) => state.loadAppVersion);
+  const checkForUpdates = useGalleryStore((state) => state.checkForUpdates);
+  const loadFfmpegStatus = useGalleryStore((state) => state.loadFfmpegStatus);
+  const loadOnboardingCompleted = useGalleryStore((state) => state.loadOnboardingCompleted);
   const activeView = useGalleryStore((state) => state.activeView);
 
   useEffect(() => {
     void initializeNotifications();
     void loadMutedFolderIds();
     void loadNotificationsPaused();
+    void loadAppVersion();
+    void loadFfmpegStatus();
+    void loadOnboardingCompleted();
+    // Quiet launch check — dev builds have no signed artifacts to update to.
+    if (import.meta.env.PROD) {
+      void checkForUpdates({ quiet: true });
+    }
     loadFolders().then(() => {
       void loadBackgroundJobProgress();
       void loadCaptionModelStatus();
@@ -79,6 +93,9 @@ export default function App() {
 
       <Lightbox />
       <SettingsModal />
+      <UpdateToast />
+      <OnboardingOverlay />
+      {import.meta.env.DEV && <DemoPanel />}
     </div>
   );
 }

src/assets/react.svg

@@ -1 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" class="iconify iconify--logos" width="35.93" height="32" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 228"><path fill="#00D8FF" d="M210.483 73.824a171.49 171.49 0 0 0-8.24-2.597c.465-1.9.893-3.777 1.273-5.621c6.238-30.281 2.16-54.676-11.769-62.708c-13.355-7.7-35.196.329-57.254 19.526a171.23 171.23 0 0 0-6.375 5.848a155.866 155.866 0 0 0-4.241-3.917C100.759 3.829 77.587-4.822 63.673 3.233C50.33 10.957 46.379 33.89 51.995 62.588a170.974 170.974 0 0 0 1.892 8.48c-3.28.932-6.445 1.924-9.474 2.98C17.309 83.498 0 98.307 0 113.668c0 15.865 18.582 31.778 46.812 41.427a145.52 145.52 0 0 0 6.921 2.165a167.467 167.467 0 0 0-2.01 9.138c-5.354 28.2-1.173 50.591 12.134 58.266c13.744 7.926 36.812-.22 59.273-19.855a145.567 145.567 0 0 0 5.342-4.923a168.064 168.064 0 0 0 6.92 6.314c21.758 18.722 43.246 26.282 56.54 18.586c13.731-7.949 18.194-32.003 12.4-61.268a145.016 145.016 0 0 0-1.535-6.842c1.62-.48 3.21-.974 4.76-1.488c29.348-9.723 48.443-25.443 48.443-41.52c0-15.417-17.868-30.326-45.517-39.844Zm-6.365 70.984c-1.4.463-2.836.91-4.3 1.345c-3.24-10.257-7.612-21.163-12.963-32.432c5.106-11 9.31-21.767 12.459-31.957c2.619.758 5.16 1.557 7.61 2.4c23.69 8.156 38.14 20.213 38.14 29.504c0 9.896-15.606 22.743-40.946 31.14Zm-10.514 20.834c2.562 12.94 2.927 24.64 1.23 33.787c-1.524 8.219-4.59 13.698-8.382 15.893c-8.067 4.67-25.32-1.4-43.927-17.412a156.726 156.726 0 0 1-6.437-5.87c7.214-7.889 14.423-17.06 21.459-27.246c12.376-1.098 24.068-2.894 34.671-5.345a134.17 134.17 0 0 1 1.386 6.193ZM87.276 214.515c-7.882 2.783-14.16 2.863-17.955.675c-8.075-4.657-11.432-22.636-6.853-46.752a156.923 156.923 0 0 1 1.869-8.499c10.486 2.32 22.093 3.988 34.498 4.994c7.084 9.967 14.501 19.128 21.976 27.15a134.668 134.668 0 0 1-4.877 4.492c-9.933 8.682-19.886 14.842-28.658 17.94ZM50.35 144.747c-12.483-4.267-22.792-9.812-29.858-15.863c-6.35-5.437-9.555-10.836-9.555-15.216c0-9.322 13.897-21.212 37.076-29.293c2.813-.98 5.757-1.905 8.812-2.773c3.204 10.42 7.406 21.315 12.477 32.332c-5.137 11.18-9.399 22.249-12.634 32.792a134.718 134.718 0 0 1-6.318-1.979Zm12.378-84.26c-4.811-24.587-1.616-43.134 6.425-47.789c8.564-4.958 27.502 2.111 47.463 19.835a144.318 144.318 0 0 1 3.841 3.545c-7.438 7.987-14.787 17.08-21.808 26.988c-12.04 1.116-23.565 2.908-34.161 5.309a160.342 160.342 0 0 1-1.76-7.887Zm110.427 27.268a347.8 347.8 0 0 0-7.785-12.803c8.168 1.033 15.994 2.404 23.343 4.08c-2.206 7.072-4.956 14.465-8.193 22.045a381.151 381.151 0 0 0-7.365-13.322Zm-45.032-43.861c5.044 5.465 10.096 11.566 15.065 18.186a322.04 322.04 0 0 0-30.257-.006c4.974-6.559 10.069-12.652 15.192-18.18ZM82.802 87.83a323.167 323.167 0 0 0-7.227 13.238c-3.184-7.553-5.909-14.98-8.134-22.152c7.304-1.634 15.093-2.97 23.209-3.984a321.524 321.524 0 0 0-7.848 12.897Zm8.081 65.352c-8.385-.936-16.291-2.203-23.593-3.793c2.26-7.3 5.045-14.885 8.298-22.6a321.187 321.187 0 0 0 7.257 13.246c2.594 4.48 5.28 8.868 8.038 13.147Zm37.542 31.03c-5.184-5.592-10.354-11.779-15.403-18.433c4.902.192 9.899.29 14.978.29c5.218 0 10.376-.117 15.453-.343c-4.985 6.774-10.018 12.97-15.028 18.486Zm52.198-57.817c3.422 7.8 6.306 15.345 8.596 22.52c-7.422 1.694-15.436 3.058-23.88 4.071a382.417 382.417 0 0 0 7.859-13.026a347.403 347.403 0 0 0 7.425-13.565Zm-16.898 8.101a358.557 358.557 0 0 1-12.281 19.815a329.4 329.4 0 0 1-23.444.823c-7.967 0-15.716-.248-23.178-.732a310.202 310.202 0 0 1-12.513-19.846h.001a307.41 307.41 0 0 1-10.923-20.627a310.278 310.278 0 0 1 10.89-20.637l-.001.001a307.318 307.318 0 0 1 12.413-19.761c7.613-.576 15.42-.876 23.31-.876H128c7.926 0 15.743.303 23.354.883a329.357 329.357 0 0 1 12.335 19.695a358.489 358.489 0 0 1 11.036 20.54a329.472 329.472 0 0 1-11 20.722Zm22.56-122.124c8.572 4.944 11.906 24.881 6.52 51.026c-.344 1.668-.73 3.367-1.15 5.09c-10.622-2.452-22.155-4.275-34.23-5.408c-7.034-10.017-14.323-19.124-21.64-27.008a160.789 160.789 0 0 1 5.888-5.4c18.9-16.447 36.564-22.941 44.612-18.3ZM128 90.808c12.625 0 22.86 10.235 22.86 22.86s-10.235 22.86-22.86 22.86s-22.86-10.235-22.86-22.86s10.235-22.86 22.86-22.86Z"></path></svg>

src/components/BackgroundTasks.tsx

@@ -1,8 +1,6 @@
 import { useEffect, useMemo, useState } from "react";
 import { invoke } from "@tauri-apps/api/core";
-import { useGalleryStore } from "../store";
-
-type WorkerKey = "thumbnail" | "metadata" | "embedding" | "tagging";
+import { useGalleryStore, WorkerKey } from "../store";
 
 const WORKER_FOR_STAGE: Record<string, WorkerKey> = {
   Thumbnails: "thumbnail",
@@ -38,21 +36,6 @@ interface FailedEmbeddingItem {
   error: string | null;
 }
 
-interface FolderWorkerStates {
-  folder_id: number;
-  thumbnail_paused: boolean;
-  metadata_paused: boolean;
-  embedding_paused: boolean;
-  tagging_paused: boolean;
-}
-
-const DEFAULT_PAUSED_STATE: Record<WorkerKey, boolean> = {
-  thumbnail: false,
-  metadata: false,
-  embedding: false,
-  tagging: false,
-};
-
 export function BackgroundTasks() {
   const folders = useGalleryStore((state) => state.folders);
   const indexingProgress = useGalleryStore((state) => state.indexingProgress);
@@ -63,32 +46,15 @@ export function BackgroundTasks() {
   const duplicateScanProgress = useGalleryStore((state) => state.duplicateScanProgress);
   const [expanded, setExpanded] = useState(false);
   const [dismissed, setDismissed] = useState<Record<number, string>>({});
-  const [paused, setPaused] = useState<Record<number, Record<WorkerKey, boolean>>>({});
   const [failedItems, setFailedItems] = useState<Record<number, FailedEmbeddingItem[]>>({});
 
-  useEffect(() => {
-    const folderIds = folders.map((folder) => folder.id);
-    if (folderIds.length === 0) {
-      setPaused({});
-      return;
-    }
+  const workerPaused = useGalleryStore((state) => state.workerPaused);
+  const loadWorkerStates = useGalleryStore((state) => state.loadWorkerStates);
+  const setWorkerPaused = useGalleryStore((state) => state.setWorkerPaused);
 
-    invoke<FolderWorkerStates[]>("get_worker_states", { folderIds }).then((states) => {
-      setPaused(
-        Object.fromEntries(
-          states.map((state) => [
-            state.folder_id,
-            {
-              thumbnail: state.thumbnail_paused,
-              metadata: state.metadata_paused,
-              embedding: state.embedding_paused,
-              tagging: state.tagging_paused,
-            },
-          ]),
-        ),
-      );
-    });
-  }, [folders]);
+  useEffect(() => {
+    void loadWorkerStates();
+  }, [folders, loadWorkerStates]);
 
   // Fetch failed embedding filenames whenever the expanded panel opens or failure counts change.
   const failedCounts = useMemo(
@@ -113,20 +79,11 @@ export function BackgroundTasks() {
   }, [expanded, failedCounts]);
 
   const isWorkerPaused = (folderId: number, worker: WorkerKey) => {
-    return paused[folderId]?.[worker] ?? DEFAULT_PAUSED_STATE[worker];
+    return workerPaused[folderId]?.[worker] ?? false;
   };
 
   const toggleWorker = (folderId: number, worker: WorkerKey) => {
-    const next = !isWorkerPaused(folderId, worker);
-    setPaused((prev) => ({
-      ...prev,
-      [folderId]: {
-        ...DEFAULT_PAUSED_STATE,
-        ...prev[folderId],
-        [worker]: next,
-      },
-    }));
-    void invoke("set_worker_paused", { worker, folderId, paused: next });
+    setWorkerPaused(folderId, worker, !isWorkerPaused(folderId, worker));
   };
 
   const dismissTask = (id: number, snapshot: string) => {

src/components/DemoPanel.tsx

@@ -0,0 +1,220 @@
+import { useEffect, useRef, useState } from "react";
+import { FolderJobProgress, useGalleryStore } from "../store";
+
+// Dev-only screenshot/demo helper. Injects frozen UI states that are otherwise
+// too transient (or unreachable) to capture: the background-worker pipeline,
+// which drains in under a second, and the auto-updater flow, which never fires
+// locally because there's no remote latest.json to check against.
+// Gated by import.meta.env.DEV in App.tsx so the whole thing is tree-shaken out
+// of production builds.
+//
+// Toggle the controls with Ctrl+Shift+D. Injected state persists in the store
+// while the panel is hidden, so: open → inject → hide → screenshot.
+
+function emptyProgress(folderId: number): FolderJobProgress {
+  return {
+    folder_id: folderId,
+    thumbnail_pending: 0,
+    metadata_pending: 0,
+    embedding_pending: 0,
+    embedding_ready: 0,
+    embedding_failed: 0,
+    caption_pending: 0,
+    caption_ready: 0,
+    caption_failed: 0,
+    tagging_pending: 0,
+    tagging_ready: 0,
+    tagging_failed: 0,
+  };
+}
+
+// A believable multi-folder "busy pipeline" — three folders at different stages.
+const BUSY_PRESETS: Partial<FolderJobProgress>[] = [
+  // Embeddings actively running, tagging queued behind it.
+  { embedding_ready: 34, embedding_pending: 16, tagging_pending: 50 },
+  // Just started: thumbnails draining, everything else queued.
+  { thumbnail_pending: 11, embedding_pending: 50, tagging_pending: 50 },
+  // Late stage: embeddings done, tagging running.
+  { embedding_ready: 40, tagging_ready: 18, tagging_pending: 22 },
+];
+
+const DEMO_UPDATE_VERSION = "0.2.0";
+
+export function DemoPanel() {
+  const folders = useGalleryStore((state) => state.folders);
+  const [open, setOpen] = useState(false);
+  const downloadTimer = useRef<number | null>(null);
+
+  useEffect(() => {
+    const onKey = (event: KeyboardEvent) => {
+      if (event.ctrlKey && event.shiftKey && event.key.toLowerCase() === "d") {
+        event.preventDefault();
+        setOpen((value) => !value);
+      }
+    };
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, []);
+
+  const stopTimer = () => {
+    if (downloadTimer.current !== null) {
+      window.clearInterval(downloadTimer.current);
+      downloadTimer.current = null;
+    }
+  };
+
+  // Stop any running download animation when the panel unmounts.
+  useEffect(() => stopTimer, []);
+
+  const injectBusy = () => {
+    const progress: Record<number, FolderJobProgress> = {};
+    folders.slice(0, BUSY_PRESETS.length).forEach((folder, index) => {
+      progress[folder.id] = { ...emptyProgress(folder.id), ...BUSY_PRESETS[index] };
+    });
+    useGalleryStore.setState({ mediaJobProgress: progress });
+  };
+
+  const injectSingleEmbedding = () => {
+    const folder = folders[0];
+    if (!folder) return;
+    useGalleryStore.setState({
+      mediaJobProgress: {
+        [folder.id]: { ...emptyProgress(folder.id), embedding_ready: 27, embedding_pending: 23 },
+      },
+    });
+  };
+
+  const clear = () => useGalleryStore.setState({ mediaJobProgress: {} });
+
+  // --- Updater flow ---------------------------------------------------------
+  // These drive the real UpdateToast + Settings "About" row. The Install button
+  // stays inert (there's no real pendingUpdate), so this validates the
+  // presentation only — see DemoPanel's header note for the real e2e path.
+
+  const updateAvailable = () => {
+    stopTimer();
+    useGalleryStore.setState({
+      updateStatus: "available",
+      updateVersion: DEMO_UPDATE_VERSION,
+      updateProgress: null,
+      updateError: null,
+      updateDismissed: false,
+    });
+  };
+
+  // Indeterminate pulse, then climb 0 → 100%, then flip to "installing".
+  const simulateDownload = () => {
+    stopTimer();
+    useGalleryStore.setState({
+      updateStatus: "downloading",
+      updateVersion: DEMO_UPDATE_VERSION,
+      updateProgress: null,
+      updateError: null,
+      updateDismissed: false,
+    });
+    let progress = 0;
+    window.setTimeout(() => {
+      downloadTimer.current = window.setInterval(() => {
+        progress = Math.min(progress + 0.07, 1);
+        useGalleryStore.setState({ updateProgress: progress });
+        if (progress >= 1) {
+          stopTimer();
+          useGalleryStore.setState({ updateStatus: "installing" });
+        }
+      }, 200);
+    }, 700);
+  };
+
+  const updateInstalling = () => {
+    stopTimer();
+    useGalleryStore.setState({
+      updateStatus: "installing",
+      updateVersion: DEMO_UPDATE_VERSION,
+      updateProgress: 1,
+      updateDismissed: false,
+    });
+  };
+
+  const updateError = () => {
+    stopTimer();
+    useGalleryStore.setState({
+      updateStatus: "error",
+      updateError: "Could not reach the update server (connection timed out).",
+      updateDismissed: false,
+    });
+  };
+
+  const updateUpToDate = () => {
+    stopTimer();
+    useGalleryStore.setState({ updateStatus: "upToDate", updateVersion: null, updateError: null });
+  };
+
+  const resetUpdate = () => {
+    stopTimer();
+    useGalleryStore.setState({
+      updateStatus: "idle",
+      updateVersion: null,
+      updateProgress: null,
+      updateError: null,
+      updateDismissed: false,
+    });
+  };
+
+  if (!open) return null;
+
+  const injectBtn =
+    "rounded-md border border-amber-400/30 bg-amber-500/15 px-2 py-1.5 text-left hover:bg-amber-500/25";
+  const neutralBtn =
+    "rounded-md border border-white/10 bg-white/[0.06] px-2 py-1.5 text-left text-gray-300 hover:bg-white/10";
+
+  return (
+    <div className="fixed bottom-4 left-4 z-[100] max-h-[calc(100vh-2rem)] w-56 overflow-y-auto rounded-lg border border-amber-400/40 bg-amber-950/90 p-3 text-xs text-amber-100 shadow-xl backdrop-blur">
+      <div className="mb-2 flex items-center justify-between">
+        <span className="font-semibold uppercase tracking-wide">Demo · Ctrl+Shift+D</span>
+      </div>
+
+      <p className="mb-1.5 text-[11px] font-semibold uppercase tracking-wide text-amber-200/60">Pipeline</p>
+      <p className="mb-2 text-[11px] leading-snug text-amber-200/70">
+        Inject a frozen worker-bar state, hide this panel, then screenshot.
+      </p>
+      <div className="flex flex-col gap-1.5">
+        <button className={injectBtn} onClick={injectBusy}>
+          Pipeline: busy (3 folders)
+        </button>
+        <button className={injectBtn} onClick={injectSingleEmbedding}>
+          Pipeline: embedding (1 folder)
+        </button>
+        <button className={neutralBtn} onClick={clear}>
+          Clear injected state
+        </button>
+      </div>
+
+      <div className="my-3 h-px bg-amber-400/20" />
+
+      <p className="mb-1.5 text-[11px] font-semibold uppercase tracking-wide text-amber-200/60">Update flow</p>
+      <p className="mb-2 text-[11px] leading-snug text-amber-200/70">
+        Drives the real toast (bottom-right) + Settings → About row. Install is inert here.
+      </p>
+      <div className="flex flex-col gap-1.5">
+        <button className={injectBtn} onClick={updateAvailable}>
+          Update available
+        </button>
+        <button className={injectBtn} onClick={simulateDownload}>
+          Simulate download → install
+        </button>
+        <button className={injectBtn} onClick={updateInstalling}>
+          Installing
+        </button>
+        <button className={injectBtn} onClick={updateError}>
+          Check failed (error)
+        </button>
+        <button className={injectBtn} onClick={updateUpToDate}>
+          Up to date
+        </button>
+        <button className={neutralBtn} onClick={resetUpdate}>
+          Reset updater state
+        </button>
+      </div>
+    </div>
+  );
+}

src/components/Lightbox.tsx

@@ -115,6 +115,29 @@ function rectToNormalisedCrop(
 /** Minimum selection size as a fraction of the viewport container dimension. */
 const MIN_SELECTION_FRACTION = 0.02;
 
+const MIN_ZOOM = 0.5;
+const MAX_ZOOM = 4;
+
+interface ViewTransform {
+  zoom: number;
+  panX: number;
+  panY: number;
+}
+
+const IDENTITY_VIEW: ViewTransform = { zoom: 1, panX: 0, panY: 0 };
+
+/** Re-anchor the pan so the point at (anchorX, anchorY) — measured from the
+ *  viewport centre — stays under the cursor across a zoom change. */
+function zoomViewAt(view: ViewTransform, newZoom: number, anchorX: number, anchorY: number): ViewTransform {
+  if (newZoom <= 1) return { ...IDENTITY_VIEW, zoom: newZoom };
+  const ratio = newZoom / view.zoom;
+  return {
+    zoom: newZoom,
+    panX: anchorX - (anchorX - view.panX) * ratio,
+    panY: anchorY - (anchorY - view.panY) * ratio,
+  };
+}
+
 export function Lightbox() {
   const selectedImage = useGalleryStore((state) => state.selectedImage);
   const closeImage = useGalleryStore((state) => state.closeImage);
@@ -135,7 +158,10 @@ export function Lightbox() {
   const currentImageIdRef = useRef<number | null>(null);
   currentImageIdRef.current = selectedImage?.id ?? null;
 
-  const [zoom, setZoom] = useState(1);
+  const [view, setView] = useState<ViewTransform>(IDENTITY_VIEW);
+  const zoom = view.zoom;
+  const [isPanning, setIsPanning] = useState(false);
+  const lastPanPointRef = useRef({ x: 0, y: 0 });
   const [imageTags, setImageTags] = useState<ImageTag[]>([]);
   const [tagInput, setTagInput] = useState("");
   const [tagAdding, setTagAdding] = useState(false);
@@ -169,8 +195,24 @@ export function Lightbox() {
     setDragRect(null);
   }, []);
 
+  // Keep the pan within bounds: when the scaled image overflows the viewport
+  // the image edge may not be dragged past the viewport edge; when it fits,
+  // the pan snaps back to centre on that axis.
+  const clampPan = useCallback((v: ViewTransform): ViewTransform => {
+    const img = imgRef.current;
+    const vp = imageViewportRef.current;
+    if (!img || !vp) return v;
+    const maxX = Math.max(0, (img.offsetWidth * v.zoom - vp.clientWidth) / 2);
+    const maxY = Math.max(0, (img.offsetHeight * v.zoom - vp.clientHeight) / 2);
+    return {
+      ...v,
+      panX: Math.min(maxX, Math.max(-maxX, v.panX)),
+      panY: Math.min(maxY, Math.max(-maxY, v.panY)),
+    };
+  }, []);
+
   useEffect(() => {
-    setZoom(1);
+    setView(IDENTITY_VIEW);
     setImageTags([]);
     setTagInput("");
     setTagsExpanded(false);
@@ -203,15 +245,19 @@ export function Lightbox() {
       if (regionSelectMode) return; // don't zoom during selection
       if (!event.ctrlKey && Math.abs(event.deltaY) < Math.abs(event.deltaX)) return;
       event.preventDefault();
-      setZoom((value) => {
+      const bounds = viewport.getBoundingClientRect();
+      const anchorX = event.clientX - (bounds.left + bounds.width / 2);
+      const anchorY = event.clientY - (bounds.top + bounds.height / 2);
+      setView((v) => {
         const delta = event.deltaY < 0 ? 0.15 : -0.15;
-        return Math.min(4, Math.max(0.5, value + delta));
+        const next = Math.min(MAX_ZOOM, Math.max(MIN_ZOOM, v.zoom + delta));
+        return clampPan(zoomViewAt(v, next, anchorX, anchorY));
       });
     };
 
     viewport.addEventListener("wheel", handleWheel, { passive: false });
     return () => viewport.removeEventListener("wheel", handleWheel);
-  }, [selectedImage, regionSelectMode]);
+  }, [selectedImage, regionSelectMode, clampPan]);
 
   useEffect(() => {
     const handler = (event: KeyboardEvent) => {
@@ -227,18 +273,29 @@ export function Lightbox() {
       // Shift+arrows are reserved for video seeking (handled by VideoPlayer)
       if (event.key === "ArrowLeft" && !event.shiftKey) goPrev();
       if (event.key === "ArrowRight" && !event.shiftKey) goNext();
-      if (event.key === "+" || event.key === "=") setZoom((value) => Math.min(3, value + 0.25));
-      if (event.key === "-") setZoom((value) => Math.max(0.75, value - 0.25));
+      if (event.key === "+" || event.key === "=")
+        setView((v) => clampPan(zoomViewAt(v, Math.min(3, v.zoom + 0.25), 0, 0)));
+      if (event.key === "-")
+        setView((v) => clampPan(zoomViewAt(v, Math.max(0.75, v.zoom - 0.25), 0, 0)));
     };
 
     window.addEventListener("keydown", handler);
     return () => window.removeEventListener("keydown", handler);
-  }, [selectedImage, closeImage, goPrev, goNext, regionSelectMode, exitRegionMode]);
+  }, [selectedImage, closeImage, goPrev, goNext, regionSelectMode, exitRegionMode, clampPan]);
 
-  // ── Region selection pointer handlers ───────────────────────────────────────
+  // ── Region selection / pan pointer handlers ─────────────────────────────────
   const handleRegionPointerDown = useCallback(
     (event: React.PointerEvent<HTMLDivElement>) => {
-      if (!regionSelectMode) return;
+      if (!regionSelectMode) {
+        // Drag-to-pan when the image is zoomed in
+        if (zoom > 1 && event.button === 0 && selectedImage?.media_kind === "image") {
+          event.preventDefault();
+          event.currentTarget.setPointerCapture(event.pointerId);
+          lastPanPointRef.current = { x: event.clientX, y: event.clientY };
+          setIsPanning(true);
+        }
+        return;
+      }
       event.preventDefault();
       event.currentTarget.setPointerCapture(event.pointerId);
       setIsDragging(true);
@@ -249,21 +306,33 @@ export function Lightbox() {
         endY: event.clientY,
       });
     },
-    [regionSelectMode],
+    [regionSelectMode, zoom, selectedImage?.media_kind],
   );
 
   const handleRegionPointerMove = useCallback(
     (event: React.PointerEvent<HTMLDivElement>) => {
+      if (isPanning) {
+        const dx = event.clientX - lastPanPointRef.current.x;
+        const dy = event.clientY - lastPanPointRef.current.y;
+        lastPanPointRef.current = { x: event.clientX, y: event.clientY };
+        setView((v) => clampPan({ ...v, panX: v.panX + dx, panY: v.panY + dy }));
+        return;
+      }
       if (!isDragging) return;
       setDragRect((prev) =>
         prev ? { ...prev, endX: event.clientX, endY: event.clientY } : null,
       );
     },
-    [isDragging],
+    [isDragging, isPanning, clampPan],
   );
 
   const handleRegionPointerUp = useCallback(
     (event: React.PointerEvent<HTMLDivElement>) => {
+      if (isPanning) {
+        event.currentTarget.releasePointerCapture(event.pointerId);
+        setIsPanning(false);
+        return;
+      }
       if (!isDragging || !dragRect || !selectedImage || !imgRef.current) {
         setIsDragging(false);
         return;
@@ -296,7 +365,7 @@ export function Lightbox() {
       void loadSimilarByRegion(selectedImage.id, crop, folderId, selectedImage.folder_id)
         .finally(() => setRegionSearching(false));
     },
-    [isDragging, dragRect, selectedImage, similarScope, loadSimilarByRegion, exitRegionMode],
+    [isPanning, isDragging, dragRect, selectedImage, similarScope, loadSimilarByRegion, exitRegionMode],
   );
 
   // Build the CSS rect for the selection overlay (viewport-relative)
@@ -332,8 +401,14 @@ export function Lightbox() {
             <div className="flex flex-1 overflow-hidden">
               <div
                 ref={imageViewportRef}
-                className={`group relative flex flex-1 items-center justify-center overflow-auto p-10 ${
-                  regionSelectMode ? "cursor-crosshair select-none" : ""
+                className={`group relative flex flex-1 items-center justify-center overflow-hidden p-10 ${
+                  regionSelectMode
+                    ? "cursor-crosshair select-none"
+                    : isPanning
+                    ? "cursor-grabbing select-none"
+                    : zoom > 1 && selectedImage.media_kind === "image"
+                    ? "cursor-grab"
+                    : ""
                 }`}
                 onPointerDown={handleRegionPointerDown}
                 onPointerMove={handleRegionPointerMove}
@@ -386,9 +461,10 @@ export function Lightbox() {
                           src={convertFileSrc(selectedImage.path)}
                           alt={selectedImage.filename}
                           className="max-w-full rounded-2xl shadow-2xl"
+                          draggable={false}
                           style={{
                             maxHeight: "calc(100vh - 10rem)",
-                            transform: `scale(${zoom})`,
+                            transform: `translate(${view.panX}px, ${view.panY}px) scale(${zoom})`,
                             transformOrigin: "center center",
                             // Slightly dim the image while in region select mode
                             ...(regionSelectMode ? { opacity: 0.85 } : {}),
@@ -399,14 +475,14 @@ export function Lightbox() {
                             <div className="pointer-events-auto flex items-center gap-1 rounded-full border border-white/10 bg-black/55 px-2 py-1 backdrop-blur">
                               <button
                                 className="px-2 text-sm text-gray-300 hover:text-white"
-                                onClick={() => setZoom((value) => Math.max(0.5, value - 0.25))}
+                                onClick={() => setView((v) => clampPan(zoomViewAt(v, Math.max(MIN_ZOOM, v.zoom - 0.25), 0, 0)))}
                               >
                                 -
                               </button>
                               <span className="min-w-14 text-center text-xs text-gray-300">{Math.round(zoom * 100)}%</span>
                               <button
                                 className="px-2 text-sm text-gray-300 hover:text-white"
-                                onClick={() => setZoom((value) => Math.min(4, value + 0.25))}
+                                onClick={() => setView((v) => clampPan(zoomViewAt(v, Math.min(MAX_ZOOM, v.zoom + 0.25), 0, 0)))}
                               >
                                 +
                               </button>

src/components/PhokusMark.tsx

@@ -0,0 +1,39 @@
+// Phokus brand mark — a camera iris, rendered inline so it inherits `currentColor`
+// and scales to any size. Drive color + dimensions from the className, e.g.
+//   <PhokusMark className="h-4 w-4 text-gray-300" />
+// The full app-icon tile (filled iris on a dark rounded square) lives in
+// branding/phokus-aperture.svg and feeds `pnpm tauri icon`.
+//
+// Pass dotClassName (e.g. "fill-amber-400") to light up the central focal point —
+// used in the titlebar as the "update available" indicator.
+const BLADE = "M0,-4.18 A10,10 0 0 1 6.43,-7.66";
+
+export function PhokusMark({
+  className,
+  dotClassName,
+}: {
+  className?: string;
+  dotClassName?: string;
+}) {
+  return (
+    <svg viewBox="0 0 24 24" fill="none" className={className}>
+      <g
+        transform="translate(12 12)"
+        stroke="currentColor"
+        strokeWidth="1.5"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      >
+        <circle r="10" />
+        <path d="M0,-4.18 A4.73,4.73 0 0 0 3.62,-2.09 A4.73,4.73 0 0 0 3.62,2.09 A4.73,4.73 0 0 0 0,4.18 A4.73,4.73 0 0 0 -3.62,2.09 A4.73,4.73 0 0 0 -3.62,-2.09 A4.73,4.73 0 0 0 0,-4.18 Z" />
+        <path d={BLADE} />
+        <path d={BLADE} transform="rotate(60)" />
+        <path d={BLADE} transform="rotate(120)" />
+        <path d={BLADE} transform="rotate(180)" />
+        <path d={BLADE} transform="rotate(240)" />
+        <path d={BLADE} transform="rotate(300)" />
+      </g>
+      {dotClassName ? <circle cx="12" cy="12" r="2.6" stroke="none" className={dotClassName} /> : null}
+    </svg>
+  );
+}

src/components/SettingsModal.tsx

@@ -1,5 +1,6 @@
 import { useEffect, useMemo, useRef, useState } from "react";
 import { CleanupOrphanedThumbnailsResult, DatabaseInfo, OrphanedThumbnailsInfo, TaggerAcceleration, TaggingQueueScope, VacuumResult, useGalleryStore } from "../store";
+import { FfmpegStatusRow } from "./onboarding/StepWelcome";
 
 type SettingsSection = "workspace" | "general";
 
@@ -8,6 +9,12 @@ const SECTIONS: { id: SettingsSection; label: string; detail: string }[] = [
   { id: "general", label: "General", detail: "App data and diagnostics" },
 ];
 
+function formatBytesShort(bytes: number): string {
+  if (bytes >= 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024 * 1024)).toFixed(1)} GB`;
+  if (bytes >= 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(0)} MB`;
+  return `${(bytes / 1024).toFixed(0)} KB`;
+}
+
 function StatusPill({ children, tone }: { children: React.ReactNode; tone: "ready" | "muted" | "busy" }) {
   const className =
     tone === "ready"
@@ -178,6 +185,13 @@ export function SettingsModal() {
   const vacuumDatabase = useGalleryStore((state) => state.vacuumDatabase);
   const getOrphanedThumbnailsInfo = useGalleryStore((state) => state.getOrphanedThumbnailsInfo);
   const cleanupOrphanedThumbnails = useGalleryStore((state) => state.cleanupOrphanedThumbnails);
+  const appVersion = useGalleryStore((state) => state.appVersion);
+  const updateStatus = useGalleryStore((state) => state.updateStatus);
+  const updateVersion = useGalleryStore((state) => state.updateVersion);
+  const updateError = useGalleryStore((state) => state.updateError);
+  const checkForUpdates = useGalleryStore((state) => state.checkForUpdates);
+  const installUpdate = useGalleryStore((state) => state.installUpdate);
+  const openOnboarding = useGalleryStore((state) => state.openOnboarding);
 
   useEffect(() => {
     if (!settingsOpen) return;
@@ -227,16 +241,24 @@ export function SettingsModal() {
         : "no folders selected";
   const thresholdDisplay = taggerThresholdDraft ?? String(taggerThreshold);
   const batchSizeDisplay = taggerBatchSizeDraft ?? String(taggerBatchSize);
-  const taggerDownloadLabel = taggerModelProgress
-    ? `Downloading ${taggerModelProgress.completed_files}/${taggerModelProgress.total_files}`
-    : taggerModelPreparing
-      ? "Preparing WD Tagger..."
-      : taggerReady
-        ? "Installed"
-        : "Install model";
-  const taggerDownloadPercent = taggerModelProgress
-    ? Math.round((taggerModelProgress.completed_files / Math.max(taggerModelProgress.total_files, 1)) * 100)
-    : 0;
+  const taggerBytesKnown =
+    taggerModelProgress?.downloaded_bytes != null &&
+    taggerModelProgress.total_bytes != null &&
+    taggerModelProgress.total_bytes > 0;
+  const taggerDownloadLabel = taggerBytesKnown
+    ? `Downloading ${formatBytesShort(taggerModelProgress!.downloaded_bytes!)} / ${formatBytesShort(taggerModelProgress!.total_bytes!)}`
+    : taggerModelProgress
+      ? `Downloading ${taggerModelProgress.completed_files}/${taggerModelProgress.total_files}`
+      : taggerModelPreparing
+        ? "Preparing WD Tagger..."
+        : taggerReady
+          ? "Installed"
+          : "Install model";
+  const taggerDownloadPercent = taggerBytesKnown
+    ? Math.round((taggerModelProgress!.downloaded_bytes! / taggerModelProgress!.total_bytes!) * 100)
+    : taggerModelProgress
+      ? Math.round((taggerModelProgress.completed_files / Math.max(taggerModelProgress.total_files, 1)) * 100)
+      : 0;
 
   const runQueueAction = (action: "queue" | "clear") => {
     const selectedIds = taggingQueueFolderIds;
@@ -578,6 +600,65 @@ export function SettingsModal() {
               </div>
             ) : (
               <div className="mt-8 space-y-9">
+                <SettingsGroup title="Updates">
+                  <SettingsItem
+                    label={
+                      <span className="inline-flex items-center gap-2.5">
+                        <span>Phokus {appVersion ? `v${appVersion}` : "—"}</span>
+                        {updateStatus === "available" || updateStatus === "downloading" || updateStatus === "installing" ? (
+                          <StatusPill tone="busy">v{updateVersion} available</StatusPill>
+                        ) : updateStatus === "upToDate" ? (
+                          <StatusPill tone="ready">Up to date</StatusPill>
+                        ) : null}
+                      </span>
+                    }
+                    description={
+                      updateStatus === "error" ? (
+                        <span className="text-amber-300/90">Update check failed: {updateError}</span>
+                      ) : updateStatus === "downloading" || updateStatus === "installing" ? (
+                        "Downloading update — the app will restart when it finishes."
+                      ) : (
+                        "Updates are checked quietly at launch and installed only when you choose."
+                      )
+                    }
+                  >
+                    {updateStatus === "available" ? (
+                      <button
+                        className="rounded-md border border-emerald-400/35 bg-emerald-500/15 px-3 py-1.5 text-xs text-emerald-200 transition-colors hover:bg-emerald-500/25"
+                        onClick={() => void installUpdate()}
+                      >
+                        Install &amp; restart
+                      </button>
+                    ) : (
+                      <button
+                        className="rounded-md border border-white/10 bg-white/[0.055] px-3 py-1.5 text-xs text-gray-300 transition-colors hover:bg-white/10 hover:text-white disabled:cursor-not-allowed disabled:opacity-45"
+                        onClick={() => void checkForUpdates()}
+                        disabled={updateStatus === "checking" || updateStatus === "downloading" || updateStatus === "installing"}
+                      >
+                        {updateStatus === "checking" ? "Checking..." : "Check for updates"}
+                      </button>
+                    )}
+                  </SettingsItem>
+                </SettingsGroup>
+
+                <SettingsGroup title="Setup">
+                  <FfmpegStatusRow />
+                  <SettingsItem
+                    label="Welcome tour"
+                    description="Replay the guided first-run tour — library setup, the background pipeline, search modes, and AI features."
+                  >
+                    <button
+                      className="rounded-md border border-white/10 bg-white/[0.055] px-3 py-1.5 text-xs text-gray-300 transition-colors hover:bg-white/10 hover:text-white"
+                      onClick={() => {
+                        setSettingsOpen(false);
+                        openOnboarding();
+                      }}
+                    >
+                      Show welcome tour
+                    </button>
+                  </SettingsItem>
+                </SettingsGroup>
+
                 <SettingsGroup title="Storage & notifications">
                   <SettingsItem
                     label="App data folder"

src/components/Sidebar.tsx

@@ -12,21 +12,25 @@ function FolderContextMenu({
   menu,
   folder,
   isMuted,
+  isPausedAll,
   onClose,
   onRename,
   onReindex,
   onLocate,
   onToggleMute,
+  onTogglePauseAll,
   onRemove,
 }: {
   menu: ContextMenuState;
   folder: Folder;
   isMuted: boolean;
+  isPausedAll: boolean;
   onClose: () => void;
   onRename: () => void;
   onReindex: () => void;
   onLocate: () => void;
   onToggleMute: () => void;
+  onTogglePauseAll: () => void;
   onRemove: () => void;
 }) {
   const ref = useRef<HTMLDivElement>(null);
@@ -65,6 +69,7 @@ function FolderContextMenu({
     >
       {item("Reindex", onReindex)}
       {item("Rename", onRename)}
+      {item(isPausedAll ? "Resume background work" : "Pause background work", onTogglePauseAll)}
       {item(isMuted ? "Unmute notifications" : "Mute notifications", onToggleMute)}
       {folder.scan_error && item("Locate Folder", onLocate)}
       <div className="my-1 border-t border-white/[0.06]" />
@@ -84,7 +89,12 @@ function FolderItem({
 }) {
   const { selectFolder, removeFolder, reindexFolder, renameFolder, updateFolderPath, toggleMutedFolder } = useGalleryStore();
   const mutedFolderIds = useGalleryStore((state) => state.mutedFolderIds);
+  const setAllWorkersPaused = useGalleryStore((state) => state.setAllWorkersPaused);
+  const folderWorkers = useGalleryStore((state) => state.workerPaused[folder.id]);
   const isMuted = mutedFolderIds.includes(folder.id);
+  // "Fully paused" only when every worker for this folder is paused.
+  const isPausedAll = !!folderWorkers &&
+    folderWorkers.thumbnail && folderWorkers.metadata && folderWorkers.embedding && folderWorkers.tagging;
   const isIndexing = progress && !progress.done;
   const isMissing = !!folder.scan_error && !isIndexing;
 
@@ -258,11 +268,13 @@ function FolderItem({
           menu={contextMenu}
           folder={folder}
           isMuted={isMuted}
+          isPausedAll={isPausedAll}
           onClose={() => setContextMenu(null)}
           onRename={() => setRenaming(true)}
           onReindex={() => void reindexFolder(folder.id)}
           onLocate={() => void handleLocateFolder()}
           onToggleMute={() => toggleMutedFolder(folder.id)}
+          onTogglePauseAll={() => setAllWorkersPaused(folder.id, !isPausedAll)}
           onRemove={() => setConfirmingRemoval(true)}
         />
       )}

src/components/TitleBar.tsx

@@ -1,6 +1,7 @@
 import { useState, useEffect } from "react";
 import { getCurrentWindow } from "@tauri-apps/api/window";
 import { useGalleryStore } from "../store";
+import { PhokusMark } from "./PhokusMark";
 
 // SVG icons for window controls
 function MinimizeIcon() {
@@ -39,6 +40,9 @@ function CloseIcon() {
 export function TitleBar() {
   const [isMaximized, setIsMaximized] = useState(false);
   const setSettingsOpen = useGalleryStore((state) => state.setSettingsOpen);
+  const updateStatus = useGalleryStore((state) => state.updateStatus);
+  const updateVersion = useGalleryStore((state) => state.updateVersion);
+  const installUpdate = useGalleryStore((state) => state.installUpdate);
   const appWindow = getCurrentWindow();
 
   useEffect(() => {
@@ -59,6 +63,10 @@ export function TitleBar() {
   const handleMaximize = () => appWindow.toggleMaximize();
   const handleClose = () => appWindow.close();
 
+  // An update is waiting for the user to act. Covers the "clicked Later" case too,
+  // since dismissing the toast doesn't change updateStatus.
+  const updatePending = updateStatus === "available";
+
   return (
     // data-tauri-drag-region is the recommended Tauri approach for drag regions.
     // WebkitAppRegion is kept as a CSS fallback for compatibility.
@@ -67,15 +75,32 @@ export function TitleBar() {
       className="titlebar relative z-50 flex h-9 shrink-0 items-center bg-gray-950 select-none"
       style={{ WebkitAppRegion: "drag" } as React.CSSProperties}
     >
-      {/* App icon + name — left side */}
+      {/* App icon + name — left side. When an update is waiting, the iris lights
+          up its focal point and the chip becomes a button that re-opens the prompt. */}
       <div className="flex items-center gap-2 pl-3 pr-4">
-        <div className="flex h-5 w-5 items-center justify-center rounded-md bg-white/8 overflow-hidden">
-          {/* Phokus logo placeholder — replace with <img src={logo} /> if you have an SVG */}
-          <svg width="12" height="12" viewBox="0 0 12 12" fill="none">
-            <circle cx="6" cy="6" r="4" stroke="#a78bfa" strokeWidth="1.5" />
-            <circle cx="6" cy="6" r="1.5" fill="#a78bfa" />
-          </svg>
-        </div>
+        {updatePending ? (
+          <div
+            className="group relative"
+            style={{ WebkitAppRegion: "no-drag" } as React.CSSProperties}
+          >
+            <button
+              onClick={() => void installUpdate()}
+              aria-label={`Update available — click to update to Phokus v${updateVersion}`}
+              className="relative flex h-5 w-5 items-center justify-center rounded-md bg-white/8 overflow-hidden text-gray-300 transition-colors hover:bg-white/12"
+            >
+              <span className="pointer-events-none absolute left-1/2 top-1/2 h-2 w-2 -translate-x-1/2 -translate-y-1/2 rounded-full bg-amber-400/60 animate-ping" />
+              <PhokusMark className="relative h-4 w-4" dotClassName="fill-amber-400" />
+            </button>
+            {/* Custom tooltip — fades in ~100ms instead of the native ~500ms delay. */}
+            <span className="pointer-events-none absolute left-0 top-full z-50 mt-1.5 whitespace-nowrap rounded-md border border-white/10 bg-gray-800 px-2 py-1 text-[11px] text-gray-200 opacity-0 shadow-lg transition-opacity duration-100 group-hover:opacity-100">
+              Click to update — v{updateVersion}
+            </span>
+          </div>
+        ) : (
+          <div className="flex h-5 w-5 items-center justify-center rounded-md bg-white/8 overflow-hidden text-gray-300">
+            <PhokusMark className="h-4 w-4" />
+          </div>
+        )}
         <span className="text-[11px] font-semibold text-gray-400 tracking-wide">Phokus</span>
       </div>
 

src/components/UpdateToast.tsx

@@ -0,0 +1,67 @@
+import { AnimatePresence, motion } from "framer-motion";
+import { useGalleryStore } from "../store";
+
+export function UpdateToast() {
+  const updateStatus = useGalleryStore((s) => s.updateStatus);
+  const updateVersion = useGalleryStore((s) => s.updateVersion);
+  const updateProgress = useGalleryStore((s) => s.updateProgress);
+  const updateDismissed = useGalleryStore((s) => s.updateDismissed);
+  const installUpdate = useGalleryStore((s) => s.installUpdate);
+  const dismissUpdate = useGalleryStore((s) => s.dismissUpdate);
+
+  const visible =
+    !updateDismissed &&
+    (updateStatus === "available" || updateStatus === "downloading" || updateStatus === "installing");
+
+  return (
+    <AnimatePresence>
+      {visible ? (
+        <motion.div
+          initial={{ opacity: 0, y: 12 }}
+          animate={{ opacity: 1, y: 0 }}
+          exit={{ opacity: 0, y: 12 }}
+          transition={{ duration: 0.18 }}
+          className="fixed bottom-4 right-4 z-50 w-80 rounded-lg border border-white/10 bg-gray-900 p-4 shadow-xl"
+        >
+          {updateStatus === "available" ? (
+            <>
+              <p className="text-sm font-medium text-white">Update available</p>
+              <p className="mt-1 text-xs text-gray-500">
+                Phokus v{updateVersion} is ready to download and install.
+              </p>
+              <div className="mt-3 flex items-center gap-2">
+                <button
+                  className="rounded-md border border-emerald-400/35 bg-emerald-500/15 px-3 py-1.5 text-xs text-emerald-200 transition-colors hover:bg-emerald-500/25"
+                  onClick={() => void installUpdate()}
+                >
+                  Install &amp; restart
+                </button>
+                <button
+                  className="rounded-md border border-transparent px-3 py-1.5 text-xs text-gray-500 transition-colors hover:bg-white/[0.06] hover:text-gray-200"
+                  onClick={dismissUpdate}
+                >
+                  Later
+                </button>
+              </div>
+            </>
+          ) : (
+            <>
+              <p className="text-sm font-medium text-white">
+                {updateStatus === "installing" ? "Installing update..." : "Downloading update..."}
+              </p>
+              <div className="mt-3 h-1 overflow-hidden rounded-full bg-white/10">
+                <div
+                  className={`h-full rounded-full bg-emerald-400/80 transition-[width] duration-200 ${
+                    updateProgress === null ? "w-full animate-pulse" : ""
+                  }`}
+                  style={updateProgress !== null ? { width: `${Math.round(updateProgress * 100)}%` } : undefined}
+                />
+              </div>
+              <p className="mt-2 text-xs text-gray-600">The app will restart when it finishes.</p>
+            </>
+          )}
+        </motion.div>
+      ) : null}
+    </AnimatePresence>
+  );
+}

src/components/onboarding/OnboardingOverlay.tsx

@@ -0,0 +1,112 @@
+import { useEffect } from "react";
+import { AnimatePresence, motion } from "framer-motion";
+import { useGalleryStore } from "../../store";
+import { StepWelcome } from "./StepWelcome";
+import { StepAddLibrary } from "./StepAddLibrary";
+import { StepPipeline } from "./StepPipeline";
+import { StepGalleryPreview } from "./StepGalleryPreview";
+import { StepSearchDemo } from "./StepSearchDemo";
+import { StepViews } from "./StepViews";
+import { StepAiFeatures } from "./StepAiFeatures";
+import { StepUpdates } from "./StepUpdates";
+
+const STEPS: { id: string; title: string; component: () => React.ReactNode }[] = [
+  { id: "welcome", title: "Welcome", component: () => <StepWelcome /> },
+  { id: "library", title: "Your library", component: () => <StepAddLibrary /> },
+  { id: "pipeline", title: "Background work", component: () => <StepPipeline /> },
+  { id: "gallery", title: "The gallery", component: () => <StepGalleryPreview /> },
+  { id: "search", title: "Search", component: () => <StepSearchDemo /> },
+  { id: "views", title: "Views", component: () => <StepViews /> },
+  { id: "ai", title: "AI features", component: () => <StepAiFeatures /> },
+  { id: "updates", title: "Staying current", component: () => <StepUpdates /> },
+];
+
+export function OnboardingOverlay() {
+  const onboardingOpen = useGalleryStore((s) => s.onboardingOpen);
+  const onboardingStep = useGalleryStore((s) => s.onboardingStep);
+  const setOnboardingStep = useGalleryStore((s) => s.setOnboardingStep);
+  const completeOnboarding = useGalleryStore((s) => s.completeOnboarding);
+
+  useEffect(() => {
+    if (!onboardingOpen) return;
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key === "Escape") completeOnboarding();
+    };
+    window.addEventListener("keydown", handleKeyDown);
+    return () => window.removeEventListener("keydown", handleKeyDown);
+  }, [onboardingOpen, completeOnboarding]);
+
+  if (!onboardingOpen) return null;
+
+  const step = STEPS[Math.min(onboardingStep, STEPS.length - 1)];
+  const isFirst = onboardingStep === 0;
+  const isLast = onboardingStep >= STEPS.length - 1;
+
+  return (
+    <div className="fixed inset-0 z-[70] flex items-center justify-center bg-black/65 backdrop-blur-sm">
+      <div className="flex max-h-[min(85vh,760px)] w-[min(90vw,720px)] flex-col rounded-lg border border-white/10 bg-[#07080f] shadow-2xl shadow-black/60">
+        {/* Header */}
+        <div className="flex items-center justify-between border-b border-white/[0.07] px-7 py-4">
+          <div>
+            <p className="text-[11px] uppercase tracking-[0.14em] text-gray-600">
+              Step {onboardingStep + 1} of {STEPS.length}
+            </p>
+            <h2 className="mt-0.5 text-base font-semibold text-white">{step.title}</h2>
+          </div>
+          <div className="flex items-center gap-1.5">
+            {STEPS.map((s, i) => (
+              <button
+                key={s.id}
+                aria-label={s.title}
+                className={`h-1.5 rounded-full transition-all ${
+                  i === onboardingStep ? "w-5 bg-white/70" : i < onboardingStep ? "w-1.5 bg-white/35" : "w-1.5 bg-white/15"
+                }`}
+                onClick={() => setOnboardingStep(i)}
+              />
+            ))}
+          </div>
+        </div>
+
+        {/* Step body */}
+        <div className="min-h-0 flex-1 overflow-y-auto px-7 py-6">
+          <AnimatePresence mode="wait">
+            <motion.div
+              key={step.id}
+              initial={{ opacity: 0, x: 14 }}
+              animate={{ opacity: 1, x: 0 }}
+              exit={{ opacity: 0, x: -14 }}
+              transition={{ duration: 0.16 }}
+            >
+              {step.component()}
+            </motion.div>
+          </AnimatePresence>
+        </div>
+
+        {/* Footer */}
+        <div className="flex items-center justify-between border-t border-white/[0.07] px-7 py-4">
+          <button
+            className="rounded-md border border-transparent px-3 py-1.5 text-xs text-gray-500 transition-colors hover:bg-white/[0.06] hover:text-gray-200"
+            onClick={completeOnboarding}
+          >
+            Skip tour
+          </button>
+          <div className="flex items-center gap-2">
+            <button
+              className="rounded-md border border-white/10 bg-white/[0.055] px-3 py-1.5 text-xs text-gray-300 transition-colors hover:bg-white/10 hover:text-white disabled:cursor-not-allowed disabled:opacity-45"
+              onClick={() => setOnboardingStep(onboardingStep - 1)}
+              disabled={isFirst}
+            >
+              Back
+            </button>
+            <button
+              className="rounded-md border border-emerald-400/35 bg-emerald-500/15 px-4 py-1.5 text-xs text-emerald-200 transition-colors hover:bg-emerald-500/25"
+              onClick={() => (isLast ? completeOnboarding() : setOnboardingStep(onboardingStep + 1))}
+            >
+              {isLast ? "Finish" : "Next"}
+            </button>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}

src/components/onboarding/StepAddLibrary.tsx

@@ -0,0 +1,77 @@
+import { useState } from "react";
+import { open } from "@tauri-apps/plugin-dialog";
+import { useGalleryStore } from "../../store";
+import { FakeTile } from "./fakes";
+
+export function StepAddLibrary() {
+  const folders = useGalleryStore((s) => s.folders);
+  const addFolder = useGalleryStore((s) => s.addFolder);
+  const [adding, setAdding] = useState(false);
+  const [addError, setAddError] = useState<string | null>(null);
+
+  const handlePick = async () => {
+    setAddError(null);
+    const selected = await open({ directory: true, multiple: false, title: "Select Media Folder" });
+    if (typeof selected !== "string") return;
+    setAdding(true);
+    try {
+      await addFolder(selected);
+    } catch (error) {
+      setAddError(error instanceof Error ? error.message : String(error));
+    } finally {
+      setAdding(false);
+    }
+  };
+
+  return (
+    <div>
+      <p className="text-sm leading-relaxed text-gray-300">
+        A library is just a folder on disk — Phokus watches it and keeps itself in sync as files are
+        added, renamed, or removed. Nothing is moved or copied.
+      </p>
+
+      <div className="mt-5 flex items-center justify-between gap-6 border-y border-white/[0.05] py-4">
+        <div className="min-w-0">
+          {folders.length > 0 ? (
+            <>
+              <p className="text-sm text-white">
+                {folders.length === 1 ? `“${folders[0].name}” added` : `${folders.length} folders in your library`}
+              </p>
+              <p className="mt-1 text-xs text-gray-500">
+                Indexing runs in the background — you can add more folders from the sidebar any time.
+              </p>
+            </>
+          ) : (
+            <>
+              <p className="text-sm text-white">Add your first folder</p>
+              <p className="mt-1 text-xs text-gray-500">
+                Pick somewhere with photos or videos. You can add more later from the sidebar.
+              </p>
+            </>
+          )}
+          {addError ? <p className="mt-1.5 text-xs text-amber-300/90">{addError}</p> : null}
+        </div>
+        <button
+          className="shrink-0 rounded-md border border-emerald-400/35 bg-emerald-500/15 px-3 py-1.5 text-xs text-emerald-200 transition-colors hover:bg-emerald-500/25 disabled:cursor-not-allowed disabled:opacity-45"
+          onClick={() => void handlePick()}
+          disabled={adding}
+        >
+          {adding ? "Adding..." : folders.length > 0 ? "Add another folder" : "Choose a folder"}
+        </button>
+      </div>
+
+      <p className="mt-5 text-xs leading-relaxed text-gray-500">
+        As indexing runs, the gallery fills in roughly like this — tiles appear immediately and sharpen
+        as thumbnails are generated:
+      </p>
+      <div className="mt-3 grid grid-cols-6 gap-1.5">
+        <FakeTile index={0} />
+        <FakeTile index={1} favorite />
+        <FakeTile index={2} duration="0:42" />
+        <FakeTile index={3} rating={4} />
+        <FakeTile index={4} loaded={false} />
+        <FakeTile index={5} loaded={false} />
+      </div>
+    </div>
+  );
+}

src/components/onboarding/StepAiFeatures.tsx

@@ -0,0 +1,113 @@
+import { useEffect } from "react";
+import { TaggerModelProgress, useGalleryStore } from "../../store";
+import { FakeProgressBar, formatBytes } from "./fakes";
+
+const FAKE_TAGS = ["landscape", "sunset", "outdoors", "no_humans", "ocean", "cloudy_sky"];
+
+// Prefer the current file's byte fraction (the 1.3 GB model dominates); fall
+// back to the coarse step count; null renders an indeterminate bar.
+function taggerDownloadFraction(progress: TaggerModelProgress | null): number | null {
+  if (!progress) return null;
+  if (progress.downloaded_bytes != null && progress.total_bytes != null && progress.total_bytes > 0) {
+    return progress.downloaded_bytes / progress.total_bytes;
+  }
+  if (progress.total_files > 0) return progress.completed_files / progress.total_files;
+  return null;
+}
+
+export function StepAiFeatures() {
+  const taggerModelStatus = useGalleryStore((s) => s.taggerModelStatus);
+  const taggerModelPreparing = useGalleryStore((s) => s.taggerModelPreparing);
+  const taggerModelProgress = useGalleryStore((s) => s.taggerModelProgress);
+  const taggerModelError = useGalleryStore((s) => s.taggerModelError);
+  const prepareTaggerModel = useGalleryStore((s) => s.prepareTaggerModel);
+  const loadTaggerModelStatus = useGalleryStore((s) => s.loadTaggerModelStatus);
+
+  useEffect(() => {
+    void loadTaggerModelStatus();
+  }, [loadTaggerModelStatus]);
+
+  const taggerReady = taggerModelStatus?.ready ?? false;
+
+  return (
+    <div>
+      <p className="text-sm leading-relaxed text-gray-300">
+        Phokus's AI runs entirely on this machine — nothing is sent anywhere. Semantic search sets
+        itself up automatically; AI tagging is optional and only downloads if you want it.
+      </p>
+
+      <h4 className="mt-6 text-[12px] font-semibold uppercase tracking-[0.08em] text-gray-400">AI tagging — optional</h4>
+      <div className="mt-1 divide-y divide-white/[0.05]">
+        <div className="py-4">
+          <div className="flex items-start justify-between gap-6">
+            <div className="min-w-0">
+              <p className="text-sm text-white">Automatic tags for every image</p>
+              <p className="mt-1 text-xs leading-relaxed text-gray-500">
+                The WD tagger model (~1.3 GB download) labels images so you can search with{" "}
+                <code className="rounded bg-white/[0.07] px-1 py-0.5 text-[11px] text-gray-200">/t</code> — tags look like:
+              </p>
+              <span className="mt-2 flex flex-wrap gap-1.5">
+                {FAKE_TAGS.map((tag) => (
+                  <span key={tag} className="rounded-md border border-white/10 bg-white/[0.04] px-2 py-0.5 text-[11px] text-gray-400">
+                    {tag}
+                  </span>
+                ))}
+              </span>
+            </div>
+            <div className="shrink-0">
+              {taggerReady ? (
+                <span className="inline-flex rounded-md border border-emerald-400/25 bg-emerald-500/10 px-2 py-0.5 text-[11px] font-medium text-emerald-300">
+                  Installed
+                </span>
+              ) : (
+                <button
+                  className="rounded-md border border-white/10 bg-white/[0.055] px-3 py-1.5 text-xs text-gray-300 transition-colors hover:bg-white/10 hover:text-white disabled:cursor-not-allowed disabled:opacity-45"
+                  onClick={() => void prepareTaggerModel()}
+                  disabled={taggerModelPreparing}
+                >
+                  {taggerModelPreparing ? "Downloading..." : "Download now"}
+                </button>
+              )}
+            </div>
+          </div>
+          {taggerModelPreparing ? (
+            <div className="mt-3">
+              <FakeProgressBar fraction={taggerDownloadFraction(taggerModelProgress)} />
+              <div className="mt-1.5 flex items-center justify-between gap-3 text-[11px] text-gray-600">
+                <span className="truncate">{taggerModelProgress?.current_file ?? "Preparing..."}</span>
+                {taggerModelProgress?.downloaded_bytes != null && taggerModelProgress.total_bytes != null ? (
+                  <span className="shrink-0 tabular-nums">
+                    {formatBytes(taggerModelProgress.downloaded_bytes)} / {formatBytes(taggerModelProgress.total_bytes)}
+                  </span>
+                ) : null}
+              </div>
+            </div>
+          ) : null}
+          {!taggerModelPreparing && taggerModelError ? (
+            <p className="mt-2 text-xs leading-relaxed text-amber-300/90">
+              Download failed: {taggerModelError}
+            </p>
+          ) : null}
+        </div>
+      </div>
+
+      <h4 className="mt-6 text-[12px] font-semibold uppercase tracking-[0.08em] text-gray-400">Semantic search & similarity — built in</h4>
+      <div className="mt-1 divide-y divide-white/[0.05]">
+        <div className="py-4">
+          <p className="text-sm text-white">Search by meaning, find look-alikes</p>
+          <p className="mt-1 text-xs leading-relaxed text-gray-500">
+            Powers <code className="rounded bg-white/[0.07] px-1 py-0.5 text-[11px] text-gray-200">/s</code> search,
+            "find similar", and the Explore view, so it's part of the standard pipeline: the CLIP model
+            (~580 MB) downloads automatically the first time embeddings run. Nothing to do — you'll see it
+            in the background-tasks bar.
+          </p>
+        </div>
+      </div>
+
+      <p className="mt-5 text-xs leading-relaxed text-gray-500">
+        Semantic search and similarity are part of the standard pipeline; AI tagging stays optional and
+        can be downloaded any time from Settings.
+      </p>
+    </div>
+  );
+}

src/components/onboarding/StepGalleryPreview.tsx

@@ -0,0 +1,61 @@
+import { useEffect, useState } from "react";
+import { FakeTile, ReplayButton } from "./fakes";
+
+const REVEAL_MS = 280;
+
+// Two rows (cols-4) keeps the explainer text visible without scrolling.
+const TILE_PROPS: { favorite?: boolean; rating?: number; duration?: string }[] = [
+  {},
+  { favorite: true },
+  {},
+  { duration: "1:24" },
+  { rating: 5 },
+  { favorite: true, rating: 3 },
+  { duration: "0:09" },
+  {},
+];
+
+const TILE_COUNT = TILE_PROPS.length;
+
+/// Placeholder tiles "loading in" once (skeleton → image), then stopping fully
+/// revealed with a replay control.
+export function StepGalleryPreview() {
+  const [revealed, setRevealed] = useState(0);
+
+  useEffect(() => {
+    if (revealed >= TILE_COUNT) return;
+    const timer = setTimeout(() => setRevealed((n) => n + 1), REVEAL_MS);
+    return () => clearTimeout(timer);
+  }, [revealed]);
+
+  const finished = revealed >= TILE_COUNT;
+
+  return (
+    <div>
+      <p className="text-sm leading-relaxed text-gray-300">
+        The gallery is a virtualized grid — it stays fast with hundreds of thousands of items. Tiles
+        carry your favorites, star ratings, and video durations; hover for filename and quick actions.
+      </p>
+
+      <div className="mt-5 grid grid-cols-4 gap-1.5">
+        {TILE_PROPS.map((props, i) => (
+          <FakeTile key={i} index={i} loaded={i < revealed} {...props} />
+        ))}
+      </div>
+
+      <div className="mt-6 flex items-start justify-between gap-4">
+        <div className="divide-y divide-white/[0.05] text-xs leading-relaxed text-gray-500">
+          <p className="pb-2.5">
+            <span className="text-gray-300">Click any tile</span> to open the lightbox — keyboard navigation,
+            zoom, inline tag editing, ratings, and a full video player.
+          </p>
+          <p className="pt-2.5">
+            <span className="text-gray-300">The toolbar</span> filters by type, favorites, or rating, sorts by
+            date/name/size, and switches grid density.
+          </p>
+        </div>
+        {finished ? <ReplayButton onClick={() => setRevealed(0)} /> : null}
+      </div>
+    </div>
+  );
+}

src/components/onboarding/StepPipeline.tsx

@@ -0,0 +1,89 @@
+import { useEffect, useState } from "react";
+import { FakeProgressBar, FakeStageTag, ReplayButton } from "./fakes";
+
+const STAGES = ["Thumbnails", "Metadata", "Embeddings", "Tags"] as const;
+const STAGE_TOTAL = 128;
+const TICK_MS = 80;
+const STEP_PER_TICK = 8;
+
+/// A one-shot fake of the background-tasks bar: each stage drains in order,
+/// then it stops at "all done" with a replay control.
+export function StepPipeline() {
+  const [stageIndex, setStageIndex] = useState(0);
+  const [filled, setFilled] = useState(0);
+
+  const finished = stageIndex >= STAGES.length;
+
+  useEffect(() => {
+    if (finished) return;
+    const timer = setTimeout(() => {
+      // Read from the closure and call setters directly — nesting one setter
+      // inside another's updater double-advances under React StrictMode.
+      if (filled + STEP_PER_TICK < STAGE_TOTAL) {
+        setFilled(filled + STEP_PER_TICK);
+      } else {
+        setStageIndex(stageIndex + 1);
+        setFilled(0);
+      }
+    }, TICK_MS);
+    return () => clearTimeout(timer);
+  }, [filled, stageIndex, finished]);
+
+  const replay = () => {
+    setStageIndex(0);
+    setFilled(0);
+  };
+
+  const remaining = STAGE_TOTAL - filled;
+
+  return (
+    <div>
+      <p className="text-sm leading-relaxed text-gray-300">
+        After indexing, Phokus works through a strict pipeline: thumbnails first, then video metadata,
+        then visual embeddings (for similarity and semantic search), then AI tags. One stage at a time,
+        so each runs at full speed.
+      </p>
+
+      <p className="mt-5 text-xs text-gray-500">
+        While it's working you'll see this bar above the gallery — here's a preview:
+      </p>
+
+      {/* Fake BackgroundTasks slim bar */}
+      <div className="mt-3 rounded-lg border border-white/[0.07] bg-white/[0.02] px-4 py-3">
+        <div className="flex items-center gap-3">
+          <span className="relative flex h-1.5 w-1.5 shrink-0">
+            {!finished ? (
+              <span className="absolute inline-flex h-full w-full animate-ping rounded-full bg-blue-400 opacity-60" />
+            ) : null}
+            <span className={`relative inline-flex h-1.5 w-1.5 rounded-full ${finished ? "bg-emerald-400" : "bg-blue-400"}`} />
+          </span>
+          <span className="text-[13px] font-medium text-white/60">Holiday Photos</span>
+          <div className="flex items-center gap-1.5">
+            {STAGES.map((stage, i) => (
+              <FakeStageTag
+                key={stage}
+                label={!finished && i === stageIndex ? `${stage} · ${remaining}` : stage}
+                state={finished || i < stageIndex ? "done" : i === stageIndex ? "active" : "waiting"}
+              />
+            ))}
+          </div>
+          <FakeProgressBar fraction={finished ? 1 : filled / STAGE_TOTAL} className="ml-auto w-24" />
+        </div>
+      </div>
+
+      <div className="mt-6 flex items-start justify-between gap-4">
+        <div className="divide-y divide-white/[0.05] text-xs leading-relaxed text-gray-500">
+          <p className="pb-2.5">
+            <span className="text-gray-300">It's all interruptible.</span> Close the app whenever you like —
+            the queue picks up where it left off next launch.
+          </p>
+          <p className="pt-2.5">
+            <span className="text-gray-300">Per-folder control.</span> Right-click a folder in the sidebar to
+            pause its background work, and click the bar itself to expand a detailed per-folder view.
+          </p>
+        </div>
+        {finished ? <ReplayButton onClick={replay} /> : null}
+      </div>
+    </div>
+  );
+}

src/components/onboarding/StepSearchDemo.tsx

@@ -0,0 +1,108 @@
+import { useEffect, useState } from "react";
+import { ReplayButton, SEARCH_RESULTS } from "./fakes";
+
+const DEMOS = [
+  {
+    query: "beach-day_042.jpg",
+    mode: "Filename",
+    description: "Plain text matches file names — the default, instant search. One name, one file.",
+    results: SEARCH_RESULTS.filename,
+  },
+  {
+    query: "/s golden sunset over water",
+    mode: "Semantic",
+    description: "Describe what's in the picture. Visual embeddings find matches even when filenames say nothing.",
+    results: SEARCH_RESULTS.semantic,
+  },
+  {
+    query: "/t landscape",
+    mode: "Tags",
+    description: "Search by AI or manual tags. Autocomplete suggests tags as you type.",
+    results: SEARCH_RESULTS.tags,
+  },
+] as const;
+
+const TYPE_MS = 55;
+const HOLD_MS = 2600;
+
+/// Types each demo query, shows matching results, advances through all three
+/// modes once, then stops on the last with a replay control.
+export function StepSearchDemo() {
+  const [demoIndex, setDemoIndex] = useState(0);
+  const [typed, setTyped] = useState(0);
+  const [finished, setFinished] = useState(false);
+
+  const demo = DEMOS[demoIndex];
+  const isLastDemo = demoIndex === DEMOS.length - 1;
+
+  useEffect(() => {
+    if (finished) return;
+    if (typed < demo.query.length) {
+      const timer = setTimeout(() => setTyped((n) => n + 1), TYPE_MS);
+      return () => clearTimeout(timer);
+    }
+    // Fully typed: hold, then advance — or finish on the last demo.
+    const timer = setTimeout(() => {
+      if (isLastDemo) {
+        setFinished(true);
+      } else {
+        setDemoIndex((i) => i + 1);
+        setTyped(0);
+      }
+    }, HOLD_MS);
+    return () => clearTimeout(timer);
+  }, [typed, demo.query.length, isLastDemo, finished]);
+
+  const replay = () => {
+    setDemoIndex(0);
+    setTyped(0);
+    setFinished(false);
+  };
+
+  const fullyTyped = typed >= demo.query.length;
+
+  return (
+    <div>
+      <p className="text-sm leading-relaxed text-gray-300">
+        One search bar, three modes — picked by prefix. No prefix searches filenames, <code className="rounded bg-white/[0.07] px-1 py-0.5 text-[11px] text-gray-200">/s</code> searches
+        by meaning, <code className="rounded bg-white/[0.07] px-1 py-0.5 text-[11px] text-gray-200">/t</code> searches tags.
+      </p>
+
+      {/* Mock search bar */}
+      <div className="mt-5 flex items-center gap-2.5 rounded-lg border border-white/10 bg-white/[0.04] px-3.5 py-2.5">
+        <svg className="h-4 w-4 shrink-0 text-gray-500" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth={2}>
+          <path strokeLinecap="round" strokeLinejoin="round" d="M21 21l-5.197-5.197m0 0A7.5 7.5 0 105.196 5.196a7.5 7.5 0 0010.607 10.607z" />
+        </svg>
+        <span className="text-sm text-white">
+          {demo.query.slice(0, typed)}
+          {!finished ? <span className="animate-pulse text-gray-500">|</span> : null}
+        </span>
+        <span className="ml-auto shrink-0 rounded-md border border-sky-400/25 bg-sky-500/10 px-2 py-0.5 text-[11px] font-medium text-sky-300">
+          {demo.mode}
+        </span>
+      </div>
+
+      {/* Results — hidden (not greyed) until the query finishes typing, so it
+          doesn't look like the app is reading the user's mind. Space is held
+          by the invisible tiles so the layout doesn't jump when they appear.
+          Keyed by demoIndex so switching demos remounts the row fresh at
+          opacity-0 instead of fading the new images out from the previous
+          demo's visible state. */}
+      <div
+        key={demoIndex}
+        className={`mt-3 flex flex-wrap justify-center gap-1.5 transition-opacity duration-300 ${fullyTyped ? "opacity-100" : "opacity-0"}`}
+      >
+        {demo.results.map((src, i) => (
+          <div key={i} className="aspect-square w-36 overflow-hidden rounded-xl bg-white/[0.04]">
+            <img src={src} alt="" className="h-full w-full object-cover" />
+          </div>
+        ))}
+      </div>
+
+      <div className="mt-4 flex min-h-10 items-start justify-between gap-4">
+        <p className="text-xs leading-relaxed text-gray-500">{demo.description}</p>
+        {finished ? <ReplayButton onClick={replay} /> : null}
+      </div>
+    </div>
+  );
+}

src/components/onboarding/StepUpdates.tsx

@@ -0,0 +1,86 @@
+import { PhokusMark } from "../PhokusMark";
+
+// Closing step. Introduces the app mark (the aperture in the title bar) and,
+// since that same mark doubles as the update indicator, explains how updates
+// work in one place. The mini app-window mockup shows the lit mark exactly
+// where it appears, so there's nothing abstract to decode.
+export function StepUpdates() {
+  return (
+    <div>
+      <p className="text-sm leading-relaxed text-gray-300">
+        Phokus keeps itself up to date — it quietly checks for new versions on startup, so you don't
+        have to go looking for one.
+      </p>
+
+      <h4 className="mt-6 text-[12px] font-semibold uppercase tracking-[0.08em] text-gray-400">
+        When an update is ready
+      </h4>
+      <div className="mt-1 py-4">
+        <p className="text-sm text-white">The mark in the title bar lights up</p>
+        <p className="mt-1 text-xs leading-relaxed text-gray-500">
+          That aperture in the top-left corner is Phokus. When a new version is waiting, its focal point
+          glows amber — click it to update and relaunch. Nothing installs on its own; you're always in
+          control.
+        </p>
+
+        {/* Mini app-window mockup: the lit mark shown in a real title bar. */}
+        <div className="mt-3 overflow-hidden rounded-lg border border-white/10 bg-gray-950 shadow-lg">
+          <div className="flex items-center gap-2 border-b border-white/[0.06] px-3 py-2">
+            <div className="relative flex h-6 w-6 items-center justify-center rounded-md bg-white/[0.08] text-gray-300">
+              <span className="pointer-events-none absolute left-1/2 top-1/2 h-3.5 w-3.5 -translate-x-1/2 -translate-y-1/2 rounded-full bg-amber-400/30 blur-[3px]" />
+              <span className="pointer-events-none absolute left-1/2 top-1/2 h-3 w-3 -translate-x-1/2 -translate-y-1/2 rounded-full bg-amber-400/55 animate-ping" />
+              <PhokusMark className="relative h-[18px] w-[18px]" dotClassName="fill-amber-400" />
+            </div>
+            <span className="text-xs font-semibold tracking-wide text-gray-300">Phokus</span>
+            <div className="flex-1" />
+            <div className="flex items-center gap-3.5 text-gray-600">
+              <svg width="9" height="9" viewBox="0 0 10 10" fill="none">
+                <rect y="4.5" width="10" height="1" rx="0.5" fill="currentColor" />
+              </svg>
+              <svg width="9" height="9" viewBox="0 0 10 10" fill="none">
+                <rect x="0.5" y="0.5" width="9" height="9" rx="1.5" stroke="currentColor" />
+              </svg>
+              <svg width="9" height="9" viewBox="0 0 10 10" fill="none">
+                <path d="M1 1L9 9M9 1L1 9" stroke="currentColor" strokeWidth="1.25" strokeLinecap="round" />
+              </svg>
+            </div>
+          </div>
+
+          {/* Ghosted window body, just enough to read as the app. */}
+          <div className="flex h-[72px] bg-gray-900/30">
+            <div className="w-14 shrink-0 border-r border-white/[0.05] p-2.5">
+              <div className="h-1.5 w-full rounded bg-white/[0.07]" />
+              <div className="mt-2 h-1.5 w-3/4 rounded bg-white/[0.04]" />
+              <div className="mt-2 h-1.5 w-3/4 rounded bg-white/[0.04]" />
+            </div>
+            <div className="flex-1 p-2.5">
+              <div className="h-2 w-20 rounded bg-white/[0.06]" />
+              <div className="mt-2.5 grid grid-cols-5 gap-1.5">
+                {Array.from({ length: 5 }).map((_, i) => (
+                  <div key={i} className="h-7 rounded bg-white/[0.04]" />
+                ))}
+              </div>
+            </div>
+          </div>
+        </div>
+      </div>
+
+      <h4 className="mt-6 text-[12px] font-semibold uppercase tracking-[0.08em] text-gray-400">
+        Prefer to manage it yourself?
+      </h4>
+      <div className="mt-1 py-4">
+        <p className="text-sm text-white">Check any time from Settings</p>
+        <p className="mt-1 text-xs leading-relaxed text-gray-500">
+          Settings → General shows your current version with a manual{" "}
+          <span className="text-gray-300">Check for updates</span> button, so you can update on your own
+          schedule.
+        </p>
+      </div>
+
+      <p className="mt-5 text-xs leading-relaxed text-gray-500">
+        That's the tour. Add folders from the sidebar, and revisit any of this from Settings — including
+        re-running this tour.
+      </p>
+    </div>
+  );
+}

src/components/onboarding/StepViews.tsx

@@ -0,0 +1,94 @@
+import { FakeTile, tileGradient } from "./fakes";
+
+function ViewRow({ title, description, preview }: { title: string; description: string; preview: React.ReactNode }) {
+  return (
+    <div className="flex items-center justify-between gap-6 py-4">
+      <div className="min-w-0">
+        <p className="text-sm text-white">{title}</p>
+        <p className="mt-1 max-w-md text-xs leading-relaxed text-gray-500">{description}</p>
+      </div>
+      <div className="shrink-0">{preview}</div>
+    </div>
+  );
+}
+
+function ExplorePreview() {
+  // Cluster blobs of varying size, like the tag cloud / cluster map.
+  const blobs = [
+    { size: 34, x: 4, y: 10, i: 0 },
+    { size: 24, x: 46, y: 0, i: 2 },
+    { size: 18, x: 86, y: 22, i: 4 },
+    { size: 26, x: 30, y: 36, i: 1 },
+    { size: 16, x: 70, y: 44, i: 6 },
+  ];
+  return (
+    <div className="relative h-[72px] w-32 overflow-hidden rounded-lg border border-white/[0.07] bg-white/[0.02]">
+      {blobs.map((blob, idx) => (
+        <div
+          key={idx}
+          className={`absolute rounded-full bg-gradient-to-br opacity-80 ${tileGradient(blob.i)}`}
+          style={{ width: blob.size, height: blob.size, left: blob.x, top: blob.y }}
+        />
+      ))}
+    </div>
+  );
+}
+
+function TimelinePreview() {
+  return (
+    <div className="flex h-[72px] w-32 flex-col justify-center gap-2 rounded-lg border border-white/[0.07] bg-white/[0.02] px-3">
+      {[2024, 2023].map((year, row) => (
+        <div key={year} className="flex items-center gap-1.5">
+          <span className="w-7 text-[9px] tabular-nums text-gray-600">{year}</span>
+          {Array.from({ length: 4 }).map((_, i) => (
+            <div key={i} className={`h-4 w-4 rounded-sm bg-gradient-to-br ${tileGradient(row * 3 + i)}`} />
+          ))}
+        </div>
+      ))}
+    </div>
+  );
+}
+
+function DuplicatesPreview() {
+  return (
+    <div className="flex h-[72px] w-32 items-center justify-center gap-1.5 rounded-lg border border-white/[0.07] bg-white/[0.02]">
+      <div className="w-10">
+        <FakeTile index={3} className="rounded-md" />
+      </div>
+      <div className="relative w-10">
+        <FakeTile index={3} className="rounded-md" />
+        <span className="absolute -right-1 -top-1 rounded-full bg-amber-500/90 px-1 text-[8px] font-semibold text-black">2×</span>
+      </div>
+    </div>
+  );
+}
+
+export function StepViews() {
+  return (
+    <div>
+      <p className="text-sm leading-relaxed text-gray-300">
+        Beyond the main grid, the sidebar switches between three more ways to look at your library:
+      </p>
+      <div className="mt-3 divide-y divide-white/[0.05]">
+        <ViewRow
+          title="Explore"
+          description="A visual cluster map and tag cloud — browse by theme instead of folder, and jump into any cluster."
+          preview={<ExplorePreview />}
+        />
+        <ViewRow
+          title="Timeline"
+          description="Everything grouped chronologically by capture date (EXIF), from years down to days."
+          preview={<TimelinePreview />}
+        />
+        <ViewRow
+          title="Duplicates"
+          description="A three-phase exact-duplicate scan with bulk delete — reclaim space from copies safely."
+          preview={<DuplicatesPreview />}
+        />
+      </div>
+      <p className="mt-4 text-xs leading-relaxed text-gray-500">
+        Each view can be scoped to a single folder from its header — no need to bounce through the sidebar.
+      </p>
+    </div>
+  );
+}

src/components/onboarding/StepWelcome.tsx

@@ -0,0 +1,92 @@
+import { useGalleryStore } from "../../store";
+import { FakeProgressBar, formatBytes } from "./fakes";
+
+export function FfmpegStatusRow() {
+  const ffmpegStatus = useGalleryStore((s) => s.ffmpegStatus);
+  const ffmpegProgress = useGalleryStore((s) => s.ffmpegProgress);
+  const ffmpegError = useGalleryStore((s) => s.ffmpegError);
+  const retryFfmpegDownload = useGalleryStore((s) => s.retryFfmpegDownload);
+
+  if (ffmpegStatus === "installed") {
+    return (
+      <div className="flex items-center gap-2.5 py-3">
+        <svg className="h-4 w-4 shrink-0 text-emerald-400" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth={2}>
+          <path strokeLinecap="round" strokeLinejoin="round" d="M9 12.75L11.25 15 15 9.75M21 12a9 9 0 11-18 0 9 9 0 0118 0z" />
+        </svg>
+        <div>
+          <p className="text-sm text-white">Media engine ready</p>
+          <p className="text-xs text-gray-500">FFmpeg is installed — video thumbnails and metadata are available.</p>
+        </div>
+      </div>
+    );
+  }
+
+  if (ffmpegStatus === "error") {
+    return (
+      <div className="py-3">
+        <div className="flex items-start justify-between gap-6">
+          <div className="min-w-0">
+            <p className="text-sm text-white">Media engine download failed</p>
+            <p className="mt-1 text-xs leading-relaxed text-amber-300/90">{ffmpegError}</p>
+            <p className="mt-1.5 text-xs leading-relaxed text-gray-500">
+              You can keep going — photos work without it. Video thumbnails and metadata will start
+              automatically once the download succeeds.
+            </p>
+          </div>
+          <button
+            className="shrink-0 rounded-md border border-white/10 bg-white/[0.055] px-3 py-1.5 text-xs text-gray-300 transition-colors hover:bg-white/10 hover:text-white"
+            onClick={() => void retryFfmpegDownload()}
+          >
+            Retry download
+          </button>
+        </div>
+      </div>
+    );
+  }
+
+  const fraction =
+    ffmpegStatus === "downloading" && ffmpegProgress && ffmpegProgress.total_bytes > 0
+      ? ffmpegProgress.downloaded_bytes / ffmpegProgress.total_bytes
+      : null;
+
+  return (
+    <div className="py-3">
+      <div className="flex items-baseline justify-between gap-6">
+        <p className="text-sm text-white">
+          {ffmpegStatus === "unpacking" ? "Unpacking media engine..." : "Downloading media engine (FFmpeg)..."}
+        </p>
+        {ffmpegProgress ? (
+          <span className="text-[11px] tabular-nums text-gray-500">
+            {formatBytes(ffmpegProgress.downloaded_bytes)} / {formatBytes(ffmpegProgress.total_bytes)}
+          </span>
+        ) : null}
+      </div>
+      <FakeProgressBar fraction={ffmpegStatus === "unpacking" ? null : fraction} className="mt-2.5" />
+      <p className="mt-2 text-xs leading-relaxed text-gray-500">
+        FFmpeg powers video thumbnails and metadata. It downloads once in the background — you can keep
+        using the tour and the app while it finishes.
+      </p>
+    </div>
+  );
+}
+
+export function StepWelcome() {
+  return (
+    <div>
+      <p className="text-sm leading-relaxed text-gray-300">
+        Phokus is a local-first media library: point it at your folders and it builds a fast, searchable
+        gallery with thumbnails, AI tags, and visual search. Everything is processed on this machine —
+        your photos and videos never leave it.
+      </p>
+      <p className="mt-2.5 text-sm leading-relaxed text-gray-500">
+        This short tour shows what to expect. Every step is skippable, and you can re-run it any time
+        from Settings.
+      </p>
+
+      <h4 className="mt-7 text-[12px] font-semibold uppercase tracking-[0.08em] text-gray-400">First-time setup</h4>
+      <div className="mt-1 divide-y divide-white/[0.05]">
+        <FfmpegStatusRow />
+      </div>
+    </div>
+  );
+}

src/components/onboarding/fakes.tsx

@@ -0,0 +1,161 @@
+// Shared placeholder primitives for the onboarding tour. Everything here is
+// deliberately fake — rights-clean demo stills (generated, owned), looping
+// demo progress — so new users see the real UI's shapes before their own
+// library exists.
+import sunset from "../../assets/onboarding/sunset.webp";
+import sunsetcoast from "../../assets/onboarding/sunsetcoast.webp";
+import sunsetlake from "../../assets/onboarding/sunsetlake.webp";
+import beach from "../../assets/onboarding/beach.webp";
+import landscape1 from "../../assets/onboarding/landscape1.webp";
+import landscape2 from "../../assets/onboarding/landscape2.webp";
+import forest from "../../assets/onboarding/forest.webp";
+import citynight from "../../assets/onboarding/citynight.webp";
+import flower from "../../assets/onboarding/flower.webp";
+import alpinelake from "../../assets/onboarding/alpinelake.webp";
+import dunes from "../../assets/onboarding/dunes.webp";
+import cozy from "../../assets/onboarding/cozy.webp";
+import cat from "../../assets/onboarding/cat.webp";
+import balloon from "../../assets/onboarding/balloon.webp";
+import architecture from "../../assets/onboarding/architecture.webp";
+
+// Ordered for grid variety: adjacent indices are visually distinct.
+const FAKE_IMAGES = [
+  sunset,
+  cozy,
+  landscape1,
+  citynight,
+  flower,
+  dunes,
+  alpinelake,
+  cat,
+  forest,
+  balloon,
+  landscape2,
+  beach,
+  architecture,
+];
+
+export function fakeImage(index: number): string {
+  return FAKE_IMAGES[index % FAKE_IMAGES.length];
+}
+
+// Result sets matched to what each query would genuinely return.
+// - filename: one exact file (a filename search hits a specific name)
+// - semantic "golden sunset over water": only the ocean-sunset stills
+// - tags "landscape": mountain valleys + the alpine lake (all landscapes)
+export const SEARCH_RESULTS = {
+  filename: [beach],
+  semantic: [sunsetcoast, sunset, sunsetlake],
+  tags: [landscape1, landscape2, alpinelake],
+} as const;
+
+// Abstract gradient blobs/ticks for the Explore & Timeline mini-previews,
+// where small non-photographic shapes read more clearly than tiny stills.
+const TILE_GRADIENTS = [
+  "from-sky-900/70 via-slate-800 to-slate-900",
+  "from-amber-900/60 via-stone-800 to-stone-900",
+  "from-emerald-900/60 via-slate-800 to-gray-900",
+  "from-rose-900/50 via-slate-800 to-slate-900",
+  "from-indigo-900/60 via-slate-800 to-gray-900",
+  "from-cyan-900/60 via-slate-800 to-slate-900",
+  "from-fuchsia-900/40 via-slate-800 to-gray-900",
+  "from-orange-900/50 via-stone-800 to-stone-900",
+];
+
+export function tileGradient(index: number): string {
+  return TILE_GRADIENTS[index % TILE_GRADIENTS.length];
+}
+
+export function FakeTile({
+  index,
+  loaded = true,
+  favorite = false,
+  rating = 0,
+  duration,
+  className = "",
+}: {
+  index: number;
+  loaded?: boolean;
+  favorite?: boolean;
+  rating?: number;
+  duration?: string;
+  className?: string;
+}) {
+  return (
+    <div className={`group relative aspect-square overflow-hidden rounded-xl bg-white/[0.04] ${className}`}>
+      {loaded ? (
+        <img src={fakeImage(index)} alt="" loading="lazy" className="absolute inset-0 h-full w-full object-cover" />
+      ) : (
+        <div className="absolute inset-0 animate-pulse bg-white/[0.04]" />
+      )}
+      {loaded && favorite ? (
+        <div className="absolute right-1.5 top-1.5 rounded-full bg-black/50 p-1 text-rose-400 backdrop-blur-sm">
+          <svg className="h-3 w-3" viewBox="0 0 24 24" fill="currentColor">
+            <path d="M11.645 20.91l-.007-.003-.022-.012a15.247 15.247 0 01-.383-.218 25.18 25.18 0 01-4.244-3.17C4.688 15.36 2.25 12.174 2.25 8.25 2.25 5.322 4.714 3 7.688 3A5.5 5.5 0 0112 5.052 5.5 5.5 0 0116.313 3c2.973 0 5.437 2.322 5.437 5.25 0 3.925-2.438 7.111-4.739 9.256a25.175 25.175 0 01-4.244 3.17 15.247 15.247 0 01-.383.219l-.022.012-.007.004-.003.001a.752.752 0 01-.704 0l-.003-.001z" />
+          </svg>
+        </div>
+      ) : null}
+      {loaded && rating > 0 ? (
+        <div className="absolute bottom-1.5 left-1.5 flex items-center gap-0.5 rounded-md bg-black/60 px-1.5 py-1 text-amber-300">
+          {Array.from({ length: rating }).map((_, i) => (
+            <svg key={i} className="h-2.5 w-2.5" viewBox="0 0 24 24" fill="currentColor">
+              <path d="M11.48 3.499a.562.562 0 011.04 0l2.125 5.111a.563.563 0 00.475.345l5.518.442c.499.04.701.663.321.988l-4.204 3.602a.563.563 0 00-.182.557l1.285 5.385a.562.562 0 01-.84.61l-4.725-2.885a.563.563 0 00-.586 0L6.982 20.54a.562.562 0 01-.84-.61l1.285-5.386a.563.563 0 00-.182-.557l-4.204-3.602a.563.563 0 01.321-.988l5.518-.442a.563.563 0 00.475-.345L11.48 3.5z" />
+            </svg>
+          ))}
+        </div>
+      ) : null}
+      {loaded && duration ? (
+        <div className="absolute bottom-1.5 right-1.5 rounded-md bg-black/60 px-1.5 py-0.5 text-[10px] font-medium text-white/80">
+          {duration}
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
+export function FakeStageTag({ label, state }: { label: string; state: "active" | "done" | "waiting" }) {
+  const className =
+    state === "active"
+      ? "bg-white/5 text-gray-300"
+      : state === "done"
+        ? "bg-emerald-500/10 text-emerald-400"
+        : "bg-white/4 text-gray-600";
+  return <span className={`rounded-md px-2 py-0.5 text-[11px] ${className}`}>{label}</span>;
+}
+
+export function FakeProgressBar({ fraction, className = "" }: { fraction: number | null; className?: string }) {
+  return (
+    <div className={`h-px overflow-hidden rounded-full bg-white/8 ${className}`}>
+      {fraction === null ? (
+        <div className="h-full w-full animate-pulse bg-blue-500/40" />
+      ) : (
+        <div
+          className="h-full bg-blue-500 transition-[width] duration-300"
+          style={{ width: `${Math.round(Math.min(fraction, 1) * 100)}%` }}
+        />
+      )}
+    </div>
+  );
+}
+
+export function ReplayButton({ onClick, label = "Replay" }: { onClick: () => void; label?: string }) {
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      className="inline-flex items-center gap-1.5 rounded-md border border-white/10 bg-white/[0.04] px-2.5 py-1 text-[11px] text-gray-400 transition-colors hover:bg-white/10 hover:text-gray-200"
+    >
+      <svg className="h-3 w-3" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth={2}>
+        <path strokeLinecap="round" strokeLinejoin="round" d="M4.5 12a7.5 7.5 0 0012.9 5.3M19.5 12A7.5 7.5 0 006.6 6.7M4.5 6.5v3h3M19.5 17.5v-3h-3" />
+      </svg>
+      {label}
+    </button>
+  );
+}
+
+export function formatBytes(bytes: number): string {
+  if (bytes >= 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024 * 1024)).toFixed(1)} GB`;
+  if (bytes >= 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(0)} MB`;
+  if (bytes >= 1024) return `${(bytes / 1024).toFixed(0)} KB`;
+  return `${bytes} B`;
+}

src/store.ts

@@ -2,6 +2,9 @@ import { create } from "zustand";
 import { invoke } from "@tauri-apps/api/core";
 import { listen, UnlistenFn } from "@tauri-apps/api/event";
 import { appDataDir, join } from "@tauri-apps/api/path";
+import { getVersion } from "@tauri-apps/api/app";
+import { check, Update } from "@tauri-apps/plugin-updater";
+import { relaunch } from "@tauri-apps/plugin-process";
 import { notifyTaskComplete } from "./notifications";
 
 // Per-folder debounce timers for batching notifications.
@@ -109,6 +112,8 @@ export interface TaggerModelProgress {
   total_files: number;
   completed_files: number;
   current_file: string | null;
+  downloaded_bytes: number | null;
+  total_bytes: number | null;
   done: boolean;
 }
 
@@ -259,6 +264,33 @@ export type SortOrder =
   | "taken_desc"
   | "taken_asc";
 
+export type UpdateStatus = "idle" | "checking" | "upToDate" | "available" | "downloading" | "installing" | "error";
+
+export type WorkerKey = "thumbnail" | "metadata" | "embedding" | "tagging";
+
+const WORKER_KEYS: WorkerKey[] = ["thumbnail", "metadata", "embedding", "tagging"];
+
+interface FolderWorkerStates {
+  folder_id: number;
+  thumbnail_paused: boolean;
+  metadata_paused: boolean;
+  embedding_paused: boolean;
+  tagging_paused: boolean;
+}
+
+export type FfmpegStatus = "unknown" | "starting" | "downloading" | "unpacking" | "installed" | "error";
+
+interface FfmpegProgressEvent {
+  phase: string;
+  downloaded_bytes: number | null;
+  total_bytes: number | null;
+  error: string | null;
+}
+
+// The Update handle from the plugin carries the download method; it's not
+// serializable state, so it lives outside the store.
+let pendingUpdate: Update | null = null;
+
 interface GalleryState {
   folders: Folder[];
   selectedFolderId: number | null;
@@ -309,6 +341,23 @@ interface GalleryState {
   taggingQueueFolderIds: number[];
   mutedFolderIds: number[];
   notificationsPaused: boolean;
+  // Per-folder background-worker pause flags, shared by the BackgroundTasks
+  // bar and the sidebar folder context menu.
+  workerPaused: Record<number, Record<WorkerKey, boolean>>;
+
+  appVersion: string | null;
+  updateStatus: UpdateStatus;
+  updateVersion: string | null;
+  updateProgress: number | null; // 0..1 download progress, null while size unknown
+  updateError: string | null;
+  updateDismissed: boolean;
+
+  ffmpegStatus: FfmpegStatus;
+  ffmpegProgress: { downloaded_bytes: number; total_bytes: number } | null;
+  ffmpegError: string | null;
+  onboardingCompleted: boolean | null; // null = not loaded yet
+  onboardingOpen: boolean;
+  onboardingStep: number;
 
   taggerModelStatus: TaggerModelStatus | null;
   taggerModelPreparing: boolean;
@@ -387,6 +436,19 @@ interface GalleryState {
   toggleMutedFolder: (folderId: number) => void;
   loadNotificationsPaused: () => Promise<void>;
   setNotificationsPaused: (paused: boolean) => void;
+  loadWorkerStates: () => Promise<void>;
+  setWorkerPaused: (folderId: number, worker: WorkerKey, paused: boolean) => void;
+  setAllWorkersPaused: (folderId: number, paused: boolean) => void;
+  loadAppVersion: () => Promise<void>;
+  checkForUpdates: (options?: { quiet?: boolean }) => Promise<void>;
+  installUpdate: () => Promise<void>;
+  dismissUpdate: () => void;
+  loadFfmpegStatus: () => Promise<void>;
+  retryFfmpegDownload: () => Promise<void>;
+  loadOnboardingCompleted: () => Promise<void>;
+  completeOnboarding: () => void;
+  openOnboarding: () => void;
+  setOnboardingStep: (step: number) => void;
   openAppDataFolder: () => Promise<void>;
   getDatabaseInfo: () => Promise<DatabaseInfo>;
   vacuumDatabase: () => Promise<VacuumResult>;
@@ -664,6 +726,21 @@ export const useGalleryStore = create<GalleryState>((set, get) => ({
   taggingQueueFolderIds: [],
   mutedFolderIds: [],
   notificationsPaused: false,
+  workerPaused: {},
+
+  appVersion: null,
+  updateStatus: "idle",
+  updateVersion: null,
+  updateProgress: null,
+  updateError: null,
+  updateDismissed: false,
+
+  ffmpegStatus: "unknown",
+  ffmpegProgress: null,
+  ffmpegError: null,
+  onboardingCompleted: null,
+  onboardingOpen: false,
+  onboardingStep: 0,
 
   taggerModelStatus: null,
   taggerModelPreparing: false,
@@ -718,16 +795,28 @@ export const useGalleryStore = create<GalleryState>((set, get) => ({
   },
 
   removeFolder: async (folderId) => {
-    await invoke("remove_folder", { folderId });
     const { selectedFolderId, loadFolders, loadImages, loadBackgroundJobProgress } = get();
+    // Optimistically drop it from the sidebar for instant feedback (the backend
+    // delete of its images/thumbnails can take a moment), clearing the active
+    // selection if it was this folder.
+    set((state) => {
+      const folders = state.folders.filter((folder) => folder.id !== folderId);
+      return selectedFolderId === folderId ? { folders, selectedFolderId: null } : { folders };
+    });
+    try {
+      await invoke("remove_folder", { folderId });
+    } catch (error) {
+      // Removal failed — resync the authoritative list and surface the error.
+      await loadFolders();
+      throw error;
+    }
     await loadFolders();
     await loadBackgroundJobProgress();
-    // Invalidate tag cloud and explore-tags cache since library content changed
+    // Invalidate tag cloud and explore-tags cache since library content changed.
     set({ tagCloudFolderId: undefined, tagCloudEntries: [], exploreTagsFolderId: undefined });
-    if (selectedFolderId === folderId) {
-      set({ selectedFolderId: null });
-      await loadImages(true);
-    }
+    // Always refresh the gallery: the removed folder's images may be on screen
+    // (e.g. in All Media), not only when that folder was the active selection.
+    await loadImages(true);
   },
 
   reindexFolder: async (folderId) => {
@@ -1468,6 +1557,183 @@ export const useGalleryStore = create<GalleryState>((set, get) => ({
     void invoke("set_notifications_paused", { paused }).catch(() => {});
   },
 
+  loadWorkerStates: async () => {
+    const folderIds = get().folders.map((folder) => folder.id);
+    if (folderIds.length === 0) {
+      set({ workerPaused: {} });
+      return;
+    }
+    try {
+      const states = await invoke<FolderWorkerStates[]>("get_worker_states", { folderIds });
+      set({
+        workerPaused: Object.fromEntries(
+          states.map((state) => [
+            state.folder_id,
+            {
+              thumbnail: state.thumbnail_paused,
+              metadata: state.metadata_paused,
+              embedding: state.embedding_paused,
+              tagging: state.tagging_paused,
+            },
+          ]),
+        ),
+      });
+    } catch {
+      // leave the existing snapshot in place
+    }
+  },
+
+  setWorkerPaused: (folderId, worker, paused) => {
+    set((state) => {
+      const current = state.workerPaused[folderId] ?? {
+        thumbnail: false,
+        metadata: false,
+        embedding: false,
+        tagging: false,
+      };
+      return {
+        workerPaused: {
+          ...state.workerPaused,
+          [folderId]: { ...current, [worker]: paused },
+        },
+      };
+    });
+    void invoke("set_worker_paused", { worker, folderId, paused }).catch(() => {});
+  },
+
+  setAllWorkersPaused: (folderId, paused) => {
+    set((state) => ({
+      workerPaused: {
+        ...state.workerPaused,
+        [folderId]: { thumbnail: paused, metadata: paused, embedding: paused, tagging: paused },
+      },
+    }));
+    for (const worker of WORKER_KEYS) {
+      void invoke("set_worker_paused", { worker, folderId, paused }).catch(() => {});
+    }
+  },
+
+  loadAppVersion: async () => {
+    try {
+      set({ appVersion: await getVersion() });
+    } catch {
+      // leave null; the UI falls back to a dash
+    }
+  },
+
+  checkForUpdates: async (options) => {
+    const quiet = options?.quiet ?? false;
+    const { updateStatus } = get();
+    if (updateStatus === "checking" || updateStatus === "downloading" || updateStatus === "installing") return;
+
+    set({ updateStatus: "checking", updateError: null });
+    try {
+      const update = await check();
+      if (update) {
+        pendingUpdate = update;
+        set({ updateStatus: "available", updateVersion: update.version, updateDismissed: false });
+      } else {
+        pendingUpdate = null;
+        set({ updateStatus: "upToDate", updateVersion: null });
+      }
+    } catch (error) {
+      pendingUpdate = null;
+      if (quiet) {
+        // Launch-time check: stay silent on network/endpoint failures.
+        set({ updateStatus: "idle" });
+      } else {
+        set({ updateStatus: "error", updateError: error instanceof Error ? error.message : String(error) });
+      }
+    }
+  },
+
+  installUpdate: async () => {
+    const update = pendingUpdate;
+    if (!update || get().updateStatus !== "available") return;
+
+    set({ updateStatus: "downloading", updateProgress: null, updateError: null });
+    try {
+      let contentLength: number | null = null;
+      let downloaded = 0;
+      await update.downloadAndInstall((event) => {
+        switch (event.event) {
+          case "Started":
+            contentLength = event.data.contentLength ?? null;
+            set({ updateProgress: contentLength ? 0 : null });
+            break;
+          case "Progress":
+            downloaded += event.data.chunkLength;
+            if (contentLength) {
+              set({ updateProgress: Math.min(downloaded / contentLength, 1) });
+            }
+            break;
+          case "Finished":
+            set({ updateStatus: "installing", updateProgress: 1 });
+            break;
+        }
+      });
+      await relaunch();
+    } catch (error) {
+      set({ updateStatus: "error", updateError: error instanceof Error ? error.message : String(error) });
+    }
+  },
+
+  dismissUpdate: () => set({ updateDismissed: true }),
+
+  loadFfmpegStatus: async () => {
+    try {
+      const status = await invoke<{ installed: boolean; downloading: boolean; failed: boolean }>(
+        "get_ffmpeg_status",
+      );
+      if (status.installed) {
+        set({ ffmpegStatus: "installed" });
+      } else if (status.failed) {
+        // The download failed before our event listener attached — surface
+        // the error state so the retry button is reachable.
+        set({ ffmpegStatus: "error", ffmpegError: "The download could not be completed. Check your connection and retry." });
+      } else {
+        // Not installed and possibly not downloading yet — the provision
+        // thread starts with the app, so treat the gap as "starting" and let
+        // the first ffmpeg-progress event settle the real state.
+        set({ ffmpegStatus: "starting" });
+      }
+    } catch {
+      // leave "unknown"; events will correct it
+    }
+  },
+
+  retryFfmpegDownload: async () => {
+    set({ ffmpegStatus: "starting", ffmpegError: null, ffmpegProgress: null });
+    try {
+      await invoke("retry_ffmpeg_download");
+    } catch (error) {
+      set({ ffmpegStatus: "error", ffmpegError: error instanceof Error ? error.message : String(error) });
+    }
+  },
+
+  loadOnboardingCompleted: async () => {
+    try {
+      const completed = await invoke<boolean>("get_onboarding_completed");
+      set(
+        completed
+          ? { onboardingCompleted: true }
+          : { onboardingCompleted: false, onboardingOpen: true, onboardingStep: 0 },
+      );
+    } catch {
+      // If the flag can't be read, don't trap the user in onboarding.
+      set({ onboardingCompleted: true });
+    }
+  },
+
+  completeOnboarding: () => {
+    set({ onboardingOpen: false, onboardingCompleted: true });
+    void invoke("set_onboarding_completed", { completed: true }).catch(() => {});
+  },
+
+  openOnboarding: () => set({ onboardingOpen: true, onboardingStep: 0 }),
+
+  setOnboardingStep: (step) => set({ onboardingStep: step }),
+
   openAppDataFolder: async () => {
     await invoke("open_app_data_folder");
   },
@@ -1976,6 +2242,33 @@ export const useGalleryStore = create<GalleryState>((set, get) => ({
       void get().loadFolders();
     });
 
+    const unlistenFfmpegProgress = await listen<FfmpegProgressEvent>("ffmpeg-progress", (event) => {
+      const payload = event.payload;
+      switch (payload.phase) {
+        case "starting":
+          set({ ffmpegStatus: "starting", ffmpegError: null });
+          break;
+        case "downloading":
+          set({
+            ffmpegStatus: "downloading",
+            ffmpegProgress:
+              payload.downloaded_bytes !== null && payload.total_bytes !== null
+                ? { downloaded_bytes: payload.downloaded_bytes, total_bytes: payload.total_bytes }
+                : null,
+          });
+          break;
+        case "unpacking":
+          set({ ffmpegStatus: "unpacking" });
+          break;
+        case "done":
+          set({ ffmpegStatus: "installed", ffmpegProgress: null, ffmpegError: null });
+          break;
+        case "error":
+          set({ ffmpegStatus: "error", ffmpegError: payload.error ?? "Download failed" });
+          break;
+      }
+    });
+
     return () => {
       unlistenProgress();
       unlistenMediaJobs();
@@ -1985,6 +2278,7 @@ export const useGalleryStore = create<GalleryState>((set, get) => ({
       unlistenThumbnails();
       unlistenWatcherDeleted();
       unlistenFolderCounts();
+      unlistenFfmpegProgress();
     };
   },
 }));