Update

kitty-direct sends c= but no rows through ConPTY (the terminal guesses the height and stretches); the plain kitty type needs tty pixel queries that ConPTY drops. The iterm type with preserveAspectRatio=1 letterboxes any aspect ratio.

.dockerignore

@@ -0,0 +1,35 @@
+# Build context is the repository root (see deploy/J621-Backend and
+# deploy/J621-Frontend). Keep the context small and, more importantly, keep
+# secrets and runtime data out of the images.
+
+# Version control / tooling
+.git
+.gitignore
+.dockerignore
+
+# Python: the dev virtualenv, caches, and anything generated at runtime
+backend/venv/
+**/__pycache__/
+**/*.py[cod]
+backend/db.sqlite3
+backend/logs/
+backend/staticfiles/
+
+# Secrets and media: the .env holds SECRET_KEY and DB passwords, media/ is
+# the actual library. The deploy composes mount these at runtime instead.
+backend/.env
+backend/.env.*
+backend/media/
+
+# Frontend build artefacts (npm ci installs fresh from the lockfile)
+frontend/node_modules/
+frontend/dist/
+
+# Deploy runtime state and env
+deploy/.env
+deploy/.env.*
+deploy/data/
+deploy/tailscale-state/
+
+# Misc
+*.log

.gitea/workflows/cd.yml

@@ -0,0 +1,197 @@
+# J621 CD — manual release workflow (Actions tab -> "Run workflow").
+#
+# One dispatch does everything; each half can be skipped with the `images`
+# and `desktop` inputs:
+#   * builds and pushes the backend + frontend images (multi-arch, :latest
+#     and :<short-sha>, GIT_HASH baked in for the version pill),
+#   * builds the desktop packages and attaches them (plus the update
+#     metadata) to the Gitea release tagged `desktop-v<package.json version>`.
+#
+# The desktop build also attaches the update metadata (latest*.yml) to the
+# release; that is the desktop updater's feed, resolved through the Gitea API
+# at check time (see desktop/README.md). The older website feed
+# (deploy/data/desktop, served at /desktop/) is runtime state on the deploy
+# host and only needed for installs before 0.1.2; it is refreshed with
+# `deploy/push_desktop.sh` from a machine that can reach the deploy host.
+#
+# Registry login uses a repo PAT with the minimal write:package scope (the
+# Gitea registry rejects the automatic job token, go-gitea/gitea#23642);
+# release creation uses the automatic job token. Jobs run on the user-scoped
+# nitro-ci runner (ubuntu-latest).
+
+name: CD
+
+on:
+  workflow_dispatch:
+    inputs:
+      images:
+        description: Build and push the Docker images
+        required: false
+        default: "true"
+      desktop:
+        description: Build the desktop release
+        required: false
+        default: "true"
+      platforms:
+        description: Image platforms (comma separated)
+        required: false
+        default: linux/amd64,linux/arm64
+      windows:
+        description: Also cross-build the Windows installer (needs wine, slow)
+        required: false
+        default: "false"
+
+concurrency:
+  group: cd
+  cancel-in-progress: false
+
+jobs:
+  images:
+    name: Build & push images
+    if: ${{ inputs.images != 'false' }}
+    runs-on: ubuntu-latest
+    # The Gitea container registry does not accept the automatic job token
+    # (go-gitea/gitea#23642 is still open), so the push uses a repo PAT with
+    # the minimal write:package scope. Releases use the job token instead.
+    permissions:
+      contents: read
+    env:
+      REGISTRY_USER: ${{ secrets.REGISTRY_USER }}
+      REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+      PLATFORMS: ${{ inputs.platforms || 'linux/amd64,linux/arm64' }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Check the registry credentials
+        run: |
+          if [ -z "$REGISTRY_USER" ] || [ -z "$REGISTRY_TOKEN" ]; then
+            echo "Set the REGISTRY_USER and REGISTRY_TOKEN repo secrets" >&2
+            echo "(a PAT with the write:package scope)." >&2
+            exit 1
+          fi
+
+      - name: Register binfmt (multi-arch builds)
+        run: docker run --privileged --rm tonistiigi/binfmt --install all
+
+      - name: Build & push both images
+        run: |
+          set -euo pipefail
+          SHA="$(git rev-parse --short HEAD)"
+          echo "Publishing $SHA for $PLATFORMS"
+          PLATFORMS="$PLATFORMS" ./deploy/push_frontend.sh "$SHA"
+          PLATFORMS="$PLATFORMS" ./deploy/push_backend.sh "$SHA"
+
+  desktop:
+    name: Desktop release
+    if: ${{ inputs.desktop != 'false' }}
+    runs-on: ubuntu-latest
+    # Creating the release and uploading its assets uses the automatic job
+    # token, so it needs write access to the repository's releases.
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+
+      - name: Install packaging tools
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends fakeroot libarchive-tools
+          if [ "${{ inputs.windows }}" = "true" ]; then
+            # electron-builder runs the 32-bit NSIS installer under wine to
+            # build the uninstaller: that needs a virtual display (Xvfb) and
+            # 32-bit wine libraries.
+            sudo dpkg --add-architecture i386
+            sudo apt-get update
+            sudo apt-get install -y --no-install-recommends xvfb wine wine32:i386
+          fi
+
+      - name: Install frontend + desktop dependencies
+        run: |
+          npm --prefix frontend ci --no-audit --no-fund
+          npm --prefix desktop ci --no-audit --no-fund
+
+      - name: Build desktop packages
+        env:
+          # Keep wine from trying to fetch Gecko/Mono on first run.
+          WINEDLLOVERRIDES: mscoree,mshtml=
+        run: |
+          if [ "${{ inputs.windows }}" = "true" ]; then
+            xvfb-run -a ./deploy/build_desktop.sh --all
+          else
+            ./deploy/build_desktop.sh --linux
+          fi
+
+      - name: Add the Gitea release
+        env:
+          GITEA_TOKEN: ${{ secrets.GITEA_TOKEN || secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+          VERSION="$(node -p "require('./desktop/package.json').version")"
+          TAG="desktop-v$VERSION"
+          API="${{ github.server_url }}/api/v1/repos/${{ github.repository }}"
+          AUTH="Authorization: token $GITEA_TOKEN"
+
+          NOTES="$(printf 'J621 desktop %s\n\n' "$VERSION"
+            cd desktop/release
+            sha256sum ./*.deb ./*.pkg.tar.zst ./*.exe 2>/dev/null || true)"
+
+          RELEASE_ID="$(curl -sf -H "$AUTH" "$API/releases/tags/$TAG" \
+            | python3 -c 'import json,sys; print(json.load(sys.stdin).get("id",""))' \
+            2>/dev/null || true)"
+          if [ -z "$RELEASE_ID" ]; then
+            echo "Creating release $TAG"
+            PAYLOAD="$(python3 - "$TAG" "${{ github.sha }}" "$NOTES" <<'PY'
+          import json, sys
+          print(json.dumps({
+              "tag_name": sys.argv[1],
+              "name": sys.argv[1],
+              "body": sys.argv[3],
+              "target_commitish": sys.argv[2],
+          }))
+          PY
+          )"
+            RELEASE_ID="$(curl -sf -X POST -H "$AUTH" \
+              -H "Content-Type: application/json" -d "$PAYLOAD" "$API/releases" \
+              | python3 -c 'import json,sys; print(json.load(sys.stdin)["id"])')"
+          else
+            echo "Release $TAG already exists (id $RELEASE_ID); attaching missing files."
+          fi
+
+          EXISTING="$(curl -sf -H "$AUTH" "$API/releases/$RELEASE_ID/assets" \
+            || echo '[]')"
+          for FILE in desktop/release/*"$VERSION"*.deb \
+                      desktop/release/*"$VERSION"*.pkg.tar.zst \
+                      desktop/release/latest-linux.yml \
+                      desktop/release/latest.yml \
+                      desktop/release/*"$VERSION"*.exe \
+                      desktop/release/*"$VERSION"*.exe.blockmap; do
+            [ -e "$FILE" ] || continue
+            NAME="$(basename "$FILE")"
+            # Replace the asset when it is already there: latest*.yml must
+            # reference the installers built by *this* run (NSIS builds are
+            # not bit-reproducible), so old copies are deleted first.
+            ASSET_ID="$(printf '%s' "$EXISTING" | python3 -c '
+          import json, sys
+          name = sys.argv[1]
+          print(next((str(a["id"]) for a in json.load(sys.stdin) if a["name"] == name), ""))
+          ' "$NAME")"
+            if [ -n "$ASSET_ID" ]; then
+              echo "    replacing $NAME"
+              curl -sf -X DELETE -H "$AUTH" \
+                "$API/releases/$RELEASE_ID/assets/$ASSET_ID" >/dev/null
+            else
+              echo "    attaching $NAME"
+            fi
+            # Names like "J621 Setup 0.1.1.exe" contain spaces: encode them
+            # or curl refuses the URL (exit 3).
+            ENCODED="$(python3 -c 'import sys, urllib.parse; print(urllib.parse.quote(sys.argv[1]))' "$NAME")"
+            curl -sf -X POST -H "$AUTH" -H "Content-Type: application/octet-stream" \
+              --data-binary @"$FILE" "$API/releases/$RELEASE_ID/assets?name=$ENCODED" >/dev/null
+          done
+          echo "Release: ${{ github.server_url }}/${{ github.repository }}/releases/tag/$TAG"

.gitea/workflows/ci.yml

@@ -0,0 +1,101 @@
+# J621 CI — runs on every push (and pull request): Django checks + the full
+# backend test suite against MariaDB/Redis, and the frontend type-check,
+# lint and production build.
+#
+# Runner: the "nitro-ci" act_runner with the custom `ubuntu-latest` label.
+
+name: CI
+
+# Tests and builds only need to read the repository; the automatic job token
+# stays read-only.
+permissions:
+  contents: read
+
+on:
+  push:
+    branches: ["**"]
+    tags-ignore: ["**"]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  backend:
+    name: Backend tests
+    runs-on: ubuntu-latest
+    services:
+      mariadb:
+        image: mariadb:11.4
+        env:
+          MARIADB_ROOT_PASSWORD: root
+          MARIADB_DATABASE: j621
+          MARIADB_USER: j621
+          MARIADB_PASSWORD: j621
+        options: >-
+          --health-cmd="healthcheck.sh --connect --innodb_initialized"
+          --health-interval=5s
+          --health-timeout=5s
+          --health-retries=12
+      redis:
+        image: redis:7-alpine
+        options: >-
+          --health-cmd="redis-cli ping"
+          --health-interval=5s
+          --health-timeout=5s
+          --health-retries=12
+    env:
+      # Connect as root so Django can create the test database itself;
+      # everything else mirrors the development defaults.
+      DB_HOST: mariadb
+      DB_PORT: "3306"
+      DB_NAME: j621
+      DB_USER: root
+      DB_PASSWORD: root
+      REDIS_URL: redis://redis:6379/1
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+
+      - name: Install backend dependencies
+        run: pip install -r backend/requirements.txt
+
+      - name: Django system checks
+        working-directory: backend
+        run: python manage.py check
+
+      - name: Backend tests
+        working-directory: backend
+        run: >-
+          python manage.py test
+          apps.core.tests
+          apps.library.tests
+          apps.follows.tests
+          apps.accounts.tests
+
+  frontend:
+    name: Frontend build & lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+
+      - name: Install frontend dependencies
+        working-directory: frontend
+        run: npm ci
+
+      - name: Lint
+        working-directory: frontend
+        run: npm run lint
+
+      - name: Type-check & build
+        working-directory: frontend
+        run: npm run build

AGENTS.md

@@ -2,6 +2,11 @@ Use the venv on backend/venv/
 
 DO NOT mess with the system's python
 
+The original J621 (Django) app is kept for reference at
+    /mnt/Disco/Proyects/Python3.13/J621-Django/
+Consult it when matching original behavior (batch sizes for e621 lookups,
+per-page sets, upload flow) instead of guessing.
+
 For Frontend work:
 
 read both Frontend Design related Markdown files on the frontend/ folder
@@ -44,6 +49,17 @@ Project constraints (do not regress):
 - Periodic commands (follow syncs, similarity cleanup, guest blacklist
   refresh) run in the composes' `scheduler` service — the backend image with
   the j621-scheduler entrypoint, intervals via J621_*_EVERY. No host cron.
+- CI/CD lives in .gitea/workflows: ci.yml runs on every push/PR (Django checks
+  + the full backend suite against MariaDB/Redis service containers, frontend
+  lint/type-check/build); cd.yml is manual and builds/pushes both images
+  multi-arch plus the desktop packages (attached to the Gitea release
+  `desktop-v<version>`). Jobs run on the user-scoped runners: `ubuntu-latest`
+  on nitro-ci, `desktop` on msi-mortar-ci. Do not add actions/cache
+  (`cache: pip`/`npm`) to these workflows: Gitea's cache service hangs the job
+  on restore/save. Desktop updates read the release assets (latest*.yml) from
+  the Gitea API at check time; the older website feed (deploy/data/desktop)
+  only matters for installs before 0.1.2 and is refreshed with
+  `deploy/push_desktop.sh` from a machine with SSH to the deploy host.
 - Security/permission tests live in backend/apps/core/tests and need a
   one-time grant: GRANT ALL ON `test_j621`.* TO 'j621'@'%';
 
@@ -80,7 +96,12 @@ Security hardening (do not weaken):
   SECRET_KEY (apps/accounts/crypto.py); rotating SECRET_KEY invalidates them
   (and all signed media URLs), so users must re-enter the key.
 - API throttles live in REST_FRAMEWORK (env-overridable): anon 120/min,
-  user 600/min, login 5/min, register 20/hour, e621_proxy 60/hour.
+  user 600/min, login 5/min, register 20/hour, e621_proxy 60/hour. Signed
+  media URLs (raw/thumbnail/staged-file/similarity-file actions) are exempt
+  on purpose: <img>/<video> tags fetch them without an Authorization header,
+  so a gallery would otherwise drain the anonymous bucket and get 429 JSON
+  instead of images. THROTTLE_ENABLED=false removes the anon+user limits for
+  private/tailnet deployments (the login/register/proxy guards stay).
 - Only admins (superusers) may grant/revoke the staff role or delete
   staff/admin accounts; staff manage regular/uploader accounts only.
 - Storage, duplicates, delete, temp-clear, uploads and downloads require

README.md

@@ -8,7 +8,7 @@ Self-hosted media library and e621 archive manager, rebuilt as a **React SPA + D
 backend/    Django 6 + DRF API (MariaDB + Redis via docker compose)
 frontend/   Vite + React + TypeScript SPA
 deploy/     Docker images, compose variants and Tailscale serve configs
-extras/     shell integrations (fish_greeting with fastfetch)
+extras/     shell integrations (fish + PowerShell greetings with fastfetch, gm-switch)
 ```
 
 ## Development
@@ -75,8 +75,11 @@ curl -H "Authorization: Token <token>" \
   the bundled nginx those aliases negotiate on `Accept`: browsers get the SPA
   page, requesters like curl/wget/fastfetch get the JSON. `/api/random/` is
   the unambiguous path for scripts; 404 when nothing matches the filters.
-- A ready-made shell greeting that uses this endpoint lives in
-  [`extras/fish_greeting/`](extras/fish_greeting/README.md).
+- Ready-made shell greetings that use this endpoint live in
+  [`extras/fish_greeting/`](extras/fish_greeting/README.md) (Linux/fish) and
+  [`extras/powershell_greeting/`](extras/powershell_greeting/README.md)
+  (Windows/PowerShell); [`extras/win-gm-switch/`](extras/win-gm-switch/)
+  (Rust) switches the rating mode on both.
 - **Scoped tokens for scripts**: the Account page's *Shell tokens* section
   (also `/tokens`) issues `j621r_…` tokens that only authenticate
   `/api/random/` — the rest of the API rejects them. They are stored as

ROADMAP.md

@@ -20,6 +20,13 @@ they land.
   - [x] Tag cloud in the sidebar (click to search, hidden from guests for
         blacklisted items)
   - [x] Status filter (matched / not_found / deleted / custom / unknown)
+- [x] **Cacheable media serving**
+  - [x] Stable signed URLs (7 d TTL, 24 h rotation) plus a `v=<md5>` cache
+        buster, so replacing a file under the same J-ID invalidates it
+  - [x] ETag/Last-Modified and a private `Cache-Control` (immutable for
+        versioned media), conditional 304s
+  - [x] Real 480 px image thumbnails (cached by MD5) instead of serving
+        full-size originals through the thumbnail endpoint
 
 - [x] **Random image** endpoint and page: `GET /api/random/` (aliases
       `/random`, `/random/`) with `rating=s,q,e` filters; fastfetch mode
@@ -95,18 +102,25 @@ Files now stage first and are resolved before entering the library.
   - [x] `cleanup_temp_uploads` command for old staged files
 - [x] **Auto-upload / auto-match**
   - [x] MD5 computed on staging; exact duplicates resolve immediately
-  - [x] MD5 batch-checked against e621; matches auto-complete with post
-        metadata stored and rating seeded
-- [x] **IQDB similarity on upload** (SPA-driven)
-  - [x] Automatic + manual IQDB checks with candidate posts
-  - [x] "Visual Similarity Detected" state with candidate picker
-  - [x] Perceptual-hash comparison against the library (staged uploads are
-        flagged with their library matches as soon as they land)
+  - [x] MD5 batch-checked against e621 in chunks of 75; matches auto-complete
+        with post metadata stored and rating seeded
+- [x] **Background pipeline** (server-side)
+  - [x] Daemon-thread worker runs MD5 → visual similarity → IQDB for every
+        staged upload, so the work continues after the page or tab is closed
+  - [x] Durable progress (`UploadRun` + per-file phase flags) polled by the
+        shell indicator; rate-limited runs retry with backoff
+  - [x] Perceptual-hash comparison against the library, loaded once per batch
+  - [x] IQDB candidates stored with one batched enrichment request
+  - [x] Indexed uploads are announced through a bounded per-run feed and the
+        staged row is deleted; nothing persists on the board to dismiss
 - [x] **Upload UI**
-  - [x] Three-column board: Pending & Unmatched / Visual Similarity Detected /
-        Auto-uploaded & Indexed
+  - [x] Four-column board: Pending & Unmatched / Visual Similarity Detected /
+        Auto-uploaded & Indexed (session feed) / Failed, private per user
+        (staff included)
   - [x] Metadata modal (link to e621 post, IQDB candidates, custom metadata)
-  - [x] Per-file progress plus batch processing indicator
+  - [x] Per-file progress plus background pipeline status
+  - [x] Bulk actions: bulk rate and discard all (chunked past the API's
+        1000-id cap)
 
 ## 4. Staff tools
 
@@ -145,7 +159,9 @@ Files now stage first and are resolved before entering the library.
 - [x] Profile pictures: staff Users page and a self-service Account picker
       (searchable library grid, remove supported) set avatars from library J-IDs
 - [x] Profile extras: per-user landing page, default rating filter/sort, items
-      per page and thumbnail size (synced to the account, applied on load)
+      per page and thumbnail size (synced to the account, applied on load),
+      plus e621 posts per page (48/100/200/320) for the Online browser and
+      pool loading
 - [x] Backend-less local mode: with no backend connected the SPA runs on the
       e621-facing pages only (Online, Pools) using credentials stored in the
       browser, and the shell offers a "Setup Backend" button instead

backend/apps/accounts/serializers.py

@@ -134,5 +134,7 @@ class PreferencesSerializer(serializers.Serializer):
     ordering = serializers.CharField(max_length=30, required=False)
     per_page = serializers.IntegerField(min_value=12, max_value=200, required=False)
     zoom = serializers.IntegerField(min_value=120, max_value=400, required=False)
+    # e621 renders at most 320 posts per request.
+    e621_per_page = serializers.IntegerField(min_value=12, max_value=320, required=False)
     # Open Online with the order:hot metatag when no search is given.
     online_hot_default = serializers.BooleanField(required=False)

backend/apps/accounts/tests/test_preferences.py

@@ -0,0 +1,49 @@
+"""Per-user browse preferences: validation and merge semantics."""
+
+import json
+
+from django.contrib.auth import get_user_model
+from django.test import Client, TestCase
+
+from rest_framework.authtoken.models import Token
+
+User = get_user_model()
+
+
+class PreferenceTests(TestCase):
+    def setUp(self):
+        self.user = User.objects.create_user(
+            username="prefs-user", password="prefs-pass-123456"
+        )
+        self.client = Client()
+        self.client.defaults["HTTP_AUTHORIZATION"] = (
+            f"Token {Token.objects.create(user=self.user).key}"
+        )
+
+    def post(self, payload):
+        return self.client.post(
+            "/api/auth/preferences/",
+            data=json.dumps(payload),
+            content_type="application/json",
+        )
+
+    def test_e621_per_page_round_trips_within_range(self):
+        response = self.post({"e621_per_page": 320})
+        self.assertEqual(response.status_code, 200)
+        self.assertEqual(response.json()["e621_per_page"], 320)
+        self.assertEqual(
+            self.client.get("/api/auth/me/").json()["preferences"]["e621_per_page"],
+            320,
+        )
+
+    def test_e621_per_page_rejects_out_of_range(self):
+        for value in (0, 8, 321, 1000):
+            self.assertEqual(self.post({"e621_per_page": value}).status_code, 400, value)
+
+    def test_merge_keeps_other_keys(self):
+        self.post({"ratings": ["s"], "e621_per_page": 100})
+        response = self.post({"per_page": 24})
+        data = response.json()
+        self.assertEqual(data["ratings"], ["s"])
+        self.assertEqual(data["e621_per_page"], 100)
+        self.assertEqual(data["per_page"], 24)

backend/apps/core/cache.py

@@ -0,0 +1,108 @@
+"""Redis cache that degrades instead of taking the whole API down.
+
+Redis backs the DRF throttles and a few caches (storage stats, guest
+blacklist, tag clouds). With Django's stock ``RedisCache``, a Redis that is
+unreachable — or merely refusing writes because its RDB snapshot failed, the
+default ``stop-writes-on-bgsave-error`` behaviour — raises inside the
+throttle check on every request, so a cache outage becomes a blanket 500.
+
+This backend treats cache failures as misses: rate limits and cached values
+simply stop working until Redis is back, and the first failure per worker is
+logged once so the cause is still visible.
+"""
+
+import logging
+
+from django.core.cache.backends.redis import RedisCache
+
+logger = logging.getLogger(__name__)
+
+_warned = False
+
+
+def _degrade(operation: str, error: Exception, default):
+    global _warned
+    if not _warned:
+        _warned = True
+        logger.warning(
+            "Cache unavailable (%s failed: %s) — continuing without it.",
+            operation,
+            error,
+        )
+    return default
+
+
+class ResilientRedisCache(RedisCache):
+    """``RedisCache`` where a broken Redis behaves like an empty cache."""
+
+    def add(self, *args, **kwargs):
+        try:
+            return super().add(*args, **kwargs)
+        except Exception as error:  # noqa: BLE001 - any backend failure degrades
+            return _degrade("add", error, False)
+
+    def get(self, key, default=None, version=None):
+        try:
+            return super().get(key, default, version)
+        except Exception as error:  # noqa: BLE001
+            return _degrade("get", error, default)
+
+    def set(self, *args, **kwargs):
+        try:
+            return super().set(*args, **kwargs)
+        except Exception as error:  # noqa: BLE001
+            return _degrade("set", error, None)
+
+    def touch(self, *args, **kwargs):
+        try:
+            return super().touch(*args, **kwargs)
+        except Exception as error:  # noqa: BLE001
+            return _degrade("touch", error, False)
+
+    def delete(self, *args, **kwargs):
+        try:
+            return super().delete(*args, **kwargs)
+        except Exception as error:  # noqa: BLE001
+            return _degrade("delete", error, False)
+
+    def get_many(self, *args, **kwargs):
+        try:
+            return super().get_many(*args, **kwargs)
+        except Exception as error:  # noqa: BLE001
+            return _degrade("get_many", error, {})
+
+    def has_key(self, *args, **kwargs):
+        try:
+            return super().has_key(*args, **kwargs)
+        except Exception as error:  # noqa: BLE001
+            return _degrade("has_key", error, False)
+
+    def incr(self, *args, **kwargs):
+        try:
+            return super().incr(*args, **kwargs)
+        except Exception as error:  # noqa: BLE001
+            return _degrade("incr", error, None)
+
+    def set_many(self, *args, **kwargs):
+        try:
+            return super().set_many(*args, **kwargs)
+        except Exception as error:  # noqa: BLE001
+            return _degrade("set_many", error, [])
+
+    def delete_many(self, *args, **kwargs):
+        try:
+            return super().delete_many(*args, **kwargs)
+        except Exception as error:  # noqa: BLE001
+            return _degrade("delete_many", error, None)
+
+    def clear(self, *args, **kwargs):
+        try:
+            return super().clear(*args, **kwargs)
+        except Exception as error:  # noqa: BLE001
+            return _degrade("clear", error, None)
+
+    def close(self, *args, **kwargs):
+        try:
+            return super().close(*args, **kwargs)
+        except Exception as error:  # noqa: BLE001
+            return _degrade("close", error, None)

backend/apps/core/tests/test_cache.py

@@ -0,0 +1,36 @@
+"""A broken Redis must degrade the cache, not 500 the API.
+
+A Redis that cannot persist (the default ``stop-writes-on-bgsave-error``)
+or is simply unreachable used to raise inside the DRF throttle check on
+every request; ``ResilientRedisCache`` treats that as a cache miss.
+"""
+
+from unittest import mock
+
+from django.core.cache import cache
+from django.core.cache.backends.redis import RedisCacheClient
+from django.test import SimpleTestCase
+
+
+def failing(method: str):
+    return mock.patch.object(
+        RedisCacheClient,
+        method,
+        side_effect=RuntimeError("redis is down"),
+    )
+
+
+class ResilientCacheTests(SimpleTestCase):
+    def test_get_returns_the_default_when_redis_fails(self):
+        with failing("get"):
+            self.assertIsNone(cache.get("j621-cache-test"))
+            self.assertEqual(cache.get("j621-cache-test", "fallback"), "fallback")
+
+    def test_writes_report_failure_without_raising(self):
+        with failing("set"):
+            self.assertIsNone(cache.set("j621-cache-test", "value"))
+
+    def test_bulk_and_delete_operations_degrade(self):
+        with failing("get_many"), failing("delete"):
+            self.assertEqual(cache.get_many(["a", "b"]), {})
+            self.assertFalse(cache.delete("a"))

backend/apps/core/tests/test_security.py

@@ -36,6 +36,7 @@ from apps.library.models import (
     TempUpload,
 )
 from apps.library.services import MEDIA_FILE_SALT
+from apps.library.signing_urls import sign_payload
 
 User = get_user_model()
 
@@ -122,21 +123,15 @@ class SecurityTestCase(TestCase):
         return item
 
     def old_signature(self, item, action="raw", age=3 * 86400):
-        """A valid signature minted `age` seconds ago."""
-        real_time = signing.time
-
-        class Backdated:
-            def time(self):
-                return real_time.time() - age
-
-        try:
-            signing.time = Backdated()
-            return signing.dumps(
-                {"item": item.id, "user": self.users["sec-uploader"].id, "action": action},
-                salt=MEDIA_FILE_SALT,
-            )
-        finally:
-            signing.time = real_time
+        """A signed media URL whose expiry is `age` seconds in the past."""
+        return signing.Signer(salt=MEDIA_FILE_SALT).sign_object(
+            {
+                "item": item.id,
+                "user": self.users["sec-uploader"].id,
+                "action": action,
+                "exp": int(time.time()) - age,
+            }
+        )
 
 
 class GuestVisibilityTests(SecurityTestCase):
@@ -183,9 +178,9 @@ class GuestVisibilityTests(SecurityTestCase):
     def test_authenticated_users_and_signed_urls_see_protected_items(self):
         uploader = self.client_for("sec-uploader")
         self.assertEqual(uploader.get(f"/api/files/J-{self.hidden.id}/").status_code, 200)
-        signed = signing.dumps(
+        signed = sign_payload(
             {"item": self.hidden.id, "user": self.users["sec-uploader"].id, "action": "raw"},
-            salt=MEDIA_FILE_SALT,
+            MEDIA_FILE_SALT,
         )
         self.assertEqual(
             self.guest.get(f"/api/files/J-{self.hidden.id}/raw/?sig={signed}").status_code,
@@ -193,9 +188,9 @@ class GuestVisibilityTests(SecurityTestCase):
         )
 
     def test_signature_integrity(self):
-        signed = signing.dumps(
+        signed = sign_payload(
             {"item": self.hidden.id, "user": self.users["sec-uploader"].id, "action": "raw"},
-            salt=MEDIA_FILE_SALT,
+            MEDIA_FILE_SALT,
         )
         raw = f"/api/files/J-{self.hidden.id}/raw/"
         thumbnail = f"/api/files/J-{self.hidden.id}/thumbnail/"
@@ -203,10 +198,29 @@ class GuestVisibilityTests(SecurityTestCase):
         self.assertEqual(self.guest.get(f"{raw}?sig={signed[:-4]}AAAA").status_code, 404)
         # Valid signature, wrong action.
         self.assertEqual(self.guest.get(f"{thumbnail}?sig={signed}").status_code, 404)
-        # Expired signature (minted three days ago).
+        # Expired signature (expiry three days ago).
         expired = self.old_signature(self.hidden)
         self.assertEqual(self.guest.get(f"{raw}?sig={expired}").status_code, 404)
 
+    def test_signed_media_urls_are_stable_and_versioned(self):
+        """The same item must keep the same URL across responses.
+
+        A per-second signature made browsers re-download every image on every
+        poll; the MD5 version parameter busts caches only when the file itself
+        changes (the optimize flow rewrites files under the same J-ID).
+        """
+        item = self.visible
+        first = services.signed_media_url(item, self.users["sec-uploader"])
+        time.sleep(1.1)
+        second = services.signed_media_url(item, self.users["sec-uploader"])
+        self.assertEqual(first, second)
+        self.assertIn(f"v={item.md5}", first)
+        MediaItem.objects.filter(pk=item.pk).update(md5="b" * 32)
+        item.refresh_from_db()
+        self.assertNotEqual(
+            services.signed_media_url(item, self.users["sec-uploader"]), first
+        )
+
 
 class RoleBoundaryTests(SecurityTestCase):
     def test_non_uploader_is_read_only(self):
@@ -345,7 +359,13 @@ class PrivacyTests(SecurityTestCase):
         )
         self.assertEqual(self.guest.get(f"/api/uploads/{temp.id}/file/").status_code, 401)
         self.assertNotIn(
-            str(temp.id), self.client_for("sec-uploader").get("/api/uploads/").content.decode()
+            str(temp.id),
+            self.client_for("sec-uploader").get("/api/uploads/").content.decode(),
+        )
+        # The board is per-user: staff only see their own staged uploads.
+        self.assertNotIn(
+            str(temp.id),
+            self.client_for("sec-staff").get("/api/uploads/").content.decode(),
         )
 
     def test_similarity_checks_are_private(self):
@@ -423,6 +443,36 @@ class ThrottleTests(SecurityTestCase):
             {self.guest.get("/api/status/").status_code for _ in range(12)}, {200}
         )
 
+    def test_signed_media_urls_are_not_throttled(self):
+        """<img>/<video> tags fetch these without an Authorization header.
+
+        Regression: they were charged to the anonymous bucket, so galleries
+        and the fish-greeting download started returning 429 JSON instead of
+        the image bytes.
+        """
+        item = self.make_item("throttle-media", owner=self.users["sec-uploader"])
+        codes = {
+            self.guest.get(f"/api/files/J-{item.id}/raw/").status_code
+            for _ in range(150)
+        }
+        self.assertEqual(codes, {200})
+
+    def test_staged_upload_files_are_not_throttled(self):
+        temp = TempUpload.objects.create(
+            user=self.users["sec-uploader"],
+            file=SimpleUploadedFile("throttle-temp.bin", b"staged"),
+            original_filename="throttle-temp.bin",
+            md5=hashlib.md5(b"throttle-temp").hexdigest(),
+            size=6,
+        )
+        signature = sign_payload(
+            {"temp": str(temp.id), "user": self.users["sec-uploader"].id},
+            services.UPLOAD_FILE_SALT,
+        )
+        url = f"/api/uploads/{temp.id}/file/?sig={signature}"
+        codes = {self.guest.get(url).status_code for _ in range(150)}
+        self.assertEqual(codes, {200})
+
 
 class RemoteUrlTests(SecurityTestCase):
     def test_allowlist(self):

backend/apps/follows/tests/test_follows_list.py

@@ -0,0 +1,78 @@
+"""The follow lists are complete sets, not pages.
+
+The SPA uses `GET /api/follows/tags/` (and pools) for two things: deciding a
+follow toggle's state, and rendering every card on the Followed page. With the
+standard 48-item pagination that silently broke past 48 follows — a 49th tag
+could not be followed (the toggle never saw it) and the page hid it. These
+tests pin the unpaginated behaviour.
+"""
+
+from django.contrib.auth import get_user_model
+from django.test import Client, TestCase
+
+from rest_framework.authtoken.models import Token
+
+from apps.follows.models import FollowedPool, FollowedTag
+
+User = get_user_model()
+
+
+class FollowListTests(TestCase):
+    def setUp(self):
+        self.user = User.objects.create_user(
+            username="follow-user", password="follow-pass-123456"
+        )
+        self.other = User.objects.create_user(
+            username="follow-other", password="follow-pass-123456"
+        )
+        self.client = self.api_client(self.user)
+        self.other_client = self.api_client(self.other)
+
+    def api_client(self, user):
+        client = Client()
+        client.defaults["HTTP_AUTHORIZATION"] = (
+            f"Token {Token.objects.create(user=user).key}"
+        )
+        return client
+
+    def test_tag_list_is_not_paginated_past_48(self):
+        FollowedTag.objects.bulk_create(
+            [
+                FollowedTag(user=self.user, tag=f"tag_{index:03d}")
+                for index in range(60)
+            ]
+        )
+        response = self.client.get("/api/follows/tags/")
+        self.assertEqual(response.status_code, 200)
+        data = response.json()
+        self.assertIsInstance(data, list, "the list must not be paginated")
+        self.assertEqual(len(data), 60)
+        self.assertEqual(data[0]["tag"], "tag_000")
+        self.assertEqual(data[-1]["tag"], "tag_059")
+        # The shape the SPA uses for its follow state.
+        self.assertIn("unseen_count", data[0])
+        self.assertIn("id", data[0])
+
+    def test_pool_list_is_not_paginated(self):
+        FollowedPool.objects.bulk_create(
+            [
+                FollowedPool(user=self.user, pool_id=59000 + index, name=f"pool {index}")
+                for index in range(55)
+            ]
+        )
+        data = self.client.get("/api/follows/pools/").json()
+        self.assertIsInstance(data, list)
+        self.assertEqual(len(data), 55)
+
+    def test_lists_only_contain_the_callers_follows(self):
+        FollowedTag.objects.create(user=self.user, tag="mine")
+        FollowedTag.objects.create(user=self.other, tag="theirs")
+
+        mine = self.client.get("/api/follows/tags/").json()
+        theirs = self.other_client.get("/api/follows/tags/").json()
+        self.assertEqual([row["tag"] for row in mine], ["mine"])
+        self.assertEqual([row["tag"] for row in theirs], ["theirs"])
+
+    def test_anonymous_cannot_list(self):
+        self.assertEqual(Client().get("/api/follows/tags/").status_code, 401)
+        self.assertEqual(Client().get("/api/follows/pools/").status_code, 401)

backend/apps/follows/views.py

@@ -36,10 +36,16 @@ class FollowedTagViewSet(
     mixins.DestroyModelMixin,
     viewsets.GenericViewSet,
 ):
-    """Tags the current user follows."""
+    """Tags the current user follows.
+
+    Deliberately unpaginated: the SPA treats this as the complete set (follow
+    toggles read their state from it and the Followed page lists every card),
+    so a 48-item page silently broke following past 48 entries.
+    """
 
     serializer_class = FollowedTagSerializer
     permission_classes = [IsAuthenticated]
+    pagination_class = None
     http_method_names = ["get", "post", "delete", "head", "options"]
 
     def get_queryset(self):
@@ -112,10 +118,11 @@ class FollowedPoolViewSet(
     mixins.DestroyModelMixin,
     viewsets.GenericViewSet,
 ):
-    """Pools the current user follows."""
+    """Pools the current user follows (unpaginated, like the tag list)."""
 
     serializer_class = FollowedPoolSerializer
     permission_classes = [IsAuthenticated]
+    pagination_class = None
     http_method_names = ["get", "post", "delete", "head", "options"]
 
     def get_queryset(self):

backend/apps/library/e621.py

@@ -1,19 +1,39 @@
 """Minimal e621 API client for server-side matching and metadata refresh.
 
 The SPA talks to e621 directly for browsing; this client exists for work the
-browser cannot do reliably: long batch scans, and requests tied to a library
-item rather than an open page. It uses the requesting user's stored
-credentials and a global throttle (e621 asks for at most two requests per
-second).
+browser cannot do reliably: long batch scans, staged-upload processing and
+requests tied to a library item rather than an open page. It uses the
+requesting user's stored credentials and a global throttle (e621 asks for at
+most two requests per second, one per second sustained).
+
+e621's load balancer also sheds load with 429s (sometimes with an HTML
+"shedding" page instead of JSON) and the IQDB endpoint has its own, much
+stricter throttle. Every call therefore retries with exponential backoff and
+honours ``Retry-After``; only 401/403 are treated as fatal.
 """
 
+import logging
+import random
 import threading
 import time
+from pathlib import Path
 
 import requests
 from django.conf import settings
 
-REQUEST_INTERVAL = 0.5  # seconds between requests, per process
+logger = logging.getLogger(__name__)
+
+# Seconds between requests, per process. e621 allows 2/s hard and 1/s
+# sustained; each gunicorn worker throttles on its own, so leave enough
+# headroom that combined traffic does not trip the limit.
+REQUEST_INTERVAL = 1.0
+# IQDB is throttled far more aggressively than the rest of the API.
+IQDB_INTERVAL = 2.0
+
+MAX_ATTEMPTS = 4
+BACKOFF_BASE = 2.0
+BACKOFF_CAP = 60.0
+RETRYABLE_STATUSES = {429, 500, 502, 503, 504}
 
 
 class E621Error(Exception):
@@ -24,6 +44,14 @@ class E621NotFound(E621Error):
     """The requested post does not exist (HTTP 404)."""
 
 
+class E621AuthError(E621Error):
+    """e621 rejected the stored credentials (401/403)."""
+
+
+class E621RateLimited(E621Error):
+    """e621 shed load or throttled the request after every retry."""
+
+
 _throttle_lock = threading.Lock()
 _last_request_at = 0.0
 
@@ -32,56 +60,170 @@ def credentials_configured(user):
     return bool(user is not None and getattr(user, "e621_configured", False))
 
 
-def _wait_for_slot():
+def _wait_for_slot(interval=REQUEST_INTERVAL):
     global _last_request_at
     with _throttle_lock:
-        delay = _last_request_at + REQUEST_INTERVAL - time.monotonic()
+        delay = _last_request_at + interval - time.monotonic()
         if delay > 0:
             time.sleep(delay)
         _last_request_at = time.monotonic()
 
 
+def _retry_delay(attempt, response=None):
+    """Backoff for a retryable failure, honouring ``Retry-After``."""
+    if response is not None:
+        retry_after = response.headers.get("Retry-After")
+        if retry_after:
+            try:
+                return max(float(retry_after), 1.0)
+            except (TypeError, ValueError):
+                pass
+    delay = min(BACKOFF_BASE * (2**attempt), BACKOFF_CAP)
+    return delay + random.uniform(0, delay * 0.25)
+
+
+def _request(
+    user,
+    method,
+    path,
+    *,
+    params=None,
+    data=None,
+    files=None,
+    timeout=30,
+    require_auth=True,
+    interval=REQUEST_INTERVAL,
+    attempts=MAX_ATTEMPTS,
+):
+    """One e621 call with retries; returns the parsed JSON payload.
+
+    ``files`` may be a callable returning the multipart mapping, which is
+    called once per attempt: streamed uploads consume their file handle, so a
+    retry needs a freshly opened file.
+
+    Raises E621NotFound for 404s, E621AuthError for 401/403 and
+    E621RateLimited when e621 keeps shedding/throttling after every attempt.
+    """
+    configured = credentials_configured(user)
+    if require_auth and not configured:
+        raise E621Error("Configure your e621 credentials in Account first.")
+    base = (getattr(user, "e621_base_url", "") or "https://e621.net").rstrip("/")
+    auth = (
+        (user.e621_username, user.e621_api_key_plain) if configured else None
+    )
+    url = f"{base}{path}"
+
+    last_error = None
+    for attempt in range(attempts):
+        request_files = files() if callable(files) else files
+        _wait_for_slot(interval)
+        response = None
+        try:
+            response = requests.request(
+                method,
+                url,
+                params=params,
+                data=data,
+                files=request_files,
+                auth=auth,
+                headers={"User-Agent": settings.USER_AGENT},
+                timeout=timeout,
+            )
+        except requests.RequestException as exc:
+            last_error = E621Error(f"Could not reach e621: {exc}")
+        else:
+            if response.status_code == 404:
+                raise E621NotFound(f"e621 returned 404 for {path}")
+            if response.status_code in {401, 403}:
+                raise E621AuthError(
+                    f"e621 rejected the request ({response.status_code}). "
+                    "Check the stored e621 credentials."
+                )
+            if response.status_code == 429:
+                # Throttles and load-shedding can arrive as JSON ({"message":
+                # "Throttled: ..."}) or as an HTML page.
+                message = ""
+                try:
+                    payload = response.json()
+                except ValueError:
+                    payload = None
+                if isinstance(payload, dict):
+                    message = str(
+                        payload.get("message") or payload.get("error") or ""
+                    )
+                last_error = E621RateLimited(
+                    message or f"e621 throttled the request for {path}"
+                )
+            elif response.status_code < 400:
+                try:
+                    return response.json()
+                except ValueError:
+                    # An HTML page with a 2xx status.
+                    last_error = E621RateLimited(
+                        f"e621 returned an unexpected {response.status_code} response."
+                    )
+            elif response.status_code in RETRYABLE_STATUSES:
+                last_error = E621RateLimited(
+                    f"e621 replied {response.status_code} for {path}"
+                )
+            else:
+                raise E621Error(f"e621 replied {response.status_code} for {path}")
+        finally:
+            _close_upload_files(request_files)
+        if attempt + 1 < attempts:
+            delay = _retry_delay(attempt, response)
+            logger.info(
+                "e621 %s %s failed (%s); retrying in %.1fs",
+                method,
+                path,
+                last_error,
+                delay,
+            )
+            time.sleep(delay)
+
+    if last_error is None:
+        last_error = E621Error("e621 request failed.")
+    raise last_error
+
+
+def _close_upload_files(files):
+    """Close the handles behind a multipart mapping (see _request)."""
+    if not isinstance(files, dict):
+        return
+    for value in files.values():
+        handle = value[1] if isinstance(value, tuple) and len(value) > 1 else value
+        close = getattr(handle, "close", None)
+        if close is not None:
+            try:
+                close()
+            except Exception:  # noqa: BLE001 - closing must never mask errors
+                pass
+
+
 def get(user, path, params=None, timeout=30, require_auth=True):
     """GET an e621 API path using the user's credentials.
 
     Reads that e621 serves anonymously (searches, pools, tags) can pass
     require_auth=False; matching endpoints keep requiring credentials.
-
-    Raises E621NotFound for 404s and E621Error for everything else that isn't
-    a 2xx, so callers never see requests exceptions.
     """
-    configured = credentials_configured(user)
-    if require_auth and not configured:
-        raise E621Error("Configure your e621 credentials in Account first.")
-    base = (getattr(user, "e621_base_url", "") or "https://e621.net").rstrip("/")
-    _wait_for_slot()
-    try:
-        response = requests.get(
-            f"{base}{path}",
-            params=params,
-            auth=(
-                (user.e621_username, user.e621_api_key_plain)
-                if configured
-                else None
-            ),
-            headers={"User-Agent": settings.USER_AGENT},
-            timeout=timeout,
-        )
-    except requests.RequestException as exc:
-        raise E621Error(f"Could not reach e621: {exc}") from exc
-    if response.status_code == 404:
-        raise E621NotFound(f"e621 returned 404 for {path}")
-    if response.status_code >= 400:
-        raise E621Error(f"e621 replied {response.status_code} for {path}")
-    try:
-        return response.json()
-    except ValueError as exc:
-        raise E621Error("e621 returned an unexpected response.") from exc
+    return _request(
+        user,
+        "GET",
+        path,
+        params=params,
+        timeout=timeout,
+        require_auth=require_auth,
+    )
 
 
 def find_post_by_md5(user, md5):
     """The e621 post with this exact MD5, or None."""
-    payload = get(user, "/posts.json", params={"tags": f"md5:{md5}", "limit": 1})
+    payload = get(
+        user,
+        "/posts.json",
+        params={"tags": f"md5:{md5}", "limit": 1},
+        require_auth=False,
+    )
     posts = payload.get("posts") if isinstance(payload, dict) else None
     if not posts:
         return None
@@ -95,3 +237,87 @@ def fetch_post(user, post_id):
     if not isinstance(post, dict):
         raise E621Error("e621 returned an unexpected post payload.")
     return post
+
+
+def check_md5_batch(user, md5s):
+    """Look many MD5s up in one posts.json query.
+
+    Returns ``{md5: post}`` for the ones e621 knows; missing MD5s are simply
+    absent. Works anonymously, like the original app's batch cache command.
+    """
+    wanted = {str(value).strip().lower() for value in md5s if value}
+    if not wanted:
+        return {}
+    values = sorted(wanted)
+    payload = get(
+        user,
+        "/posts.json",
+        params={
+            "tags": f"md5:{','.join(values)}",
+            "limit": min(len(values), 320),
+        },
+        require_auth=False,
+    )
+    posts = payload.get("posts") if isinstance(payload, dict) else None
+    found = {}
+    for post in posts or []:
+        if not isinstance(post, dict):
+            continue
+        file_data = post.get("file") or {}
+        md5 = str(file_data.get("md5") or "").strip().lower()
+        if md5 in wanted:
+            found[md5] = post
+    return found
+
+
+def fetch_posts_by_ids(user, ids):
+    """Fetch many posts in one query (up to 320 ids). Missing ids are absent."""
+    values = sorted({int(value) for value in ids})
+    if not values:
+        return []
+    payload = get(
+        user,
+        "/posts.json",
+        params={
+            "tags": f"id:{','.join(str(value) for value in values)}",
+            "limit": min(len(values), 320),
+        },
+        require_auth=False,
+    )
+    posts = payload.get("posts") if isinstance(payload, dict) else None
+    return [post for post in posts or [] if isinstance(post, dict)]
+
+
+def iqdb_search(user, path, timeout=60):
+    """Reverse-image search one file through e621's IQDB endpoint.
+
+    Returns the legacy match list. Uses the extra-strict IQDB interval and
+    retries through e621's throttle; raises E621RateLimited when it persists.
+    """
+    path = Path(path)
+
+    def open_file():
+        # A fresh handle per attempt: the stream is consumed by the request.
+        return {"search[file]": (path.name, open(path, "rb"))}
+
+    payload = _request(
+        user,
+        "POST",
+        "/iqdb_queries.json",
+        files=open_file,
+        timeout=timeout,
+        require_auth=False,
+        interval=IQDB_INTERVAL,
+    )
+    if isinstance(payload, list):
+        return payload
+    if isinstance(payload, dict):
+        matches = payload.get("matches")
+        if isinstance(matches, list):
+            return matches
+        # e621 answers its throttle with {"success": false, "message": ...}.
+        message = payload.get("message") or payload.get("error")
+        if message:
+            raise E621RateLimited(str(message))
+        raise E621Error("e621 returned an unexpected IQDB payload.")
+    return []

backend/apps/library/management/commands/cleanup_temp_uploads.py

@@ -18,6 +18,9 @@ class Command(BaseCommand):
         )
 
     def handle(self, *args, **options):
+        from apps.library.upload_pipeline import reap_stale_claims
+
+        reap_stale_claims()
         cutoff = timezone.now() - timedelta(hours=options["hours"])
         queryset = TempUpload.objects.filter(created_at__lt=cutoff)
         if not options["include_completed"]:

backend/apps/library/management/commands/process_uploads.py

@@ -0,0 +1,68 @@
+"""Process staged uploads: e621 MD5, visual similarity, IQDB.
+
+Runs synchronously, unlike the daemon thread the API starts on demand. Useful
+for tests, for a manual drain after an outage and for the scheduler if a
+deployment wants a periodic safety net.
+
+    python manage.py process_uploads             # every user with queued work, once
+    python manage.py process_uploads --user 3    # one user
+    python manage.py process_uploads --loop 60   # keep draining every 60s
+"""
+
+import time
+
+from django.core.management.base import BaseCommand
+
+from apps.library.models import TempUpload
+from apps.library.upload_pipeline import (
+    MAX_ATTEMPTS,
+    OUTSTANDING_Q,
+    WORK_STATUSES,
+    reap_stale_claims,
+    run_pipeline,
+)
+
+
+class Command(BaseCommand):
+    help = "Run the staged-upload pipeline (MD5 -> visual similarity -> IQDB)."
+
+    def add_arguments(self, parser):
+        parser.add_argument(
+            "--user",
+            type=int,
+            default=None,
+            help="Only process this user id.",
+        )
+        parser.add_argument(
+            "--loop",
+            type=int,
+            default=0,
+            metavar="SECONDS",
+            help="Keep draining every SECONDS seconds instead of exiting.",
+        )
+
+    def handle(self, *args, **options):
+        interval = options["loop"] or 0
+        while True:
+            self.drain(user_id=options["user"])
+            if interval <= 0:
+                return
+            time.sleep(interval)
+
+    def drain(self, user_id=None):
+        reap_stale_claims()
+        queryset = (
+            TempUpload.objects.filter(status__in=WORK_STATUSES)
+            .filter(OUTSTANDING_Q)
+            .filter(attempts__lt=MAX_ATTEMPTS)
+        )
+        if user_id is not None:
+            queryset = queryset.filter(user_id=user_id)
+        user_ids = list(queryset.values_list("user_id", flat=True).distinct())
+        if not user_ids:
+            self.stdout.write("No staged uploads need processing.")
+            return
+        for value in user_ids:
+            self.stdout.write(f"Processing staged uploads for user {value}...")
+            run_pipeline(value)
+        self.stdout.write(self.style.SUCCESS(f"Processed {len(user_ids)} queue(s)."))

backend/apps/library/migrations/0011_upload_pipeline.py

@@ -0,0 +1,81 @@
+# Generated by Django 6.1.1 on 2026-09-21 13:27
+
+import django.db.models.deletion
+from django.conf import settings
+from django.db import migrations, models
+
+
+def backfill_pipeline_checks(apps, schema_editor):
+    """Mark pre-pipeline rows as already MD5/visual-checked when they were.
+
+    Rows with an e621 post id (or already completed) clearly went through the
+    MD5 phase; rows with visual matches went through the visual phase.
+    Everything else stays unset so the new pipeline picks it up once after
+    deploy — a re-check of stale pending uploads is the desired behavior.
+    """
+    TempUpload = apps.get_model("library", "TempUpload")
+    TempUpload.objects.filter(
+        models.Q(e621_post_id__isnull=False) | models.Q(status="completed")
+    ).update(e621_checked_at=models.F("updated_at"))
+    TempUpload.objects.filter(visual_matches__isnull=False).update(
+        visual_checked_at=models.F("updated_at")
+    )
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('library', '0010_similaritycheck'),
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='tempupload',
+            name='attempts',
+            field=models.PositiveSmallIntegerField(default=0),
+        ),
+        migrations.AddField(
+            model_name='tempupload',
+            name='claimed_at',
+            field=models.DateTimeField(blank=True, db_index=True, null=True),
+        ),
+        migrations.AddField(
+            model_name='tempupload',
+            name='e621_checked_at',
+            field=models.DateTimeField(blank=True, null=True),
+        ),
+        migrations.AddField(
+            model_name='tempupload',
+            name='pipeline_error',
+            field=models.TextField(blank=True, default=''),
+        ),
+        migrations.AddField(
+            model_name='tempupload',
+            name='visual_checked_at',
+            field=models.DateTimeField(blank=True, null=True),
+        ),
+        migrations.CreateModel(
+            name='UploadRun',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('status', models.CharField(choices=[('idle', 'Idle'), ('running', 'Running'), ('paused', 'Paused'), ('error', 'Error')], default='idle', max_length=20)),
+                ('phase', models.CharField(blank=True, choices=[('', 'None'), ('md5', 'e621 MD5'), ('visual', 'Visual similarity'), ('iqdb', 'IQDB')], default='', max_length=20)),
+                ('total', models.IntegerField(default=0)),
+                ('processed', models.IntegerField(default=0)),
+                ('matched', models.IntegerField(default=0)),
+                ('failed', models.IntegerField(default=0)),
+                ('error', models.TextField(blank=True, default='')),
+                ('started_at', models.DateTimeField(blank=True, null=True)),
+                ('updated_at', models.DateTimeField(auto_now=True)),
+                ('user', models.OneToOneField(on_delete=django.db.models.deletion.CASCADE, related_name='upload_run', to=settings.AUTH_USER_MODEL)),
+            ],
+            options={
+                'ordering': ['-updated_at'],
+            },
+        ),
+        migrations.RunPython(
+            code=backfill_pipeline_checks, reverse_code=migrations.RunPython.noop
+        ),
+    ]
+

backend/apps/library/migrations/0012_uploadrun_recent_completions.py

@@ -0,0 +1,34 @@
+# Generated by Django 6.1.1 on 2026-09-23
+
+from django.db import migrations, models
+
+
+def purge_completed_uploads(apps, schema_editor):
+    """Completed staged uploads are notifications, not records.
+
+    The board used to keep every auto-uploaded/indexed row until it was
+    dismissed by hand, so they accumulated without bound (and bulk dismissal
+    is capped at 1000 ids). Completions now live in a small per-run feed, so
+    the old rows are removed here.
+    """
+    TempUpload = apps.get_model("library", "TempUpload")
+    for temp in TempUpload.objects.filter(status="completed").iterator():
+        if temp.file:
+            temp.file.delete(save=False)
+        temp.delete()
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("library", "0011_upload_pipeline"),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="uploadrun",
+            name="recent_completions",
+            field=models.JSONField(blank=True, default=list),
+        ),
+        migrations.RunPython(purge_completed_uploads, migrations.RunPython.noop),
+    ]

backend/apps/library/models.py

@@ -164,6 +164,16 @@ class TempUpload(models.Model):
         on_delete=models.SET_NULL,
         related_name="temp_uploads",
     )
+    # Background pipeline bookkeeping (see apps/library/upload_pipeline.py).
+    # e621_checked_at/visual_checked_at are set once the corresponding phase
+    # ran, so "never checked" and "checked, nothing found" stay distinct.
+    e621_checked_at = models.DateTimeField(null=True, blank=True)
+    visual_checked_at = models.DateTimeField(null=True, blank=True)
+    # Worker claim for cross-process mutual exclusion; stale claims are
+    # reaped and the row queued again.
+    claimed_at = models.DateTimeField(null=True, blank=True, db_index=True)
+    pipeline_error = models.TextField(blank=True, default="")
+    attempts = models.PositiveSmallIntegerField(default=0)
     created_at = models.DateTimeField(auto_now_add=True)
     updated_at = models.DateTimeField(auto_now=True)
 
@@ -174,6 +184,66 @@ class TempUpload(models.Model):
         return f"{self.original_filename} ({self.status})"
 
 
+class UploadRun(models.Model):
+    """Per-user state of the background upload pipeline.
+
+    One row per user acts as the cheap status source the SPA polls and as a
+    place for batch-level failures (broken e621 credentials, outages) that
+    would otherwise be repeated on every row.
+    """
+
+    STATUS_IDLE = "idle"
+    STATUS_RUNNING = "running"
+    STATUS_PAUSED = "paused"
+    STATUS_ERROR = "error"
+    STATUS_CHOICES = [
+        (STATUS_IDLE, "Idle"),
+        (STATUS_RUNNING, "Running"),
+        (STATUS_PAUSED, "Paused"),
+        (STATUS_ERROR, "Error"),
+    ]
+
+    PHASE_MD5 = "md5"
+    PHASE_VISUAL = "visual"
+    PHASE_IQDB = "iqdb"
+    PHASE_CHOICES = [
+        ("", "None"),
+        (PHASE_MD5, "e621 MD5"),
+        (PHASE_VISUAL, "Visual similarity"),
+        (PHASE_IQDB, "IQDB"),
+    ]
+
+    user = models.OneToOneField(
+        settings.AUTH_USER_MODEL,
+        on_delete=models.CASCADE,
+        related_name="upload_run",
+    )
+    status = models.CharField(
+        max_length=20, choices=STATUS_CHOICES, default=STATUS_IDLE
+    )
+    phase = models.CharField(
+        max_length=20, choices=PHASE_CHOICES, blank=True, default=""
+    )
+    total = models.IntegerField(default=0)
+    processed = models.IntegerField(default=0)
+    matched = models.IntegerField(default=0)
+    failed = models.IntegerField(default=0)
+    error = models.TextField(blank=True, default="")
+    # Rolling feed of recent completions for the upload board. Completed
+    # staged uploads are deleted as soon as they are indexed; this only tells
+    # the live page "filename -> J-x" while it watches. Bounded, never
+    # dismissed, and ignored by fresh page loads.
+    recent_completions = models.JSONField(default=list, blank=True)
+    started_at = models.DateTimeField(null=True, blank=True)
+    updated_at = models.DateTimeField(auto_now=True)
+
+    class Meta:
+        ordering = ["-updated_at"]
+
+    def __str__(self):
+        return f"Upload run for {self.user_id} ({self.status})"
+
+
 class DownloadTask(models.Model):
     """A background 'Download to Library' job with progress tracking."""
 

backend/apps/library/serializers.py

@@ -3,7 +3,6 @@ from datetime import timedelta
 from pathlib import Path
 
 from django.conf import settings
-from django.core import signing
 from rest_framework import serializers
 
 from .models import (
@@ -20,6 +19,7 @@ from .services import (
     VIDEO_EXTENSIONS,
     signed_media_url,
 )
+from .signing_urls import sign_payload
 
 
 class MediaLocationSerializer(serializers.ModelSerializer):
@@ -145,6 +145,12 @@ class TempUploadSerializer(serializers.ModelSerializer):
     library_j_id = serializers.SerializerMethodField()
     file_url = serializers.SerializerMethodField()
     preview_url = serializers.SerializerMethodField()
+    md5_checked = serializers.SerializerMethodField()
+    visual_checked = serializers.SerializerMethodField()
+    iqdb_checked = serializers.SerializerMethodField()
+    processing = serializers.SerializerMethodField()
+    similar_count = serializers.SerializerMethodField()
+    visual_matches = serializers.SerializerMethodField()
 
     class Meta:
         model = TempUpload
@@ -165,6 +171,13 @@ class TempUploadSerializer(serializers.ModelSerializer):
             "library_j_id",
             "file_url",
             "preview_url",
+            "pipeline_error",
+            "attempts",
+            "md5_checked",
+            "visual_checked",
+            "iqdb_checked",
+            "processing",
+            "similar_count",
             "created_at",
             "updated_at",
         ]
@@ -187,9 +200,9 @@ class TempUploadSerializer(serializers.ModelSerializer):
         user = self._request_user()
         if user is None:
             return None
-        signature = signing.dumps(
+        signature = sign_payload(
             {"temp": str(obj.id), "user": user.id},
-            salt=UPLOAD_FILE_SALT,
+            UPLOAD_FILE_SALT,
         )
         url = f"/api/uploads/{obj.id}/file/?sig={signature}"
         request = self.context.get("request")
@@ -215,6 +228,89 @@ class TempUploadSerializer(serializers.ModelSerializer):
             item, user, action, request=self.context.get("request")
         )
 
+    def get_md5_checked(self, obj):
+        return obj.e621_checked_at is not None
+
+    def get_visual_checked(self, obj):
+        return obj.visual_checked_at is not None
+
+    def get_iqdb_checked(self, obj):
+        return obj.iqdb_data is not None
+
+    def get_processing(self, obj):
+        return obj.claimed_at is not None
+
+    def get_similar_count(self, obj):
+        return len(obj.iqdb_data or []) + len(obj.visual_matches or [])
+
+    @staticmethod
+    def _visual_item_id(entry):
+        if not isinstance(entry, dict):
+            return None
+        item_id = entry.get("item_id")
+        if item_id is None:
+            j_id = str(entry.get("j_id") or "")
+            if j_id.upper().startswith("J-"):
+                j_id = j_id[2:]
+            item_id = j_id if j_id.isdigit() else None
+        try:
+            return int(item_id)
+        except (TypeError, ValueError):
+            return None
+
+    def get_visual_matches(self, obj):
+        """Rebuild match rows with fresh signed thumbnail URLs.
+
+        Storing the signed URL meant it aged out (or came from an older
+        signing scheme) and the "Already in your library" grid showed broken
+        tiles. The stored rows only carry the item reference now.
+        """
+        entries = obj.visual_matches or []
+        if not entries:
+            return entries
+        wanted = {}
+        for entry in entries:
+            item_id = self._visual_item_id(entry)
+            if item_id is not None:
+                wanted[item_id] = None
+        items = MediaItem.objects.in_bulk(list(wanted))
+        user = self._request_user()
+        request = self.context.get("request")
+        matches = []
+        for entry in entries:
+            item_id = self._visual_item_id(entry)
+            item = items.get(item_id) if item_id is not None else None
+            if item is None:
+                continue
+            matches.append(
+                {
+                    "j_id": f"J-{item.id}",
+                    "filename": entry.get("filename") or item.md5,
+                    "similarity": entry.get("similarity"),
+                    "thumbnail_url": signed_media_url(
+                        item, user, "thumbnail", request=request
+                    ),
+                }
+            )
+        return matches
+
+
+class TempUploadListSerializer(TempUploadSerializer):
+    """Compact staged-upload row for the board and the status polling.
+
+    Drops the heavy post/IQDB payloads (the metadata modal fetches the full
+    row) while keeping the pipeline flags the board renders per tile.
+    """
+
+    class Meta(TempUploadSerializer.Meta):
+        fields = [
+            field
+            for field in TempUploadSerializer.Meta.fields
+            if field
+            not in {"e621_data", "iqdb_data", "visual_matches", "custom_tags", "custom_notes"}
+        ]
+        read_only_fields = fields
+
 
 class DownloadTaskSerializer(serializers.ModelSerializer):
     task_id = serializers.UUIDField(source="id", read_only=True)
@@ -295,9 +391,9 @@ class SimilarityCheckSerializer(serializers.ModelSerializer):
         user = self._request_user()
         if user is None or not obj.file:
             return None
-        signature = signing.dumps(
+        signature = sign_payload(
             {"check": str(obj.id), "user": user.id},
-            salt=UPLOAD_FILE_SALT,
+            UPLOAD_FILE_SALT,
         )
         url = f"/api/similarity/{obj.id}/file/?sig={signature}"
         request = self.context.get("request")

backend/apps/library/services.py

@@ -6,16 +6,21 @@ import os
 import re
 import shutil
 import subprocess
+import uuid
+from datetime import datetime, timezone
 from pathlib import Path
+from urllib.parse import urlencode
 
 import imagehash
 from django.conf import settings
-from django.core import signing
 from django.http import FileResponse, Http404, HttpResponse
+from django.utils.cache import get_conditional_response
+from django.utils.http import http_date
 from django.utils.text import get_valid_filename
-from PIL import Image
+from PIL import Image, ImageOps
 
 from .models import MediaItem, MediaLocation
+from .signing_urls import sign_payload
 
 logger = logging.getLogger(__name__)
 
@@ -37,6 +42,11 @@ UPLOAD_FILE_SALT = "j621.upload-file"
 MEDIA_FILE_SALT = "j621.media-file"
 CHUNK_SIZE = 1024 * 1024
 RANGE_RE = re.compile(r"bytes=(\d*)-(\d*)$")
+# Versioned media URLs are immutable, so they may sit in the browser cache for
+# as long as the signature is guaranteed to stay valid (7 days).
+MEDIA_CACHE_SECONDS = 6 * 86400
+# Staged uploads and similarity files can be deleted at any moment.
+TEMP_CACHE_SECONDS = 3600
 
 
 def compute_md5(path):
@@ -78,14 +88,24 @@ def signed_media_url(item, user, action="raw", request=None):
 
     With a ``request`` the URL is absolute, so the SPA also works when it is
     served from a different origin; without one it stays relative.
+
+    The ``v`` parameter is the item's MD5: it busts the browser cache exactly
+    when the file is replaced (the optimize flow rewrites files under the same
+    J-ID), which is what lets the URL be cached for days instead of re-minted
+    on every response.
     """
     path = f"/api/files/J-{item.id}/{action}/"
+    params = {}
     if user is not None and getattr(user, "is_authenticated", False):
-        signature = signing.dumps(
-            {"item": item.id, "user": user.id, "action": action},
-            salt=MEDIA_FILE_SALT,
-        )
-        path = f"{path}?sig={signature}"
+        params = {
+            "v": item.md5,
+            "sig": sign_payload(
+                {"item": item.id, "user": user.id, "action": action},
+                MEDIA_FILE_SALT,
+            ),
+        }
+    if params:
+        path = f"{path}?{urlencode(params)}"
     if request is None:
         return path
     return request.build_absolute_uri(path)
@@ -207,12 +227,36 @@ class RangeFileWrapper:
         self.file.close()
 
 
-def serve_file(request, path, download=False):
-    """Serve a file with HTTP range support (needed for video seeking)."""
+def _apply_cache_headers(response, cache_control, etag, mtime):
+    response["Cache-Control"] = cache_control
+    response["ETag"] = etag
+    response["Last-Modified"] = http_date(mtime)
+    return response
+
+
+def serve_file(request, path, download=False, *, max_age=TEMP_CACHE_SECONDS, immutable=False):
+    """Serve a file with HTTP range support (needed for video seeking).
+
+    Responses carry validators (ETag/Last-Modified) and a private
+    ``Cache-Control`` so browsers reuse media instead of re-downloading it on
+    every SPA poll. ``max_age``/``immutable`` are chosen by the caller: versioned
+    library media can be cached hard, staged files only briefly.
+    """
     path = Path(path)
     if not path.is_file():
         raise Http404
-    size = path.stat().st_size
+    stat = path.stat()
+    size = stat.st_size
+    etag = f'W/"{size:x}-{stat.st_mtime_ns:x}"'
+    last_modified = datetime.fromtimestamp(stat.st_mtime, tz=timezone.utc)
+    conditional = get_conditional_response(
+        request, etag=etag, last_modified=last_modified
+    )
+    if conditional is not None:
+        return conditional
+    cache_control = f"private, max-age={int(max_age)}"
+    if immutable:
+        cache_control += ", immutable"
     content_type = mimetypes.guess_type(str(path))[0] or "application/octet-stream"
     range_header = request.headers.get("Range", "").strip()
     if range_header:
@@ -240,7 +284,9 @@ def serve_file(request, path, download=False):
             response["Content-Length"] = str(length)
             response["Content-Range"] = f"bytes {start}-{end}/{size}"
             response["Accept-Ranges"] = "bytes"
-            return response
+            return _apply_cache_headers(
+                response, cache_control, etag, stat.st_mtime
+            )
     response = FileResponse(
         open(path, "rb"),
         content_type=content_type,
@@ -248,7 +294,7 @@ def serve_file(request, path, download=False):
         filename=path.name,
     )
     response["Accept-Ranges"] = "bytes"
-    return response
+    return _apply_cache_headers(response, cache_control, etag, stat.st_mtime)
 
 
 class DownloadCancelled(Exception):
@@ -436,15 +482,38 @@ def sanitize_iqdb_results(results):
     return cleaned
 
 
+def _thumbnail_is_fresh(target, path):
+    """True when the cached thumbnail exists and is at least as new as source."""
+    try:
+        stat = target.stat()
+        if stat.st_size <= 0:
+            return False
+        return stat.st_mtime >= os.path.getmtime(path)
+    except OSError:
+        return False
+
+
+def _thumbs_dir():
+    thumbs_dir = Path(settings.MEDIA_ROOT) / "thumbs"
+    thumbs_dir.mkdir(parents=True, exist_ok=True)
+    return thumbs_dir
+
+
 def generate_video_thumbnail(md5, path):
     """Extract a JPEG thumbnail from a video, cached under MEDIA_ROOT/thumbs."""
     if not shutil.which("ffmpeg"):
         return None
-    thumbs_dir = Path(settings.MEDIA_ROOT) / "thumbs"
-    thumbs_dir.mkdir(parents=True, exist_ok=True)
+    try:
+        thumbs_dir = _thumbs_dir()
+    except OSError:
+        logger.exception("Could not create the thumbnail folder")
+        return None
     target = thumbs_dir / f"{md5}.jpg"
-    if target.exists() and target.stat().st_mtime >= os.path.getmtime(path):
+    if _thumbnail_is_fresh(target, path):
         return target
+    # Write beside the target and move it into place, so a concurrent request
+    # can never read a half-written JPEG.
+    temp = thumbs_dir / f".{md5}.{uuid.uuid4().hex}.part.jpg"
     command = [
         "ffmpeg",
         "-y",
@@ -458,10 +527,63 @@ def generate_video_thumbnail(md5, path):
         "scale=480:-2",
         "-loglevel",
         "error",
-        str(target),
+        str(temp),
     ]
     try:
         subprocess.run(command, check=True, capture_output=True, timeout=60)
+        os.replace(temp, target)
     except (subprocess.SubprocessError, OSError):
+        logger.exception("Could not build a video thumbnail for %s", path)
+        temp.unlink(missing_ok=True)
         return None
     return target if target.exists() else None
+
+
+def generate_image_thumbnail(md5, path):
+    """Downscale an image, cached under MEDIA_ROOT/thumbs like video thumbs.
+
+    The thumbnail action used to serve full-size originals for images; a
+    cached 480px JPEG keeps the library grid light without touching the
+    original file. Returns ``None`` when the source is missing or Pillow
+    cannot decode it, so callers can fall back to the original.
+    """
+    try:
+        thumbs_dir = _thumbs_dir()
+    except OSError:
+        logger.exception("Could not create the thumbnail folder")
+        return None
+    target = thumbs_dir / f"{md5}.jpg"
+    if _thumbnail_is_fresh(target, path):
+        return target
+    temp = thumbs_dir / f".{md5}.{uuid.uuid4().hex}.part.jpg"
+    try:
+        with Image.open(path) as image:
+            # Animated formats: the first frame is the preview.
+            image.seek(0)
+            frame = ImageOps.exif_transpose(image) or image
+            frame = frame.convert("RGB")
+            frame.thumbnail((480, 480))
+            frame.save(temp, "JPEG", quality=82, optimize=True)
+        os.replace(temp, target)
+    except Exception:  # noqa: BLE001 - previews must never break serving
+        logger.exception("Could not build an image thumbnail for %s", path)
+        temp.unlink(missing_ok=True)
+        return None
+    return target if target.exists() else None
+
+
+def ensure_thumbnail(item):
+    """Generate an item's cached thumbnail if it is missing or stale.
+
+    Warming thumbnails when a file is indexed keeps image decoding out of the
+    request path, where the upload pipeline's hashing used to starve it.
+    """
+    location = item.locations.first()
+    if location is None:
+        return None
+    path = Path(location.path)
+    if not path.is_file():
+        return None
+    if path.suffix.lower() in VIDEO_EXTENSIONS:
+        return generate_video_thumbnail(item.md5, path)
+    return generate_image_thumbnail(item.md5, path)

backend/apps/library/signing_urls.py

@@ -0,0 +1,64 @@
+"""Stable, expiring signatures for media URLs.
+
+The SPA loads media with ``<img>``/``<video>`` tags, which cannot send the
+API's ``Authorization`` header, so those URLs carry a signature instead. The
+signature has to be *stable*: a URL that changes on every response makes the
+browser treat every refetch as a new resource and re-download the file.
+
+URLs are signed with a plain ``Signer`` (no per-second timestamp) plus an
+explicit ``exp`` claim quantized to a bucket, so every request inside a bucket
+mints the exact same URL. The URL rotates once per bucket and is valid for at
+least ``URL_TTL_SECONDS`` and at most ``URL_TTL_SECONDS + URL_BUCKET_SECONDS``.
+"""
+
+import time
+
+from django.core import signing
+
+URL_TTL_SECONDS = 7 * 86400
+URL_BUCKET_SECONDS = 24 * 3600
+_BUCKETS = URL_TTL_SECONDS // URL_BUCKET_SECONDS
+
+
+def _expiry(now=None):
+    current = time.time() if now is None else now
+    bucket = int(current // URL_BUCKET_SECONDS)
+    return (bucket + _BUCKETS + 1) * URL_BUCKET_SECONDS
+
+
+def sign_payload(payload, salt, now=None):
+    """Sign a payload with a stable, bucket-quantized expiry."""
+    return signing.Signer(salt=salt).sign_object(
+        {**payload, "exp": _expiry(now)}
+    )
+
+
+def load_payload(signature, salt, legacy_max_age=86400):
+    """Verify a signed payload; ``None`` when missing, tampered with or expired.
+
+    Legacy ``TimestampSigner`` values are still accepted for one release.
+    Detect them by their extra separator (``payload:timestamp:signature``):
+    a plain ``Signer`` accepts the HMAC a ``TimestampSigner`` computed over
+    ``payload:timestamp`` and then chokes on the embedded timestamp while
+    decoding the JSON payload, which used to surface as a 500.
+    """
+    if not signature:
+        return None
+    if signature.count(":") >= 2:
+        try:
+            return signing.TimestampSigner(salt=salt).unsign_object(
+                signature, max_age=legacy_max_age
+            )
+        except (signing.BadSignature, ValueError):
+            return None
+    try:
+        data = signing.Signer(salt=salt).unsign_object(signature)
+    except (signing.BadSignature, ValueError):
+        return None
+    if not isinstance(data, dict):
+        return None
+    try:
+        expired = int(data.get("exp", 0)) < time.time()
+    except (TypeError, ValueError):
+        return None
+    return None if expired else data

backend/apps/library/similarity.py

@@ -11,7 +11,6 @@ from datetime import timedelta
 from pathlib import Path
 
 from django.conf import settings
-from django.core import signing
 from django.utils import timezone
 from rest_framework import mixins, status, viewsets
 from rest_framework.decorators import action
@@ -22,6 +21,7 @@ from rest_framework.response import Response
 from . import services
 from .models import MediaItem, SimilarityCheck
 from .serializers import SimilarityCheckSerializer
+from .signing_urls import load_payload
 from .tools import item_brief
 from .uploads import find_library_matches
 
@@ -136,7 +136,12 @@ class SimilarityCheckViewSet(
             self.get_serializer(check).data, status=status.HTTP_201_CREATED
         )
 
-    @action(detail=True, methods=["get", "head"], permission_classes=[AllowAny])
+    @action(
+        detail=True,
+        methods=["get", "head"],
+        permission_classes=[AllowAny],
+        throttle_classes=[],
+    )
     def file(self, request, pk=None):
         """Serve the temp file; accepts a signed URL like staged uploads."""
         check = None
@@ -144,14 +149,7 @@ class SimilarityCheckViewSet(
             check = self.get_queryset().filter(pk=pk).first()
         else:
             signature = request.query_params.get("sig")
-            payload = None
-            if signature:
-                try:
-                    payload = signing.loads(
-                        signature, salt=services.UPLOAD_FILE_SALT, max_age=86400
-                    )
-                except signing.BadSignature:
-                    payload = None
+            payload = load_payload(signature, services.UPLOAD_FILE_SALT) if signature else None
             if payload and payload.get("check") == str(pk):
                 check = SimilarityCheck.objects.filter(pk=pk).first()
         if check is None or not check.file:

backend/apps/library/tests/test_e621.py

@@ -0,0 +1,99 @@
+"""The server-side e621 client: batching, retries and IQDB stream handling."""
+
+from pathlib import Path
+from tempfile import TemporaryDirectory
+from unittest import mock
+
+from django.test import SimpleTestCase
+
+from apps.library import e621
+
+
+class FakeResponse:
+    def __init__(self, status_code, payload=None, headers=None):
+        self.status_code = status_code
+        self._payload = payload
+        self.headers = headers or {}
+
+    def json(self):
+        if self._payload is None:
+            raise ValueError("not json")
+        return self._payload
+
+
+class E621ClientTests(SimpleTestCase):
+    def test_iqdb_search_reopens_the_file_on_retry(self):
+        bodies = []
+
+        def fake_request(method, url, **kwargs):
+            handle = kwargs["files"]["search[file]"][1]
+            bodies.append(handle.read())
+            if len(bodies) == 1:
+                return FakeResponse(
+                    429, {"success": False, "message": "Throttled"}
+                )
+            return FakeResponse(200, [{"post_id": 1, "score": 90.0}])
+
+        with TemporaryDirectory() as tmp:
+            path = Path(tmp) / "x.png"
+            path.write_bytes(b"image-bytes")
+            with mock.patch.object(
+                e621.requests, "request", side_effect=fake_request
+            ), mock.patch.object(e621.time, "sleep"), mock.patch.object(
+                e621, "_wait_for_slot"
+            ):
+                result = e621.iqdb_search(None, path)
+
+        # Both attempts must send the full body, not the consumed handle.
+        self.assertEqual(bodies, [b"image-bytes", b"image-bytes"])
+        self.assertEqual(result, [{"post_id": 1, "score": 90.0}])
+
+    def test_check_md5_batch_keys_by_md5(self):
+        payload = {
+            "posts": [
+                {"id": 5, "file": {"md5": "a" * 32}},
+                {"id": 6, "file": {"md5": "b" * 32}},
+            ]
+        }
+        with mock.patch.object(e621, "get", return_value=payload) as getter:
+            found = e621.check_md5_batch(None, ["A" * 32, "b" * 32])
+        self.assertEqual(set(found), {"a" * 32, "b" * 32})
+        params = getter.call_args.kwargs["params"]
+        self.assertTrue(params["tags"].startswith("md5:"))
+        self.assertEqual(params["limit"], 2)
+
+    def test_auth_errors_are_not_retried(self):
+        calls = []
+
+        def fake_request(*args, **kwargs):
+            calls.append(1)
+            return FakeResponse(403, {"error": "nope"})
+
+        with mock.patch.object(
+            e621.requests, "request", side_effect=fake_request
+        ), mock.patch.object(e621, "_wait_for_slot"):
+            with self.assertRaises(e621.E621AuthError):
+                e621._request(None, "GET", "/posts.json", require_auth=False)
+        self.assertEqual(len(calls), 1)
+
+    def test_load_shedding_html_raises_rate_limited_after_retries(self):
+        with mock.patch.object(
+            e621.requests,
+            "request",
+            return_value=FakeResponse(200, None),
+        ), mock.patch.object(e621.time, "sleep"), mock.patch.object(
+            e621, "_wait_for_slot"
+        ):
+            with self.assertRaises(e621.E621RateLimited):
+                e621._request(
+                    None, "GET", "/posts.json", require_auth=False, attempts=2
+                )
+
+    def test_fetch_posts_by_ids_queries_with_id_tag(self):
+        with mock.patch.object(
+            e621, "get", return_value={"posts": [{"id": 9}]}
+        ) as getter:
+            posts = e621.fetch_posts_by_ids(None, [9])
+        self.assertEqual(posts, [{"id": 9}])
+        params = getter.call_args.kwargs["params"]
+        self.assertEqual(params["tags"], "id:9")

backend/apps/library/tests/test_media_cache.py

@@ -0,0 +1,188 @@
+"""Signed media URLs must be stable, versioned and cacheable.
+
+Regression: signatures embedded the current second, so every API response
+re-minted every URL and browsers re-downloaded each image on every poll; the
+file responses also carried no cache headers at all.
+"""
+
+import base64
+import hashlib
+import io
+import shutil
+import tempfile
+import time
+from pathlib import Path
+from unittest import mock
+
+from django.contrib.auth import get_user_model
+from django.core import signing
+from django.core.files.uploadedfile import SimpleUploadedFile
+from django.test import Client, TestCase, override_settings
+
+from PIL import Image
+
+from rest_framework.authtoken.models import Token
+
+from apps.library import services
+from apps.library.models import MediaItem, MediaLocation, TempUpload
+from apps.library.signing_urls import load_payload, sign_payload
+
+User = get_user_model()
+
+TINY_PNG = base64.b64decode(
+    "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg=="
+)
+
+
+def png_bytes(width=1200, height=800, color=(20, 120, 200)):
+    buffer = io.BytesIO()
+    Image.new("RGB", (width, height), color).save(buffer, format="PNG")
+    return buffer.getvalue()
+
+
+class MediaCacheTests(TestCase):
+    @classmethod
+    def setUpClass(cls):
+        super().setUpClass()
+        cls._tmp = tempfile.mkdtemp(prefix="j621-cache-")
+        cls._media = Path(cls._tmp) / "media"
+        cls._watched = cls._media / "library"
+        cls._watched.mkdir(parents=True, exist_ok=True)
+        cls._settings = override_settings(
+            MEDIA_ROOT=str(cls._media), WATCHED_FOLDER=str(cls._watched)
+        )
+        cls._settings.enable()
+
+    @classmethod
+    def tearDownClass(cls):
+        cls._settings.disable()
+        shutil.rmtree(cls._tmp, ignore_errors=True)
+        super().tearDownClass()
+
+    def setUp(self):
+        self.user = User.objects.create_user(
+            username="cache-uploader", password="cache-pass-123456"
+        )
+        self.user.role = "uploader"
+        self.user.save(update_fields=["role"])
+        self.token = Token.objects.create(user=self.user).key
+        payload = png_bytes()
+        path = self._watched / "cache-image.png"
+        path.write_bytes(payload)
+        self.item = MediaItem.objects.create(
+            md5=hashlib.md5(payload).hexdigest(), size=len(payload)
+        )
+        MediaLocation.objects.create(
+            item=self.item, path=str(path), rel_path=path.name, mtime=time.time()
+        )
+        self.client = Client()
+
+    def signed(self, action):
+        return {
+            "sig": sign_payload(
+                {"item": self.item.id, "user": self.user.id, "action": action},
+                services.MEDIA_FILE_SALT,
+            )
+        }
+
+    def test_media_response_carries_cache_headers(self):
+        response = self.client.get(
+            f"/api/files/J-{self.item.id}/raw/", self.signed("raw")
+        )
+        self.assertEqual(response.status_code, 200)
+        self.assertIn("private", response["Cache-Control"])
+        self.assertIn(
+            f"max-age={services.MEDIA_CACHE_SECONDS}", response["Cache-Control"]
+        )
+        self.assertIn("immutable", response["Cache-Control"])
+        self.assertTrue(response["ETag"])
+        self.assertTrue(response["Last-Modified"])
+
+    def test_media_revalidation_returns_304(self):
+        url = f"/api/files/J-{self.item.id}/raw/"
+        first = self.client.get(url, self.signed("raw"))
+        second = self.client.get(
+            url, self.signed("raw"), HTTP_IF_NONE_MATCH=first["ETag"]
+        )
+        self.assertEqual(second.status_code, 304)
+        self.assertEqual(second.content, b"")
+
+    def test_image_thumbnail_is_generated_and_reused(self):
+        url = f"/api/files/J-{self.item.id}/thumbnail/"
+        response = self.client.get(url, self.signed("thumbnail"))
+        self.assertEqual(response.status_code, 200)
+        self.assertEqual(response["Content-Type"], "image/jpeg")
+        thumb = self._media / "thumbs" / f"{self.item.md5}.jpg"
+        self.assertTrue(thumb.exists())
+        with Image.open(thumb) as image:
+            self.assertLessEqual(max(image.size), 480)
+        before = thumb.stat().st_mtime_ns
+        self.client.get(url, self.signed("thumbnail"))
+        self.assertEqual(thumb.stat().st_mtime_ns, before)
+
+    def test_ensure_thumbnail_reuses_the_cache(self):
+        first = services.ensure_thumbnail(self.item)
+        self.assertIsNotNone(first)
+        self.assertTrue(first.exists())
+        mtime = first.stat().st_mtime_ns
+        second = services.ensure_thumbnail(self.item)
+        self.assertEqual(second, first)
+        self.assertEqual(second.stat().st_mtime_ns, mtime)
+
+    def test_thumbnail_of_a_missing_source_does_not_error(self):
+        """Regression: getmtime() on a vanished source used to raise a 500."""
+        thumbs = self._media / "thumbs"
+        thumbs.mkdir(parents=True, exist_ok=True)
+        (thumbs / f"{self.item.md5}.jpg").write_bytes(b"stale")
+        Path(self.item.locations.first().path).unlink()
+        self.assertIsNone(services.ensure_thumbnail(self.item))
+        response = self.client.get(
+            f"/api/files/J-{self.item.id}/thumbnail/", self.signed("thumbnail")
+        )
+        self.assertEqual(response.status_code, 404)
+
+    def test_staged_files_cache_briefly(self):
+        temp = TempUpload.objects.create(
+            user=self.user,
+            file=SimpleUploadedFile("staged.png", TINY_PNG, content_type="image/png"),
+            original_filename="staged.png",
+            md5=hashlib.md5(b"staged").hexdigest(),
+            size=len(TINY_PNG),
+        )
+        signature = sign_payload(
+            {"temp": str(temp.id), "user": self.user.id}, services.UPLOAD_FILE_SALT
+        )
+        response = self.client.get(
+            f"/api/uploads/{temp.id}/file/", {"sig": signature}
+        )
+        self.assertEqual(response.status_code, 200)
+        self.assertIn(
+            f"max-age={services.TEMP_CACHE_SECONDS}", response["Cache-Control"]
+        )
+        self.assertNotIn("immutable", response["Cache-Control"])
+
+    def test_legacy_timestamp_signatures_are_accepted(self):
+        """URLs minted before the stable scheme must not 500.
+
+        A TimestampSigner HMAC also passes a plain Signer's check, so the
+        embedded timestamp used to reach the JSON decoder and blow up.
+        """
+        payload = {"item": self.item.id, "user": self.user.id, "action": "raw"}
+        legacy = signing.dumps(payload, salt=services.MEDIA_FILE_SALT)
+        self.assertEqual(
+            load_payload(legacy, services.MEDIA_FILE_SALT)["item"], self.item.id
+        )
+        response = self.client.get(
+            f"/api/files/J-{self.item.id}/raw/", {"sig": legacy}
+        )
+        self.assertEqual(response.status_code, 200)
+
+    def test_expired_and_malformed_signatures_return_none(self):
+        payload = {"item": self.item.id, "user": self.user.id, "action": "raw"}
+        with mock.patch.object(signing, "time") as clock:
+            clock.time.return_value = time.time() - 3 * 86400
+            expired = signing.dumps(payload, salt=services.MEDIA_FILE_SALT)
+        self.assertIsNone(load_payload(expired, services.MEDIA_FILE_SALT))
+        self.assertIsNone(load_payload("bogus", services.MEDIA_FILE_SALT))
+        self.assertIsNone(load_payload("a:b", services.MEDIA_FILE_SALT))
+        self.assertIsNone(load_payload("", services.MEDIA_FILE_SALT))

backend/apps/library/tests/test_uploads.py

@@ -0,0 +1,788 @@
+"""Staged uploads: listing, phases (MD5/visual/IQDB) and the bulk tool."""
+
+import base64
+import hashlib
+import io
+import json
+import shutil
+import tempfile
+from datetime import timedelta
+from pathlib import Path
+from unittest import mock
+
+from django.contrib.auth import get_user_model
+from django.core.files.uploadedfile import SimpleUploadedFile
+from django.test import Client, TestCase, override_settings
+from django.utils import timezone
+
+from PIL import Image
+
+from rest_framework.authtoken.models import Token
+
+from apps.library import upload_pipeline
+from apps.library.models import MediaItem, TempUpload, UploadRun
+
+User = get_user_model()
+
+# 1x1 transparent PNG so indexing/hashing has a real image to chew on.
+TINY_PNG = base64.b64decode(
+    "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg=="
+)
+
+
+def similar_png(color=(200, 30, 40)):
+    """A 1x1 PNG with the same visual hashes but a different MD5."""
+    buffer = io.BytesIO()
+    Image.new("RGB", (1, 1), color).save(buffer, format="PNG")
+    return buffer.getvalue()
+
+
+def jpost(client, path, body=None):
+    return client.post(path, data=json.dumps(body or {}), content_type="application/json")
+
+
+class TempUploadListTests(TestCase):
+    def setUp(self):
+        self.uploader = User.objects.create_user(
+            username="upload-user", password="upload-pass-123456"
+        )
+        self.uploader.role = "uploader"
+        self.uploader.save(update_fields=["role"])
+        self.other = User.objects.create_user(
+            username="upload-other", password="upload-pass-123456"
+        )
+        self.other.role = "uploader"
+        self.other.save(update_fields=["role"])
+
+    def api_client(self, user):
+        client = Client()
+        client.defaults["HTTP_AUTHORIZATION"] = (
+            f"Token {Token.objects.create(user=user).key}"
+        )
+        return client
+
+    def test_list_is_not_paginated_past_48(self):
+        TempUpload.objects.bulk_create(
+            [
+                TempUpload(
+                    user=self.uploader,
+                    original_filename=f"file_{index:03d}.png",
+                    md5=hashlib.md5(f"file-{index}".encode()).hexdigest(),
+                    size=index,
+                )
+                for index in range(69)
+            ]
+        )
+        response = self.api_client(self.uploader).get("/api/uploads/")
+        self.assertEqual(response.status_code, 200)
+        data = response.json()
+        self.assertIsInstance(data, list, "the list must not be paginated")
+        self.assertEqual(len(data), 69)
+
+    def test_list_only_contains_the_callers_uploads(self):
+        TempUpload.objects.create(
+            user=self.uploader,
+            original_filename="mine.png",
+            md5=hashlib.md5(b"mine").hexdigest(),
+            size=1,
+        )
+        TempUpload.objects.create(
+            user=self.other,
+            original_filename="theirs.png",
+            md5=hashlib.md5(b"theirs").hexdigest(),
+            size=1,
+        )
+        mine = self.api_client(self.uploader).get("/api/uploads/").json()
+        self.assertEqual([row["original_filename"] for row in mine], ["mine.png"])
+
+    def test_anonymous_cannot_list(self):
+        self.assertEqual(Client().get("/api/uploads/").status_code, 401)
+
+
+@override_settings(UPLOAD_PIPELINE_AUTOSTART=False)
+class StagedUploadWorkflowTests(TestCase):
+    @classmethod
+    def setUpClass(cls):
+        super().setUpClass()
+        cls._tmp = tempfile.mkdtemp(prefix="j621-bulk-")
+        cls._watched = Path(cls._tmp) / "library"
+        cls._watched.mkdir(parents=True, exist_ok=True)
+        cls._settings = override_settings(
+            MEDIA_ROOT=cls._tmp, WATCHED_FOLDER=str(cls._watched)
+        )
+        cls._settings.enable()
+
+    @classmethod
+    def tearDownClass(cls):
+        cls._settings.disable()
+        shutil.rmtree(cls._tmp, ignore_errors=True)
+        super().tearDownClass()
+
+    def setUp(self):
+        self.uploader = User.objects.create_user(
+            username="bulk-uploader", password="bulk-pass-123456"
+        )
+        self.uploader.role = "uploader"
+        self.uploader.save(update_fields=["role"])
+        self.other = User.objects.create_user(
+            username="bulk-other", password="bulk-pass-123456"
+        )
+        self.other.role = "uploader"
+        self.other.save(update_fields=["role"])
+
+    def api_client(self, user):
+        client = Client()
+        client.defaults["HTTP_AUTHORIZATION"] = (
+            f"Token {Token.objects.create(user=user).key}"
+        )
+        return client
+
+    def make_temp(
+        self, user, label, status=TempUpload.STATUS_PENDING, payload=None
+    ):
+        return TempUpload.objects.create(
+            user=user,
+            file=SimpleUploadedFile(
+                f"{label}.png", payload or TINY_PNG, content_type="image/png"
+            ),
+            original_filename=f"{label}.png",
+            md5=hashlib.md5(label.encode()).hexdigest(),
+            size=len(payload or TINY_PNG),
+            status=status,
+        )
+
+    def resolve_bulk(self, client, ids, rating):
+        return jpost(
+            client,
+            "/api/uploads/resolve-bulk/",
+            {"temp_ids": [str(value) for value in ids], "rating": rating},
+        )
+
+    def test_resolves_selected_uploads_with_the_rating(self):
+        client = self.api_client(self.uploader)
+        first = self.make_temp(self.uploader, "one")
+        second = self.make_temp(self.uploader, "two")
+        untouched = self.make_temp(self.uploader, "three")
+
+        response = self.resolve_bulk(client, [first.id, second.id], "q")
+        self.assertEqual(response.status_code, 200)
+        body = response.json()
+        self.assertEqual(len(body["resolved"]), 2)
+        self.assertEqual(body["errors"], [])
+
+        # Completed uploads are notifications now: the staged rows are gone
+        # and the live feed carries the filename -> J-ID mapping.
+        self.assertFalse(
+            TempUpload.objects.filter(pk__in=[first.id, second.id]).exists()
+        )
+        feed = UploadRun.objects.get(user=self.uploader).recent_completions
+        self.assertEqual(
+            {entry["filename"] for entry in feed}, {"one.png", "two.png"}
+        )
+        for item in MediaItem.objects.all():
+            self.assertEqual(item.rating, "q")
+            self.assertEqual(item.uploaded_by_id, self.uploader.id)
+        untouched.refresh_from_db()
+        self.assertEqual(untouched.status, TempUpload.STATUS_PENDING)
+
+    def test_rejects_bad_input(self):
+        client = self.api_client(self.uploader)
+        temp = self.make_temp(self.uploader, "input")
+        self.assertEqual(self.resolve_bulk(client, [], "s").status_code, 400)
+        self.assertEqual(self.resolve_bulk(client, [temp.id], "").status_code, 400)
+        self.assertEqual(self.resolve_bulk(client, [temp.id], "x").status_code, 400)
+        self.assertEqual(
+            jpost(
+                client,
+                "/api/uploads/resolve-bulk/",
+                {"temp_ids": ["not-a-uuid"], "rating": "s"},
+            ).status_code,
+            400,
+        )
+
+    def test_other_users_uploads_are_left_alone(self):
+        client = self.api_client(self.uploader)
+        theirs = self.make_temp(self.other, "theirs")
+        response = self.resolve_bulk(client, [theirs.id], "s")
+        self.assertEqual(response.status_code, 200)
+        body = response.json()
+        self.assertEqual(body["resolved"], [])
+        self.assertEqual(body["errors"][0]["error"], "not found")
+        theirs.refresh_from_db()
+        self.assertEqual(theirs.status, TempUpload.STATUS_PENDING)
+
+    def test_completed_uploads_report_an_error_but_others_resolve(self):
+        client = self.api_client(self.uploader)
+        done = self.make_temp(self.uploader, "done", status=TempUpload.STATUS_COMPLETED)
+        pending = self.make_temp(self.uploader, "pending")
+        response = self.resolve_bulk(client, [done.id, pending.id], "e")
+        body = response.json()
+        self.assertEqual(len(body["resolved"]), 1)
+        self.assertEqual(body["errors"][0]["error"], "already in the library")
+        self.assertEqual(MediaItem.objects.count(), 1)
+
+    def upload_via_api(self, client, label="phase.png"):
+        return client.post(
+            "/api/uploads/",
+            {
+                "file": SimpleUploadedFile(
+                    label, similar_png(), content_type="image/png"
+                )
+            },
+        )
+
+    def seed_library_item(self, client, label):
+        seed = self.make_temp(self.uploader, label)
+        response = self.resolve_bulk(client, [seed.id], "s")
+        self.assertEqual(response.status_code, 200)
+        return seed
+
+    def test_duplicate_upload_returns_a_completion_without_a_record(self):
+        client = self.api_client(self.uploader)
+        first = self.upload_via_api(client, "same.png")
+        self.assertEqual(first.status_code, 201)
+        # Index the first upload so the second one is byte-identical.
+        seed = TempUpload.objects.get(pk=first.json()["temp_id"])
+        self.resolve_bulk(client, [seed.id], "s")
+
+        response = self.upload_via_api(client, "same.png")
+        self.assertEqual(response.status_code, 201)
+        body = response.json()
+        self.assertEqual(body["status"], TempUpload.STATUS_COMPLETED)
+        self.assertEqual(body["resolution"], TempUpload.RESOLUTION_DUPLICATE)
+        self.assertTrue(body["library_j_id"].startswith("J-"))
+        # Duplicates never become board records; the feed announces them.
+        self.assertFalse(TempUpload.objects.filter(pk=body["temp_id"]).exists())
+        feed = UploadRun.objects.get(user=self.uploader).recent_completions
+        self.assertEqual(feed[-1]["filename"], "same.png")
+
+    def test_upload_defers_visual_similarity_to_its_phase(self):
+        client = self.api_client(self.uploader)
+        self.seed_library_item(client, "seed-defer")
+        response = self.upload_via_api(client)
+        self.assertEqual(response.status_code, 201)
+        body = response.json()
+        # Uploading must not run the expensive library scan.
+        self.assertEqual(body["status"], TempUpload.STATUS_PENDING)
+        self.assertFalse(body["visual_matches"])
+
+    def test_visual_match_phase_flags_similar_library_items(self):
+        client = self.api_client(self.uploader)
+        self.seed_library_item(client, "seed-visual")
+        temp = self.make_temp(self.uploader, "check-visual")
+        response = client.post(f"/api/uploads/{temp.id}/visual-match/")
+        self.assertEqual(response.status_code, 200)
+        body = response.json()
+        self.assertEqual(body["status"], TempUpload.STATUS_VISUAL_MATCH)
+        self.assertGreaterEqual(len(body["visual_matches"]), 1)
+        temp.refresh_from_db()
+        self.assertEqual(temp.status, TempUpload.STATUS_VISUAL_MATCH)
+
+    def test_visual_match_phase_with_empty_library_stays_pending(self):
+        client = self.api_client(self.uploader)
+        temp = self.make_temp(self.uploader, "no-matches")
+        response = client.post(f"/api/uploads/{temp.id}/visual-match/")
+        self.assertEqual(response.status_code, 200)
+        body = response.json()
+        self.assertEqual(body["visual_matches"], [])
+        self.assertEqual(body["status"], TempUpload.STATUS_PENDING)
+
+    def test_detail_resigns_stored_visual_match_urls(self):
+        """Stored matches carry only the item reference; URLs are re-minted.
+
+        Embedding the signed URL meant it expired (or used an older signing
+        scheme) and the modal showed alt text instead of thumbnails.
+        """
+        client = self.api_client(self.uploader)
+        self.seed_library_item(client, "seed-resign")
+        item = MediaItem.objects.get()
+        temp = self.make_temp(self.uploader, "resign")
+        TempUpload.objects.filter(pk=temp.pk).update(
+            visual_matches=[
+                {
+                    "item_id": item.id,
+                    "j_id": f"J-{item.id}",
+                    "filename": "seed-resign.png",
+                    "similarity": 96.5,
+                    "thumbnail_url": "/api/files/J-x/thumbnail/?sig=stale",
+                },
+                {"item_id": 999999, "j_id": "J-999999", "filename": "gone.png"},
+            ]
+        )
+        body = client.get(f"/api/uploads/{temp.id}/").json()
+        self.assertEqual(len(body["visual_matches"]), 1)
+        match = body["visual_matches"][0]
+        self.assertEqual(match["j_id"], f"J-{item.id}")
+        self.assertEqual(match["similarity"], 96.5)
+        self.assertNotIn("stale", match["thumbnail_url"])
+        self.assertIn("/thumbnail/", match["thumbnail_url"])
+        self.assertIn(f"v={item.md5}", match["thumbnail_url"])
+
+    def test_visual_match_phase_rejects_completed_uploads(self):
+        client = self.api_client(self.uploader)
+        temp = self.make_temp(
+            self.uploader, "done-visual", status=TempUpload.STATUS_COMPLETED
+        )
+        response = client.post(f"/api/uploads/{temp.id}/visual-match/")
+        self.assertEqual(response.status_code, 400)
+
+    def test_link_bulk_moves_a_batch_with_one_call(self):
+        client = self.api_client(self.uploader)
+        first = self.make_temp(self.uploader, "bulk-link-1")
+        second = self.make_temp(
+            self.uploader, "bulk-link-2", payload=similar_png((10, 200, 30))
+        )
+        response = jpost(
+            client,
+            "/api/uploads/link-bulk/",
+            {
+                "links": [
+                    {
+                        "temp_id": str(first.id),
+                        "post": {
+                            "id": 900001,
+                            "rating": "s",
+                            "file": {
+                                "md5": first.md5,
+                                # Identical MD5: the staged file is indexed
+                                # without downloading the URL.
+                                "url": "https://static1.e621.net/data/fake-1.png",
+                            },
+                        },
+                    },
+                    {
+                        "temp_id": str(second.id),
+                        "post": {
+                            "id": 900002,
+                            "rating": "q",
+                            "file": {
+                                "md5": second.md5,
+                                "url": "https://static1.e621.net/data/fake-2.png",
+                            },
+                        },
+                    },
+                ]
+            },
+        )
+        self.assertEqual(response.status_code, 200)
+        body = response.json()
+        self.assertEqual(body["errors"], [])
+        self.assertEqual(len(body["updated"]), 2)
+        for entry, post_id in zip(body["updated"], (900001, 900002)):
+            self.assertEqual(entry["resolution"], TempUpload.RESOLUTION_AUTO_MD5)
+            self.assertEqual(entry["e621_post_id"], post_id)
+            self.assertTrue(entry["library_j_id"].startswith("J-"))
+        # Indexed uploads no longer leave a board record; the completion feed
+        # carries them for the live page instead.
+        self.assertFalse(TempUpload.objects.exists())
+        self.assertEqual(
+            {item.e621_post_id for item in MediaItem.objects.all()},
+            {900001, 900002},
+        )
+        feed = UploadRun.objects.get(user=self.uploader).recent_completions
+        self.assertEqual(len(feed), 2)
+        self.assertEqual(
+            {entry["filename"] for entry in feed},
+            {"bulk-link-1.png", "bulk-link-2.png"},
+        )
+
+
+class IqdbRecordingTests(TestCase):
+    """The modal needs to tell "checked, no match" from "never checked"."""
+
+    @classmethod
+    def setUpClass(cls):
+        super().setUpClass()
+        cls._tmp = tempfile.mkdtemp(prefix="j621-iqdb-")
+        cls._settings = override_settings(MEDIA_ROOT=cls._tmp)
+        cls._settings.enable()
+
+    @classmethod
+    def tearDownClass(cls):
+        cls._settings.disable()
+        shutil.rmtree(cls._tmp, ignore_errors=True)
+        super().tearDownClass()
+
+    def setUp(self):
+        self.uploader = User.objects.create_user(
+            username="iqdb-uploader", password="iqdb-pass-123456"
+        )
+        self.uploader.role = "uploader"
+        self.uploader.save(update_fields=["role"])
+        self.client = Client()
+        self.client.defaults["HTTP_AUTHORIZATION"] = (
+            f"Token {Token.objects.create(user=self.uploader).key}"
+        )
+
+    def make_temp(self):
+        return TempUpload.objects.create(
+            user=self.uploader,
+            file=SimpleUploadedFile(
+                "checked.png", TINY_PNG, content_type="image/png"
+            ),
+            original_filename="checked.png",
+            md5=hashlib.md5(b"checked").hexdigest(),
+            size=len(TINY_PNG),
+        )
+
+    def test_empty_result_records_the_check_without_a_match(self):
+        temp = self.make_temp()
+        response = jpost(
+            self.client, f"/api/uploads/{temp.id}/iqdb/", {"results": []}
+        )
+        self.assertEqual(response.status_code, 200)
+        temp.refresh_from_db()
+        self.assertEqual(temp.iqdb_data, [])
+        # No candidates must not masquerade as a visual match.
+        self.assertEqual(temp.status, TempUpload.STATUS_PENDING)
+
+    def test_candidates_are_stored_and_flag_a_visual_match(self):
+        temp = self.make_temp()
+        response = jpost(
+            self.client,
+            f"/api/uploads/{temp.id}/iqdb/",
+            {
+                "results": [
+                    {
+                        "post_id": 123,
+                        "score": 91.5,
+                        "preview_url": "https://static1.e621.net/data/preview/ab/cd/x.jpg",
+                        "rating": "q",
+                        "md5": "a" * 32,
+                        "score_total": 12,
+                        "fav_count": 3,
+                        "width": 800,
+                        "height": 600,
+                        "tags_preview": ["canine", "solo"],
+                    }
+                ]
+            },
+        )
+        self.assertEqual(response.status_code, 200)
+        temp.refresh_from_db()
+        self.assertEqual(len(temp.iqdb_data), 1)
+        self.assertEqual(temp.iqdb_data[0]["post_id"], 123)
+        self.assertEqual(temp.status, TempUpload.STATUS_VISUAL_MATCH)
+
+    def test_rejects_a_non_list_payload(self):
+        temp = self.make_temp()
+        response = jpost(
+            self.client, f"/api/uploads/{temp.id}/iqdb/", {"results": "nope"}
+        )
+        self.assertEqual(response.status_code, 400)
+
+
+@override_settings(UPLOAD_PIPELINE_AUTOSTART=False)
+class UploadPipelineTests(TestCase):
+    """The server-side MD5 -> visual -> IQDB queue and its board API."""
+
+    @classmethod
+    def setUpClass(cls):
+        super().setUpClass()
+        cls._tmp = tempfile.mkdtemp(prefix="j621-pipeline-")
+        cls._watched = Path(cls._tmp) / "library"
+        cls._watched.mkdir(parents=True, exist_ok=True)
+        cls._settings = override_settings(
+            MEDIA_ROOT=cls._tmp, WATCHED_FOLDER=str(cls._watched)
+        )
+        cls._settings.enable()
+
+    @classmethod
+    def tearDownClass(cls):
+        cls._settings.disable()
+        shutil.rmtree(cls._tmp, ignore_errors=True)
+        super().tearDownClass()
+
+    def setUp(self):
+        self.uploader = User.objects.create_user(
+            username="pipe-uploader", password="pipe-pass-123456"
+        )
+        self.uploader.role = "uploader"
+        self.uploader.save(update_fields=["role"])
+        self.other = User.objects.create_user(
+            username="pipe-other", password="pipe-pass-123456"
+        )
+        self.other.role = "uploader"
+        self.other.save(update_fields=["role"])
+
+    def api_client(self, user):
+        client = Client()
+        client.defaults["HTTP_AUTHORIZATION"] = (
+            f"Token {Token.objects.create(user=user).key}"
+        )
+        return client
+
+    def stage(self, user=None, label="file", payload=None, filename=None):
+        user = user or self.uploader
+        payload = payload or TINY_PNG
+        name = filename or f"{label}.png"
+        return TempUpload.objects.create(
+            user=user,
+            file=SimpleUploadedFile(name, payload, content_type="image/png"),
+            original_filename=name,
+            md5=hashlib.md5(payload + label.encode()).hexdigest(),
+            size=len(payload),
+        )
+
+    def test_md5_match_auto_imports_the_file(self):
+        temp = self.stage(label="match")
+        temp_id = temp.id
+        post = {
+            "id": 123456,
+            "rating": "s",
+            "file": {
+                "md5": temp.md5,
+                "url": "https://static1.e621.net/data/m.png",
+            },
+            "tags": {"general": ["canine"]},
+        }
+        with mock.patch.object(
+            upload_pipeline.e621,
+            "check_md5_batch",
+            return_value={temp.md5: post},
+        ):
+            upload_pipeline.run_pipeline(self.uploader.id)
+
+        # The indexed upload leaves no board record; the feed reports it.
+        self.assertFalse(TempUpload.objects.filter(pk=temp_id).exists())
+        item = MediaItem.objects.get(e621_post_id=123456)
+        self.assertEqual(item.uploaded_by_id, self.uploader.id)
+        run = UploadRun.objects.get(user=self.uploader)
+        self.assertEqual(run.status, UploadRun.STATUS_IDLE)
+        self.assertEqual(run.matched, 1)
+        self.assertEqual(run.processed, 1)
+        self.assertEqual(len(run.recent_completions), 1)
+        entry = run.recent_completions[0]
+        self.assertEqual(entry["id"], str(temp_id))
+        self.assertEqual(entry["item_id"], item.id)
+        self.assertEqual(entry["filename"], "match.png")
+        self.assertEqual(entry["resolution"], TempUpload.RESOLUTION_AUTO_MD5)
+
+    def test_status_reports_the_completion_feed(self):
+        temp = self.stage(label="feed")
+        client = self.api_client(self.uploader)
+        post = {
+            "id": 654321,
+            "rating": "s",
+            "file": {"md5": temp.md5, "url": "https://static1.e621.net/data/f.png"},
+        }
+        with mock.patch.object(
+            upload_pipeline.e621,
+            "check_md5_batch",
+            return_value={temp.md5: post},
+        ):
+            upload_pipeline.run_pipeline(self.uploader.id)
+
+        body = client.get("/api/uploads/status/").json()
+        completions = body["recent_completions"]
+        self.assertEqual(len(completions), 1)
+        self.assertEqual(completions[0]["filename"], "feed.png")
+        self.assertEqual(completions[0]["j_id"], f"J-{MediaItem.objects.get().id}")
+        self.assertIn("/thumbnail/", completions[0]["thumbnail_url"])
+
+    def test_unmatched_file_runs_every_phase(self):
+        temp = self.stage(label="nomatch")
+        raw_iqdb = [
+            {
+                "post_id": 777,
+                "score": 91.0,
+                "post": {
+                    "id": 777,
+                    "rating": "q",
+                    "md5": "a" * 32,
+                    "score": 5,
+                    "fav_count": 2,
+                    "image_width": 800,
+                    "image_height": 600,
+                },
+            }
+        ]
+        modern = [
+            {
+                "id": 777,
+                "rating": "q",
+                "fav_count": 4,
+                "score": {"total": 9},
+                "preview": {"url": "https://static1.e621.net/data/preview/x.jpg"},
+                "file": {"md5": "a" * 32, "width": 801, "height": 601},
+                "tags": {"general": ["canine", "solo"]},
+            }
+        ]
+        with mock.patch.object(
+            upload_pipeline.e621, "check_md5_batch", return_value={}
+        ), mock.patch.object(
+            upload_pipeline.e621, "iqdb_search", return_value=raw_iqdb
+        ), mock.patch.object(
+            upload_pipeline.e621, "fetch_posts_by_ids", return_value=modern
+        ):
+            upload_pipeline.run_pipeline(self.uploader.id)
+
+        temp.refresh_from_db()
+        self.assertIsNotNone(temp.e621_checked_at)
+        self.assertIsNotNone(temp.visual_checked_at)
+        self.assertEqual(temp.status, TempUpload.STATUS_VISUAL_MATCH)
+        self.assertEqual(len(temp.iqdb_data), 1)
+        candidate = temp.iqdb_data[0]
+        self.assertEqual(candidate["post_id"], 777)
+        self.assertEqual(candidate["score_total"], 9)
+        self.assertEqual(candidate["fav_count"], 4)
+        self.assertEqual(candidate["width"], 801)
+        self.assertEqual(
+            candidate["preview_url"], "https://static1.e621.net/data/preview/x.jpg"
+        )
+        self.assertEqual(candidate["tags_preview"], ["canine", "solo"])
+        run = UploadRun.objects.get(user=self.uploader)
+        self.assertEqual(run.status, UploadRun.STATUS_IDLE)
+        self.assertEqual(run.processed, 1)
+
+    def test_visual_match_flags_similar_library_items(self):
+        from apps.library.uploads import complete_temp_upload
+
+        seed = self.stage(label="seed")
+        complete_temp_upload(seed)
+        self.assertTrue(MediaItem.objects.exists())
+
+        temp = self.stage(label="similar")
+        with mock.patch.object(
+            upload_pipeline.e621, "check_md5_batch", return_value={}
+        ), mock.patch.object(
+            upload_pipeline.e621, "iqdb_search", return_value=[]
+        ):
+            upload_pipeline.run_pipeline(self.uploader.id)
+
+        temp.refresh_from_db()
+        self.assertGreaterEqual(len(temp.visual_matches or []), 1)
+        self.assertEqual(temp.status, TempUpload.STATUS_VISUAL_MATCH)
+
+    def test_iqdb_rate_limit_pauses_the_run(self):
+        temp = self.stage(label="throttled")
+        with mock.patch.object(
+            upload_pipeline.e621, "check_md5_batch", return_value={}
+        ), mock.patch.object(
+            upload_pipeline.e621,
+            "iqdb_search",
+            side_effect=upload_pipeline.e621.E621RateLimited("Throttled"),
+        ):
+            upload_pipeline.run_pipeline(self.uploader.id)
+
+        run = UploadRun.objects.get(user=self.uploader)
+        self.assertEqual(run.status, UploadRun.STATUS_PAUSED)
+        self.assertIn("e621", run.error)
+        temp.refresh_from_db()
+        self.assertEqual(temp.attempts, 1)
+        self.assertNotEqual(temp.pipeline_error, "")
+        self.assertIsNone(temp.iqdb_data)
+        self.assertIsNone(temp.claimed_at)
+
+        client = self.api_client(self.uploader)
+        response = jpost(client, f"/api/uploads/{temp.id}/retry/", {})
+        self.assertEqual(response.status_code, 200)
+        temp.refresh_from_db()
+        self.assertEqual(temp.attempts, 0)
+        self.assertEqual(temp.pipeline_error, "")
+
+    def test_failed_rows_stop_after_the_attempt_cap(self):
+        temp = self.stage(label="broken")
+        for _ in range(upload_pipeline.MAX_ATTEMPTS):
+            with mock.patch.object(
+                upload_pipeline.e621, "check_md5_batch", return_value={}
+            ), mock.patch.object(
+                upload_pipeline.e621,
+                "iqdb_search",
+                side_effect=upload_pipeline.e621.E621Error("boom"),
+            ):
+                upload_pipeline.run_pipeline(self.uploader.id)
+        temp.refresh_from_db()
+        self.assertEqual(temp.attempts, upload_pipeline.MAX_ATTEMPTS)
+        self.assertEqual(upload_pipeline.count_outstanding(self.uploader), 0)
+        run = UploadRun.objects.get(user=self.uploader)
+        self.assertGreaterEqual(run.failed, 1)
+
+    def test_status_process_and_compact_board_payload(self):
+        temp = self.stage(label="board")
+        client = self.api_client(self.uploader)
+
+        status = client.get("/api/uploads/status/").json()
+        self.assertEqual(status["status"], UploadRun.STATUS_IDLE)
+        self.assertTrue(status["active"])
+        self.assertEqual(status["outstanding"], 1)
+        self.assertEqual(status["waiting"]["md5"], 1)
+
+        self.assertEqual(client.post("/api/uploads/process/").status_code, 200)
+
+        rows = client.get("/api/uploads/").json()
+        self.assertEqual(len(rows), 1)
+        row = rows[0]
+        for key in (
+            "md5_checked",
+            "visual_checked",
+            "iqdb_checked",
+            "processing",
+            "similar_count",
+            "pipeline_error",
+        ):
+            self.assertIn(key, row)
+        self.assertNotIn("e621_data", row)
+        self.assertNotIn("iqdb_data", row)
+
+        detail = client.get(f"/api/uploads/{temp.id}/").json()
+        self.assertIn("e621_data", detail)
+        self.assertIn("iqdb_data", detail)
+
+    def test_discard_bulk_removes_only_own_rows(self):
+        client = self.api_client(self.uploader)
+        first = self.stage(label="discard-a")
+        second = self.stage(label="discard-b")
+        theirs = self.stage(self.other, label="discard-theirs")
+        paths = [Path(first.file.path), Path(second.file.path)]
+
+        response = jpost(
+            client,
+            "/api/uploads/discard-bulk/",
+            {"temp_ids": [str(first.id), str(second.id), str(theirs.id)]},
+        )
+        self.assertEqual(response.status_code, 200)
+        body = response.json()
+        self.assertEqual(len(body["discarded"]), 2)
+        self.assertEqual(len(body["errors"]), 1)
+        self.assertEqual(body["errors"][0]["error"], "not found")
+        for path in paths:
+            self.assertFalse(path.exists())
+        self.assertFalse(
+            TempUpload.objects.filter(pk__in=[first.id, second.id]).exists()
+        )
+        self.assertTrue(TempUpload.objects.filter(pk=theirs.id).exists())
+
+    def test_retry_with_phase_rechecks_iqdb(self):
+        temp = self.stage(label="recheck")
+        TempUpload.objects.filter(pk=temp.pk).update(
+            iqdb_data=[{"post_id": 1}],
+            status=TempUpload.STATUS_VISUAL_MATCH,
+        )
+        client = self.api_client(self.uploader)
+        response = jpost(
+            client, f"/api/uploads/{temp.id}/retry/", {"phase": "iqdb"}
+        )
+        self.assertEqual(response.status_code, 200)
+        temp.refresh_from_db()
+        self.assertIsNone(temp.iqdb_data)
+        self.assertEqual(temp.status, TempUpload.STATUS_VISUAL_MATCH)
+
+    def test_stale_claims_are_released(self):
+        temp = self.stage(label="stale")
+        TempUpload.objects.filter(pk=temp.pk).update(
+            claimed_at=timezone.now() - upload_pipeline.STALE_CLAIM_AFTER
+            - timedelta(minutes=1)
+        )
+        UploadRun.objects.create(user=self.uploader, status=UploadRun.STATUS_RUNNING)
+        UploadRun.objects.filter(user=self.uploader).update(
+            updated_at=timezone.now() - upload_pipeline.STALE_RUN_AFTER
+            - timedelta(minutes=1)
+        )
+        released, paused = upload_pipeline.reap_stale_claims()
+        self.assertEqual(released, 1)
+        self.assertEqual(paused, 1)
+        temp.refresh_from_db()
+        self.assertIsNone(temp.claimed_at)
+        run = UploadRun.objects.get(user=self.uploader)
+        self.assertEqual(run.status, UploadRun.STATUS_PAUSED)

backend/apps/library/upload_pipeline.py

@@ -0,0 +1,648 @@
+"""Background processing for staged uploads.
+
+Each staged upload runs through three phases, in batches of 75 (the same
+lookup size the original app used for its e621 MD5 cache command):
+
+1. e621 MD5 lookup — one ``posts.json`` query per round; byte-identical
+   matches are imported straight into the library (``auto_md5``).
+2. Local visual similarity — perceptual hashes are compared against the
+   whole library once per round.
+3. e621 IQDB — reverse-image search for whatever is still unresolved.
+
+The pipeline runs in a daemon thread started on demand (like the download and
+match scans), so the browser can navigate away and the work keeps going.
+Progress and pause/error state live in the ``UploadRun`` row; per-file state
+lives on ``TempUpload``. Rows are claimed with ``SELECT ... FOR UPDATE SKIP
+LOCKED`` so several gunicorn workers cannot process the same file, and stale
+claims left by a recycled worker are reaped and picked up again.
+"""
+
+import logging
+import threading
+import time
+from datetime import timedelta
+
+from django.conf import settings
+from django.contrib.auth import get_user_model
+from django.db import connection, transaction
+from django.db.models import F, Q
+from django.utils import timezone
+
+from . import e621, services
+from .models import MediaItem, TempUpload, UploadRun
+
+logger = logging.getLogger(__name__)
+
+# Same batch size as the original app's e621 cache command.
+MD5_BATCH_SIZE = 75
+# Rows one worker round claims; also the MD5 query size.
+CLAIM_SIZE = MD5_BATCH_SIZE
+# A claimed row is assumed dead after this long and is queued again.
+STALE_CLAIM_AFTER = timedelta(minutes=15)
+# A run whose heartbeat stopped this long ago can be taken over.
+STALE_RUN_AFTER = timedelta(minutes=15)
+# Per-row failures before the pipeline stops retrying automatically.
+MAX_ATTEMPTS = 3
+# Round-level e621 retries before the run is paused.
+ROUND_ATTEMPTS = 3
+ROUND_RETRY_SECONDS = 20
+# Completions kept in the live feed. The board only shows what happened while
+# the page was open, so a bounded rolling window is plenty.
+COMPLETION_FEED_LIMIT = 200
+
+WORK_STATUSES = (TempUpload.STATUS_PENDING, TempUpload.STATUS_VISUAL_MATCH)
+VIDEO_RE = r"\.(mp4|webm)$"
+
+# A staged upload still needs work when any phase has not run yet. IQDB is
+# skipped for videos, which never get iqdb_data, so they must not stay
+# "outstanding" forever.
+OUTSTANDING_Q = (
+    Q(e621_checked_at__isnull=True)
+    | Q(visual_checked_at__isnull=True)
+    | (Q(iqdb_data__isnull=True) & ~Q(original_filename__iregex=VIDEO_RE))
+)
+
+_running_lock = threading.Lock()
+_running_users: set[int] = set()
+
+
+class PipelinePaused(Exception):
+    """A round-level failure that should pause the run instead of failing rows."""
+
+
+def is_video(filename):
+    return bool(filename) and filename.lower().endswith((".mp4", ".webm"))
+
+
+def is_finished(temp):
+    """True when every phase this file needs has run."""
+    if temp.status == TempUpload.STATUS_COMPLETED:
+        return True
+    if temp.e621_checked_at is None or temp.visual_checked_at is None:
+        return False
+    return is_video(temp.original_filename) or temp.iqdb_data is not None
+
+
+def outstanding_queryset(user):
+    return (
+        TempUpload.objects.filter(user=user, status__in=WORK_STATUSES)
+        .filter(OUTSTANDING_Q)
+        .filter(attempts__lt=MAX_ATTEMPTS)
+    )
+
+
+def count_outstanding(user):
+    return outstanding_queryset(user).count()
+
+
+def count_failed(user):
+    return (
+        TempUpload.objects.filter(user=user, status__in=WORK_STATUSES)
+        .filter(attempts__gte=MAX_ATTEMPTS)
+        .count()
+    )
+
+
+def waiting_counts(user):
+    """How many files are left per phase (phases overlap by design)."""
+    base = TempUpload.objects.filter(
+        user=user, status__in=WORK_STATUSES, attempts__lt=MAX_ATTEMPTS
+    )
+    return {
+        "md5": base.filter(e621_checked_at__isnull=True).count(),
+        "visual": base.filter(visual_checked_at__isnull=True).count(),
+        "iqdb": (
+            base.filter(iqdb_data__isnull=True)
+            .exclude(original_filename__iregex=VIDEO_RE)
+            .count()
+        ),
+    }
+
+
+def status_payload(user, request=None):
+    """Cheap state for the shell/upload page to poll."""
+    run = UploadRun.objects.filter(user=user).first()
+    outstanding = count_outstanding(user)
+    failed = count_failed(user)
+    status = run.status if run is not None else UploadRun.STATUS_IDLE
+    total = run.total if run is not None else 0
+    processed = run.processed if run is not None else 0
+    # A paused run with nothing left to do is not "active" (the user may have
+    # resolved or discarded the failed rows); failed rows stay visible until
+    # they are retried or dismissed.
+    active = (
+        outstanding > 0 or failed > 0 or status == UploadRun.STATUS_RUNNING
+    )
+    return {
+        "status": status,
+        "active": active,
+        "phase": run.phase if run is not None else "",
+        "total": max(total, processed + failed),
+        "processed": processed,
+        "matched": run.matched if run is not None else 0,
+        "failed": max(failed, run.failed if run is not None else 0),
+        "error": run.error if run is not None else "",
+        "outstanding": outstanding,
+        "waiting": waiting_counts(user),
+        "recent_completions": completion_payload(run, user, request=request),
+        "updated_at": run.updated_at.isoformat() if run is not None else None,
+    }
+
+
+def completion_payload(run, user, request=None):
+    """The live completion feed: filename -> J-ID for freshly indexed uploads.
+
+    Completed ``TempUpload`` rows are deleted, so this is the only place the
+    board learns about them. It is a notification feed, not durable state:
+    bounded, never dismissed, and ignored by fresh page loads.
+    """
+    entries = list(run.recent_completions or []) if run is not None else []
+    if not entries:
+        return []
+    ids = [entry.get("item_id") for entry in entries if entry.get("item_id")]
+    items = MediaItem.objects.in_bulk(ids)
+    out = []
+    for entry in reversed(entries):  # newest first
+        item = items.get(entry.get("item_id"))
+        if item is None:
+            continue
+        out.append(
+            {
+                "id": entry.get("id"),
+                "filename": entry.get("filename"),
+                "j_id": f"J-{item.id}",
+                "resolution": entry.get("resolution", ""),
+                "post_id": entry.get("post_id"),
+                "thumbnail_url": services.signed_media_url(
+                    item, user, "thumbnail", request=request
+                ),
+                "at": entry.get("at"),
+            }
+        )
+    return out
+
+
+def record_completion(temp, item, resolution=""):
+    """Append one completion to the owner's feed; never fails an import."""
+    entry = {
+        "id": str(temp.pk),
+        "filename": temp.original_filename,
+        "item_id": item.pk,
+        "resolution": resolution or temp.resolution or "",
+        "post_id": temp.e621_post_id,
+        "at": timezone.now().isoformat(),
+    }
+    try:
+        with transaction.atomic():
+            run, _ = UploadRun.objects.select_for_update().get_or_create(
+                user_id=temp.user_id
+            )
+            feed = list(run.recent_completions or [])
+            feed.append(entry)
+            run.recent_completions = feed[-COMPLETION_FEED_LIMIT:]
+            run.save(update_fields=["recent_completions", "updated_at"])
+    except Exception:  # noqa: BLE001 - a notification must not break an import
+        logger.exception("Could not record the completion of %s", temp.pk)
+
+
+def reap_stale_claims():
+    """Queue rows left claimed by a recycled worker and pause dead runs."""
+    cutoff = timezone.now() - STALE_CLAIM_AFTER
+    released = TempUpload.objects.filter(claimed_at__lt=cutoff).update(
+        claimed_at=None
+    )
+    paused = UploadRun.objects.filter(
+        status=UploadRun.STATUS_RUNNING, updated_at__lt=cutoff
+    ).update(
+        status=UploadRun.STATUS_PAUSED,
+        phase="",
+        error="The worker stopped before finishing. Retry to resume.",
+        updated_at=timezone.now(),
+    )
+    if released or paused:
+        logger.info(
+            "Reaped %s stale upload claims and %s dead upload runs", released, paused
+        )
+    return released, paused
+
+
+def start_pipeline(user):
+    """Start the pipeline for one user in a daemon thread (idempotent)."""
+    if not getattr(settings, "UPLOAD_PIPELINE_AUTOSTART", True):
+        return False
+    if user is None or not getattr(user, "can_upload", False):
+        return False
+    user_id = int(user.pk)
+    with _running_lock:
+        if user_id in _running_users:
+            return False
+        _running_users.add(user_id)
+    reap_stale_claims()
+    thread = threading.Thread(target=_thread_entry, args=(user_id,), daemon=True)
+    thread.start()
+    return True
+
+
+def _thread_entry(user_id):
+    try:
+        run_pipeline(user_id)
+    except Exception:  # noqa: BLE001 - a thread must never crash the worker
+        logger.exception("Upload pipeline for user %s crashed", user_id)
+    finally:
+        with _running_lock:
+            _running_users.discard(user_id)
+        connection.close()
+
+
+def run_pipeline(user_id):
+    user = get_user_model().objects.filter(pk=user_id).first()
+    if user is None or not user.can_upload:
+        return
+    now = timezone.now()
+    # Claim the run row so two gunicorn workers cannot own the same queue.
+    with transaction.atomic():
+        run, _ = UploadRun.objects.select_for_update().get_or_create(user=user)
+        if (
+            run.status == UploadRun.STATUS_RUNNING
+            and run.updated_at is not None
+            and run.updated_at > now - STALE_RUN_AFTER
+        ):
+            # Another worker owns this run.
+            return
+
+        # Reset the counters when a new queue starts cleanly; otherwise keep
+        # accumulating so failed rows from an earlier pass stay visible.
+        live_failed = count_failed(user)
+        outstanding = count_outstanding(user)
+        if run.status == UploadRun.STATUS_IDLE and live_failed == 0:
+            run.total = outstanding
+            run.processed = 0
+            run.matched = 0
+            run.failed = 0
+        else:
+            run.total = max(
+                run.total or 0, run.processed + run.failed + outstanding
+            )
+            run.failed = max(run.failed, live_failed)
+        run.status = UploadRun.STATUS_RUNNING
+        run.phase = ""
+        run.error = ""
+        run.started_at = now
+        run.save()
+
+    try:
+        while True:
+            rows = claim_round(user)
+            if not rows:
+                break
+            process_round(run, user, rows)
+    except PipelinePaused as exc:
+        _save_run(run, status=UploadRun.STATUS_PAUSED, phase="", error=str(exc))
+    except Exception as exc:  # noqa: BLE001 - surface crashes as a run error
+        logger.exception("Upload pipeline for user %s failed", user_id)
+        _save_run(
+            run,
+            status=UploadRun.STATUS_ERROR,
+            phase="",
+            error=f"The upload pipeline stopped: {exc}",
+        )
+    else:
+        _save_run(run, status=UploadRun.STATUS_IDLE, phase="")
+
+
+def claim_round(user, size=CLAIM_SIZE):
+    """Claim up to ``size`` outstanding rows for this worker."""
+    now = timezone.now()
+    with transaction.atomic():
+        rows = list(
+            TempUpload.objects.select_for_update(skip_locked=True)
+            .filter(user=user, status__in=WORK_STATUSES)
+            .filter(OUTSTANDING_Q)
+            .filter(claimed_at__isnull=True, attempts__lt=MAX_ATTEMPTS)
+            .order_by("created_at")[:size]
+        )
+        if rows:
+            TempUpload.objects.filter(pk__in=[row.pk for row in rows]).update(
+                claimed_at=now
+            )
+            for row in rows:
+                row.claimed_at = now
+    return rows
+
+
+def process_round(run, user, rows):
+    """Run every phase for one claimed round, then release/account the rows."""
+    ids = [row.pk for row in rows]
+    matched = 0
+    try:
+        matched += md5_phase(run, user, rows)
+        rows = refresh(ids)
+        visual_phase(run, user, rows)
+        rows = refresh(ids)
+        iqdb_phase(run, user, rows)
+    finally:
+        finalize_round(run, ids, matched)
+
+
+def refresh(ids):
+    return list(TempUpload.objects.filter(pk__in=ids))
+
+
+def _save_run(run, **fields):
+    for key, value in fields.items():
+        setattr(run, key, value)
+    run.save(
+        update_fields=[*fields.keys(), "updated_at"]
+    )
+
+
+def md5_phase(run, user, rows):
+    """One e621 MD5 batch query; matches are imported into the library."""
+    targets = [row for row in rows if row.e621_checked_at is None]
+    if not targets:
+        return 0
+    _save_run(
+        run,
+        phase=UploadRun.PHASE_MD5,
+        total=run.processed + run.failed + count_outstanding(user),
+    )
+    posts = _e621_round(
+        lambda: e621.check_md5_batch(user, [row.md5 for row in targets])
+    )
+    by_md5 = {}
+    for post in posts.values():
+        file_data = post.get("file") or {}
+        md5 = str(file_data.get("md5") or "").strip().lower()
+        if md5:
+            by_md5[md5] = post
+
+    matched = 0
+    now = timezone.now()
+    for row in targets:
+        post = by_md5.get(str(row.md5).strip().lower())
+        if post is None:
+            TempUpload.objects.filter(pk=row.pk).update(
+                e621_checked_at=now, pipeline_error="", updated_at=now
+            )
+            continue
+        try:
+            trimmed = services.trim_e621_post(post)
+            if trimmed is None or not trimmed.get("id"):
+                raise e621.E621Error("e621 returned an unexpected post payload.")
+            TempUpload.objects.filter(pk=row.pk).update(
+                e621_post_id=int(trimmed["id"]),
+                e621_data=trimmed,
+                resolution=TempUpload.RESOLUTION_AUTO_MD5,
+                e621_checked_at=now,
+                pipeline_error="",
+                updated_at=now,
+            )
+            row.refresh_from_db()
+            from .uploads import complete_temp_upload
+
+            complete_temp_upload(row)
+            matched += 1
+        except Exception as exc:  # noqa: BLE001 - keep going for other files
+            logger.exception("Could not auto-import staged upload %s", row.pk)
+            record_failure(row, f"Could not finish the upload: {exc}")
+    return matched
+
+
+def visual_phase(run, user, rows):
+    """Compare each row's perceptual hashes against the library once."""
+    from .uploads import build_hash_index, match_hashes
+
+    targets = [
+        row
+        for row in rows
+        if row.visual_checked_at is None
+        and row.status in WORK_STATUSES
+        and row.file
+    ]
+    if not targets:
+        return
+    _save_run(run, phase=UploadRun.PHASE_VISUAL)
+    index = build_hash_index()
+    now = timezone.now()
+    for row in targets:
+        try:
+            hashes = services.compute_visual_hashes(row.file.path)
+            if not hashes:
+                TempUpload.objects.filter(pk=row.pk).update(
+                    visual_checked_at=now, pipeline_error="", updated_at=now
+                )
+                continue
+            matches = match_hashes(hashes, index, user=user)
+            update = {
+                "visual_matches": matches,
+                "visual_checked_at": now,
+                "pipeline_error": "",
+                "updated_at": now,
+            }
+            if matches and row.status == TempUpload.STATUS_PENDING:
+                update["status"] = TempUpload.STATUS_VISUAL_MATCH
+            TempUpload.objects.filter(pk=row.pk).update(**update)
+        except Exception as exc:  # noqa: BLE001 - keep going for other files
+            logger.exception("Visual similarity failed for %s", row.pk)
+            record_failure(row, f"Visual similarity failed: {exc}")
+
+
+def iqdb_phase(run, user, rows):
+    """Reverse-image search every unresolved image, one e621 query each."""
+    targets = [
+        row
+        for row in rows
+        if row.iqdb_data is None
+        and row.status in WORK_STATUSES
+        and row.file
+        and not is_video(row.original_filename)
+    ]
+    if not targets:
+        return
+    _save_run(run, phase=UploadRun.PHASE_IQDB)
+    heartbeat_at = time.monotonic()
+    for row in targets:
+        # Keep the run row fresh: a 75-file IQDB round takes minutes and must
+        # not look like a dead worker to another request.
+        if time.monotonic() - heartbeat_at > 30:
+            UploadRun.objects.filter(pk=run.pk).update(updated_at=timezone.now())
+            heartbeat_at = time.monotonic()
+        try:
+            raw = e621.iqdb_search(user, row.file.path)
+            results = normalize_iqdb_results(user, raw)
+        except e621.E621AuthError as exc:
+            record_failure(row, str(exc))
+            raise PipelinePaused(
+                "e621 rejected the credentials — fix them in Account and retry."
+            ) from exc
+        except e621.E621RateLimited as exc:
+            record_failure(row, str(exc))
+            raise PipelinePaused(
+                "e621 is throttling IQDB right now; the queue will resume."
+            ) from exc
+        except Exception as exc:  # noqa: BLE001 - keep going for other files
+            logger.exception("IQDB search failed for %s", row.pk)
+            record_failure(row, f"IQDB search failed: {exc}")
+            continue
+        now = timezone.now()
+        update = {
+            "iqdb_data": results,
+            "pipeline_error": "",
+            "updated_at": now,
+        }
+        if results and row.status == TempUpload.STATUS_PENDING:
+            update["status"] = TempUpload.STATUS_VISUAL_MATCH
+        TempUpload.objects.filter(pk=row.pk).update(**update)
+
+
+def record_failure(row, message):
+    """Count one failed attempt against a row and queue it for a retry."""
+    TempUpload.objects.filter(pk=row.pk).update(
+        attempts=F("attempts") + 1,
+        pipeline_error=str(message)[:2000],
+        claimed_at=None,
+        updated_at=timezone.now(),
+    )
+
+
+def finalize_round(run, ids, matched):
+    """Account finished/failed rows and release the rest of the claims."""
+    rows = refresh(ids)
+    finished = {row.pk for row in rows if is_finished(row)}
+    failed = {row.pk for row in rows if row.attempts >= MAX_ATTEMPTS}
+    # Release every claim: finished rows must not keep looking "processing"
+    # to the board, and unfinished rows are re-queued for the next run.
+    release = [row.pk for row in rows if row.claimed_at is not None]
+    if release:
+        TempUpload.objects.filter(pk__in=release).update(claimed_at=None)
+    _save_run(
+        run,
+        # Completed rows are deleted as they are imported, so they cannot be
+        # seen in the refreshed rows; count the matches explicitly.
+        processed=run.processed + len(finished) + matched,
+        failed=run.failed + len(failed - finished),
+        matched=run.matched + matched,
+    )
+
+
+def _e621_round(task):
+    """Run a round-level e621 call, retrying through rate limits."""
+    last_error = None
+    for attempt in range(ROUND_ATTEMPTS):
+        try:
+            return task()
+        except e621.E621AuthError:
+            raise
+        except (e621.E621RateLimited, e621.E621Error) as exc:
+            last_error = exc
+            if attempt + 1 >= ROUND_ATTEMPTS:
+                break
+            delay = ROUND_RETRY_SECONDS * (attempt + 1)
+            logger.info("e621 round failed (%s); retrying in %ss", exc, delay)
+            time.sleep(delay)
+    raise PipelinePaused(
+        f"e621 is not answering right now ({last_error}); the queue will resume."
+    ) from last_error
+
+
+def flatten_tag_preview(tags, limit=8):
+    """First few tag names from a modern post payload, like the SPA shows."""
+    if not isinstance(tags, dict):
+        return []
+    out = []
+    for values in tags.values():
+        if not isinstance(values, list):
+            continue
+        for tag in values:
+            if isinstance(tag, str) and tag not in out:
+                out.append(tag)
+                if len(out) >= limit:
+                    return out
+    return out
+
+
+def _legacy_iqdb_post(entry):
+    """Unwrap the post payload embedded in a legacy IQDB match."""
+    post = entry.get("post")
+    if not isinstance(post, dict):
+        return {}
+    inner = post.get("posts")
+    return inner if isinstance(inner, dict) else post
+
+
+def normalize_iqdb_results(user, raw_results):
+    """Shape legacy IQDB matches like the SPA's E621IqdbCandidate entries.
+
+    The IQDB payload carries little post data, so candidates are enriched
+    with one batched ``id:`` lookup before they are stored.
+    """
+    candidates = []
+    for entry in (raw_results or [])[:10]:
+        if not isinstance(entry, dict):
+            continue
+        post = _legacy_iqdb_post(entry)
+        post_id = entry.get("post_id")
+        if not isinstance(post_id, int):
+            post_id = post.get("id")
+        score = entry.get("score")
+        candidates.append(
+            {
+                "post_id": post_id if isinstance(post_id, int) else None,
+                "score": float(score) if isinstance(score, (int, float)) else None,
+                "preview_url": None,
+                "rating": (
+                    post.get("rating") if isinstance(post.get("rating"), str) else None
+                ),
+                "md5": post.get("md5") if isinstance(post.get("md5"), str) else None,
+                "score_total": (
+                    post.get("score") if isinstance(post.get("score"), int) else None
+                ),
+                "fav_count": (
+                    post.get("fav_count")
+                    if isinstance(post.get("fav_count"), int)
+                    else None
+                ),
+                "width": (
+                    post.get("image_width")
+                    if isinstance(post.get("image_width"), int)
+                    else None
+                ),
+                "height": (
+                    post.get("image_height")
+                    if isinstance(post.get("image_height"), int)
+                    else None
+                ),
+                "tags_preview": [],
+            }
+        )
+
+    ids = [entry["post_id"] for entry in candidates if entry["post_id"]]
+    if not ids:
+        return services.sanitize_iqdb_results(candidates)
+
+    try:
+        posts = e621.fetch_posts_by_ids(user, ids)
+    except e621.E621Error as exc:
+        # Candidates without enrichment still show up; keep them.
+        logger.info("Could not enrich IQDB candidates: %s", exc)
+        posts = []
+    by_id = {post.get("id"): post for post in posts}
+
+    for entry in candidates:
+        post = by_id.get(entry["post_id"])
+        if not isinstance(post, dict):
+            continue
+        file_data = post.get("file") or {}
+        preview = post.get("preview") or {}
+        score = post.get("score") or {}
+        entry["preview_url"] = preview.get("url") or entry["preview_url"]
+        entry["rating"] = post.get("rating") or entry["rating"]
+        entry["md5"] = file_data.get("md5") or entry["md5"]
+        if isinstance(score, dict):
+            entry["score_total"] = score.get("total")
+        entry["fav_count"] = post.get("fav_count")
+        entry["width"] = file_data.get("width")
+        entry["height"] = file_data.get("height")
+        entry["tags_preview"] = flatten_tag_preview(post.get("tags"))
+
+    return services.sanitize_iqdb_results(candidates)

backend/apps/library/uploads.py

@@ -16,7 +16,7 @@ from urllib.parse import urlparse
 
 from django.conf import settings
 from django.contrib.auth import get_user_model
-from django.core import signing
+from django.core.exceptions import ValidationError
 from django.http import Http404
 from django.utils import timezone
 from rest_framework import mixins, status, viewsets
@@ -28,32 +28,39 @@ from rest_framework.response import Response
 from . import services
 from .models import MediaItem, TempUpload
 from .permissions import CanUpload
-from .serializers import TempUploadSerializer
-from .tools import HASH_FIELDS, hashes_similarity
+from .serializers import TempUploadListSerializer, TempUploadSerializer
+from .signing_urls import load_payload
+from .tools import HASH_FIELDS, hashed_items, hashes_similarity
 
 logger = logging.getLogger(__name__)
 
 
-def find_library_matches(path, limit=10, user=None, request=None):
-    """Library items visually similar to a staged file."""
-    hashes = services.compute_visual_hashes(path)
-    if not hashes:
-        return []
+def build_hash_index():
+    """Library hash mappings for similarity scans, loaded once per batch.
+
+    Only items that actually carry perceptual hashes are included; the old
+    per-file scan walked every row (including videos and unchecked items).
+    """
+    algorithms = list(HASH_FIELDS)
+    return [
+        (item, {field: getattr(item, field, "") for field in algorithms})
+        for item in hashed_items(algorithms)
+    ]
+
+
+def match_hashes(hashes, index, limit=10, user=None, request=None):
+    """Library items whose perceptual hashes are close to ``hashes``."""
     algorithms = list(HASH_FIELDS)
     threshold = settings.VISUAL_MATCH_THRESHOLD
     matches = []
-    for item in MediaItem.objects.prefetch_related("locations"):
-        similarity = hashes_similarity(
-            hashes,
-            {field: getattr(item, field, "") for field in algorithms},
-            algorithms,
-            threshold,
-        )
+    for item, item_hashes in index:
+        similarity = hashes_similarity(hashes, item_hashes, algorithms, threshold)
         if similarity is None:
             continue
         location = item.locations.first()
         matches.append(
             {
+                "item_id": item.id,
                 "j_id": f"J-{item.id}",
                 "filename": Path(location.rel_path).name if location else item.md5,
                 "similarity": round(similarity * 100, 1),
@@ -66,6 +73,20 @@ def find_library_matches(path, limit=10, user=None, request=None):
     return matches[:limit]
 
 
+def find_library_matches(path, limit=10, user=None, request=None, index=None):
+    """Library items visually similar to a staged file.
+
+    Pass a prebuilt ``index`` (see build_hash_index) to reuse it across a
+    whole batch instead of rescanning the library per file.
+    """
+    hashes = services.compute_visual_hashes(path)
+    if not hashes:
+        return []
+    if index is None:
+        index = build_hash_index()
+    return match_hashes(hashes, index, limit=limit, user=user, request=request)
+
+
 def complete_temp_upload(temp, download_url=None):
     """Index the upload into the library.
 
@@ -107,6 +128,12 @@ def complete_temp_upload(temp, download_url=None):
         services.ensure_visual_hashes(item)
         temp.file.delete(save=False)
 
+    # Warm the preview while the import is still off the request path.
+    try:
+        services.ensure_thumbnail(item)
+    except Exception:  # noqa: BLE001 - a preview must not fail the import
+        logger.exception("Could not warm the thumbnail for J-%s", item.id)
+
     temp.library_item = item
     temp.status = TempUpload.STATUS_COMPLETED
 
@@ -138,6 +165,13 @@ def complete_temp_upload(temp, download_url=None):
         item.save(update_fields=update_fields + ["updated_at"])
 
     temp.save()
+    from .upload_pipeline import record_completion
+
+    record_completion(temp, item)
+    # The board learns about completions from the live feed, so the record is
+    # deleted as soon as the file is indexed: nothing left to dismiss. Delete
+    # through the queryset so callers keep ``temp.pk`` for their response.
+    TempUpload.objects.filter(pk=temp.pk).delete()
     return item
 
 
@@ -150,14 +184,47 @@ class TempUploadViewSet(
     serializer_class = TempUploadSerializer
     permission_classes = [CanUpload]
     parser_classes = [MultiPartParser, FormParser, JSONParser]
+    # Unpaginated: the board shows every staged upload (69-file batches were
+    # silently cut to the API's 48-item page).
+    pagination_class = None
     http_method_names = ["get", "post", "delete", "head", "options"]
 
+    def get_serializer_class(self):
+        # The board polls the list, so its payload stays small; the metadata
+        # modal fetches the full row from the detail endpoint.
+        if self.action == "list":
+            return TempUploadListSerializer
+        return TempUploadSerializer
+
     def get_queryset(self):
-        queryset = TempUpload.objects.select_related("library_item")
-        user = self.request.user
-        if not user.is_app_staff:
-            queryset = queryset.filter(user=user)
-        return queryset
+        # Staged uploads are private: everyone, staff included, only sees
+        # their own board. (The file action still lets staff read bytes by id
+        # for support purposes.)
+        return TempUpload.objects.select_related("library_item").filter(
+            user=self.request.user
+        )
+
+    def _completed_payload(self, temp, item):
+        """Synthetic row for an upload that is indexed immediately.
+
+        Duplicates and resolved uploads never leave a board record; the SPA
+        turns this response (or the live completion feed) into a "J-x
+        uploaded" card that lives only in the page session.
+        """
+        return {
+            "temp_id": str(temp.pk),
+            "original_filename": temp.original_filename,
+            "md5": temp.md5,
+            "size": temp.size,
+            "status": TempUpload.STATUS_COMPLETED,
+            "resolution": temp.resolution,
+            "e621_post_id": temp.e621_post_id,
+            "library_j_id": f"J-{item.id}",
+            "file_url": None,
+            "preview_url": services.signed_media_url(
+                item, self.request.user, "thumbnail", request=self.request
+            ),
+        }
 
     def create(self, request):
         upload = request.FILES.get("file")
@@ -186,33 +253,190 @@ class TempUploadViewSet(
             temp.resolution = TempUpload.RESOLUTION_DUPLICATE
             temp.library_item = existing
             temp.file.delete(save=False)
-        else:
-            matches = find_library_matches(
-                temp.file.path, user=request.user, request=request
-            )
-            if matches:
-                temp.visual_matches = matches
-                temp.status = TempUpload.STATUS_VISUAL_MATCH
+            temp.save()
+            from .upload_pipeline import record_completion
+
+            record_completion(temp, existing)
+            payload = self._completed_payload(temp, existing)
+            TempUpload.objects.filter(pk=temp.pk).delete()
+            return Response(payload, status=status.HTTP_201_CREATED)
+        # Visual similarity and IQDB run in the background pipeline so a large
+        # batch uploads at full speed and the work survives the browser.
         temp.save()
+        # Kick the server-side pipeline; staging no longer waits on e621 and
+        # the work continues even if the browser navigates away.
+        from .upload_pipeline import start_pipeline
+
+        start_pipeline(request.user)
         return Response(
             self.get_serializer(temp).data, status=status.HTTP_201_CREATED
         )
 
-    @action(detail=True, methods=["get", "head"], permission_classes=[AllowAny])
+    @action(detail=True, methods=["post"], url_path="visual-match")
+    def visual_match(self, request, pk=None):
+        """Run the local visual-similarity pass for one staged upload."""
+        temp = self.get_object()
+        if temp.status == TempUpload.STATUS_COMPLETED:
+            return Response(
+                {"detail": "This upload is already in the library."},
+                status=status.HTTP_400_BAD_REQUEST,
+            )
+        if not temp.file:
+            return Response(
+                {"detail": "The staged file is missing."},
+                status=status.HTTP_400_BAD_REQUEST,
+            )
+        matches = find_library_matches(
+            temp.file.path, user=request.user, request=request
+        )
+        temp.visual_matches = matches
+        if matches and temp.status == TempUpload.STATUS_PENDING:
+            temp.status = TempUpload.STATUS_VISUAL_MATCH
+        temp.save(update_fields=["visual_matches", "status", "updated_at"])
+        return Response(self.get_serializer(temp).data)
+
+    @action(detail=False, methods=["get"])
+    def status(self, request):
+        """Cheap pipeline state for the shell indicator and the upload page."""
+        from .upload_pipeline import status_payload
+
+        return Response(status_payload(request.user, request=request))
+
+    @action(detail=False, methods=["post"])
+    def process(self, request):
+        """Start (or resume) the pipeline for the caller's staged uploads.
+
+        Idempotent: the client calls this after staging files, on page load
+        and when a paused run should be retried.
+        """
+        from .upload_pipeline import start_pipeline, status_payload
+
+        start_pipeline(request.user)
+        return Response(status_payload(request.user, request=request))
+
+    @action(detail=True, methods=["post"])
+    def retry(self, request, pk=None):
+        """Queue one staged upload for another pipeline pass."""
+        from .upload_pipeline import start_pipeline, status_payload
+
+        temp = self.get_object()
+        if temp.status == TempUpload.STATUS_COMPLETED:
+            return Response(
+                {"detail": "This upload is already in the library."},
+                status=status.HTTP_400_BAD_REQUEST,
+            )
+        if not temp.file:
+            return Response(
+                {"detail": "The staged file is missing."},
+                status=status.HTTP_400_BAD_REQUEST,
+            )
+        update = {
+            "claimed_at": None,
+            "attempts": 0,
+            "pipeline_error": "",
+            "updated_at": timezone.now(),
+        }
+        # An explicit phase re-runs that one check even if it already ran.
+        phase = str(request.data.get("phase") or "").strip()
+        if phase == "md5":
+            update["e621_checked_at"] = None
+        elif phase == "visual":
+            update["visual_matches"] = None
+            update["visual_checked_at"] = None
+        elif phase == "iqdb":
+            update["iqdb_data"] = None
+        if temp.status == TempUpload.STATUS_ERROR:
+            # A failed import has to go through the MD5 phase again so the
+            # completion is retried; other errors only re-run missing phases.
+            update["status"] = TempUpload.STATUS_PENDING
+            update["e621_checked_at"] = None
+        elif temp.status not in (
+            TempUpload.STATUS_PENDING,
+            TempUpload.STATUS_VISUAL_MATCH,
+        ):
+            update["status"] = TempUpload.STATUS_PENDING
+        TempUpload.objects.filter(pk=temp.pk).update(**update)
+        start_pipeline(request.user)
+        return Response(status_payload(request.user, request=request))
+
+    @action(detail=False, methods=["post"], url_path="retry-all")
+    def retry_all(self, request):
+        """Queue every retryable staged upload for another pipeline pass."""
+        from .upload_pipeline import start_pipeline, status_payload
+
+        now = timezone.now()
+        retryable = self.get_queryset().filter(
+            status__in=[
+                TempUpload.STATUS_PENDING,
+                TempUpload.STATUS_VISUAL_MATCH,
+                TempUpload.STATUS_ERROR,
+            ]
+        )
+        retryable.exclude(file="").update(
+            claimed_at=None,
+            attempts=0,
+            pipeline_error="",
+            updated_at=now,
+        )
+        retryable.exclude(file="").filter(status=TempUpload.STATUS_ERROR).update(
+            status=TempUpload.STATUS_PENDING,
+            e621_checked_at=None,
+        )
+        start_pipeline(request.user)
+        return Response(status_payload(request.user, request=request))
+
+    @action(detail=False, methods=["post"], url_path="discard-bulk")
+    def discard_bulk(self, request):
+        """Discard many staged uploads in one request (the board's "all")."""
+        ids = request.data.get("temp_ids")
+        if not isinstance(ids, list) or not ids:
+            return Response(
+                {"detail": "temp_ids must be a non-empty list."},
+                status=status.HTTP_400_BAD_REQUEST,
+            )
+        if len(ids) > 1000:
+            return Response(
+                {"detail": "Too many ids in one request (max 1000)."},
+                status=status.HTTP_400_BAD_REQUEST,
+            )
+        values = list(dict.fromkeys(str(value) for value in ids))
+        try:
+            queryset = self.get_queryset().filter(pk__in=values)
+        except (ValidationError, ValueError):
+            return Response(
+                {"detail": "One or more temp_ids are not valid upload ids."},
+                status=status.HTTP_400_BAD_REQUEST,
+            )
+        by_id = {str(temp.pk): temp for temp in queryset}
+
+        discarded: list[str] = []
+        errors: list[dict[str, str]] = []
+        for value in values:
+            temp = by_id.get(value)
+            if temp is None:
+                errors.append({"temp_id": value, "error": "not found"})
+                continue
+            try:
+                self.perform_destroy(temp)
+                discarded.append(value)
+            except Exception as exc:  # noqa: BLE001 - report per-file failures
+                logger.exception("Could not discard staged upload %s", value)
+                errors.append({"temp_id": value, "error": str(exc)})
+        return Response({"discarded": discarded, "errors": errors})
+
+    @action(
+        detail=True,
+        methods=["get", "head"],
+        permission_classes=[AllowAny],
+        throttle_classes=[],
+    )
     def file(self, request, pk=None):
         """Serve the staged file; accepts a signed URL for media tags."""
         user = request.user if request.user.is_authenticated else None
         if user is None:
             signature = request.query_params.get("sig")
             if signature:
-                try:
-                    payload = signing.loads(
-                        signature,
-                        salt=services.UPLOAD_FILE_SALT,
-                        max_age=86400,
-                    )
-                except signing.BadSignature:
-                    payload = None
+                payload = load_payload(signature, services.UPLOAD_FILE_SALT)
                 if payload and str(payload.get("temp")) == str(pk):
                     user = (
                         get_user_model()
@@ -313,7 +537,7 @@ class TempUploadViewSet(
 
         temp.save()
         try:
-            complete_temp_upload(temp, download_url=download_url)
+            item = complete_temp_upload(temp, download_url=download_url)
         except Exception as exc:  # noqa: BLE001 - report completion failures
             logger.exception("Could not complete staged upload %s", temp.id)
             temp.status = TempUpload.STATUS_ERROR
@@ -322,8 +546,146 @@ class TempUploadViewSet(
                 {"detail": f"Could not finish the upload: {exc}"},
                 status=status.HTTP_400_BAD_REQUEST,
             )
-        temp.refresh_from_db()
-        return Response(self.get_serializer(temp).data)
+        return Response(self._completed_payload(temp, item))
+
+    @action(detail=False, methods=["post"], url_path="link-bulk")
+    def link_bulk(self, request):
+        """Attach e621 posts to many staged uploads in one request.
+
+        The upload board's MD5 phase sends one posts.json query per 75 files
+        and hands the matches over here, so a whole batch moves into the
+        library in one update instead of one request per file.
+        """
+        links = request.data.get("links")
+        if not isinstance(links, list) or not links:
+            return Response(
+                {"detail": "links must be a non-empty list."},
+                status=status.HTTP_400_BAD_REQUEST,
+            )
+        ids = []
+        for link in links:
+            if not isinstance(link, dict) or link.get("temp_id") is None:
+                return Response(
+                    {"detail": "Each link needs a temp_id."},
+                    status=status.HTTP_400_BAD_REQUEST,
+                )
+            ids.append(str(link["temp_id"]))
+        try:
+            queryset = self.get_queryset().filter(pk__in=ids)
+        except (ValidationError, ValueError):
+            return Response(
+                {"detail": "One or more temp_ids are not valid upload ids."},
+                status=status.HTTP_400_BAD_REQUEST,
+            )
+        by_id = {str(temp.id): temp for temp in queryset}
+
+        updated = []
+        errors = []
+        for link in links:
+            temp_id = str(link["temp_id"])
+            temp = by_id.get(temp_id)
+            if temp is None:
+                errors.append({"temp_id": temp_id, "error": "not found"})
+                continue
+            if temp.status == TempUpload.STATUS_COMPLETED:
+                errors.append({"temp_id": temp_id, "error": "already in the library"})
+                continue
+            trimmed = services.trim_e621_post(link.get("post"))
+            post_id = link.get("post_id")
+            has_numeric_id = post_id is not None and str(post_id).isdigit()
+            if trimmed is None and not has_numeric_id:
+                errors.append({"temp_id": temp_id, "error": "no post payload"})
+                continue
+            if trimmed is not None and trimmed.get("id") is not None:
+                temp.e621_post_id = int(trimmed["id"])
+            elif has_numeric_id:
+                temp.e621_post_id = int(post_id)
+            temp.e621_data = trimmed
+            temp.resolution = (
+                TempUpload.RESOLUTION_AUTO_MD5
+                if link.get("auto", True)
+                else TempUpload.RESOLUTION_LINKED
+            )
+            # An MD5 match means the staged file is byte-identical, so there
+            # is nothing to download from e621; only link a remote URL when
+            # the post's file differs.
+            file_data = (trimmed or {}).get("file") or {}
+            candidate_url = str(
+                link.get("file_url") or file_data.get("url") or ""
+            ).strip()
+            post_md5 = str(file_data.get("md5") or "").strip().lower()
+            if candidate_url and post_md5 and post_md5 == temp.md5.lower():
+                candidate_url = ""
+            temp.save()
+            try:
+                item = complete_temp_upload(temp, download_url=candidate_url or None)
+            except Exception as exc:  # noqa: BLE001 - report per-file failures
+                logger.exception("Could not complete staged upload %s", temp.id)
+                temp.status = TempUpload.STATUS_ERROR
+                temp.save(update_fields=["status", "updated_at"])
+                errors.append({"temp_id": temp_id, "error": str(exc)})
+                continue
+            updated.append(self._completed_payload(temp, item))
+
+        return Response({"updated": updated, "errors": errors})
+
+    @action(detail=False, methods=["post"], url_path="resolve-bulk")
+    def resolve_bulk(self, request):
+        """Move many staged uploads into the library with one rating.
+
+        The upload board's bulk tool: pick a rating, tick pending files, and
+        they are all resolved as custom entries (their staged tags/notes are
+        kept). Own rows only, like the rest of the viewset.
+        """
+        ids = request.data.get("temp_ids")
+        if not isinstance(ids, list) or not ids:
+            return Response(
+                {"detail": "temp_ids must be a non-empty list."},
+                status=status.HTTP_400_BAD_REQUEST,
+            )
+        rating = str(request.data.get("rating") or "").strip()
+        if rating not in {"s", "q", "e"}:
+            return Response(
+                {"detail": "rating must be one of s, q or e."},
+                status=status.HTTP_400_BAD_REQUEST,
+            )
+
+        try:
+            queryset = self.get_queryset().filter(
+                pk__in=[str(value) for value in ids]
+            )
+        except (ValidationError, ValueError):
+            return Response(
+                {"detail": "One or more ids are not valid upload ids."},
+                status=status.HTTP_400_BAD_REQUEST,
+            )
+
+        resolved: list[str] = []
+        errors: list[dict[str, str]] = []
+        for temp in queryset:
+            if temp.status == TempUpload.STATUS_COMPLETED:
+                errors.append(
+                    {"temp_id": str(temp.id), "error": "already in the library"}
+                )
+                continue
+            temp.custom_rating = rating
+            temp.resolution = TempUpload.RESOLUTION_CUSTOM
+            temp.save(update_fields=["custom_rating", "resolution", "updated_at"])
+            try:
+                complete_temp_upload(temp)
+            except Exception as exc:  # noqa: BLE001 - report per-file failures
+                logger.exception("Could not complete staged upload %s", temp.id)
+                temp.status = TempUpload.STATUS_ERROR
+                temp.save(update_fields=["status", "updated_at"])
+                errors.append({"temp_id": str(temp.id), "error": str(exc)})
+                continue
+            resolved.append(str(temp.id))
+
+        found = {str(temp.id) for temp in queryset}
+        for value in sorted({str(value) for value in ids} - found):
+            errors.append({"temp_id": value, "error": "not found"})
+
+        return Response({"resolved": resolved, "errors": errors})
 
     def perform_destroy(self, instance):
         if instance.file:

backend/apps/library/views.py

@@ -5,7 +5,6 @@ from pathlib import Path
 from urllib.parse import urlparse
 
 from django.conf import settings
-from django.core import signing
 from django.db.models import Min, Q
 from django.http import Http404, StreamingHttpResponse
 from django.shortcuts import get_object_or_404
@@ -31,6 +30,7 @@ from .serializers import (
     MatchTaskSerializer,
     MediaItemSerializer,
 )
+from .signing_urls import load_payload
 
 LIST_ORDERINGS = {"name", "-name", "size", "-size", "created_at", "-created_at"}
 MD5_RE = re.compile(r"[0-9a-fA-F]{32}")
@@ -132,11 +132,8 @@ class MediaItemViewSet(
         signature = request.query_params.get("sig")
         if not signature:
             return None
-        try:
-            payload = signing.loads(
-                signature, salt=services.MEDIA_FILE_SALT, max_age=86400
-            )
-        except signing.BadSignature:
+        payload = load_payload(signature, services.MEDIA_FILE_SALT)
+        if payload is None:
             return None
         if payload.get("action") != action_name:
             return None
@@ -148,7 +145,7 @@ class MediaItemViewSet(
             return item
         return self.get_object()
 
-    @action(detail=True, methods=["get"])
+    @action(detail=True, methods=["get"], throttle_classes=[])
     def raw(self, request, pk=None):
         item = self._media_object(request, "raw")
         location = item.locations.first()
@@ -158,10 +155,14 @@ class MediaItemViewSet(
                 status=status.HTTP_404_NOT_FOUND,
             )
         return services.serve_file(
-            request, location.path, download=request.query_params.get("download") == "1"
+            request,
+            location.path,
+            download=request.query_params.get("download") == "1",
+            max_age=services.MEDIA_CACHE_SECONDS,
+            immutable=True,
         )
 
-    @action(detail=True, methods=["get"])
+    @action(detail=True, methods=["get"], throttle_classes=[])
     def thumbnail(self, request, pk=None):
         item = self._media_object(request, "thumbnail")
         location = item.locations.first()
@@ -173,13 +174,26 @@ class MediaItemViewSet(
         path = Path(location.path)
         if path.suffix.lower() in services.VIDEO_EXTENSIONS:
             thumbnail = services.generate_video_thumbnail(item.md5, path)
-            if thumbnail is None:
-                return Response(
-                    {"detail": "Thumbnail unavailable."},
-                    status=status.HTTP_404_NOT_FOUND,
-                )
-            return services.serve_file(request, thumbnail)
-        return services.serve_file(request, path)
+        else:
+            thumbnail = services.generate_image_thumbnail(item.md5, path)
+        if thumbnail is not None:
+            return services.serve_file(
+                request,
+                thumbnail,
+                max_age=services.MEDIA_CACHE_SECONDS,
+                immutable=True,
+            )
+        if path.suffix.lower() in services.VIDEO_EXTENSIONS:
+            return Response(
+                {"detail": "Thumbnail unavailable."},
+                status=status.HTTP_404_NOT_FOUND,
+            )
+        return services.serve_file(
+            request,
+            path,
+            max_age=services.MEDIA_CACHE_SECONDS,
+            immutable=True,
+        )
 
     @action(detail=False, methods=["post"], permission_classes=[AllowAny])
     def lookup(self, request):

backend/config/settings.py

@@ -206,7 +206,9 @@ WATCHED_FOLDER = str(WATCHED_FOLDER)
 # e621 integration
 
 E621_BASE_URL = os.getenv("E621_BASE_URL", "https://e621.net").rstrip("/")
-USER_AGENT = os.getenv("USER_AGENT", "J621/0.1 (by J621 on e621)")
+# e621 asks for "Application name/version (developer)". Browser clients cannot
+# set a User-Agent, so the SPA sends the same string in its `_client` parameter.
+USER_AGENT = os.getenv("USER_AGENT", f"J621/{GIT_COMMIT_HASH} (JakeBreath)")
 # Hosts the client-download proxy is allowed to stream from.
 E621_MEDIA_HOSTS = [
     host.strip()
@@ -232,6 +234,12 @@ GUEST_BLACKLIST_TTL = int(os.getenv("GUEST_BLACKLIST_TTL", "3600"))
 # Similarity threshold for flagging staged uploads that match library items.
 VISUAL_MATCH_THRESHOLD = float(os.getenv("VISUAL_MATCH_THRESHOLD", "0.9"))
 
+# Start the staged-upload pipeline when a file is staged (daemon thread in the
+# worker). Tests turn this off and drive the pipeline synchronously.
+UPLOAD_PIPELINE_AUTOSTART = os.getenv(
+    "UPLOAD_PIPELINE_AUTOSTART", "true"
+).strip().lower() not in {"0", "false", "no", "off"}
+
 # Ephemeral similarity-check uploads are deleted after this many minutes
 # (and always on startup).
 SIMILARITY_TTL_MINUTES = int(os.getenv("SIMILARITY_TTL_MINUTES", "30"))
@@ -240,13 +248,23 @@ SIMILARITY_TTL_MINUTES = int(os.getenv("SIMILARITY_TTL_MINUTES", "30"))
 # workers and management commands (e.g. the mirrored guest blacklist).
 CACHES = {
     "default": {
-        "BACKEND": "django.core.cache.backends.redis.RedisCache",
+        "BACKEND": "apps.core.cache.ResilientRedisCache",
         "LOCATION": os.getenv("REDIS_URL", "redis://127.0.0.1:6380/1"),
     }
 }
 
 # Django REST Framework
 
+# Private / tailnet-only deployments can drop the general anon+user limits
+# entirely (THROTTLE_ENABLED=false). The scoped guards below (login, register,
+# e621 proxy) and the media endpoints' own protections stay active either way.
+THROTTLE_ENABLED = os.getenv("THROTTLE_ENABLED", "true").strip().lower() not in {
+    "0",
+    "false",
+    "no",
+    "off",
+}
+
 REST_FRAMEWORK = {
     "DEFAULT_AUTHENTICATION_CLASSES": [
         "rest_framework.authentication.TokenAuthentication",
@@ -261,11 +279,18 @@ REST_FRAMEWORK = {
     ],
     "DEFAULT_PAGINATION_CLASS": "config.pagination.StandardPagination",
     "PAGE_SIZE": 48,
-    # Per-IP/per-user rate limits (counted in the shared Redis cache).
-    "DEFAULT_THROTTLE_CLASSES": [
-        "rest_framework.throttling.AnonRateThrottle",
-        "rest_framework.throttling.UserRateThrottle",
-    ],
+    # Per-IP/per-user rate limits (counted in the shared Redis cache). Signed
+    # media URLs are deliberately excluded at the view level: <img>/<video>
+    # tags fetch them without an Authorization header, so a library page would
+    # otherwise burn the anonymous bucket and start returning JSON 429s.
+    "DEFAULT_THROTTLE_CLASSES": (
+        [
+            "rest_framework.throttling.AnonRateThrottle",
+            "rest_framework.throttling.UserRateThrottle",
+        ]
+        if THROTTLE_ENABLED
+        else []
+    ),
     "DEFAULT_THROTTLE_RATES": {
         # Generous enough for the shell polling (status every 5s, stats every 2s).
         "anon": os.getenv("THROTTLE_ANON", "120/min"),

deploy/.env.example

@@ -30,7 +30,10 @@ ALLOWED_HOSTS=j621.rainbow-herring.ts.net,localhost,127.0.0.1
 # ---------------------------------------------------------------------------
 # Cross-origin access (needed for the separate frontend + backend deploys)
 # ---------------------------------------------------------------------------
-# The origin the SPA is served from, e.g. https://j621-frontend.<tailnet>.ts.net
+# The origin the SPA is served from for split deploys, e.g.
+# https://j621-frontend.<tailnet>.ts.net. gen_env.sh writes this plus the
+# desktop shell's app://j621 origin into the line below (and keeps existing
+# entries on --update).
 # CORS_ALLOWED_ORIGINS=
 # CSRF_TRUSTED_ORIGINS=
 
@@ -61,6 +64,10 @@ DB_ROOT_PASSWORD=j621root
 # THROTTLE_LOGIN=5/min
 # THROTTLE_REGISTER=20/hour
 # THROTTLE_E621_PROXY=60/hour
+# Tailnet-only / private deployments can drop the general limits entirely.
+# Signed media URLs (<img>/<video>) and the login/register/proxy guards are
+# exempt from this switch either way.
+# THROTTLE_ENABLED=false
 
 # e621 media hosts the backend may fetch from (downloads, proxies)
 # E621_MEDIA_HOSTS=static1.e621.net,static2.e621.net,static3.e621.net

deploy/J621-Backend

@@ -30,6 +30,14 @@ COPY backend/ ./
 COPY deploy/backend-entrypoint.sh /usr/local/bin/j621-entrypoint
 COPY deploy/scheduler-entrypoint.sh /usr/local/bin/j621-scheduler
 
+# Guard: fail the build if the context leaked secrets or runtime data
+# (.dockerignore excludes them — see the repository root).
+RUN test ! -e /app/.env \
+    && test ! -d /app/venv \
+    && test ! -d /app/media/library \
+    && test ! -e /app/db.sqlite3 \
+    && echo "build context clean"
+
 RUN chmod +x /usr/local/bin/j621-entrypoint /usr/local/bin/j621-scheduler \
     && mkdir -p /app/media /app/logs \
     && python manage.py collectstatic --noinput

deploy/J621-Frontend

@@ -10,6 +10,8 @@
 # syntax=docker/dockerfile:1
 
 FROM node:22-alpine AS build
+ARG GIT_HASH=dev
+ENV GIT_HASH=$GIT_HASH
 WORKDIR /app
 COPY frontend/package.json frontend/package-lock.json ./
 RUN npm ci --no-audit --no-fund

deploy/README.md

@@ -92,6 +92,10 @@ The SPA asks where the backend is (`/setup`) in production builds:
   backend's funnel URL, e.g. `https://j621-backend.<tailnet>.ts.net:8443`,
   and give the backend `CORS_ALLOWED_ORIGINS=https://<frontend-host>.<tailnet>.ts.net`
   (plus `CSRF_TRUSTED_ORIGINS` for the admin).
+- **Desktop app** — the Electron shell (`desktop/`) is served from the
+  `app://j621` origin, which `gen_env.sh` includes in `CORS_ALLOWED_ORIGINS`
+  automatically (add it by hand if you wrote `.env` yourself). The shell's
+  setup screen prints the exact origin when the connection test fails.
 - Without a backend at all, choose **"Continue without a backend"** to run in
   local mode (e621 browsing only).
 
@@ -114,6 +118,15 @@ ffmpeg for video thumbnails. The `GIT_HASH` build arg is baked into the
 backend image so the shell's version pill shows the commit (images have no
 `.git` directory); the push scripts pass it automatically.
 
+Both build from the repository root, which is filtered by `.dockerignore`:
+`backend/venv`, `backend/media`, `backend/logs`, `backend/staticfiles`,
+`backend/.env`, `frontend/node_modules`, `frontend/dist` and the deploy
+runtime state never enter the images — the database, media and logs come
+from the compose volumes and `deploy/.env` at runtime. The backend build
+also asserts that (`.env`, `venv`, `media/library`, `db.sqlite3` absent), so
+a missing ignore file fails the build instead of shipping secrets. Rebuild
+(and `docker image prune`) if you built before that guard existed.
+
 Push multi-arch images to the Gitea registry:
 
 ```bash
@@ -123,6 +136,41 @@ Push multi-arch images to the Gitea registry:
 They tag `:latest` and `:<commit-sha>` and expect `docker login
 gitea.rainbow-herring.ts.net` to succeed.
 
+Build the desktop installers without publishing anything:
+
+```bash
+./build_desktop.sh           # Arch + Debian + Windows -> desktop/release/
+./build_desktop.sh --linux   # Arch + Debian only
+./build_desktop.sh --win     # Windows installer only
+```
+
+Hand the files out or attach them to a Gitea release manually — the script
+prints sizes and SHA-256 sums for the release notes. The release assets are
+also the desktop update feed; the app resolves the newest `desktop-v*`
+release on Gitea at check time (see `desktop/README.md`).
+
+The frontend's `/desktop/` feed is optional now — kept for manual downloads
+and for installs older than 0.1.2. To publish it:
+
+```bash
+./push_desktop.sh            # build Linux packages + copy the feed to jakerasp
+./push_desktop.sh --win      # also cross-build the NSIS installer (wine)
+./push_desktop.sh --local    # publish locally only, skip the remote copy
+./push_desktop.sh --host other:/path/to/J621
+```
+
+The remote copy defaults to `jakerasp:/home/jake/servers/J621`, or
+`$J621_DESKTOP_FEED_HOST` when set. Artifacts land in `deploy/data/desktop/`,
+which the frontend nginx mounts read-only and serves at `/desktop/`. The
+remote copy uses rsync when both ends have it, tar over ssh when the server
+does not. Backend-only composes have no frontend, so no website feed.
+
+The manual **CD** workflow (Actions tab) builds the desktop packages on the
+runner and attaches them plus the update metadata to the Gitea release
+`desktop-v<version>`; that is what the desktop updater reads. The website feed
+is not touched by CI (runtime state on the deploy host, no SSH key there); use
+`push_desktop.sh` when it needs refreshing for old installs.
+
 ## Scheduled jobs
 
 Compose files with a backend also run a **`scheduler`** service — the same

deploy/build_desktop.sh

@@ -0,0 +1,79 @@
+#!/bin/bash
+# Build the J621 desktop packages into desktop/release/ — Arch (.pkg.tar.zst),
+# Debian (.deb) and the Windows NSIS installer. Nothing is published: install
+# the package locally, hand the files out, or attach them to a Gitea release
+# manually. Use push_desktop.sh when the in-app update feed should get them.
+#
+# Usage: ./build_desktop.sh [--linux | --win | --all]
+#   --linux   Arch + Debian packages only
+#   --win     Windows installer only (cross-built with wine)
+#   --all     everything (default)
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+TARGET="${1:---all}"
+case "$TARGET" in
+    --linux) TARGET=linux ;;
+    --win) TARGET=win ;;
+    --all) TARGET=all ;;
+    *)
+        echo "usage: $0 [--linux|--win|--all]" >&2
+        exit 2
+        ;;
+esac
+
+VERSION="$(node -p "require('./desktop/package.json').version")"
+
+if [ ! -d desktop/node_modules ]; then
+    echo "==> Installing desktop dependencies ..."
+    npm --prefix desktop ci --no-audit --no-fund
+fi
+
+if [ "$TARGET" != "linux" ] && ! command -v wine >/dev/null 2>&1; then
+    echo "==> wine is not installed; the Windows installer needs it." >&2
+    exit 1
+fi
+
+# release/ should only ever hold the current version: old installers are
+# rebuilt from git when needed, and the unpacked trees are regenerated.
+shopt -s nullglob
+stale=(desktop/release/*.deb desktop/release/*.pkg.tar.zst desktop/release/"J621 Setup "*.exe
+    desktop/release/*.blockmap desktop/release/latest*.yml)
+for file in "${stale[@]}"; do
+    case "$(basename "$file")" in
+        *"$VERSION"*) ;;
+        *) echo "    removing $(basename "$file")"; rm -f "$file" ;;
+    esac
+done
+rm -rf desktop/release/linux-unpacked desktop/release/win-unpacked
+
+case "$TARGET" in
+    linux) npm --prefix desktop run dist:linux ;;
+    win) npm --prefix desktop run dist:win ;;
+    all) npm --prefix desktop run dist:all ;;
+esac
+
+case "$TARGET" in
+    linux) ARTIFACTS=(-name "*${VERSION}*.deb" -o -name "*${VERSION}*.pkg.tar.zst") ;;
+    win) ARTIFACTS=(-name "*${VERSION}*.exe") ;;
+    all) ARTIFACTS=(-name "*${VERSION}*.deb" -o -name "*${VERSION}*.pkg.tar.zst" -o -name "*${VERSION}*.exe") ;;
+esac
+
+echo
+echo "==> Artifacts in desktop/release/:"
+find desktop/release -maxdepth 1 -type f \( "${ARTIFACTS[@]}" \) \
+    -printf '%s\t%p\n' |
+    sort -rn |
+    while IFS=$'\t' read -r size file; do
+        printf '    %8s  %s\n' "$(numfmt --to=iec "$size")" "$file"
+    done
+
+echo
+echo "==> SHA-256 (for release notes):"
+find desktop/release -maxdepth 1 -type f \( "${ARTIFACTS[@]}" \) \
+    -exec sha256sum {} + | sed 's/^/    /'
+
+echo
+echo "==> J621 desktop $VERSION built."
+echo "    Install here:        sudo pacman -U desktop/release/j621-desktop-*.pkg.tar.zst"
+echo "    Gitea release tag:   desktop-v$VERSION"

deploy/compose.frontend.yml

@@ -20,6 +20,9 @@ services:
       context: ..
       dockerfile: deploy/J621-Frontend
     restart: unless-stopped
+    volumes:
+      # Desktop update feed (deploy/push_desktop.sh): latest*.yml + installers.
+      - ./data/desktop:/usr/share/nginx/html/desktop:ro
 
   nginx:
     image: nginx:1.29-alpine

deploy/compose.tailnet.frontend.yml

@@ -21,6 +21,9 @@ services:
       context: ..
       dockerfile: deploy/J621-Frontend
     restart: unless-stopped
+    volumes:
+      # Desktop update feed (deploy/push_desktop.sh): latest*.yml + installers.
+      - ./data/desktop:/usr/share/nginx/html/desktop:ro
 
   nginx:
     image: nginx:1.29-alpine

deploy/compose.tailnet.yml

@@ -100,6 +100,9 @@ services:
       context: ..
       dockerfile: deploy/J621-Frontend
     restart: unless-stopped
+    volumes:
+      # Desktop update feed (deploy/push_desktop.sh): latest*.yml + installers.
+      - ./data/desktop:/usr/share/nginx/html/desktop:ro
 
   nginx:
     image: nginx:1.29-alpine

deploy/compose.yml

@@ -99,6 +99,9 @@ services:
       context: ..
       dockerfile: deploy/J621-Frontend
     restart: unless-stopped
+    volumes:
+      # Desktop update feed (deploy/push_desktop.sh): latest*.yml + installers.
+      - ./data/desktop:/usr/share/nginx/html/desktop:ro
 
   nginx:
     image: nginx:1.29-alpine

deploy/gen_env.sh

@@ -86,7 +86,26 @@ FQDN="${FQDN:-$DEFAULT_FQDN}"
 # Derive the rest from the tailnet hostname.
 TS_HOSTNAME="${FQDN%%.*}"
 ALLOWED_HOSTS="$FQDN,localhost,127.0.0.1"
-CORS_ALLOWED_ORIGINS="${FRONTEND:+https://$FRONTEND}"
+
+# Cross-origin access: the optional split-deploy frontend plus the desktop
+# shell, which is always a different origin from the backend. On --update the
+# existing list is kept, so hand-added origins survive.
+CORS_ALLOWED_ORIGINS=""
+add_origin() {
+    [ -n "${1:-}" ] || return 0
+    case ",$CORS_ALLOWED_ORIGINS," in
+        *",$1,"*) ;;
+        *) CORS_ALLOWED_ORIGINS="${CORS_ALLOWED_ORIGINS:+$CORS_ALLOWED_ORIGINS,}$1" ;;
+    esac
+}
+if [ "$UPDATE" -eq 1 ]; then
+    while IFS= read -r origin; do
+        add_origin "$origin"
+    done < <(existing CORS_ALLOWED_ORIGINS | tr ',' '\n')
+fi
+[ -n "$FRONTEND" ] && add_origin "https://$FRONTEND"
+add_origin "app://j621"
+
 CSRF_TRUSTED_ORIGINS="${FRONTEND:+https://$FRONTEND}"
 
 J621_SECRET_KEY="$SECRET_KEY" \

deploy/push_backend.sh

@@ -10,10 +10,16 @@ REGISTRY="gitea.rainbow-herring.ts.net/jakebreath/j621-backend"
 REGISTRY_HOST="$(printf '%s' "$REGISTRY" | cut -d/ -f1)"
 SHA="${1:-$(git rev-parse --short HEAD)}"
 BUILDER=multiarch
-PLATFORMS="linux/amd64,linux/arm64"
+PLATFORMS="${PLATFORMS:-linux/amd64,linux/arm64}"
 
 echo "==> Logging in to $REGISTRY_HOST ..."
-docker login "$REGISTRY_HOST"
+if [ -n "${REGISTRY_USER:-}" ] && [ -n "${REGISTRY_TOKEN:-}" ]; then
+    # Non-interactive login for CI (workflow passes GITHUB_TOKEN).
+    printf '%s' "$REGISTRY_TOKEN" | docker login "$REGISTRY_HOST" \
+        -u "$REGISTRY_USER" --password-stdin
+else
+    docker login "$REGISTRY_HOST"
+fi
 
 if ! docker buildx inspect "$BUILDER" >/dev/null 2>&1; then
     echo "==> Creating buildx builder '$BUILDER' ..."

deploy/push_desktop.sh

@@ -0,0 +1,126 @@
+#!/bin/bash
+# Build the J621 desktop packages, optionally publish them to the website
+# feed.
+#
+# Desktop updates no longer depend on this: the app resolves the newest
+# `desktop-v*` release on Gitea at check time (see desktop/README.md). This
+# script builds the packages and can copy them to deploy/data/desktop, which
+# the frontend nginx mounts read-only and serves at /desktop/ for manual
+# downloads and for pre-0.1.2 installs.
+#
+# Usage: ./push_desktop.sh [--win] [--no-build] [--local] [--host user@server:/path]
+#   --win       also cross-build the Windows NSIS installer (needs wine)
+#   --no-build  publish what is already in desktop/release/
+#   --local     only publish locally, skip the remote copy
+#   --host      override the remote deploy checkout
+#
+# The remote copy defaults to $J621_DESKTOP_FEED_HOST, or
+# jakerasp:/home/jake/servers/J621 when that is not set.
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+DEFAULT_REMOTE="jakerasp:/home/jake/servers/J621"
+BUILD=1
+WIN=0
+REMOTE="${J621_DESKTOP_FEED_HOST:-$DEFAULT_REMOTE}"
+while [ $# -gt 0 ]; do
+    case "$1" in
+        --win) WIN=1 ;;
+        --no-build) BUILD=0 ;;
+        --local) REMOTE="" ;;
+        --host) REMOTE="${2:?--host needs user@server:/path}"; shift ;;
+        *)
+            echo "usage: $0 [--win] [--no-build] [--local] [--host user@server:/path]" >&2
+            exit 2
+            ;;
+    esac
+    shift
+done
+
+if [ -n "$REMOTE" ] && [ "$REMOTE" = "${REMOTE#*:}" ]; then
+    echo "--host needs user@server:/path (got '$REMOTE')" >&2
+    exit 2
+fi
+
+if [ "$BUILD" = 1 ]; then
+    echo "==> Building Linux packages (deb + pacman) ..."
+    npm --prefix desktop run dist:linux
+    if [ "$WIN" = 1 ]; then
+        echo "==> Cross-building the Windows installer (wine) ..."
+        npm --prefix desktop run dist:win
+    fi
+fi
+
+FEED=deploy/data/desktop
+mkdir -p "$FEED"
+
+shopt -s nullglob
+VERSION="$(node -p "require('./desktop/package.json').version")"
+deb=(desktop/release/*"$VERSION"*.deb)
+zst=(desktop/release/*"$VERSION"*.pkg.tar.zst)
+linux_meta=(desktop/release/latest-linux.yml)
+win_exe=("desktop/release/J621 Setup ${VERSION}"*.exe)
+win_meta=(desktop/release/latest.yml)
+blockmaps=(desktop/release/*"$VERSION"*.exe.blockmap)
+
+if [ "${#deb[@]}" -eq 0 ] && [ "${#zst[@]}" -eq 0 ]; then
+    echo "No $VERSION artifacts in desktop/release/ — run without --no-build first." >&2
+    exit 1
+fi
+
+# Replace the previous release's metadata and drop older installers from the
+# feed: latest*.yml only ever points at the current version.
+rm -f "$FEED"/latest-linux.yml "$FEED"/latest.yml
+old=("$FEED"/*.deb "$FEED"/*.pkg.tar.zst "$FEED"/"J621 Setup "*.exe "$FEED"/*.exe.blockmap)
+for file in "${old[@]}"; do
+    case "$(basename "$file")" in
+        *"$VERSION"*) ;;
+        *) echo "    pruning $(basename "$file")"; rm -f "$file" ;;
+    esac
+done
+cp -f "${deb[@]}" "${zst[@]}" "${linux_meta[@]}" "$FEED"/ 2>/dev/null || true
+if [ "${#win_exe[@]}" -gt 0 ]; then
+    cp -f "${win_exe[@]}" "${win_meta[@]}" "${blockmaps[@]}" "$FEED"/ 2>/dev/null || true
+fi
+
+echo "==> Published to $FEED:"
+ls -1sh "$FEED" | sed 's/^/    /'
+
+if [ -n "$REMOTE" ]; then
+    REMOTE_TARGET="${REMOTE%%:*}"
+    REMOTE_ROOT="${REMOTE#*:}"
+    REMOTE_FEED="${REMOTE_ROOT%/}/deploy/data/desktop"
+
+    echo
+    echo "==> Copying the feed to $REMOTE_TARGET:$REMOTE_FEED ..."
+    if ! ssh "$REMOTE_TARGET" "mkdir -p '$REMOTE_FEED'"; then
+        echo "ssh to $REMOTE_TARGET failed; nothing was copied." >&2
+        exit 1
+    fi
+    # The remote feed keeps only the current version, like the local one.
+    if ! ssh "$REMOTE_TARGET" \
+        "find '$REMOTE_FEED' -maxdepth 1 -type f \\( -name '*.deb' -o -name '*.pkg.tar.zst' -o -name '*.exe' -o -name '*.exe.blockmap' \\) ! -name '*$VERSION*' -exec rm -f {} +"; then
+        echo "==> Could not prune old installers on $REMOTE_TARGET (continuing)." >&2
+    fi
+
+    transferred=0
+    if command -v rsync >/dev/null 2>&1; then
+        if rsync -a --info=progress2 "$FEED"/ "$REMOTE_TARGET:$REMOTE_FEED/"; then
+            transferred=1
+        else
+            echo "==> rsync did not work (missing on the server?); trying tar over ssh ..."
+        fi
+    fi
+    if [ "$transferred" -eq 0 ]; then
+        if ! tar -C "$FEED" -cf - . |
+            ssh "$REMOTE_TARGET" "tar -C '$REMOTE_FEED' -xf -"; then
+            echo "Copy to $REMOTE_TARGET:$REMOTE_FEED failed." >&2
+            exit 1
+        fi
+    fi
+    echo "==> Feed live at $REMOTE_TARGET:$REMOTE_FEED (no restart needed)."
+fi
+
+echo
+echo "Served read-only by the frontend nginx at /desktop/ (no restart needed):"
+echo "    https://<frontend-host>/desktop/latest-linux.yml"

deploy/push_frontend.sh

@@ -10,10 +10,16 @@ REGISTRY="gitea.rainbow-herring.ts.net/jakebreath/j621-frontend"
 REGISTRY_HOST="$(printf '%s' "$REGISTRY" | cut -d/ -f1)"
 SHA="${1:-$(git rev-parse --short HEAD)}"
 BUILDER=multiarch
-PLATFORMS="linux/amd64,linux/arm64"
+PLATFORMS="${PLATFORMS:-linux/amd64,linux/arm64}"
 
 echo "==> Logging in to $REGISTRY_HOST ..."
-docker login "$REGISTRY_HOST"
+if [ -n "${REGISTRY_USER:-}" ] && [ -n "${REGISTRY_TOKEN:-}" ]; then
+    # Non-interactive login for CI (workflow passes GITHUB_TOKEN).
+    printf '%s' "$REGISTRY_TOKEN" | docker login "$REGISTRY_HOST" \
+        -u "$REGISTRY_USER" --password-stdin
+else
+    docker login "$REGISTRY_HOST"
+fi
 
 if ! docker buildx inspect "$BUILDER" >/dev/null 2>&1; then
     echo "==> Creating buildx builder '$BUILDER' ..."
@@ -26,6 +32,7 @@ fi
 echo "==> Building + pushing $PLATFORMS -> $REGISTRY:{latest,$SHA} ..."
 docker buildx build --builder "$BUILDER" --push \
     --platform "$PLATFORMS" \
+    --build-arg "GIT_HASH=$SHA" \
     -f deploy/J621-Frontend \
     -t "$REGISTRY:latest" \
     -t "$REGISTRY:$SHA" \

desktop/.gitignore

@@ -0,0 +1,4 @@
+node_modules/
+dist/
+release/
+*.tsbuildinfo

desktop/README.md

@@ -0,0 +1,119 @@
+# J621 desktop (Electron)
+
+An Electron shell around the web build. The main process serves the SPA from
+the privileged `app://j621` scheme — a real origin, so `localStorage`, OPFS,
+Web Workers and WebCodecs all behave exactly like they do in Chrome — and the
+SPA keeps its normal first-run flow: on launch it asks where the backend is
+(or runs in local mode with no backend at all).
+
+The renderer code is not forked: the shell loads `frontend/dist` as built by
+`npm run build` in `frontend/`.
+
+Licensed under the Jake Labs Non-Commercial Software Licence — see
+`../LICENSE`.
+
+## Layout
+
+```
+src/main.ts      window, app:// protocol handler, menu, external links
+src/preload.ts   window.j621Desktop bridge
+electron-builder.yml   deb + pacman + nsis packaging
+```
+
+The main process attaches a `Referer` to requests for e621 hosts: Chromium
+sends no referrer from a custom-scheme page, and e621's CDN answers
+cross-site image loads without one with a 403 (which Chromium then blocks as
+ORB). API calls work either way.
+
+## Development
+
+```bash
+# terminal 1: the SPA with its /api proxy (needs the backend for library pages)
+cd frontend && npm run dev
+
+# terminal 2
+cd desktop && npm run dev
+```
+
+`npm run dev` builds the main process and points the window at
+`http://localhost:5173` (`J621_DEV_SERVER`). Without the dev server,
+`npm start` builds both halves and serves the bundled SPA over `app://j621`.
+
+## Builds
+
+```bash
+npm run dist:linux   # release/j621-desktop_0.1.0_amd64.deb + j621-desktop-0.1.0.pkg.tar.zst
+npm run dist:win     # release/J621 Setup 0.1.0.exe (cross-built with wine; untested)
+npm run dist:all
+```
+
+`deploy/build_desktop.sh` wraps the same commands, installs dependencies on
+first run and prints sizes plus SHA-256 sums for release notes. Nothing is
+published by it; the CD workflow attaches the artifacts to the Gitea release,
+which is also the update feed.
+
+The Arch package can be installed and removed with pacman:
+
+```bash
+sudo pacman -U release/j621-desktop-*.pkg.tar.zst
+sudo pacman -R j621-desktop
+```
+
+It installs to `/opt/J621` with a `/usr/bin/j621-desktop` symlink and a
+`io.j621.desktop` launcher entry (`StartupWMClass` matches the shell's
+`desktopName`). The Windows installer is a per-user NSIS build, so no admin
+rights are needed to install or update it — but it is unsigned, so SmartScreen
+will warn, and it has not been smoke-tested on real Windows.
+
+## Updates
+
+The app checks only when asked (**J621 → Check for updates…** in the menu):
+Linux packages install through pacman/dpkg, which needs administrator rights,
+and the Windows build is unsigned, so nothing installs silently.
+
+The check resolves the feed itself: it asks the Gitea API for the newest
+non-draft `desktop-v*` release (`J621_UPDATE_REPO`, default
+`https://gitea.rainbow-herring.ts.net/jakebreath/j621` — lowercase on purpose,
+the API path is case-sensitive), picks the `latest-linux.yml` / `latest.yml`
+asset for the platform and uses that release as an electron-updater generic
+feed. The baked `publish.url` in `electron-builder.yml` is metadata only.
+`J621_UPDATE_URL` overrides the whole lookup (the smoke test uses this).
+
+Publishing a release:
+
+1. Bump `version` in `desktop/package.json` — that is what the updater compares.
+2. Run the manual CD workflow, which builds the packages and attaches them
+   plus both channel files to the Gitea release `desktop-v<version>`.
+   `./deploy/push_desktop.sh --win` does the same build locally (and can also
+   copy the files to the website feed, which is optional now).
+3. Existing installs find the new version on their next manual check.
+
+Note for the 0.1.1 → 0.1.2 step: 0.1.1 only knows the old `/desktop/` feed, so
+publish 0.1.2 there once (`./deploy/push_desktop.sh --no-build`, or install it
+manually). From 0.1.2 on, updates come from Gitea.
+
+`package-type` in the app resources tells electron-updater whether to run
+`pacman -U` or `dpkg -i` (both via pkexec/sudo); the per-user NSIS install
+updates without elevation.
+
+## Smoke test
+
+`npm run smoke` builds everything, runs Electron headless through `xvfb-run`
+and checks that the bundled SPA loads over `app://j621`: the SPA fallback, an
+asset fetch, `localStorage`, OPFS, WebCodecs and the preload bridge. It exits
+non-zero on failure. With `J621_UPDATE_URL` set it also checks that the feed
+reports the expected version. Pointing `J621_DEV_SERVER` at the Vite dev
+server checks the development path instead of the bundled one.
+
+## Backend CORS
+
+A desktop app is cross-origin to the backend, exactly like the frontend-only
+Docker deployment. Add the shell's origin to the backend:
+
+```
+CORS_ALLOWED_ORIGINS=app://j621
+```
+
+The setup screen shows this hint (with the actual origin) when the connection
+test fails. Without a backend, choose "Continue without a backend" — the
+e621-facing pages work the same as in the browser.

desktop/electron-builder.yml

@@ -0,0 +1,71 @@
+appId: io.j621.desktop
+productName: J621
+copyright: Copyright (c) 2026 JakeBreath — Jake Labs Non-Commercial Software Licence
+
+# Update feed: desktop/src/main.ts resolves the newest desktop-v* release on
+# Gitea at check time (J621_UPDATE_REPO). This block only tells electron-builder
+# to emit latest.yml/latest-linux.yml next to the installers; J621_UPDATE_URL
+# overrides the feed for a fork or a test.
+publish:
+  provider: generic
+  url: https://gitea.rainbow-herring.ts.net/JakeBreath/J621/releases
+
+directories:
+  output: release
+  buildResources: build
+
+# The Electron main process and preload live in dist/ (tsc output). The SPA is
+# copied from the web build as an extra resource and served over app://j621.
+files:
+  - dist/**
+  - package.json
+
+extraResources:
+  - from: ../frontend/dist
+    to: dist
+    filter:
+      - "**/*"
+
+linux:
+  target:
+    - deb
+    - pacman
+  category: AudioVideo
+  synopsis: Desktop client for the J621 self-hosted media archive
+  description: >-
+    J621 is a self-hosted browser for an e621-linked media library. This
+    desktop build talks to a J621 backend over the network, the same way the
+    web app does.
+  icon: build/icons
+  syncDesktopName: true
+
+pacman:
+  compression: zstd
+  artifactName: ${name}-${version}.pkg.tar.zst
+  # Electron's shared-library requirements on Arch (the electron-builder
+  # defaults still list an ancient Electron 2 dependency set).
+  depends:
+    - gtk3
+    - nss
+    - libxss
+    - libxtst
+    - xdg-utils
+    - at-spi2-core
+    - libsecret
+    - libnotify
+    - alsa-lib
+    - libcups
+    - libdrm
+    - mesa
+    - libxkbcommon
+
+win:
+  target:
+    - nsis
+  icon: build/icon.ico
+
+nsis:
+  oneClick: false
+  perMachine: false
+  allowToChangeInstallationDirectory: true
+  shortcutName: J621

desktop/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "j621-desktop",
+  "productName": "J621",
+  "version": "0.1.2",
+  "private": true,
+  "description": "Desktop shell for the J621 self-hosted media archive",
+  "author": {
+    "name": "JakeBreath",
+    "email": "tolozacdcmo@gmail.com"
+  },
+  "homepage": "https://gitea.rainbow-herring.ts.net/JakeBreath/J621",
+  "license": "LicenseRef-Jake-Labs-Non-Commercial",
+  "desktopName": "io.j621.desktop",
+  "main": "dist/main.js",
+  "scripts": {
+    "build:main": "tsc -p tsconfig.json",
+    "build:renderer": "npm --prefix ../frontend run build",
+    "build": "npm run build:main && npm run build:renderer",
+    "dev": "npm run build:main && J621_DEV_SERVER=http://localhost:5173 electron .",
+    "start": "npm run build && electron .",
+    "smoke": "npm run build && xvfb-run -a electron . --j621-smoke",
+    "dist:linux": "npm run build && electron-builder --linux",
+    "dist:win": "npm run build && electron-builder --win",
+    "dist:all": "npm run build && electron-builder --linux --win"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.6",
+    "electron": "^44.4.3",
+    "electron-builder": "^26.15.3",
+    "typescript": "^6.0.3"
+  },
+  "dependencies": {
+    "electron-updater": "^6.8.9"
+  }
+}

desktop/src/main.ts

@@ -0,0 +1,681 @@
+/**
+ * Electron shell for the J621 SPA.
+ *
+ * The renderer is the normal web build (`frontend/dist`), served from the
+ * privileged `app://j621` scheme so it is a real secure origin: localStorage,
+ * OPFS, Web Workers, WebCodecs and `history.pushState` all behave exactly
+ * like they do in Chrome. In development `J621_DEV_SERVER` points the window
+ * at the Vite dev server instead, which keeps HMR and the `/api` proxy.
+ *
+ * The shell is deliberately thin: the SPA still asks for its backend URL on
+ * first launch (or runs in local e621-only mode) and talks to it over HTTP
+ * the same way it does in a browser. The only desktop-specific bits are the
+ * origin, external-link handling and (later) updates.
+ */
+import { app, BrowserWindow, dialog, ipcMain, Menu, protocol, session, shell } from "electron";
+import { autoUpdater } from "electron-updater";
+import { readFileSync, rmSync } from "node:fs";
+import { readFile, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+const SCHEME = "app";
+const HOST = "j621";
+const APP_ORIGIN = `${SCHEME}://${HOST}`;
+const DEV_SERVER = (process.env.J621_DEV_SERVER ?? "").replace(/\/+$/, "");
+const SMOKE = process.argv.includes("--j621-smoke");
+
+if (SMOKE) {
+  // A throwaway profile keeps the checks deterministic (always the first-run
+  // setup screen) and never touches real state or leaves a stale
+  // single-instance lock behind.
+  const smokeDir = path.join(app.getPath("temp"), "j621-smoke");
+  rmSync(smokeDir, { recursive: true, force: true });
+  app.setPath("userData", smokeDir);
+}
+
+protocol.registerSchemesAsPrivileged([
+  {
+    scheme: SCHEME,
+    privileges: {
+      standard: true,
+      secure: true,
+      supportFetchAPI: true,
+      corsEnabled: true,
+      stream: true,
+    },
+  },
+]);
+
+const MIME_TYPES: Record<string, string> = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".mjs": "text/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".map": "application/json; charset=utf-8",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".webp": "image/webp",
+  ".gif": "image/gif",
+  ".ico": "image/x-icon",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".wasm": "application/wasm",
+  ".mp4": "video/mp4",
+  ".webm": "video/webm",
+  ".txt": "text/plain; charset=utf-8",
+};
+
+/** Where `vite build` output lives, packaged or not. */
+function rendererRoot(): string {
+  return app.isPackaged
+    ? path.join(process.resourcesPath, "dist")
+    : path.resolve(__dirname, "..", "..", "frontend", "dist");
+}
+
+async function existingFile(candidate: string): Promise<boolean> {
+  try {
+    return (await stat(candidate)).isFile();
+  } catch {
+    return false;
+  }
+}
+
+async function fileResponse(file: string): Promise<Response> {
+  const body = await readFile(file);
+  const type =
+    MIME_TYPES[path.extname(file).toLowerCase()] ?? "application/octet-stream";
+  return new Response(body, {
+    headers: { "content-type": type, "cache-control": "no-cache" },
+  });
+}
+
+/** Paths the nginx proxy sends to Django; there is no backend behind app://. */
+const BACKEND_PREFIXES = ["/api/", "/admin/", "/static/", "/health"];
+
+/**
+ * e621's CDN refuses cross-site image loads that carry no Referer
+ * (`Sec-Fetch-Site: cross-site` with an empty referrer returns 403), and
+ * Chromium never sends one for pages on a custom scheme like app://j621.
+ * Attach a normal e621 referrer to its hosts so images load; API calls are
+ * unaffected.
+ */
+function installRefererFix(targetSession: Electron.Session): void {
+  targetSession.webRequest.onBeforeSendHeaders(
+    { urls: ["*://e621.net/*", "*://*.e621.net/*"] },
+    (details, callback) => {
+      const headers = details.requestHeaders;
+      if (!headers.Referer && !headers.referer) {
+        headers.Referer = "https://e621.net/";
+      }
+      callback({ requestHeaders: headers });
+    },
+  );
+}
+
+async function handleAppRequest(request: Request): Promise<Response> {
+  const url = new URL(request.url);
+  if (url.host !== HOST) return new Response("Not found", { status: 404 });
+
+  const root = rendererRoot();
+  let pathname = decodeURIComponent(url.pathname);
+  if (!pathname || pathname === "/") pathname = "/index.html";
+
+  // Never answer backend paths with the SPA: that made the setup screen's
+  // connection test "succeed" against the shell's own origin.
+  if (
+    BACKEND_PREFIXES.some(
+      (prefix) => pathname === prefix.replace(/\/$/, "") || pathname.startsWith(prefix),
+    )
+  ) {
+    return new Response(
+      JSON.stringify({
+        detail: "No backend is attached to the desktop app; set one in /setup.",
+      }),
+      { status: 404, headers: { "content-type": "application/json" } },
+    );
+  }
+
+  const target = path.resolve(root, "." + pathname);
+  if (target !== root && !target.startsWith(root + path.sep)) {
+    return new Response("Forbidden", { status: 403 });
+  }
+
+  try {
+    if (await existingFile(target)) return await fileResponse(target);
+    // Missing assets keep their 404; anything else is a client route and
+    // falls back to the SPA entry point (BrowserRouter).
+    if (path.extname(pathname)) return new Response("Not found", { status: 404 });
+    return await fileResponse(path.join(root, "index.html"));
+  } catch (error) {
+    const hint = app.isPackaged
+      ? "The bundled frontend is missing from the application resources."
+      : "Build the frontend first: npm --prefix ../frontend run build";
+    console.error("[app://]", error);
+    return new Response(`${hint}\n`, { status: 500 });
+  }
+}
+
+interface WindowState {
+  x?: number;
+  y?: number;
+  width: number;
+  height: number;
+  maximized: boolean;
+}
+
+const DEFAULT_WINDOW_STATE: WindowState = {
+  width: 1440,
+  height: 900,
+  maximized: false,
+};
+
+function stateFile(): string {
+  return path.join(app.getPath("userData"), "window-state.json");
+}
+
+function readWindowState(): WindowState {
+  try {
+    const parsed = JSON.parse(
+      readFileSync(stateFile(), "utf8"),
+    ) as Partial<WindowState>;
+    return { ...DEFAULT_WINDOW_STATE, ...parsed };
+  } catch {
+    return DEFAULT_WINDOW_STATE;
+  }
+}
+
+function saveWindowState(win: BrowserWindow): void {
+  if (win.isDestroyed()) return;
+  const { x, y, width, height } = win.getNormalBounds();
+  const state: WindowState = {
+    x,
+    y,
+    width,
+    height,
+    maximized: win.isMaximized(),
+  };
+  void writeFile(stateFile(), JSON.stringify(state)).catch(() => {
+    // Window geometry is a nice-to-have; never fail a quit over it.
+  });
+}
+
+function openExternal(rawUrl: string): void {
+  if (/^https?:/i.test(rawUrl)) void shell.openExternal(rawUrl);
+}
+
+/** File extensions the SPA navigates to when it wants a save dialog. */
+const DOWNLOAD_EXTENSIONS = new Set([
+  ".jpg",
+  ".jpeg",
+  ".jpe",
+  ".png",
+  ".gif",
+  ".webp",
+  ".avif",
+  ".mp4",
+  ".webm",
+  ".mov",
+  ".swf",
+  ".zip",
+  ".pdf",
+  ".bin",
+]);
+
+/**
+ * Downloads in the SPA are same-window navigations (`location.href =
+ * url?download=1`, `<a href=...>`), and Chromium cancels those when
+ * `will-navigate` is prevented. Recognise them so they become real
+ * downloads instead of being opened in the browser.
+ */
+function isDownloadNavigation(url: URL): boolean {
+  if (/(?:^|&)download=1(?:&|$)/.test(url.search.slice(1))) return true;
+  return DOWNLOAD_EXTENSIONS.has(path.extname(url.pathname).toLowerCase());
+}
+
+/**
+ * Updates are manual by design: Linux packages install through pacman/dpkg
+ * (pkexec/sudo) and the Windows build is unsigned, so the app asks before
+ * downloading and again before installing. The feed is resolved at check time
+ * from the newest `desktop-v*` release on Gitea (`J621_UPDATE_REPO`);
+ * `J621_UPDATE_URL` overrides it for forks and the smoke test.
+ */
+type UpdateEvent =
+  | { state: "available"; version: string }
+  | { state: "not-available" }
+  | { state: "downloaded"; version: string }
+  | { state: "error"; message: string };
+
+let updateReporter: ((event: UpdateEvent) => void) | null = null;
+let updateCheckRunning = false;
+
+const UPDATE_REPO =
+  process.env.J621_UPDATE_REPO?.trim() ||
+  "https://gitea.rainbow-herring.ts.net/jakebreath/j621";
+
+interface ReleaseAsset {
+  name: string;
+  browser_download_url: string;
+}
+
+interface Release {
+  tag_name: string;
+  draft: boolean;
+  prerelease: boolean;
+  assets?: ReleaseAsset[];
+}
+
+function releaseVersion(tag: string): [number, number, number] | null {
+  const match = /^desktop-v(\d+)\.(\d+)\.(\d+)$/.exec(tag);
+  if (!match) return null;
+  return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+
+function compareVersions(
+  a: [number, number, number],
+  b: [number, number, number],
+): number {
+  for (let index = 0; index < 3; index += 1) {
+    if (a[index] !== b[index]) return a[index] - b[index];
+  }
+  return 0;
+}
+
+/**
+ * Resolve the generic feed base electron-updater should use.
+ *
+ * Gitea's API path is case-sensitive (owner/repo must match the login), while
+ * the asset URLs it returns are canonical, so the base is derived from the
+ * platform's metadata asset (`latest-linux.yml` / `latest.yml`).
+ */
+async function resolveReleaseFeed(): Promise<string> {
+  const override = process.env.J621_UPDATE_URL?.trim();
+  if (override) return override;
+  const match = /^(https?:\/\/[^/]+)\/([^/]+)\/([^/]+?)\/?$/.exec(UPDATE_REPO);
+  if (!match) {
+    throw new Error(
+      `J621_UPDATE_REPO must be <origin>/<owner>/<repo> (got ${UPDATE_REPO}).`,
+    );
+  }
+  const [, origin, owner, repo] = match;
+  const response = await fetch(
+    `${origin}/api/v1/repos/${owner}/${repo}/releases?limit=50`,
+    { headers: { Accept: "application/json" } },
+  );
+  if (!response.ok) {
+    throw new Error(`Release lookup on Gitea failed (HTTP ${response.status}).`);
+  }
+  const releases = (await response.json()) as Release[];
+  const assetName =
+    process.platform === "win32" ? "latest.yml" : "latest-linux.yml";
+  let best: { version: [number, number, number]; asset: ReleaseAsset } | null =
+    null;
+  for (const release of releases) {
+    if (release.draft || release.prerelease) continue;
+    const version = releaseVersion(release.tag_name);
+    if (!version) continue;
+    const asset = release.assets?.find((entry) => entry.name === assetName);
+    if (!asset) continue;
+    if (!best || compareVersions(version, best.version) > 0) {
+      best = { version, asset };
+    }
+  }
+  if (!best) {
+    throw new Error(`No ${assetName} asset found in ${UPDATE_REPO} releases.`);
+  }
+  return best.asset.browser_download_url.replace(/\/[^/]*$/, "");
+}
+
+function setUpUpdates(win: BrowserWindow): void {
+  if (!app.isPackaged) autoUpdater.forceDevUpdateConfig = true;
+  autoUpdater.autoDownload = false;
+  autoUpdater.autoInstallOnAppQuit = false;
+
+  autoUpdater.on("error", (error) => {
+    updateReporter?.({ state: "error", message: error.message });
+  });
+
+  autoUpdater.on("update-not-available", () => {
+    if (SMOKE) return updateReporter?.({ state: "not-available" });
+    void dialog.showMessageBox(win, {
+      type: "info",
+      title: "Updates",
+      message: `J621 ${app.getVersion()} is up to date.`,
+    });
+  });
+
+  autoUpdater.on("update-available", (info) => {
+    if (SMOKE) {
+      return updateReporter?.({ state: "available", version: info.version });
+    }
+    void (async () => {
+      const { response } = await dialog.showMessageBox(win, {
+        type: "info",
+        title: "Updates",
+        message: `J621 ${info.version} is available.`,
+        detail:
+          "Download it now? Installing it later needs administrator rights " +
+          "on Linux (pacman/dpkg); the Windows installer runs without them.",
+        buttons: ["Download", "Later"],
+        defaultId: 0,
+        cancelId: 1,
+      });
+      if (response !== 0) return;
+      try {
+        await autoUpdater.downloadUpdate();
+      } catch (error) {
+        await dialog.showMessageBox(win, {
+          type: "error",
+          title: "Update failed",
+          message: "The update could not be downloaded.",
+          detail: error instanceof Error ? error.message : String(error),
+        });
+      }
+    })();
+  });
+
+  autoUpdater.on("download-progress", (progress) => {
+    win.setProgressBar(Math.min(progress.percent / 100, 1));
+  });
+
+  autoUpdater.on("update-downloaded", (info) => {
+    win.setProgressBar(-1);
+    if (SMOKE) {
+      return updateReporter?.({ state: "downloaded", version: info.version });
+    }
+    void (async () => {
+      const { response } = await dialog.showMessageBox(win, {
+        type: "info",
+        title: "Updates",
+        message: `J621 ${info.version} is ready to install.`,
+        detail:
+          process.platform === "linux"
+            ? "Installing asks for administrator rights and then restarts J621."
+            : "J621 will restart to finish installing.",
+        buttons: ["Restart and install", "Later"],
+        defaultId: 0,
+        cancelId: 1,
+      });
+      if (response === 0) {
+        autoUpdater.quitAndInstall(false, true);
+      } else {
+        // Linux packages elevate, so never install silently on quit there.
+        autoUpdater.autoInstallOnAppQuit = process.platform !== "linux";
+      }
+    })();
+  });
+}
+
+async function checkForUpdates(win: BrowserWindow): Promise<void> {
+  if (updateCheckRunning) return;
+  updateCheckRunning = true;
+  try {
+    const feed = await resolveReleaseFeed();
+    autoUpdater.setFeedURL({ provider: "generic", url: feed });
+    await autoUpdater.checkForUpdates();
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    updateReporter?.({ state: "error", message });
+    if (!SMOKE) {
+      await dialog.showMessageBox(win, {
+        type: "error",
+        title: "Updates",
+        message: "Could not check for updates.",
+        detail: message,
+      });
+    }
+  } finally {
+    updateCheckRunning = false;
+  }
+}
+
+let mainWindow: BrowserWindow | null = null;
+
+function buildMenu(win: BrowserWindow): void {
+  const template: Electron.MenuItemConstructorOptions[] = [
+    {
+      label: "J621",
+      submenu: [
+        {
+          label: "Backend setup…",
+          click: () => void win.loadURL(`${APP_ORIGIN}/setup`),
+        },
+        {
+          label: "Open backend in browser",
+          click: () => win.webContents.send("j621:open-backend"),
+        },
+        {
+          label: "Check for updates…",
+          click: () => void checkForUpdates(win),
+        },
+        { type: "separator" },
+        { role: "quit" },
+      ],
+    },
+    { role: "editMenu" },
+    {
+      label: "View",
+      submenu: [
+        { role: "reload" },
+        { role: "forceReload" },
+        { role: "toggleDevTools" },
+        { type: "separator" },
+        { role: "resetZoom" },
+        { role: "zoomIn" },
+        { role: "zoomOut" },
+        { type: "separator" },
+        { role: "togglefullscreen" },
+      ],
+    },
+  ];
+  Menu.setApplicationMenu(Menu.buildFromTemplate(template));
+}
+
+function createWindow(): BrowserWindow {
+  const state = readWindowState();
+  const win = new BrowserWindow({
+    x: state.x,
+    y: state.y,
+    width: state.width,
+    height: state.height,
+    minWidth: 960,
+    minHeight: 600,
+    backgroundColor: "#11111b",
+    show: false,
+    webPreferences: {
+      preload: path.join(__dirname, "preload.js"),
+      contextIsolation: true,
+      nodeIntegration: false,
+      sandbox: true,
+      spellcheck: false,
+    },
+  });
+
+  if (state.maximized) win.maximize();
+  win.once("ready-to-show", () => win.show());
+  win.on("close", () => saveWindowState(win));
+  win.on("closed", () => {
+    mainWindow = null;
+  });
+
+  // Links to the web open in the user's browser, never in this window.
+  win.webContents.setWindowOpenHandler(({ url }) => {
+    openExternal(url);
+    return { action: "deny" };
+  });
+  win.webContents.on("will-navigate", (event, url) => {
+    const allowed = DEV_SERVER
+      ? url.startsWith(DEV_SERVER)
+      : url.startsWith(APP_ORIGIN);
+    if (allowed) return;
+    event.preventDefault();
+    let parsed: URL;
+    try {
+      parsed = new URL(url);
+    } catch {
+      return;
+    }
+    if (/^https?:$/.test(parsed.protocol) && isDownloadNavigation(parsed)) {
+      win.webContents.downloadURL(url);
+      return;
+    }
+    openExternal(url);
+  });
+
+  buildMenu(win);
+  setUpUpdates(win);
+  void win.loadURL(DEV_SERVER || `${APP_ORIGIN}/`);
+  if (SMOKE) runSmokeTest(win);
+  return win;
+}
+
+/**
+ * `npm run smoke`: load the bundled SPA and check the things that are only
+ * true under the custom scheme. Exits non-zero on the first broken promise.
+ */
+function runSmokeTest(win: BrowserWindow): void {
+  win.webContents.once("did-finish-load", () => {
+    void (async () => {
+      try {
+        const result = (await win.webContents.executeJavaScript(`(async () => {
+          const waitFor = async (probe, timeout = 8000) => {
+            const start = Date.now();
+            while (Date.now() - start < timeout) {
+              if (probe()) return true;
+              await new Promise((resolve) => setTimeout(resolve, 100));
+            }
+            return false;
+          };
+          const asset = await fetch("/favicon.svg");
+          const route = await fetch("/gallery/some/deep/route");
+          const routeBody = await route.text();
+          const health = await fetch("/health");
+          localStorage.setItem("j621.smoke", "ok");
+          history.pushState({}, "", "/gallery");
+          return {
+            origin: location.origin,
+            title: document.title,
+            assetOk: asset.ok && (await asset.text()).includes("<svg"),
+            routeOk: route.ok && routeBody.includes('id="root"'),
+            // /health must not fall back to the SPA (false "connected" test).
+            healthOk: health.status === 404,
+            // Testing an empty backend URL on the desktop must say so instead
+            // of "Connected" against the shell's own origin.
+            emptyTestOk: await (async () => {
+              const button = [...document.querySelectorAll("button")].find((b) =>
+                b.textContent.includes("Test connection"),
+              );
+              if (!button) return false;
+              button.click();
+              return waitFor(() => document.body.innerText.includes("no backend of its own"));
+            })(),
+            mounted: await waitFor(() => (document.querySelector("#root")?.childElementCount ?? 0) > 0),
+            setupOk: document.body.innerText.includes("Where is your backend?"),
+            storageOk: localStorage.getItem("j621.smoke") === "ok",
+            historyOk: location.pathname === "/gallery",
+            opfsOk: typeof navigator.storage?.getDirectory === "function",
+            webcodecsOk: typeof VideoEncoder !== "undefined",
+            bridgeOk: window.j621Desktop?.isDesktop === true,
+          };
+        })()`, true)) as Record<string, unknown>;
+
+        const expected: Record<string, unknown> = {
+          // In dev the window hosts the Vite dev server, which has no /setup
+          // screen (the SPA only asks for a backend in production builds).
+          origin: DEV_SERVER || APP_ORIGIN,
+          title: "J621",
+          assetOk: true,
+          routeOk: true,
+          mounted: true,
+          setupOk: !DEV_SERVER,
+          // Both are app://-only checks: the Vite dev server serves the SPA
+          // for /health and never shows the setup screen.
+          healthOk: !DEV_SERVER,
+          emptyTestOk: !DEV_SERVER,
+          storageOk: true,
+          historyOk: true,
+          opfsOk: true,
+          webcodecsOk: true,
+          bridgeOk: true,
+        };
+        const failures = Object.entries(expected).filter(
+          ([key, value]) => result[key] !== value,
+        );
+        console.log(
+          "[smoke] electron",
+          process.versions.electron,
+          "chrome",
+          process.versions.chrome,
+        );
+        console.log("[smoke]", JSON.stringify(result));
+        if (failures.length > 0) {
+          console.error(
+            "[smoke] FAILED:",
+            failures.map(([key]) => key).join(", "),
+          );
+          app.exit(1);
+          return;
+        }
+        if (process.env.J621_UPDATE_URL) {
+          const update = await new Promise<UpdateEvent>((resolve) => {
+            updateReporter = resolve;
+            const timer = setTimeout(
+              () => resolve({ state: "error", message: "update check timed out" }),
+              60_000,
+            );
+            void checkForUpdates(win).finally(() => clearTimeout(timer));
+          });
+          updateReporter = null;
+          console.log("[smoke] update:", JSON.stringify(update));
+          if (update.state === "error") {
+            console.error("[smoke] FAILED: update check");
+            app.exit(1);
+            return;
+          }
+        }
+        console.log("[smoke] OK");
+        app.exit(0);
+      } catch (error) {
+        console.error("[smoke] FAILED:", error);
+        app.exit(1);
+      }
+    })();
+  });
+}
+
+const gotLock = app.requestSingleInstanceLock();
+if (!gotLock) {
+  app.quit();
+} else {
+  app.on("second-instance", () => {
+    if (!mainWindow) return;
+    if (mainWindow.isMinimized()) mainWindow.restore();
+    mainWindow.focus();
+  });
+
+  app.setAppUserModelId("io.j621.desktop");
+
+  app.whenReady().then(() => {
+    protocol.handle(SCHEME, handleAppRequest);
+    installRefererFix(session.defaultSession);
+
+    ipcMain.handle("j621:version", () => app.getVersion());
+    ipcMain.handle("j621:open-external", (_event, url: unknown) => {
+      if (typeof url === "string") openExternal(url);
+    });
+
+    mainWindow = createWindow();
+
+    app.on("activate", () => {
+      if (BrowserWindow.getAllWindows().length === 0) {
+        mainWindow = createWindow();
+      }
+    });
+  });
+
+  app.on("window-all-closed", () => {
+    if (process.platform !== "darwin") app.quit();
+  });
+}

desktop/src/preload.ts

@@ -0,0 +1,27 @@
+/**
+ * The only bridge between the desktop shell and the SPA. Keep it tiny: the
+ * renderer is the normal web build and must not need Electron to work.
+ */
+import { contextBridge, ipcRenderer } from "electron";
+
+contextBridge.exposeInMainWorld("j621Desktop", {
+  isDesktop: true as const,
+  platform: process.platform,
+  // The SPA's own origin (`app://j621`), shown by the setup screen when it
+  // has to explain which origin to allow in the backend's CORS settings.
+  origin: window.location.origin,
+  getVersion: (): Promise<string> => ipcRenderer.invoke("j621:version"),
+});
+
+// Menu → "Open backend in browser": read the SPA's stored backend URL and
+// hand it to the main process after checking it is a real web URL.
+ipcRenderer.on("j621:open-backend", () => {
+  let url = "";
+  try {
+    url = window.localStorage.getItem("j621.backend") ?? "";
+  } catch {
+    // Storage can be unavailable in rare cases; nothing to open then.
+  }
+  if (url === "none") url = "";
+  if (url) void ipcRenderer.invoke("j621:open-external", url);
+});

desktop/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "node16",
+    "moduleResolution": "node16",
+    "lib": ["ES2023", "DOM"],
+    "types": ["node"],
+    "outDir": "dist",
+    "rootDir": "src",
+    "sourceMap": true,
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src"]
+}

extras/install-windows.ps1

@@ -0,0 +1,59 @@
+# Install the J621 Windows extras (PowerShell greeting + Rust gm-switch).
+#
+# Usage:
+#   .\install-windows.ps1
+#   .\install-windows.ps1 -Url https://j621.example.ts.net -Token <token>
+#   .\install-windows.ps1 -NoPrompt
+#   .\install-windows.ps1 -Uninstall
+#
+# Options are forwarded to the component installers (see
+# powershell_greeting\install.ps1 and win-gm-switch\install.ps1).
+
+[CmdletBinding()]
+param(
+    [string]$Url,
+    [string]$Token,
+    [switch]$NoPrompt,
+    [switch]$Force,
+    [switch]$NoProfilePatch,
+    [switch]$SkipGreeting,
+    [switch]$SkipGmSwitch,
+    [switch]$Uninstall
+)
+
+$ErrorActionPreference = 'Stop'
+
+$here = $PSScriptRoot
+if (-not $here) { $here = Split-Path -Parent $MyInvocation.MyCommand.Path }
+$failures = New-Object System.Collections.Generic.List[string]
+
+if (-not $SkipGmSwitch) {
+    Write-Host ''
+    Write-Host '=== gm-switch ==='
+    $params = @{}
+    if ($Uninstall) { $params.Uninstall = $true }
+    & (Join-Path $here 'win-gm-switch\install.ps1') @params
+    if ($LASTEXITCODE -ne 0) { $failures.Add('gm-switch installer failed') }
+}
+
+if (-not $SkipGreeting) {
+    Write-Host ''
+    Write-Host '=== PowerShell greeting ==='
+    $params = @{}
+    if ($Uninstall) { $params.Uninstall = $true }
+    if ($Url) { $params.Url = $Url }
+    if ($Token) { $params.Token = $Token }
+    if ($NoPrompt) { $params.NoPrompt = $true }
+    if ($Force) { $params.Force = $true }
+    if ($NoProfilePatch) { $params.NoProfilePatch = $true }
+    & (Join-Path $here 'powershell_greeting\install.ps1') @params
+    if ($LASTEXITCODE -ne 0) { $failures.Add('greeting installer failed') }
+}
+
+Write-Host ''
+if ($failures.Count -eq 0) {
+    Write-Host 'All done.'
+    exit 0
+}
+foreach ($failure in $failures) { Write-Host $failure }
+exit 1

extras/powershell_greeting/J621Greeting.ps1

@@ -0,0 +1,200 @@
+# J621Greeting.ps1 - show a random J621 library image as the shell greeting.
+#
+# PowerShell port of extras/fish_greeting/fish_greeting.fish (the J621 REST
+# rewrite): asks GET /api/random/?fastfetch=1&rating=X for a random
+# png/jpg/gif, downloads the signed url and runs fastfetch with the image as
+# its logo. Based on the original script from
+# J621-Django/extras/fish_greeting system/fish_greeting.fish.
+#
+# Requires: fastfetch and curl.exe (ships with Windows 10 1803+).
+#
+# Rating modes (same file name as the fish version):
+#   %APPDATA%\j621Greeting\greeting_mode   0 = NSFW (explicit)
+#                                          1 = SFW (safe)
+#                                          2 = Questionable (default)
+#
+# Configuration: %APPDATA%\j621Greeting\config.ps1 (sets environment
+# variables; see config.example.ps1):
+#   J621_BASE               API origin (default https://j621.rainbow-herring.ts.net)
+#   J621_TOKEN              API / scoped greeting token, sent as "Authorization: Token ..."
+#   J621_WEB                web origin used in the printed link (defaults to J621_BASE)
+#   J621_FASTFETCH_CONFIG   fastfetch config name (default "jake")
+#   J621_MODE_FILE          mode file override
+#   J621_LOGO_TYPE          force a fastfetch logo type (sixel, kitty-direct, ...)
+#   J621_ALWAYS_FETCH=1     fetch even in terminals without image support
+#   J621_LOGO_WIDTH         logo width in columns (default 35)
+#   J621_LOGO_HEIGHT        iterm box height in rows (default 25)
+
+#Requires -Version 5.1
+
+function Get-J621FileKind {
+    param([string]$Path)
+    try {
+        $stream = [IO.File]::OpenRead($Path)
+        try {
+            $buffer = New-Object byte[] 8
+            $read = $stream.Read($buffer, 0, 8)
+            if ($read -ge 4 -and $buffer[0] -eq 0x89 -and $buffer[1] -eq 0x50 -and $buffer[2] -eq 0x4E -and $buffer[3] -eq 0x47) { return 'png' }
+            if ($read -ge 2 -and $buffer[0] -eq 0xFF -and $buffer[1] -eq 0xD8) { return 'jpeg' }
+            if ($read -ge 3 -and $buffer[0] -eq 0x47 -and $buffer[1] -eq 0x49 -and $buffer[2] -eq 0x46) { return 'gif' }
+            return 'unknown'
+        } finally { $stream.Dispose() }
+    } catch { return 'unknown' }
+}
+
+function Format-J621Accent {
+    param([string]$Text)
+    return "$([char]27)[4;2;38;2;138;0;222;49m$Text$([char]27)[0m"
+}
+
+function Format-J621Error {
+    param([string]$Text)
+    return "$([char]27)[31m$Text$([char]27)[0m"
+}
+
+function Get-J621FastfetchArgs {
+    $configName = if ($env:J621_FASTFETCH_CONFIG) { $env:J621_FASTFETCH_CONFIG } else { 'jake' }
+    $candidates = @(
+        (Join-Path $env:APPDATA "fastfetch\$configName.jsonc"),
+        (Join-Path $env:APPDATA "fastfetch\$configName\config.jsonc")
+    )
+    foreach ($candidate in $candidates) {
+        if (Test-Path -LiteralPath $candidate) { return @('--config', $configName) }
+    }
+    return @()
+}
+
+function Show-J621Greeting {
+    param([int]$Depth = 0)
+
+    # --- Configuration ---
+    $configFile = Join-Path $env:APPDATA 'j621Greeting\config.ps1'
+    if (Test-Path -LiteralPath $configFile) { . $configFile }
+
+    $base = if ($env:J621_BASE) { $env:J621_BASE.TrimEnd('/') } else { 'https://j621.rainbow-herring.ts.net' }
+    $webBase = if ($env:J621_WEB) { $env:J621_WEB.TrimEnd('/') } else { $base }
+    $token = $env:J621_TOKEN
+    $logoWidth = if ($env:J621_LOGO_WIDTH) { $env:J621_LOGO_WIDTH } else { '35' }
+    $modeFile = if ($env:J621_MODE_FILE) { $env:J621_MODE_FILE } else { Join-Path $env:APPDATA 'j621Greeting\greeting_mode' }
+
+    # --- Setup logging ---
+    $logDir = Join-Path $env:APPDATA 'j621Logos'
+    $logFile = Join-Path $logDir 'logs.log'
+    if (-not (Test-Path -LiteralPath $logDir)) { New-Item -ItemType Directory -Path $logDir -Force | Out-Null }
+    $stamp = (Get-Date).ToString('yyyy-MM-dd HH:mm:ss')
+
+    # --- Mode selection ---
+    $mode = '2'
+    if (Test-Path -LiteralPath $modeFile) {
+        $raw = Get-Content -LiteralPath $modeFile -Raw -ErrorAction SilentlyContinue
+        if ($null -ne $raw) { $mode = $raw.Trim() }
+    }
+    switch ($mode) {
+        '0' { $rating = 'e'; $modeName = 'NSFW' }
+        '1' { $rating = 's'; $modeName = 'SFW' }
+        '2' { $rating = 'q'; $modeName = 'Questionable' }
+        default { Write-Output 'Unknown mode, using default NSFW'; $rating = 'e'; $modeName = 'NSFW' }
+    }
+
+    # --- Pick the image protocol for this terminal ---
+    $logoType = $env:J621_LOGO_TYPE
+    if (-not $logoType) {
+        if ($env:WT_SESSION) { $logoType = 'sixel' }
+        elseif ($env:WEZTERM_PANE) { $logoType = 'iterm' }
+    }
+    $fetchImage = [bool]$logoType -or ($env:J621_ALWAYS_FETCH -eq '1')
+    $ffArgs = @(Get-J621FastfetchArgs)
+
+    if (-not $fetchImage) {
+        # Terminal without image support (e.g. VS Code): plain fastfetch.
+        & fastfetch @ffArgs
+        return
+    }
+
+    # --- Ask the API for a random image (JSON with a signed URL) ---
+    $apiUrl = "$base/api/random/?fastfetch=1&rating=$rating"
+    $curlArgs = @('-s', '-L', '--max-time', '20')
+    if ($token) { $curlArgs += @('-H', "Authorization: Token $token") }
+    $json = & curl.exe @curlArgs $apiUrl 2>$null | Out-String
+
+    $data = $null
+    try { $data = $json | ConvertFrom-Json } catch { $data = $null }
+
+    $imageUrl = $null; $jId = $null; $md5 = $null; $filename = $null; $detail = $null; $ext = 'img'
+    if ($data) {
+        if ($data.url) { $imageUrl = [string]$data.url }
+        if ($data.j_id) { $jId = [string]$data.j_id }
+        if ($data.md5) { $md5 = [string]$data.md5 }
+        if ($data.filename) { $filename = [string]$data.filename }
+        if ($data.detail) { $detail = [string]$data.detail }
+        if ($data.extension) { $ext = [string]$data.extension }
+    }
+    if ($ext -notmatch '^[A-Za-z0-9]+$') { $ext = 'img' }
+
+    if (-not $imageUrl) {
+        & fastfetch @ffArgs
+        if ($detail) { Write-Host (Format-J621Accent "No logo ($detail)") } else { Write-Host (Format-J621Accent 'No logo (API error)') }
+        Add-Content -LiteralPath $logFile -Value "$stamp No logo for rating=${rating}: $detail"
+        return
+    }
+
+    # --- Download the signed image ---
+    $tempFile = Join-Path ([IO.Path]::GetTempPath()) ('j621_logo_' + [guid]::NewGuid().ToString('N') + '.' + $ext)
+    $downloadSuccess = $false
+    & curl.exe -s -L --max-time 60 -o $tempFile $imageUrl 2>$null
+    if ($LASTEXITCODE -eq 0 -and (Test-Path -LiteralPath $tempFile) -and (Get-Item -LiteralPath $tempFile).Length -gt 0) { $downloadSuccess = $true }
+
+    if (-not $downloadSuccess) {
+        & fastfetch @ffArgs
+        Write-Host (Format-J621Accent 'No logo (download failed)')
+        Add-Content -LiteralPath $logFile -Value "$stamp Download failed for $jId"
+        Remove-Item -LiteralPath $tempFile -ErrorAction SilentlyContinue
+        return
+    }
+
+    # --- Accept only PNG, JPEG, GIF; anything else causes one more roll ---
+    $kind = Get-J621FileKind -Path $tempFile
+    if ($kind -eq 'unknown') {
+        if ($Depth -lt 3) {
+            Show-J621Greeting -Depth ($Depth + 1)
+        } else {
+            Write-Host (Format-J621Error 'Max recursion depth reached, skipping unsupported file type: unknown')
+        }
+        if ($Depth -eq 0) {
+            Write-Host (Format-J621Error ("Forked (Got unsupported type: unknown - $filename)"))
+            if ($md5) { Write-Output "Link: $webBase/view/$md5" }
+        }
+        Remove-Item -LiteralPath $tempFile -ErrorAction SilentlyContinue
+        return
+    }
+
+    # --- Display result ---
+    if ($logoType) {
+        $logoArgs = @('--logo-type', $logoType, '--logo', $tempFile, '--logo-width', $logoWidth)
+        if ($logoType -eq 'iterm') {
+            # Box + preserveAspectRatio: never stretched, whatever the aspect ratio
+            # (kitty-direct cannot do this through ConPTY: its payload has no rows).
+            $logoHeight = if ($env:J621_LOGO_HEIGHT) { $env:J621_LOGO_HEIGHT } else { '25' }
+            $logoArgs += @('--logo-height', $logoHeight, '--logo-preserve-aspect-ratio', 'true')
+        } elseif ($env:J621_LOGO_HEIGHT) {
+            $logoArgs += @('--logo-height', $env:J621_LOGO_HEIGHT)
+        }
+        & fastfetch @ffArgs @logoArgs
+    } else {
+        & fastfetch @ffArgs
+    }
+    Add-Content -LiteralPath $logFile -Value "$stamp Downloaded: $jId $filename [$modeName]"
+    if ($filename) {
+        Write-Host (Format-J621Accent "Logo from API: $filename ($modeName, $jId)")
+        Write-Output "Link: $webBase/detail/$jId"
+    } else {
+        Write-Host (Format-J621Accent "Logo from API ($modeName)")
+    }
+
+    # --- Keep only the last 1000 lines of the log ---
+    $lines = @(Get-Content -LiteralPath $logFile -Tail 1000)
+    Set-Content -LiteralPath $logFile -Value $lines
+
+    # --- Cleanup ---
+    Remove-Item -LiteralPath $tempFile -ErrorAction SilentlyContinue
+}

extras/powershell_greeting/README.md

@@ -0,0 +1,127 @@
+# PowerShell greeting (J621 Windows port)
+
+Shows a random J621 library image as your shell greeting, using fastfetch.
+This is the Windows/PowerShell port of [`../fish_greeting/`](../fish_greeting/) -
+same API, same modes, same logs, adapted to PowerShell 5.1+ and Windows
+terminals.
+
+## What changed from the fish version
+
+| | fish | PowerShell (this port) |
+| --- | --- | --- |
+| Entry point | `fish_greeting` function | `Show-J621Greeting` (loaded from your profile) |
+| Endpoint | `GET /api/random/?fastfetch=1&rating=X` | same |
+| Config | `~/.config/j621Greeting/config.fish` | `%APPDATA%\j621Greeting\config.ps1` |
+| Mode file | `~/.config/fish/greeting_mode` | `%APPDATA%\j621Greeting\greeting_mode` (the file `gm-switch.exe` writes) |
+| JSON parsing | `jq` / `python3` / grep | `ConvertFrom-Json` (built-in) |
+| MIME detection | `file --mime-type` | PNG/JPEG/GIF magic bytes |
+| GIFs | `gifsicle` + `kitten icat` | none: static first frame in Windows Terminal, animated in WezTerm (its `kitty-direct` plays the GIF) |
+| fastfetch logo | `--logo-type kitty --logo ... --logo-width 35` | `sixel` in Windows Terminal, `iterm` (aspect-preserving box) in WezTerm, no image elsewhere |
+| Logs | `~/.config/j621Logos/logs.log` | `%APPDATA%\j621Logos\logs.log` |
+
+## Install
+
+```powershell
+cd extras\powershell_greeting
+.\install.ps1
+```
+
+The installer copies `J621Greeting.ps1` into `%APPDATA%\j621Greeting\`, asks
+for your API origin (and an optional scoped token), writes
+`%APPDATA%\j621Greeting\config.ps1`, wires a marker block into your
+PowerShell profile (it replaces the previous plain-`fastfetch` hook), checks
+the tools it needs and probes the backend (`/health` plus a random roll). It
+exits non-zero when the backend cannot be reached.
+
+Non-interactive / re-install:
+
+```powershell
+.\install.ps1 -Url https://j621.example.ts.net -Token <api-token>
+.\install.ps1 -NoPrompt          # defaults, never asks
+.\install.ps1 -Force             # rewrite an existing config
+.\install.ps1 -NoProfilePatch    # do not touch your PowerShell profile
+.\install.ps1 -Uninstall         # remove the profile block + installed script
+```
+
+Test it manually any time with:
+
+```powershell
+greeting
+```
+
+The profile block also installs a `greeting` helper that (re)sources
+`J621Greeting.ps1` and runs `Show-J621Greeting`, so it works even when the
+automatic interactive greeting was skipped.
+
+Requirements: `fastfetch` and `curl.exe` (ships with Windows 10 1803+).
+Image logos need Windows Terminal 1.22+ (sixel) or WezTerm with kitty
+graphics enabled; other terminals fall back to a plain fastfetch.
+
+## No token? That is fine
+
+The greeting is meant to run **without** a token: it then behaves like a
+guest of your instance - unsigned image links and only items that are
+visible to guests. Adding a token to the config unlocks signed links and
+items that are hidden from guests. The recommended value is a **scoped
+greeting token**: open the app, go to *Account -> Shell tokens* (or `/tokens`),
+create one and copy the `j621r_...` key - it only works with `/api/random/`,
+so it is safe to keep in the config file.
+
+## Configuration
+
+`%APPDATA%\j621Greeting\config.ps1` is read on every run (environment
+variables already set in your session win over it):
+
+```powershell
+if (-not $env:J621_BASE) { $env:J621_BASE = 'https://j621.rainbow-herring.ts.net' }  # API origin
+if (-not $env:J621_WEB)  { $env:J621_WEB  = 'https://j621.example.ts.net' }          # link origin (split deploys)
+if (-not $env:J621_TOKEN) { $env:J621_TOKEN = '<api token>' }                        # signed URLs + hidden items
+if (-not $env:J621_FASTFETCH_CONFIG) { $env:J621_FASTFETCH_CONFIG = 'jake' }         # fastfetch config name
+```
+
+Extra escapes (all optional):
+
+- `J621_LOGO_TYPE` - force a fastfetch logo type (`sixel`, `kitty-direct`, ...)
+- `J621_ALWAYS_FETCH=1` - fetch even in terminals without image support (prints the link, ASCII logo)
+- `J621_LOGO_WIDTH` - logo width in columns (default 35)
+- `J621_MODE_FILE` - mode file override (shared with `gm-switch`)
+
+## Rating filters
+
+| `greeting_mode` | Rating requested | Label |
+| --- | --- | --- |
+| `0` | `e` | NSFW |
+| `1` | `s` | SFW |
+| `2` (default) | `q` | Questionable |
+
+The mode file is `%APPDATA%\j621Greeting\greeting_mode`. Use
+[`../win-gm-switch/`](../win-gm-switch/) (or its Start Menu shortcuts) to
+switch, or just edit the file.
+
+## Troubleshooting
+
+- **No image logo in Windows Terminal**: WT 1.22+ is required for sixel;
+  update with `winget upgrade Microsoft.WindowsTerminal`.
+- **WezTerm**: kitty graphics must be on - `config.enable_kitty_graphics = true`
+  in `~/.wezterm.lua`. The default uses the `iterm` logo type with
+  `preserveAspectRatio`, which never stretches. If something looks off, try
+  `J621_LOGO_TYPE=kitty-direct`, `kitty`, or `sixel` (note: through ConPTY,
+  plain `kitty` falls back to ASCII and `kitty-direct` stretches tall images).
+- **VS Code / other terminals**: no image protocol, so the greeting prints a
+  plain fastfetch on purpose (no fetch delay). `J621_ALWAYS_FETCH=1` still
+  fetches and prints the link.
+- `No logo (No image matches those filters.)` - the library has no images
+  for that rating; try another mode or add files.
+- `No logo (API error)` - check `J621_BASE` and that the deployment is up
+  (`https://<host>/health`).
+- `No logo (download failed)` - the signed URL expired (they last 24 h) or
+  the item was deleted between the two requests; just run it again.
+- **The greeting is slow** - the API and image fetch have `--max-time`
+  guards; a slow tailnet link is usually the cause.
+- Log file: `%APPDATA%\j621Logos\logs.log` (only the last 1000 lines are kept).
+
+## gm-switch
+
+The Rust [`../win-gm-switch/`](../win-gm-switch/) tool writes the same mode
+file, and on Linux it can replace the old C++ `gm-switch` (it writes
+`~/.config/fish/greeting_mode` there, the same file the fish greeting reads).

extras/powershell_greeting/config.example.ps1

@@ -0,0 +1,26 @@
+# Copy to %APPDATA%\j621Greeting\config.ps1 and adjust.
+# This file runs every time the greeting starts; an environment variable that
+# is already set in your session wins over the values here.
+
+# API origin (no trailing slash needed).
+if (-not $env:J621_BASE) { $env:J621_BASE = 'https://j621.rainbow-herring.ts.net' }
+
+# Web origin used in the printed link. Only needed when the SPA is served
+# from a different host than the API (split deployment).
+# if (-not $env:J621_WEB) { $env:J621_WEB = 'https://j621-frontend.rainbow-herring.ts.net' }
+
+# API token. Optional: gives you signed image URLs and access to items that
+# are hidden from guests. The recommended value is a scoped greeting token
+# (Account -> Shell tokens, or /tokens in the app): those only work with
+# /api/random/, so they are safe to keep in this file. The full API token
+# works too, but grants everything.
+# if (-not $env:J621_TOKEN) { $env:J621_TOKEN = 'j621r_paste-your-token-here' }
+
+# fastfetch config name used for the greeting logo.
+# if (-not $env:J621_FASTFETCH_CONFIG) { $env:J621_FASTFETCH_CONFIG = 'jake' }
+
+# Force a fastfetch logo type instead of the per-terminal default
+# (Windows Terminal -> sixel, WezTerm -> iterm with preserveAspectRatio,
+# others -> no image).
+# if (-not $env:J621_LOGO_TYPE) { $env:J621_LOGO_TYPE = 'iterm' }
+# if (-not $env:J621_LOGO_HEIGHT) { $env:J621_LOGO_HEIGHT = '25' }

extras/powershell_greeting/install.ps1

@@ -0,0 +1,219 @@
+# Install the J621 PowerShell greeting:
+#   * copies J621Greeting.ps1 into %APPDATA%\j621Greeting\
+#   * writes %APPDATA%\j621Greeting\config.ps1 (asks for the API origin and an
+#     optional token, or takes them as parameters)
+#   * wires the greeting into your PowerShell profile (marker block, once)
+#   * checks the tools it needs and probes the configured backend
+#
+# Usage:
+#   .\install.ps1
+#   .\install.ps1 -Url https://j621.example.ts.net -Token <api-token>
+#   .\install.ps1 -NoPrompt          # never ask, keep/derive defaults
+#   .\install.ps1 -Force             # rewrite an existing config
+#   .\install.ps1 -NoProfilePatch    # do not touch your PowerShell profile
+#   .\install.ps1 -Uninstall         # remove the profile block + installed script
+
+[CmdletBinding()]
+param(
+    [string]$Url,
+    [string]$Token,
+    [switch]$NoPrompt,
+    [switch]$Force,
+    [switch]$NoProfilePatch,
+    [switch]$Uninstall
+)
+
+$ErrorActionPreference = 'Stop'
+
+$here = $PSScriptRoot
+if (-not $here) { $here = Split-Path -Parent $MyInvocation.MyCommand.Path }
+$configDir = Join-Path $env:APPDATA 'j621Greeting'
+$configFile = Join-Path $configDir 'config.ps1'
+$installedScript = Join-Path $configDir 'J621Greeting.ps1'
+$defaultUrl = 'https://j621.rainbow-herring.ts.net'
+$markerBegin = '# >>> J621 greeting >>>'
+$markerEnd = '# <<< J621 greeting <<<'
+$profilePath = $PROFILE
+
+function Get-InstalledConfigValue {
+    param([string]$Name)
+    if (-not (Test-Path -LiteralPath $configFile)) { return $null }
+    $content = Get-Content -LiteralPath $configFile -Raw
+    # Ignore commented-out lines: the config ships an example token line, and
+    # matching it would make us probe with the placeholder as a real token.
+    $content = (@($content -split "`r?`n") | Where-Object { $_ -notmatch '^\s*#' }) -join "`n"
+    $rx = '\$env:' + $Name + ' = ''([^'']*)'''
+    if ($content -match $rx) { return $Matches[1] }
+    return $null
+}
+
+function Remove-ProfileBlock {
+    if (-not (Test-Path -LiteralPath $profilePath)) { return }
+    $lines = @(Get-Content -LiteralPath $profilePath)
+    if (-not ($lines -contains $markerBegin)) { return }
+    $out = New-Object System.Collections.Generic.List[string]
+    $inside = $false
+    foreach ($line in $lines) {
+        if ($line.Trim() -eq $markerBegin) { $inside = $true; continue }
+        if ($line.Trim() -eq $markerEnd) { $inside = $false; continue }
+        if (-not $inside) { $out.Add($line) }
+    }
+    while ($out.Count -gt 0 -and [string]::IsNullOrWhiteSpace($out[$out.Count - 1])) { $out.RemoveAt($out.Count - 1) }
+    Set-Content -LiteralPath $profilePath -Value ($out -join "`r`n") -Encoding ASCII
+}
+
+# --- Uninstall -----------------------------------------------------------------
+if ($Uninstall) {
+    Remove-ProfileBlock
+    if (Test-Path -LiteralPath $installedScript) { Remove-Item -LiteralPath $installedScript -Force }
+    Write-Host "Removed the J621 greeting from the profile and $installedScript"
+    Write-Host "Your config and logs were left in place: $configDir"
+    exit 0
+}
+
+# --- Install the function ------------------------------------------------------
+New-Item -ItemType Directory -Path $configDir -Force | Out-Null
+$source = Join-Path $here 'J621Greeting.ps1'
+if (-not (Test-Path -LiteralPath $source)) { throw "J621Greeting.ps1 not found next to this installer ($source)" }
+Copy-Item -LiteralPath $source -Destination $installedScript -Force
+Write-Host "Installed $installedScript"
+
+# --- Configuration -------------------------------------------------------------
+$writeConfig = $false
+if (-not (Test-Path -LiteralPath $configFile)) {
+    $writeConfig = $true
+} elseif ($Force -or $PSBoundParameters.ContainsKey('Url')) {
+    $writeConfig = $true
+} else {
+    Write-Host "Keeping existing $configFile (use -Force to rewrite it)"
+    $current = Get-InstalledConfigValue -Name 'J621_BASE'
+    if ($current) { $Url = $current }
+    if (-not $Token) { $Token = Get-InstalledConfigValue -Name 'J621_TOKEN' }
+}
+
+if ($writeConfig) {
+    if (-not $NoPrompt) {
+        if (-not $Url) {
+            $answer = Read-Host "API origin [$defaultUrl]"
+            if ($answer) { $Url = $answer }
+        }
+        if (-not $Token) {
+            $answer = Read-Host 'API token (optional, Enter to run as a guest)'
+            if ($answer) { $Token = $answer }
+        }
+    }
+    if (-not $Url) { $Url = $defaultUrl }
+    $Url = $Url.Trim().TrimEnd('/').Replace("'", "")
+    if ($Token) { $Token = $Token.Trim().Replace("'", "") }
+
+    $lines = New-Object System.Collections.Generic.List[string]
+    $lines.Add('# J621 greeting configuration - written by install.ps1 on ' + (Get-Date -Format 'yyyy-MM-dd'))
+    $lines.Add('# Values here are defaults; an environment variable already set in your')
+    $lines.Add('# session wins over them.')
+    $lines.Add('if (-not $env:J621_BASE) { $env:J621_BASE = ''' + $Url + ''' }')
+    if ($Token) {
+        $lines.Add('if (-not $env:J621_TOKEN) { $env:J621_TOKEN = ''' + $Token + ''' }')
+    } else {
+        $lines.Add('# if (-not $env:J621_TOKEN) { $env:J621_TOKEN = ''paste-a-token-here'' }')
+    }
+    $lines.Add('# if (-not $env:J621_WEB) { $env:J621_WEB = ''' + $Url + ''' }')
+    $lines.Add('# if (-not $env:J621_FASTFETCH_CONFIG) { $env:J621_FASTFETCH_CONFIG = ''jake'' }')
+    Set-Content -LiteralPath $configFile -Value $lines -Encoding ASCII
+    Write-Host "Wrote $configFile"
+}
+
+# --- Profile -------------------------------------------------------------------
+if (-not $NoProfilePatch) {
+    $existing = ''
+    if (Test-Path -LiteralPath $profilePath) { $existing = Get-Content -LiteralPath $profilePath -Raw }
+    if ($existing -match [regex]::Escape($markerBegin)) {
+        Write-Host 'Profile already sources the greeting (marker present)'
+    } else {
+        $normalized = $existing -replace "`r`n", "`n"
+        $legacy = @(
+            '# Fastfetch greeting on interactive PowerShell start',
+            'if ([Environment]::UserInteractive -and -not [Console]::IsOutputRedirected) {',
+            '    fastfetch',
+            '}'
+        ) -join "`n"
+        if ($normalized.Contains($legacy)) {
+            $normalized = $normalized.Replace($legacy, '').TrimEnd() + "`n"
+            Write-Host 'Replaced the plain fastfetch block in your profile'
+        }
+
+        $block = @(
+            $markerBegin,
+            '# Random J621 library image as the fastfetch logo (extras/powershell_greeting).',
+            '$j621GreetingScript = "$env:APPDATA\j621Greeting\J621Greeting.ps1"',
+            'if (Test-Path -LiteralPath $j621GreetingScript) { . $j621GreetingScript }',
+            '# Run it again any time with: greeting',
+            'function greeting {',
+            '    if (-not (Get-Command Show-J621Greeting -ErrorAction Ignore) -and (Test-Path -LiteralPath $j621GreetingScript)) { . $j621GreetingScript }',
+            '    Show-J621Greeting',
+            '}',
+            'if ((Test-Path -LiteralPath $j621GreetingScript) -and [Environment]::UserInteractive -and -not [Console]::IsOutputRedirected) {',
+            '    Show-J621Greeting',
+            '}',
+            $markerEnd
+        ) -join "`r`n"
+
+        $profileDir = Split-Path -Parent $profilePath
+        if (-not (Test-Path -LiteralPath $profileDir)) { New-Item -ItemType Directory -Path $profileDir -Force | Out-Null }
+        Set-Content -LiteralPath $profilePath -Value ($normalized.TrimEnd() + "`r`n`r`n" + $block + "`r`n") -Encoding ASCII
+        Write-Host "Added the J621 greeting to $profilePath"
+    }
+}
+
+# --- Dependencies --------------------------------------------------------------
+$problems = 0
+foreach ($tool in 'fastfetch', 'curl.exe') {
+    if (-not (Get-Command $tool -ErrorAction SilentlyContinue)) {
+        $problems = 1
+        Write-Host "Missing required tool: $tool"
+    }
+}
+if (-not ($env:WT_SESSION -or $env:WEZTERM_PANE)) {
+    Write-Host 'Note: image logos need Windows Terminal 1.22+ (sixel) or WezTerm (kitty graphics);'
+    Write-Host 'other terminals fall back to a plain fastfetch.'
+}
+
+# --- Probe the configured backend -----------------------------------------------
+Write-Host ''
+$probeUrl = $Url
+$probeToken = $Token
+if (-not $probeUrl) { $probeUrl = $defaultUrl }
+Write-Host "Checking $probeUrl ..."
+$health = & curl.exe -s -m 10 ($probeUrl + '/health') 2>$null | Out-String
+if ($health -match '"status"\s*:\s*"ok"') {
+    Write-Host '  backend: ok'
+    $probeArgs = @('-s', '-m', '10')
+    if ($probeToken) { $probeArgs += @('-H', "Authorization: Token $probeToken") }
+    $probe = & curl.exe @probeArgs ($probeUrl + '/api/random/?fastfetch=1') 2>$null | Out-String
+    $detail = $null
+    try {
+        $parsed = $probe | ConvertFrom-Json
+        if ($parsed.detail) { $detail = [string]$parsed.detail }
+    } catch { }
+    if ($detail) {
+        Write-Host "  random: $detail"
+        if (-not $probeToken) { Write-Host '  (a token would also let you see items that are hidden from guests)' }
+    } else {
+        Write-Host '  random: ok'
+    }
+} else {
+    $problems = 1
+    Write-Host "  backend did not answer at $probeUrl/health"
+    Write-Host "  got: $health"
+    Write-Host "  Fix J621_BASE in $configFile (or pass -Url) and run again."
+}
+
+# --- Wrap up --------------------------------------------------------------------
+Write-Host ''
+if ($problems -eq 0) {
+    Write-Host 'Done. Test it now with:  Show-J621Greeting'
+} else {
+    Write-Host 'Finished with problems above; the greeting will report them too.'
+}
+Write-Host ('Rating mode lives in ' + (Join-Path $configDir 'greeting_mode') + ' (0=NSFW, 1=SFW, 2=Questionable).')
+Write-Host 'gm-switch.exe and its Start Menu shortcuts write that same file.'
+exit $problems

extras/win-gm-switch/.gitignore

@@ -0,0 +1 @@
+/target

extras/win-gm-switch/Cargo.lock

@@ -0,0 +1,7 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "gm-switch"
+version = "0.1.0"

extras/win-gm-switch/Cargo.toml

@@ -0,0 +1,10 @@
+[package]
+name = "gm-switch"
+version = "0.1.0"
+edition = "2021"
+description = "Set the J621 shell greeting rating mode (NSFW / SFW / Questionable)"
+publish = false
+
+[profile.release]
+strip = true
+lto = true

extras/win-gm-switch/README.md

@@ -0,0 +1,54 @@
+# win-gm-switch (Rust)
+
+Rust port of the old `gm-switch.cpp` from
+`J621-Django/extras/fish_greeting system/`: a tiny CLI that sets the J621
+shell greeting rating mode (0 = NSFW, 1 = SFW, 2 = Questionable).
+
+## Usage
+
+```
+gm-switch --mode 0      # NSFW (explicit)
+gm-switch --mode 1      # SFW (safe)
+gm-switch --mode 2      # Questionable
+gm-switch --status      # print the current mode
+```
+
+`--path <file>` overrides the mode file (also via the `J621_MODE_FILE`
+environment variable). Invalid input prints the same usage/errors as the C++
+tool and exits 1.
+
+Mode file locations:
+
+- **Windows**: `%APPDATA%\j621Greeting\greeting_mode` - read by
+  [`../powershell_greeting/`](../powershell_greeting/).
+- **Linux/macOS**: `~/.config/fish/greeting_mode` - read by
+  [`../fish_greeting/`](../fish_greeting/), so this binary can stand in for
+  the C++ tool there.
+
+## Install (Windows)
+
+```powershell
+cd extras\win-gm-switch
+.\install.ps1
+```
+
+The installer builds with `cargo build --release`, installs `gm-switch.exe`
+to `%LOCALAPPDATA%\J621\bin`, adds that folder to your user PATH (new
+terminals pick it up) and creates Start Menu shortcuts under **J621
+Greeting** (NSFW / SFW / Questionable). Each shortcut opens a small console
+showing the confirmation; close it with `exit` or the window button.
+
+Uninstall:
+
+```powershell
+.\install.ps1 -Uninstall
+```
+
+## Build and test without installing
+
+```powershell
+cargo build --release   # -> target\release\gm-switch.exe
+cargo test
+```
+
+Zero runtime dependencies (std only). The `target\` folder is gitignored.

extras/win-gm-switch/install.ps1

@@ -0,0 +1,105 @@
+# Build and install gm-switch:
+#   * cargo build --release (needs the Rust toolchain on PATH)
+#   * copies gm-switch.exe to %LOCALAPPDATA%\J621\bin
+#   * adds that folder to your user PATH (if missing)
+#   * creates Start Menu shortcuts for each mode under "J621 Greeting"
+#
+# Usage:
+#   .\install.ps1
+#   .\install.ps1 -Uninstall
+
+[CmdletBinding()]
+param(
+    [switch]$Uninstall
+)
+
+$ErrorActionPreference = 'Stop'
+
+$here = $PSScriptRoot
+if (-not $here) { $here = Split-Path -Parent $MyInvocation.MyCommand.Path }
+$binDir = Join-Path $env:LOCALAPPDATA 'J621\bin'
+$exe = Join-Path $binDir 'gm-switch.exe'
+$startMenuDir = Join-Path $env:APPDATA 'Microsoft\Windows\Start Menu\Programs\J621 Greeting'
+
+if ($Uninstall) {
+    if (Test-Path -LiteralPath $startMenuDir) {
+        Remove-Item -LiteralPath $startMenuDir -Recurse -Force
+        Write-Host "Removed $startMenuDir"
+    }
+    if (Test-Path -LiteralPath $exe) {
+        Remove-Item -LiteralPath $exe -Force
+        Write-Host "Removed $exe"
+    }
+    $userPath = [Environment]::GetEnvironmentVariable('Path', 'User')
+    if ($userPath) {
+        $parts = @($userPath -split ';' | Where-Object { $_ -and $_ -ne $binDir })
+        [Environment]::SetEnvironmentVariable('Path', ($parts -join ';'), 'User')
+        Write-Host "Removed $binDir from your user PATH"
+    }
+    exit 0
+}
+
+# --- Build ---------------------------------------------------------------------
+if (-not (Get-Command cargo -ErrorAction SilentlyContinue)) {
+    Write-Host 'cargo was not found on PATH - install the Rust toolchain (https://rustup.rs) first.'
+    exit 1
+}
+Push-Location $here
+try {
+    Write-Host 'Building gm-switch (cargo build --release) ...'
+    # cargo writes progress to stderr; keep that from tripping $ErrorActionPreference.
+    $previousPreference = $ErrorActionPreference
+    $ErrorActionPreference = 'Continue'
+    cargo build --release 2>&1 | Write-Host
+    $buildExit = $LASTEXITCODE
+    $ErrorActionPreference = $previousPreference
+    if ($buildExit -ne 0) {
+        Write-Host 'cargo build failed.'
+        exit 1
+    }
+} finally {
+    Pop-Location
+}
+
+$built = Join-Path $here 'target\release\gm-switch.exe'
+if (-not (Test-Path -LiteralPath $built)) {
+    Write-Host "Build output not found: $built"
+    exit 1
+}
+
+# --- Install -------------------------------------------------------------------
+New-Item -ItemType Directory -Path $binDir -Force | Out-Null
+Copy-Item -LiteralPath $built -Destination $exe -Force
+Write-Host "Installed $exe"
+
+$userPath = [Environment]::GetEnvironmentVariable('Path', 'User')
+if (-not $userPath) { $userPath = '' }
+if (-not (($userPath -split ';') -contains $binDir)) {
+    $newPath = ($userPath.TrimEnd(';') + ';' + $binDir).TrimStart(';')
+    [Environment]::SetEnvironmentVariable('Path', $newPath, 'User')
+    Write-Host "Added $binDir to your user PATH (open a new terminal to pick it up)"
+}
+
+# --- Shortcuts ------------------------------------------------------------------
+New-Item -ItemType Directory -Path $startMenuDir -Force | Out-Null
+$modes = @(
+    @{ Value = '0'; Name = 'NSFW' },
+    @{ Value = '1'; Name = 'SFW' },
+    @{ Value = '2'; Name = 'Questionable' }
+)
+$shell = New-Object -ComObject WScript.Shell
+foreach ($m in $modes) {
+    $lnkPath = Join-Path $startMenuDir ('J621 Greeting - ' + $m.Name + '.lnk')
+    $shortcut = $shell.CreateShortcut($lnkPath)
+    $shortcut.TargetPath = "$env:SystemRoot\System32\cmd.exe"
+    $shortcut.Arguments = '/k ""' + $exe + '" --mode ' + $m.Value + '"'
+    $shortcut.WorkingDirectory = $env:USERPROFILE
+    $shortcut.Description = 'Set the J621 shell greeting to ' + $m.Name + ' mode'
+    $shortcut.Save()
+    Write-Host ('Created shortcut: ' + $lnkPath)
+}
+
+Write-Host ''
+Write-Host 'Done. Try:  gm-switch --status'
+Write-Host 'The Start Menu shortcuts open a small console showing the confirmation.'
+exit 0

extras/win-gm-switch/src/main.rs

@@ -0,0 +1,188 @@
+//! gm-switch - set the J621 shell greeting rating mode.
+//!
+//! Rust port of the old gm-switch.cpp (J621-Django/extras/fish_greeting
+//! system). On Windows it writes the mode file used by the PowerShell
+//! greeting (%APPDATA%\j621Greeting\greeting_mode); on Linux/macOS it writes
+//! ~/.config/fish/greeting_mode, so it can stand in for the C++ tool there.
+//!
+//! Usage:
+//!   gm-switch --mode <0|1|2> [--path <file>]
+//!   gm-switch --status [--path <file>]
+
+use std::env;
+use std::fs;
+use std::path::{Path, PathBuf};
+use std::process::exit;
+
+const USAGE: &str = "\
+Usage: gm-switch --mode <0|1|2>
+  --mode 0    Set to NSFW mode (explicit)
+  --mode 1    Set to SFW mode (safe)
+  --mode 2    Set to Questionable mode
+  --status    Print the current greeting mode
+  --path <file>  Override the mode file location
+";
+
+fn mode_name(mode: &str) -> Option<&'static str> {
+    match mode {
+        "0" => Some("NSFW"),
+        "1" => Some("SFW"),
+        "2" => Some("Questionable"),
+        _ => None,
+    }
+}
+
+fn default_mode_file() -> PathBuf {
+    if let Ok(path) = env::var("J621_MODE_FILE") {
+        if !path.is_empty() {
+            return PathBuf::from(path);
+        }
+    }
+    #[cfg(windows)]
+    {
+        if let Ok(appdata) = env::var("APPDATA") {
+            return Path::new(&appdata).join("j621Greeting").join("greeting_mode");
+        }
+    }
+    #[cfg(not(windows))]
+    {
+        if let Ok(home) = env::var("HOME") {
+            return Path::new(&home)
+                .join(".config")
+                .join("fish")
+                .join("greeting_mode");
+        }
+    }
+    PathBuf::from("greeting_mode")
+}
+
+fn main() {
+    let args: Vec<String> = env::args().skip(1).collect();
+
+    let mut mode: Option<String> = None;
+    let mut status = false;
+    let mut path_override: Option<String> = None;
+
+    let mut i = 0;
+    while i < args.len() {
+        match args[i].as_str() {
+            "--mode" => {
+                if i + 1 < args.len() {
+                    mode = Some(args[i + 1].clone());
+                    i += 2;
+                } else {
+                    eprintln!("Error: --mode requires a value");
+                    print!("{USAGE}");
+                    exit(1);
+                }
+            }
+            "--status" => {
+                status = true;
+                i += 1;
+            }
+            "--path" => {
+                if i + 1 < args.len() {
+                    path_override = Some(args[i + 1].clone());
+                    i += 2;
+                } else {
+                    eprintln!("Error: --path requires a value");
+                    print!("{USAGE}");
+                    exit(1);
+                }
+            }
+            "-h" | "--help" => {
+                print!("{USAGE}");
+                exit(0);
+            }
+            other => {
+                eprintln!("Error: unknown argument: {other}");
+                print!("{USAGE}");
+                exit(1);
+            }
+        }
+    }
+
+    let mode_file = match &path_override {
+        Some(p) => PathBuf::from(p),
+        None => default_mode_file(),
+    };
+
+    if status {
+        match fs::read_to_string(&mode_file) {
+            Ok(content) => {
+                let value = content.trim().to_string();
+                match mode_name(&value) {
+                    Some(name) => println!("Current greeting mode: {name} ({value})"),
+                    None => println!(
+                        "Current greeting mode: {value} (unrecognized - the greeting falls back to NSFW)"
+                    ),
+                }
+            }
+            Err(_) => {
+                println!("Current greeting mode: 2 (Questionable, default - no mode file yet)")
+            }
+        }
+        return;
+    }
+
+    let value = match mode {
+        Some(v) => v,
+        None => {
+            print!("{USAGE}");
+            exit(1);
+        }
+    };
+
+    let name = match mode_name(&value) {
+        Some(name) => name,
+        None => {
+            eprintln!("Error: Mode must be 0, 1, or 2");
+            print!("{USAGE}");
+            exit(1);
+        }
+    };
+
+    if let Some(parent) = mode_file.parent() {
+        if !parent.as_os_str().is_empty() {
+            if let Err(err) = fs::create_dir_all(parent) {
+                eprintln!("Error: {err}");
+                exit(1);
+            }
+        }
+    }
+
+    if let Err(err) = fs::write(&mode_file, &value) {
+        eprintln!(
+            "Error: Could not open file for writing: {}",
+            mode_file.display()
+        );
+        eprintln!("Error: {err}");
+        exit(1);
+    }
+
+    println!("Successfully set greeting mode to: {name}");
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn maps_modes_to_names() {
+        assert_eq!(mode_name("0"), Some("NSFW"));
+        assert_eq!(mode_name("1"), Some("SFW"));
+        assert_eq!(mode_name("2"), Some("Questionable"));
+        assert_eq!(mode_name("x"), None);
+    }
+
+    #[test]
+    fn writes_and_reads_mode_file() {
+        let dir = env::temp_dir().join("gm-switch-test");
+        let _ = fs::remove_dir_all(&dir);
+        fs::create_dir_all(&dir).unwrap();
+        let file = dir.join("greeting_mode");
+        fs::write(&file, "1").unwrap();
+        assert_eq!(fs::read_to_string(&file).unwrap().trim(), "1");
+        let _ = fs::remove_dir_all(&dir);
+    }
+}

frontend/src/components/AppShell.tsx

@@ -15,6 +15,7 @@ import { ConfirmDialog } from "@/components/ConfirmDialog";
 import { StatusFooter } from "@/components/StatusFooter";
 import { StatusPill } from "@/components/StatusPill";
 import { Toasts } from "@/components/Toasts";
+import { UploadIndicator } from "@/components/UploadIndicator";
 import { api } from "@/lib/api";
 import { hasBackend } from "@/lib/backend";
 import { cn } from "@/lib/cn";
@@ -112,7 +113,7 @@ export function AppShell() {
   return (
     <div className="flex min-h-screen flex-col">
       <header className="sticky top-0 z-40 border-b border-ctp-surface0 bg-ctp-crust/95 backdrop-blur">
-        <div className="mx-auto flex h-14 w-full max-w-[1600px] items-center gap-4 px-4">
+        <div className="flex h-14 w-full items-center gap-4 px-3 sm:px-4">
           <Link to="/" className="flex shrink-0 items-center">
             <span className="rounded bg-ctp-mauve px-2 py-1 font-mono text-xs font-bold tracking-wide text-ctp-crust">
               J621
@@ -153,6 +154,7 @@ export function AppShell() {
           <div className="ml-auto flex items-center gap-3">
             {backend ? (
               <>
+                <UploadIndicator />
                 <StatusPill status={status} />
                 {user ? (
                   <>

frontend/src/components/MediaCard.tsx

@@ -1,5 +1,6 @@
 import { Link } from "react-router-dom";
 
+import { apiUrl } from "@/lib/api";
 import { cn } from "@/lib/cn";
 import { formatBytes } from "@/lib/format";
 import type { MediaItem } from "@/lib/types";
@@ -17,8 +18,9 @@ const ratingLabels: Record<string, string> = {
 };
 
 export function MediaCard({ item }: { item: MediaItem }) {
-  const preview =
-    item.kind === "video" ? item.thumbnail_url : item.raw_url;
+  // The thumbnail endpoint now builds real 480px previews for images too, so
+  // the grid no longer pulls full-size originals.
+  const preview = apiUrl(item.thumbnail_url);
   const rating = item.display_rating;
 
   return (

frontend/src/components/UploadIndicator.tsx

@@ -0,0 +1,56 @@
+import { Link } from "react-router-dom";
+
+import { cn } from "@/lib/cn";
+import { useUploadStatus } from "@/lib/uploadStatus";
+
+const PHASE_LABELS: Record<string, string> = {
+  md5: "e621 MD5",
+  visual: "Visual similarity",
+  iqdb: "IQDB",
+};
+
+/**
+ * Shell-wide progress for the server-side upload pipeline.
+ *
+ * Staged uploads keep processing after the Upload page is closed, so this
+ * pill is the "leave and keep an eye on it" view: it lives in the header on
+ * every page and links back to the board.
+ */
+export function UploadIndicator() {
+  const { data: status } = useUploadStatus();
+  if (!status || !status.active) return null;
+
+  const total = Math.max(status.total, status.processed + status.failed);
+  const done = status.processed + status.failed;
+  const percent = total > 0 ? Math.min(100, Math.round((done / total) * 100)) : 0;
+  const broken = status.status === "paused" || status.status === "error";
+  const label =
+    status.status === "paused"
+      ? "uploads paused"
+      : status.status === "error"
+        ? "uploads failed"
+        : (PHASE_LABELS[status.phase] ?? "processing uploads");
+  const count = total > 0 ? `${done}/${total}` : `${status.outstanding} left`;
+
+  return (
+    <Link
+      to="/upload"
+      title={status.error || "Staged uploads are being processed in the background"}
+      className={cn(
+        "flex items-center gap-2 rounded-md border px-2 py-1 font-mono text-[10px] transition",
+        broken
+          ? "border-ctp-red/40 text-ctp-red hover:bg-ctp-red/10"
+          : "border-ctp-surface1 text-ctp-subtext0 hover:bg-ctp-surface0 hover:text-ctp-text",
+      )}
+    >
+      <span className="hidden sm:inline">{label}</span>
+      <span>{count}</span>
+      <span className="h-1 w-12 overflow-hidden rounded-full bg-ctp-surface0">
+        <span
+          className={cn("block h-full", broken ? "bg-ctp-red" : "bg-ctp-teal")}
+          style={{ width: `${percent}%` }}
+        />
+      </span>
+    </Link>
+  );
+}

frontend/src/features/account/PreferencesCard.tsx

@@ -9,6 +9,8 @@ import type { UserPreferences } from "@/lib/types";
 import { useAuth } from "@/store/auth";
 import { toast } from "@/store/toasts";
 
+const E621_PER_PAGE_OPTIONS = [48, 100, 200, 320];
+
 const LANDING_OPTIONS: { value: NonNullable<UserPreferences["landing_page"]>; label: string }[] = [
   { value: "library", label: "Library" },
   { value: "online", label: "Online" },
@@ -26,6 +28,7 @@ export function PreferencesCard() {
     per_page: user?.preferences?.per_page ?? 48,
     zoom: user?.preferences?.zoom ?? 190,
     online_hot_default: user?.preferences?.online_hot_default ?? true,
+    e621_per_page: user?.preferences?.e621_per_page ?? 48,
   });
   const [saving, setSaving] = useState(false);
 
@@ -149,8 +152,32 @@ export function PreferencesCard() {
               ))}
             </select>
           </Field>
+
+          <Field label="e621 posts per page">
+            <select
+              className={inputClass}
+              value={values.e621_per_page ?? 48}
+              onChange={(event) =>
+                setValues((current) => ({
+                  ...current,
+                  e621_per_page: Number(event.target.value),
+                }))
+              }
+            >
+              {E621_PER_PAGE_OPTIONS.map((option) => (
+                <option key={option} value={option}>
+                  {option}
+                </option>
+              ))}
+            </select>
+          </Field>
         </div>
 
+        <p className="text-[11px] leading-relaxed text-ctp-overlay0">
+          e621 posts per page drives the Online browser and how many pool posts
+          load per request; e621 caps a request at 320.
+        </p>
+
         <label className="flex flex-col gap-1.5">
           <span className="text-xs font-medium uppercase tracking-wide text-ctp-overlay1">
             Thumbnail size

frontend/src/features/detail/DetailPage.tsx

@@ -14,11 +14,14 @@ export default function DetailPage() {
   if (J_ID_RE.test(itemId)) {
     if (!hasBackend()) return <BackendNeeded />;
     const normalized = `J-${itemId.slice(2)}`;
-    return <LibraryDetail jId={normalized} />;
+    // Key per item: remount so local state (delete confirm, optimizer, task
+    // view) cannot leak from the previously viewed item.
+    return <LibraryDetail key={normalized} jId={normalized} />;
   }
 
   if (/^\d+$/.test(itemId)) {
-    return <OnlineDetail postId={Number(itemId)} />;
+    // Key per post: the download task view must not survive a post change.
+    return <OnlineDetail key={itemId} postId={Number(itemId)} />;
   }
 
   return (

frontend/src/features/follows/FollowedPage.tsx

@@ -1,5 +1,5 @@
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
-import { Eye, StarOff } from "lucide-react";
+import { ChevronDown, ChevronRight, Eye, StarOff } from "lucide-react";
 import { useState } from "react";
 import { Link } from "react-router-dom";
 
@@ -13,7 +13,6 @@ import type {
   FollowedPool,
   FollowedTag,
   FollowFeed,
-  Paginated,
 } from "@/lib/types";
 
 const ratingPill: Record<string, string> = {
@@ -149,48 +148,65 @@ function BlacklistCloudPanel() {
       q.state.data?.status === "building" ? 2000 : false,
   });
   const cloud = query.data;
+  const [expanded, setExpanded] = useState(false);
 
   return (
     <section className="rounded-lg border border-ctp-surface0 bg-ctp-base p-4">
-      <div className="flex flex-wrap items-center justify-between gap-2">
+      <button
+        type="button"
+        onClick={() => setExpanded((value) => !value)}
+        title={expanded ? "Hide the tags" : "Show the tags"}
+        className="flex w-full items-center justify-between gap-2 text-left"
+      >
         <h2 className="text-sm font-semibold text-ctp-subtext1">
           Blacklisted tags
         </h2>
-        <p className="text-xs text-ctp-overlay0">
-          {cloud?.source === "user"
-            ? "From your e621 blacklist"
-            : "From e621's anonymous default blacklist"}
-          {cloud ? ` · ${cloud.blacklist_count} entries` : ""}
-          {cloud ? ` · ${cloud.posts} feed post(s) scanned` : ""}
-          {cloud?.computed_at ? ` · computed ${formatDate(cloud.computed_at)}` : ""}
+        <span className="flex items-center gap-1.5 font-mono text-[11px] text-ctp-overlay0">
+          {cloud ? `${cloud.blacklist_count} entries` : "…"}
           {cloud?.status === "building" ? (
-            <span className="ml-2 inline-flex items-center gap-1.5">
-              <Spinner className="h-3 w-3" /> building…
-            </span>
+            <Spinner className="h-3 w-3" />
           ) : null}
-        </p>
-      </div>
+          {expanded ? (
+            <ChevronDown className="h-3.5 w-3.5" />
+          ) : (
+            <ChevronRight className="h-3.5 w-3.5" />
+          )}
+        </span>
+      </button>
 
-      {query.isPending ? (
-        <div className="mt-3 flex justify-center py-4">
-          <Spinner className="h-4 w-4" />
-        </div>
-      ) : cloud && cloud.tags.length > 0 ? (
-        <div className="mt-3 flex flex-wrap gap-1.5">
-          {cloud.tags.map(([tag, count]) => (
-            <span
-              key={tag}
-              className="rounded border border-ctp-red/30 bg-ctp-red/10 px-1.5 py-0.5 font-mono text-[11px] text-ctp-red"
-            >
-              {tag} ({count})
-            </span>
-          ))}
-        </div>
-      ) : (
-        <p className="mt-3 text-xs text-ctp-overlay0">
-          No blacklisted tags in your feeds.
-        </p>
-      )}
+      {expanded ? (
+        <>
+          <p className="mt-2 text-xs text-ctp-overlay0">
+            {cloud?.source === "user"
+              ? "From your e621 blacklist"
+              : "From e621's anonymous default blacklist"}
+            {cloud ? ` · ${cloud.posts} feed post(s) scanned` : ""}
+            {cloud?.computed_at
+              ? ` · computed ${formatDate(cloud.computed_at)}`
+              : ""}
+          </p>
+          {query.isPending ? (
+            <div className="mt-3 flex justify-center py-4">
+              <Spinner className="h-4 w-4" />
+            </div>
+          ) : cloud && cloud.tags.length > 0 ? (
+            <div className="mt-3 flex flex-wrap gap-1.5">
+              {cloud.tags.map(([tag, count]) => (
+                <span
+                  key={tag}
+                  className="rounded border border-ctp-red/30 bg-ctp-red/10 px-1.5 py-0.5 font-mono text-[11px] text-ctp-red"
+                >
+                  {tag} ({count})
+                </span>
+              ))}
+            </div>
+          ) : (
+            <p className="mt-3 text-xs text-ctp-overlay0">
+              No blacklisted tags in your feeds.
+            </p>
+          )}
+        </>
+      ) : null}
     </section>
   );
 }
@@ -207,11 +223,12 @@ export default function FollowedPage() {
 
   const tagsQuery = useQuery({
     queryKey: ["follows-tags"],
-    queryFn: () => api<Paginated<FollowedTag>>("/api/follows/tags/"),
+    // Unpaginated: this is the complete follow list, shown as cards below.
+    queryFn: () => api<FollowedTag[]>("/api/follows/tags/"),
   });
   const poolsQuery = useQuery({
     queryKey: ["follows-pools"],
-    queryFn: () => api<Paginated<FollowedPool>>("/api/follows/pools/"),
+    queryFn: () => api<FollowedPool[]>("/api/follows/pools/"),
   });
 
   const feedQuery = useQuery({
@@ -269,8 +286,8 @@ export default function FollowedPage() {
     );
   }
 
-  const tags = tagsQuery.data?.results ?? [];
-  const pools = poolsQuery.data?.results ?? [];
+  const tags = tagsQuery.data ?? [];
+  const pools = poolsQuery.data ?? [];
   const feed = feedQuery.data;
 
   return (

frontend/src/features/follows/PoolFollowButton.tsx

@@ -5,7 +5,7 @@ import { useState } from "react";
 import { Button, Spinner } from "@/components/ui";
 import { api, errorMessage } from "@/lib/api";
 import { hasBackend } from "@/lib/backend";
-import type { FollowedPool, Paginated } from "@/lib/types";
+import type { FollowedPool } from "@/lib/types";
 import { useAuth } from "@/store/auth";
 import { toast } from "@/store/toasts";
 
@@ -23,12 +23,13 @@ export function PoolFollowButton({
 
   const query = useQuery({
     queryKey: ["follows-pools"],
-    queryFn: () => api<Paginated<FollowedPool>>("/api/follows/pools/"),
+    // Unpaginated on purpose: the button must see every follow, not page one.
+    queryFn: () => api<FollowedPool[]>("/api/follows/pools/"),
     enabled: Boolean(user),
     staleTime: 30_000,
   });
 
-  const follow = query.data?.results.find((entry) => entry.pool_id === poolId);
+  const follow = query.data?.find((entry) => entry.pool_id === poolId);
   const followed = Boolean(follow);
 
   const mutation = useMutation({

frontend/src/features/follows/TagFollowToggle.tsx

@@ -4,7 +4,7 @@ import { useState, type MouseEvent } from "react";
 
 import { api, errorMessage } from "@/lib/api";
 import { cn } from "@/lib/cn";
-import type { FollowedTag, Paginated } from "@/lib/types";
+import type { FollowedTag } from "@/lib/types";
 import { useAuth } from "@/store/auth";
 import { toast } from "@/store/toasts";
 
@@ -16,13 +16,14 @@ export function TagFollowToggle({ tag }: { tag: string }) {
 
   const query = useQuery({
     queryKey: ["follows-tags"],
-    queryFn: () => api<Paginated<FollowedTag>>("/api/follows/tags/"),
+    // Unpaginated on purpose: the toggle must see every follow, not page one.
+    queryFn: () => api<FollowedTag[]>("/api/follows/tags/"),
     enabled: Boolean(user),
     staleTime: 30_000,
   });
 
   const normalized = tag.trim().toLowerCase();
-  const follow = query.data?.results.find((entry) => entry.tag === normalized);
+  const follow = query.data?.find((entry) => entry.tag === normalized);
   const followed = Boolean(follow);
 
   const mutation = useMutation({

frontend/src/features/library/DeletePage.tsx

@@ -3,7 +3,7 @@ import { useState } from "react";
 import { Link } from "react-router-dom";
 
 import { Button, EmptyState, Spinner, inputClass } from "@/components/ui";
-import { api, errorMessage } from "@/lib/api";
+import { api, apiUrl, errorMessage } from "@/lib/api";
 import { cn } from "@/lib/cn";
 import { formatBytes } from "@/lib/format";
 import type { MediaItem, Paginated, StorageInfo } from "@/lib/types";
@@ -245,7 +245,7 @@ export default function DeletePage() {
                   >
                     <div className="relative aspect-square overflow-hidden bg-ctp-mantle">
                       <img
-                        src={item.thumbnail_url}
+                        src={apiUrl(item.thumbnail_url)}
                         alt={item.filename}
                         loading="lazy"
                         className="h-full w-full object-cover"

frontend/src/features/library/IqdbCard.tsx

@@ -4,7 +4,7 @@ import { useState } from "react";
 import { Link } from "react-router-dom";
 
 import { Button, Spinner } from "@/components/ui";
-import { api, errorMessage } from "@/lib/api";
+import { api, apiUrl, errorMessage } from "@/lib/api";
 import { cn } from "@/lib/cn";
 import {
   e621ErrorMessage,
@@ -44,7 +44,7 @@ export function IqdbCard({
     setSelected(null);
     setCandidates(null);
     try {
-      const response = await fetch(item.raw_url);
+      const response = await fetch(apiUrl(item.raw_url));
       if (!response.ok) {
         throw new Error(`Could not load the file (HTTP ${response.status}).`);
       }

frontend/src/features/online/OnlineDetail.tsx

@@ -121,6 +121,10 @@ export function OnlineDetail({ postId }: { postId: number }) {
   });
 
   const [downloadTaskId, setDownloadTaskId] = useState<string | null>(null);
+  // True once this visit has seen the download running. Only then is "your
+  // last download finished" worth showing; a revisit stays quiet (the "In
+  // library" button already says where the file is).
+  const [watchedDownload, setWatchedDownload] = useState(false);
 
   // Server-side tasks outlive this page; re-attach to the newest one for this
   // post so navigating away and back keeps the progress view.
@@ -186,6 +190,19 @@ export function OnlineDetail({ postId }: { postId: number }) {
   const downloadStatus = downloadTask?.status;
   const downloadActive =
     downloadStatus === "pending" || downloadStatus === "downloading";
+  // Never render another post's task — this covers the single frame before the
+  // remount (DetailPage keys this component per post). A null post_id (older or
+  // hand-made tasks) stays visible rather than hiding a real download.
+  const downloadTaskMatchesPost =
+    !downloadTask ||
+    downloadTask.post_id === null ||
+    downloadTask.post_id === post?.id;
+
+  // Derived state (safe to set during render): remember that this visit saw
+  // the download running.
+  if (downloadActive && !watchedDownload) {
+    setWatchedDownload(true);
+  }
 
   useEffect(() => {
     if (!downloadStatus) return;
@@ -340,7 +357,8 @@ export function OnlineDetail({ postId }: { postId: number }) {
             </a>
           </div>
 
-          {downloadTask &&
+          {downloadTaskMatchesPost &&
+          downloadTask &&
           (downloadTask.status === "pending" ||
             downloadTask.status === "downloading") ? (
             <div className="rounded-lg border border-ctp-surface0 bg-ctp-base p-3">
@@ -372,7 +390,7 @@ export function OnlineDetail({ postId }: { postId: number }) {
                 cancel
               </button>
             </div>
-          ) : downloadTask?.status === "complete" ? (
+          ) : downloadTaskMatchesPost && downloadTask?.status === "complete" ? (
             <p className="flex items-center gap-2 rounded-md border border-ctp-green/30 bg-ctp-green/10 px-3 py-2 text-sm text-ctp-green">
               <CheckCircle2 className="h-4 w-4 shrink-0" />
               Downloaded to the library
@@ -385,13 +403,13 @@ export function OnlineDetail({ postId }: { postId: number }) {
                 </Link>
               ) : null}
             </p>
-          ) : downloadTask?.status === "cancelled" ? (
+          ) : downloadTaskMatchesPost && downloadTask?.status === "cancelled" ? (
             <p className="text-xs text-ctp-overlay0">Download cancelled.</p>
-          ) : downloadTask?.status === "error" ? (
+          ) : downloadTaskMatchesPost && downloadTask?.status === "error" ? (
             <p className="rounded-md border border-ctp-red/30 bg-ctp-red/10 px-3 py-2 text-sm text-ctp-red">
               {downloadTask.error || "Download failed."}
             </p>
-          ) : remoteFinishedTask && !downloadMutation.isPending ? (
+          ) : remoteFinishedTask && watchedDownload && !downloadMutation.isPending ? (
             <p className="flex items-center gap-2 text-xs text-ctp-overlay0">
               <CheckCircle2 className="h-3.5 w-3.5 shrink-0 text-ctp-green" />
               Your last download for this post finished

frontend/src/features/online/OnlinePage.tsx

@@ -1,5 +1,5 @@
 import { keepPreviousData, useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
-import { X } from "lucide-react";
+import { ChevronDown, ChevronRight, X } from "lucide-react";
 import { useEffect, useMemo, useRef, useState } from "react";
 import { Link, useLocation, useSearchParams } from "react-router-dom";
 
@@ -18,13 +18,14 @@ import {
   type E621Post,
 } from "@/lib/e621";
 import { hotDefaultAction, HOT_ORDER } from "@/features/online/hotDefault";
+import { schedulePreferenceSave } from "@/lib/preferences";
 import { useE621 } from "@/store/e621";
 import { useAuth } from "@/store/auth";
 import { useUi } from "@/store/ui";
 import { toast } from "@/store/toasts";
 import { hasBackend } from "@/lib/backend";
 
-const PAGE_SIZE = 48;
+const E621_PER_PAGE_OPTIONS = [48, 100, 200, 320];
 const EMPTY_POSTS: E621Post[] = [];
 
 export default function OnlinePage() {
@@ -42,8 +43,11 @@ export default function OnlinePage() {
   const queryClient = useQueryClient();
   const [draft, setDraft] = useState<string | null>(null);
   const [blacklistDraft, setBlacklistDraft] = useState("");
+  const [showBlacklist, setShowBlacklist] = useState(false);
   const tagInput = draft ?? tags;
   const zoom = useUi((state) => state.zoom);
+  const perPage = useUi((state) => state.e621PerPage);
+  const setE621PerPage = useUi((state) => state.setE621PerPage);
   const appliedHotDefault = useRef(false);
 
   // Landing on Online follows the account's order:hot default: applied when
@@ -100,12 +104,12 @@ export default function OnlinePage() {
   }
 
   const postsQuery = useQuery({
-    queryKey: ["e621", "posts", tags, page, credentials?.username ?? ""],
+    queryKey: ["e621", "posts", tags, page, perPage, credentials?.username ?? ""],
     queryFn: ({ signal }) =>
       fetchPosts(effectiveCredentials(credentials), {
         tags,
         page,
-        limit: PAGE_SIZE,
+        limit: perPage,
         signal,
       }),
     placeholderData: keepPreviousData,
@@ -166,7 +170,7 @@ export default function OnlinePage() {
     return [...counts.entries()].sort((a, b) => b[1] - a[1]).slice(0, 40);
   }, [visiblePosts]);
 
-  const hasNext = posts.length >= PAGE_SIZE;
+  const hasNext = posts.length >= perPage;
 
   function buildParams(tagValue: string, pageValue: number): URLSearchParams {
     const params = new URLSearchParams();
@@ -223,6 +227,31 @@ export default function OnlinePage() {
           </p>
         </form>
 
+        <label className="flex flex-col gap-2">
+          <span className="text-xs font-medium uppercase tracking-wide text-ctp-overlay1">
+            Posts per page
+          </span>
+          <select
+            className={inputClass}
+            value={perPage}
+            onChange={(event) => {
+              const value = Number(event.target.value);
+              setE621PerPage(value);
+              schedulePreferenceSave({ e621_per_page: value });
+              setSearchParams(buildParams(tags, 1), { replace: true });
+            }}
+          >
+            {E621_PER_PAGE_OPTIONS.map((option) => (
+              <option key={option} value={option}>
+                {option}
+              </option>
+            ))}
+          </select>
+          <span className="text-[11px] leading-relaxed text-ctp-overlay0">
+            e621 returns at most 320 posts per request.
+          </span>
+        </label>
+
         <div className="flex flex-col gap-2">
           <span className="text-xs font-medium uppercase tracking-wide text-ctp-overlay1">
             Tags on this page
@@ -243,73 +272,91 @@ export default function OnlinePage() {
         </div>
 
         <div className="flex flex-col gap-2">
-          <span className="text-xs font-medium uppercase tracking-wide text-ctp-overlay1">
-            Your blacklist
-          </span>
-          {credentials?.configured ? (
-            <>
-              {blacklistEntries.length > 0 ? (
-                <div className="flex flex-wrap gap-1.5">
-                  {blacklistEntries.map(({ line, index }) => (
-                    <span
-                      key={`${line}-${index}`}
-                      className="inline-flex items-center gap-1 rounded border border-ctp-red/30 bg-ctp-red/10 px-1.5 py-0.5 font-mono text-[11px] text-ctp-red"
-                    >
-                      {line}
-                      <button
-                        type="button"
-                        title={`Remove ${line}`}
-                        disabled={blacklistMutation.isPending}
-                        onClick={() => removeBlacklistEntry(index)}
-                        className="text-ctp-red/70 transition hover:text-ctp-red disabled:opacity-40"
-                      >
-                        <X className="h-3 w-3" />
-                      </button>
-                    </span>
-                  ))}
-                </div>
+          <button
+            type="button"
+            onClick={() => setShowBlacklist((value) => !value)}
+            title={showBlacklist ? "Hide the blacklist" : "Show the blacklist"}
+            className="flex items-center justify-between gap-2 text-left"
+          >
+            <span className="text-xs font-medium uppercase tracking-wide text-ctp-overlay1">
+              Your blacklist
+            </span>
+            <span className="flex items-center gap-1 font-mono text-[11px] text-ctp-overlay0">
+              {blacklistEntries.length} tag
+              {blacklistEntries.length === 1 ? "" : "s"}
+              {showBlacklist ? (
+                <ChevronDown className="h-3.5 w-3.5" />
               ) : (
-                <p className="text-xs text-ctp-overlay0">
-                  No blacklisted tags.
-                </p>
+                <ChevronRight className="h-3.5 w-3.5" />
               )}
-              <form
-                onSubmit={(event) => {
-                  event.preventDefault();
-                  addBlacklistEntry();
-                }}
-                className="flex gap-2"
-              >
-                <input
-                  className={cn(inputClass, "font-mono")}
-                  placeholder="Add a tag…"
-                  value={blacklistDraft}
-                  onChange={(event) => setBlacklistDraft(event.target.value)}
-                />
-                <Button
-                  type="submit"
-                  variant="secondary"
-                  disabled={!blacklistDraft.trim() || blacklistMutation.isPending}
+            </span>
+          </button>
+          {showBlacklist ? (
+            credentials?.configured ? (
+              <>
+                {blacklistEntries.length > 0 ? (
+                  <div className="flex flex-wrap gap-1.5">
+                    {blacklistEntries.map(({ line, index }) => (
+                      <span
+                        key={`${line}-${index}`}
+                        className="inline-flex items-center gap-1 rounded border border-ctp-red/30 bg-ctp-red/10 px-1.5 py-0.5 font-mono text-[11px] text-ctp-red"
+                      >
+                        {line}
+                        <button
+                          type="button"
+                          title={`Remove ${line}`}
+                          disabled={blacklistMutation.isPending}
+                          onClick={() => removeBlacklistEntry(index)}
+                          className="text-ctp-red/70 transition hover:text-ctp-red disabled:opacity-40"
+                        >
+                          <X className="h-3 w-3" />
+                        </button>
+                      </span>
+                    ))}
+                  </div>
+                ) : (
+                  <p className="text-xs text-ctp-overlay0">
+                    No blacklisted tags.
+                  </p>
+                )}
+                <form
+                  onSubmit={(event) => {
+                    event.preventDefault();
+                    addBlacklistEntry();
+                  }}
+                  className="flex gap-2"
                 >
-                  {blacklistMutation.isPending ? (
-                    <Spinner className="h-3.5 w-3.5" />
-                  ) : (
-                    "Add"
-                  )}
-                </Button>
-              </form>
-              <p className="text-[11px] text-ctp-overlay0">
-                Saved to your e621 account.
+                  <input
+                    className={cn(inputClass, "font-mono")}
+                    placeholder="Add a tag…"
+                    value={blacklistDraft}
+                    onChange={(event) => setBlacklistDraft(event.target.value)}
+                  />
+                  <Button
+                    type="submit"
+                    variant="secondary"
+                    disabled={!blacklistDraft.trim() || blacklistMutation.isPending}
+                  >
+                    {blacklistMutation.isPending ? (
+                      <Spinner className="h-3.5 w-3.5" />
+                    ) : (
+                      "Add"
+                    )}
+                  </Button>
+                </form>
+                <p className="text-[11px] text-ctp-overlay0">
+                  Saved to your e621 account.
+                </p>
+              </>
+            ) : (
+              <p className="text-xs text-ctp-overlay0">
+                <Link to="/account" className="text-ctp-blue hover:underline">
+                  Add e621 credentials
+                </Link>{" "}
+                to manage your blacklist.
               </p>
-            </>
-          ) : (
-            <p className="text-xs text-ctp-overlay0">
-              <Link to="/account" className="text-ctp-blue hover:underline">
-                Add e621 credentials
-              </Link>{" "}
-              to manage your blacklist.
-            </p>
-          )}
+            )
+          ) : null}
         </div>
 
         <div className="flex flex-col gap-2">

frontend/src/features/optimize/OptimizeModal.tsx

@@ -3,7 +3,7 @@ import { X } from "lucide-react";
 import { useState, type ReactNode } from "react";
 
 import { Button, Spinner, inputClass } from "@/components/ui";
-import { errorMessage, uploadFile } from "@/lib/api";
+import { apiUrl, errorMessage, uploadFile } from "@/lib/api";
 import { cn } from "@/lib/cn";
 import { formatBytes } from "@/lib/format";
 import type { MediaItem } from "@/lib/types";
@@ -171,6 +171,9 @@ export function OptimizeModal({
   const queryClient = useQueryClient();
   const extensionKind: OptimizeKind =
     kindForExtension(item.extension) ?? "image";
+  // Same-origin through the proxy in dev; the worker and the range requests
+  // cannot use a cross-origin URL without CORS.
+  const fileUrl = apiUrl(item.raw_url);
   const [options, setOptions] = useState<OptimizeOptions>({
     ...DEFAULT_OPTIONS,
     maxDimension: null,
@@ -180,7 +183,7 @@ export function OptimizeModal({
   const sniffQuery = useQuery({
     queryKey: ["image-kind", item.j_id, item.updated_at],
     queryFn: async () => {
-      const response = await fetch(item.raw_url, {
+      const response = await fetch(fileUrl, {
         headers: { Range: "bytes=0-4095" },
       });
       if (!response.ok && response.status !== 206) {
@@ -315,7 +318,7 @@ export function OptimizeModal({
     if (result?.storageKey) void deleteStoredFile(result.storageKey);
     setResultInfo(null);
     run({
-      url: item.raw_url,
+      url: fileUrl,
       filename: item.filename,
       kind,
       options,
@@ -366,7 +369,7 @@ export function OptimizeModal({
             <div className="grid gap-3 sm:grid-cols-2">
               <PreviewPanel
                 title="Original"
-                url={item.raw_url}
+                url={fileUrl}
                 isVideo={isVideo}
                 size={originalSize}
                 state="original"

frontend/src/features/pools/PoolDetailPage.tsx

@@ -25,17 +25,18 @@ import { useIsMobile } from "@/lib/useMediaQuery";
 import { useE621 } from "@/store/e621";
 import { useUi } from "@/store/ui";
 
-const CHUNK = 100;
+const CHUNK_FALLBACK = 100;
 
 async function fetchPostsChunked(
   credentials: ReturnType<typeof effectiveCredentials>,
   ids: number[],
+  chunk: number,
   signal?: AbortSignal,
 ): Promise<E621Post[]> {
   const posts: E621Post[] = [];
-  for (let index = 0; index < ids.length; index += CHUNK) {
-    const chunk = ids.slice(index, index + CHUNK);
-    posts.push(...(await fetchPostsByIds(credentials, chunk, signal)));
+  for (let index = 0; index < ids.length; index += chunk) {
+    const slice = ids.slice(index, index + chunk);
+    posts.push(...(await fetchPostsByIds(credentials, slice, signal)));
   }
   return posts;
 }
@@ -54,8 +55,11 @@ export default function PoolDetailPage() {
   const blacklistSet = useMemo(() => new Set(blacklist), [blacklist]);
   const isMobile = useIsMobile();
   const zoom = useUi((state) => state.zoom);
+  // Pool posts load in chunks of the user's e621 page size (max 320).
+  const e621PerPage = useUi((state) => state.e621PerPage);
+  const chunk = Math.min(320, Math.max(24, e621PerPage || CHUNK_FALLBACK));
 
-  const [visibleCount, setVisibleCount] = useState(CHUNK);
+  const [visibleCount, setVisibleCount] = useState(chunk);
   const [showBlacklisted, setShowBlacklisted] = useState(false);
 
   const poolQuery = useQuery({
@@ -84,6 +88,7 @@ export default function PoolDetailPage() {
       fetchPostsChunked(
         effectiveCredentials(credentials),
         postIds,
+        chunk,
         signal,
       ),
     enabled: postIds.length > 0,
@@ -319,7 +324,7 @@ export default function PoolDetailPage() {
             <Button
               variant="secondary"
               disabled={postsQuery.isFetching}
-              onClick={() => setVisibleCount((count) => count + CHUNK)}
+              onClick={() => setVisibleCount((count) => count + chunk)}
             >
               {postsQuery.isFetching
                 ? "Loading…"

frontend/src/features/setup/SetupPage.tsx

@@ -17,6 +17,16 @@ import { setToken } from "@/lib/api";
 type TestResult = { ok: boolean; text: string } | null;
 
 async function testBackend(base: string): Promise<TestResult> {
+  // The desktop shell has no server of its own: an empty URL is not a
+  // same-origin backend, and /health on app://j621 is answered by the shell.
+  if (!base && window.j621Desktop) {
+    return {
+      ok: false,
+      text:
+        "The desktop app has no backend of its own. Enter your J621 server's " +
+        "URL, or continue without a backend.",
+    };
+  }
   const controller = new AbortController();
   const timeout = window.setTimeout(() => controller.abort(), 5_000);
   try {
@@ -41,11 +51,17 @@ async function testBackend(base: string): Promise<TestResult> {
       text: `The backend answered HTTP ${response.status}.`,
     };
   } catch {
+    // The desktop shell is a different origin from the backend, and that is
+    // the usual reason the first connection test fails there.
+    const desktopHint = window.j621Desktop
+      ? ` The desktop app's origin is ${window.j621Desktop.origin} — allow it in CORS_ALLOWED_ORIGINS on the backend.`
+      : "";
     return {
       ok: false,
       text:
         "Could not reach the backend. Check the URL, and if it lives on " +
-        "another domain add this site to CORS_ALLOWED_ORIGINS there.",
+        "another domain add this site to CORS_ALLOWED_ORIGINS there." +
+        desktopHint,
     };
   } finally {
     window.clearTimeout(timeout);
@@ -104,10 +120,15 @@ export function SetupPage() {
           </div>
 
           <p className="mt-3 text-sm leading-relaxed text-ctp-subtext0">
-            Enter the origin this app should call for its API. Leave it blank
-            when the app and the API are served from the same domain. Without a
-            backend the app runs in local mode: e621 browsing only, with
-            credentials kept in this browser.
+            {window.j621Desktop
+              ? "Enter the origin of your J621 server (for example " +
+                "https://j621.example.com). Without a backend the app runs in " +
+                "local mode: e621 browsing only, with credentials kept on this " +
+                "device."
+              : "Enter the origin this app should call for its API. Leave it " +
+                "blank when the app and the API are served from the same " +
+                "domain. Without a backend the app runs in local mode: e621 " +
+                "browsing only, with credentials kept in this browser."}
           </p>
 
           <label className="mt-5 flex flex-col gap-1.5">
@@ -116,7 +137,11 @@ export function SetupPage() {
             </span>
             <input
               className={cn(inputClass, "font-mono")}
-              placeholder="https://j621.example.com — blank for this server"
+              placeholder={
+                window.j621Desktop
+                  ? "https://j621.example.com"
+                  : "https://j621.example.com — blank for this server"
+              }
               value={value}
               onChange={(event) => {
                 setValue(event.target.value);
@@ -155,7 +180,7 @@ export function SetupPage() {
               {testing ? <Spinner className="h-3.5 w-3.5" /> : null}
               {testing ? "Testing…" : "Test connection"}
             </Button>
-            {value.trim() ? (
+            {value.trim() && !window.j621Desktop ? (
               <Button variant="ghost" onClick={() => save("")}>
                 Use this server
               </Button>
@@ -166,8 +191,10 @@ export function SetupPage() {
           </div>
 
           <p className="mt-4 text-xs leading-relaxed text-ctp-overlay0">
-            Stored in this browser only. Changing the backend signs you out of
-            the previous one.
+            {window.j621Desktop
+              ? "Stored in this app only."
+              : "Stored in this browser only."}{" "}
+            Changing the backend signs you out of the previous one.
           </p>
         </div>
       </div>

frontend/src/features/similar/SimilarPage.tsx

@@ -10,7 +10,7 @@ import { Link } from "react-router-dom";
 
 import { ResponsivePanel } from "@/components/BottomSheet";
 import { Button, Spinner } from "@/components/ui";
-import { api, errorMessage, uploadFile } from "@/lib/api";
+import { api, apiUrl, errorMessage, uploadFile } from "@/lib/api";
 import { cn } from "@/lib/cn";
 import {
   e621ErrorMessage,
@@ -257,7 +257,7 @@ export default function SimilarPage() {
                 >
                   {exact.thumbnail_url ? (
                     <img
-                      src={exact.thumbnail_url}
+                      src={apiUrl(exact.thumbnail_url)}
                       alt={exact.j_id}
                       className="h-14 w-14 rounded object-cover"
                     />
@@ -309,7 +309,7 @@ export default function SimilarPage() {
                       <span className="relative block aspect-square overflow-hidden bg-ctp-mantle">
                         {match.thumbnail_url ? (
                           <img
-                            src={match.thumbnail_url}
+                            src={apiUrl(match.thumbnail_url)}
                             alt={match.j_id}
                             loading="lazy"
                             className="h-full w-full object-cover transition group-hover:scale-[1.03]"

frontend/src/features/upload/BulkRateModal.tsx

@@ -0,0 +1,365 @@
+import { useQueryClient } from "@tanstack/react-query";
+import { Check, Video, X } from "lucide-react";
+import { useState } from "react";
+
+import { Button, Spinner } from "@/components/ui";
+import { api, apiUrl, errorMessage } from "@/lib/api";
+import { cn } from "@/lib/cn";
+import type { TempUpload } from "@/lib/types";
+import { toast } from "@/store/toasts";
+
+const RATING_OPTIONS = [
+  {
+    value: "s",
+    label: "Safe",
+    active: "border-ctp-green/40 bg-ctp-green/15 text-ctp-green",
+  },
+  {
+    value: "q",
+    label: "Questionable",
+    active: "border-ctp-peach/40 bg-ctp-peach/15 text-ctp-peach",
+  },
+  {
+    value: "e",
+    label: "Explicit",
+    active: "border-ctp-red/40 bg-ctp-red/15 text-ctp-red",
+  },
+];
+
+/**
+ * How many files one request resolves. Copying and hashing is serial per
+ * file on the server, so a 200-file batch in one request risks the proxy
+ * timeout and gives no feedback; small chunks keep every request short and
+ * let the bar advance as they land.
+ */
+const CHUNK_SIZE = 8;
+
+interface BulkResult {
+  resolved: string[];
+  errors: { temp_id: string; error: string }[];
+}
+
+interface Failure {
+  id: string;
+  name: string;
+  error: string;
+}
+
+type Phase = "select" | "running" | "done";
+
+/**
+ * Bulk-rating tool for the Pending & Unmatched column: pick a rating, tick
+ * every thumbnail that belongs to it, and they all move into the library,
+ * reporting progress chunk by chunk.
+ */
+export function BulkRateModal({
+  uploads,
+  onClose,
+}: {
+  uploads: TempUpload[];
+  onClose: () => void;
+}) {
+  const queryClient = useQueryClient();
+  const [rating, setRating] = useState<string | null>(null);
+  const [selected, setSelected] = useState<Set<string>>(new Set());
+  const [phase, setPhase] = useState<Phase>("select");
+  const [progress, setProgress] = useState({ done: 0, total: 0, moved: 0 });
+  const [failures, setFailures] = useState<Failure[]>([]);
+
+  const names = new Map(uploads.map((temp) => [temp.temp_id, temp.original_filename]));
+  const busy = phase === "running";
+  const percent =
+    progress.total > 0
+      ? Math.min(100, Math.round((progress.done / progress.total) * 100))
+      : 0;
+  const retryable = failures.filter((failure) => names.has(failure.id));
+
+  async function run() {
+    if (!rating || selected.size === 0 || busy) return;
+    const ids = [...selected];
+
+    setPhase("running");
+    setFailures([]);
+    setProgress({ done: 0, total: ids.length, moved: 0 });
+
+    let moved = 0;
+    const problems: Failure[] = [];
+    for (let index = 0; index < ids.length; index += CHUNK_SIZE) {
+      const chunk = ids.slice(index, index + CHUNK_SIZE);
+      try {
+        const result = await api<BulkResult>("/api/uploads/resolve-bulk/", {
+          method: "POST",
+          json: { temp_ids: chunk, rating },
+        });
+        moved += result.resolved.length;
+        for (const problem of result.errors) {
+          problems.push({
+            id: problem.temp_id,
+            name: names.get(problem.temp_id) ?? problem.temp_id,
+            error: problem.error,
+          });
+        }
+      } catch (error) {
+        for (const id of chunk) {
+          problems.push({
+            id,
+            name: names.get(id) ?? id,
+            error: errorMessage(error),
+          });
+        }
+      }
+      setProgress({
+        done: Math.min(index + CHUNK_SIZE, ids.length),
+        total: ids.length,
+        moved,
+      });
+    }
+
+    void queryClient.invalidateQueries({ queryKey: ["uploads"] });
+    void queryClient.invalidateQueries({ queryKey: ["files"] });
+    setFailures(problems);
+    setPhase("done");
+
+    if (problems.length === 0) {
+      toast.ok(`Moved ${moved} upload(s) into the library.`);
+      onClose();
+    } else if (moved > 0) {
+      toast.error(`Moved ${moved}, ${problems.length} failed.`);
+    } else {
+      toast.error(`Nothing could be moved (${problems.length} failed).`);
+    }
+  }
+
+  function toggle(id: string) {
+    setSelected((current) => {
+      const next = new Set(current);
+      if (next.has(id)) next.delete(id);
+      else next.add(id);
+      return next;
+    });
+  }
+
+  function requestClose() {
+    if (!busy) onClose();
+  }
+
+  function retryFailed() {
+    setSelected(new Set(retryable.map((failure) => failure.id)));
+    setFailures([]);
+    setPhase("select");
+  }
+
+  return (
+    <div
+      className="fixed inset-0 z-[70] flex items-start justify-center overflow-y-auto bg-ctp-crust/70 px-4 py-8 backdrop-blur-sm"
+      onClick={requestClose}
+    >
+      <div
+        className="flex w-full max-w-6xl flex-col overflow-hidden rounded-lg border border-ctp-surface1 bg-ctp-base"
+        onClick={(event) => event.stopPropagation()}
+      >
+        <header className="flex items-start justify-between gap-3 border-b border-ctp-surface0 px-4 py-3">
+          <div>
+            <h2 className="text-sm font-semibold text-ctp-text">
+              Rate unmatched uploads
+            </h2>
+            <p className="mt-0.5 text-xs text-ctp-overlay0">
+              {busy
+                ? "Moving files into the library — this can take a moment, keep this open."
+                : "Pick a rating, tick every file that belongs to it, and they move into the library in one go (" +
+                  uploads.length +
+                  " pending)."}
+            </p>
+          </div>
+          <button
+            type="button"
+            onClick={requestClose}
+            disabled={busy}
+            title={busy ? "Wait for the move to finish" : "Close"}
+            className="rounded-md p-1 text-ctp-overlay0 transition hover:bg-ctp-surface0 hover:text-ctp-text disabled:pointer-events-none disabled:opacity-40"
+          >
+            <X className="h-4 w-4" />
+          </button>
+        </header>
+
+        <div className="flex flex-wrap items-center gap-2 border-b border-ctp-surface0 px-4 py-2.5">
+          {RATING_OPTIONS.map((option) => (
+            <button
+              key={option.value}
+              type="button"
+              disabled={busy}
+              onClick={() => setRating(option.value)}
+              className={cn(
+                "rounded-full border px-3 py-1 text-xs font-medium transition disabled:pointer-events-none disabled:opacity-40",
+                rating === option.value
+                  ? option.active
+                  : "border-ctp-surface1 text-ctp-subtext0 hover:border-ctp-surface2 hover:text-ctp-text",
+              )}
+            >
+              {option.label}
+            </button>
+          ))}
+          <span className="ml-auto flex items-center gap-2">
+            <Button
+              variant="secondary"
+              className="px-2 py-1 text-xs"
+              disabled={busy}
+              onClick={() =>
+                setSelected(new Set(uploads.map((temp) => temp.temp_id)))
+              }
+            >
+              Select all
+            </Button>
+            <Button
+              variant="ghost"
+              className="px-2 py-1 text-xs"
+              disabled={busy || selected.size === 0}
+              onClick={() => setSelected(new Set())}
+            >
+              Clear
+            </Button>
+          </span>
+        </div>
+
+        <div className="max-h-[60vh] overflow-y-auto overscroll-contain p-4">
+          {uploads.length === 0 ? (
+            <p className="py-8 text-center text-sm text-ctp-overlay0">
+              Nothing pending.
+            </p>
+          ) : (
+            <div
+              className={cn(
+                "grid grid-cols-[repeat(auto-fill,minmax(130px,1fr))] content-start gap-2 transition",
+                busy && "pointer-events-none opacity-60",
+              )}
+            >
+              {uploads.map((temp) => {
+                const isSelected = selected.has(temp.temp_id);
+                const preview = apiUrl(
+                  temp.preview_url ?? temp.file_url ?? "",
+                );
+                return (
+                  <button
+                    key={temp.temp_id}
+                    type="button"
+                    disabled={phase !== "select"}
+                    onClick={() => toggle(temp.temp_id)}
+                    title={temp.original_filename}
+                    className={cn(
+                      "relative overflow-hidden rounded-md border bg-ctp-mantle text-left transition disabled:cursor-default",
+                      isSelected
+                        ? "border-ctp-mauve ring-2 ring-ctp-mauve/40"
+                        : "border-ctp-surface0 hover:border-ctp-surface2",
+                    )}
+                  >
+                    <span className="block aspect-square overflow-hidden">
+                      {preview ? (
+                        <img
+                          src={preview}
+                          alt={temp.original_filename}
+                          loading="lazy"
+                          className="h-full w-full object-cover"
+                        />
+                      ) : (
+                        <span className="flex h-full w-full items-center justify-center">
+                          <Video className="h-5 w-5 text-ctp-overlay0" />
+                        </span>
+                      )}
+                    </span>
+                    {isSelected ? (
+                      <span className="absolute left-1 top-1 flex h-4 w-4 items-center justify-center rounded-full bg-ctp-mauve text-ctp-crust">
+                        <Check className="h-3 w-3" strokeWidth={3} />
+                      </span>
+                    ) : null}
+                    <span className="block truncate px-1 py-0.5 font-mono text-[10px] text-ctp-overlay0">
+                      {temp.original_filename}
+                    </span>
+                  </button>
+                );
+              })}
+            </div>
+          )}
+        </div>
+
+        <footer className="flex flex-wrap items-center justify-between gap-3 border-t border-ctp-surface0 px-4 py-3">
+          {busy ? (
+            <div className="flex w-full flex-col gap-1.5">
+              <div className="flex items-center justify-between gap-3 font-mono text-[11px] text-ctp-overlay0">
+                <span className="flex items-center gap-1.5">
+                  <Spinner className="h-3 w-3" />
+                  Moving {progress.total} upload(s) into the library…
+                </span>
+                <span>
+                  {progress.moved} moved · {progress.done}/{progress.total} ·{" "}
+                  {percent}%
+                </span>
+              </div>
+              <div className="h-1.5 overflow-hidden rounded-full bg-ctp-surface0">
+                <div
+                  className="h-full bg-ctp-mauve transition-[width] duration-200"
+                  style={{ width: `${percent}%` }}
+                />
+              </div>
+            </div>
+          ) : phase === "done" ? (
+            <div className="flex w-full flex-col gap-2">
+              <div className="max-h-32 overflow-y-auto overscroll-contain rounded-md border border-ctp-surface0 bg-ctp-mantle">
+                {failures.map((failure) => (
+                  <div
+                    key={failure.id}
+                    className="flex items-start justify-between gap-3 border-b border-ctp-surface0/60 px-2 py-1 text-[11px] last:border-0"
+                  >
+                    <span
+                      className="truncate font-mono text-ctp-subtext1"
+                      title={failure.name}
+                    >
+                      {failure.name}
+                    </span>
+                    <span className="shrink-0 text-ctp-red">
+                      {failure.error}
+                    </span>
+                  </div>
+                ))}
+              </div>
+              <div className="flex flex-wrap items-center justify-between gap-3">
+                <span className="font-mono text-[11px] text-ctp-overlay0">
+                  {progress.moved} moved · {failures.length} failed
+                </span>
+                <span className="flex items-center gap-2">
+                  <Button variant="ghost" onClick={onClose}>
+                    Close
+                  </Button>
+                  <Button
+                    variant="secondary"
+                    disabled={retryable.length === 0}
+                    onClick={retryFailed}
+                  >
+                    Retry failed ({retryable.length})
+                  </Button>
+                </span>
+              </div>
+            </div>
+          ) : (
+            <>
+              <span className="font-mono text-[11px] text-ctp-overlay0">
+                {selected.size} selected
+                {rating ? "" : " · pick a rating"}
+              </span>
+              <div className="flex items-center gap-2">
+                <Button variant="ghost" onClick={onClose}>
+                  Cancel
+                </Button>
+                <Button
+                  disabled={selected.size === 0 || !rating}
+                  onClick={() => void run()}
+                >
+                  Move {selected.size} into the library
+                </Button>
+              </div>
+            </>
+          )}
+        </footer>
+      </div>
+    </div>
+  );
+}

frontend/src/globals.d.ts

@@ -0,0 +1,18 @@
+/** Baked at build time by Vite (see vite.config.ts). */
+declare const __GIT_HASH__: string;
+
+/**
+ * Injected by the Electron shell (desktop/src/preload.ts) when it hosts the
+ * SPA. Absent in browsers.
+ */
+interface J621DesktopBridge {
+  readonly isDesktop: true;
+  readonly platform: string;
+  /** The shell's origin (e.g. `app://j621`), for backend CORS hints. */
+  readonly origin: string;
+  getVersion(): Promise<string>;
+}
+
+interface Window {
+  j621Desktop?: J621DesktopBridge;
+}

frontend/src/lib/api.ts

@@ -5,8 +5,20 @@ const TOKEN_KEY = "j621.token";
 
 /** Absolutise a backend path; external/absolute URLs pass through. */
 export function apiUrl(path: string): string {
-  if (!path.startsWith("/")) return path;
-  return `${getBackendUrl()}${path}`;
+  if (path.startsWith("/")) return `${getBackendUrl()}${path}`;
+  // Absolute URL built by the API. In same-origin mode (the dev proxy, the
+  // single deploy nginx) keep it on the page's origin: the proxy serves
+  // /api too, and auth'd fetches like the IQDB staging blob would otherwise
+  // need CORS. With an explicit backend URL, leave it pointing there.
+  if (!getBackendUrl()) {
+    try {
+      const url = new URL(path);
+      return `${url.pathname}${url.search}`;
+    } catch {
+      return path;
+    }
+  }
+  return path;
 }
 
 export function getToken(): string | null {

frontend/src/lib/e621.ts

@@ -82,13 +82,59 @@ export function effectiveCredentials(
   return credentials ?? ANONYMOUS_CREDENTIALS;
 }
 
-const CLIENT_VERSION = "J621/0.1";
+// e621 asks for "Application name/version (developer)". Browsers cannot set a
+// User-Agent, so the same string is sent in the `_client` parameter instead.
+// `__GIT_HASH__` is replaced by Vite at build time; guard it so the dev
+// server (which may not substitute it) still works.
+const GIT_HASH = typeof __GIT_HASH__ === "string" ? __GIT_HASH__ : "dev";
+const CLIENT_VERSION = `J621/${GIT_HASH} (JakeBreath)`;
 
 // e621 allows 2 requests/second hard, 1/second sustained. Serialize every
-// request through a queue with a 1s minimum gap.
+// request through a queue with a minimum gap; IQDB is throttled much harder
+// by e621, so it gets a wider gap of its own.
 let lastRequestAt = 0;
 let queue: Promise<unknown> = Promise.resolve();
 
+/** A hung request would block the whole serialized queue forever. */
+const REQUEST_TIMEOUT_MS = 20_000;
+const REQUEST_GAP_MS = 1000;
+const IQDB_GAP_MS = 2500;
+
+/** A 429 (or a CORS-blocked failure) pauses every e621 call briefly. */
+const RATE_LIMIT_COOLDOWN_MS = 15_000;
+const COOLDOWN_KEY = "j621.e621.cooldown";
+let cooldownUntil = 0;
+
+function storedCooldown(): number {
+  try {
+    return Number(window.localStorage.getItem(COOLDOWN_KEY)) || 0;
+  } catch {
+    return 0;
+  }
+}
+
+export function e621CooldownRemainingMs(): number {
+  return Math.max(0, Math.max(cooldownUntil, storedCooldown()) - Date.now());
+}
+
+function startCooldown(): void {
+  cooldownUntil = Date.now() + RATE_LIMIT_COOLDOWN_MS;
+  try {
+    window.localStorage.setItem(COOLDOWN_KEY, String(cooldownUntil));
+  } catch {
+    // Storage disabled; the in-memory cooldown still applies.
+  }
+}
+
+function isRateLimitError(error: unknown): boolean {
+  if (error instanceof E621Error) {
+    return error.status === 429 || error.status === 503;
+  }
+  // Browsers hide the status of a CORS-blocked response; a rate-limited 429
+  // arrives here as a network error.
+  return error instanceof TypeError || error instanceof DOMException;
+}
+
 function schedule<T>(task: () => Promise<T>): Promise<T> {
   const run = queue.then(task, task);
   queue = run.then(
@@ -98,8 +144,12 @@ function schedule<T>(task: () => Promise<T>): Promise<T> {
   return run;
 }
 
-async function throttle(): Promise<void> {
-  const wait = Math.max(0, lastRequestAt + 1000 - Date.now());
+async function throttle(minGap = REQUEST_GAP_MS): Promise<void> {
+  const wait = Math.max(
+    0,
+    lastRequestAt + minGap - Date.now(),
+    e621CooldownRemainingMs(),
+  );
   if (wait > 0) {
     await new Promise((resolve) => setTimeout(resolve, wait));
   }
@@ -119,15 +169,14 @@ export function e621Request<T>(
   options: E621RequestOptions = {},
 ): Promise<T> {
   return schedule(async () => {
-    await throttle();
+    await throttle(
+      path.includes("iqdb_queries") ? IQDB_GAP_MS : REQUEST_GAP_MS,
+    );
 
     const base = credentials.base_url.replace(/\/+$/, "");
     const url = new URL(`${base}/${path.replace(/^\/+/, "")}`);
     // Browsers cannot set User-Agent; e621 documents `_client` for this case.
-    url.searchParams.set(
-      "_client",
-      `${CLIENT_VERSION} (by ${credentials.username || "anonymous"} on e621)`,
-    );
+    url.searchParams.set("_client", CLIENT_VERSION);
     for (const [key, value] of Object.entries(options.params ?? {})) {
       if (value !== undefined) {
         url.searchParams.set(key, String(value));
@@ -143,12 +192,20 @@ export function e621Request<T>(
     }
 
     const startedAt = performance.now();
+    const controller = new AbortController();
+    const timer = setTimeout(
+      () =>
+        controller.abort(new DOMException("e621 request timed out", "TimeoutError")),
+      REQUEST_TIMEOUT_MS,
+    );
+    const forwardAbort = () => controller.abort(options.signal?.reason);
+    options.signal?.addEventListener("abort", forwardAbort, { once: true });
     try {
       const response = await fetch(url, {
         method: options.method ?? "GET",
         headers,
         body: options.body,
-        signal: options.signal,
+        signal: controller.signal,
       });
 
       if (!response.ok) {
@@ -164,7 +221,15 @@ export function e621Request<T>(
         return undefined as T;
       }
       return (await response.json()) as T;
+    } catch (error) {
+      // Cancelled requests (navigation, unmounted query) are not rate limits.
+      if (!options.signal?.aborted && isRateLimitError(error)) {
+        startCooldown();
+      }
+      throw error;
     } finally {
+      clearTimeout(timer);
+      options.signal?.removeEventListener("abort", forwardAbort);
       useE621Metrics
         .getState()
         .record(path, performance.now() - startedAt);
@@ -190,8 +255,11 @@ export function e621ErrorMessage(error: unknown): string {
     }
     return `e621 request failed (${error.status}).`;
   }
+  if (error instanceof DOMException && error.name === "TimeoutError") {
+    return "e621 did not answer in time.";
+  }
   if (error instanceof TypeError) {
-    return "Could not reach e621. Check the base URL and your connection.";
+    return "Could not reach e621. If this keeps happening it is usually the rate limit — wait a minute and retry.";
   }
   return error instanceof Error
     ? error.message
@@ -255,7 +323,7 @@ export async function fetchPostsByIds(
     credentials,
     "/posts.json",
     {
-      params: { tags: `id:${ids.join(",")}`, limit: Math.min(ids.length, 100) },
+      params: { tags: `id:${ids.join(",")}`, limit: Math.min(ids.length, 320) },
       signal,
     },
   );
@@ -308,7 +376,7 @@ export async function fetchPostsByMd5(
     {
       params: {
         tags: `md5:${md5s.join(",")}`,
-        limit: Math.min(md5s.length, 100),
+        limit: Math.min(md5s.length, 320),
       },
       signal,
     },

frontend/src/lib/preferences.ts

@@ -12,6 +12,9 @@ export function applyPreferences(
   if (typeof preferences.ordering === "string") ui.setOrdering(preferences.ordering);
   if (typeof preferences.per_page === "number") ui.setPerPage(preferences.per_page);
   if (typeof preferences.zoom === "number") ui.setZoom(preferences.zoom);
+  if (typeof preferences.e621_per_page === "number") {
+    ui.setE621PerPage(preferences.e621_per_page);
+  }
 }
 
 /** The browse settings currently in effect, as a preferences payload. */
@@ -22,6 +25,7 @@ export function preferencesPayload(extra?: UserPreferences): UserPreferences {
     ordering: ui.ordering,
     per_page: ui.perPage,
     zoom: ui.zoom,
+    e621_per_page: ui.e621PerPage,
     ...extra,
   };
 }

frontend/src/lib/types.ts

@@ -33,6 +33,8 @@ export interface UserPreferences {
   per_page?: number;
   zoom?: number;
   online_hot_default?: boolean;
+  /** Posts per e621 request for the Online browser and pool loading (max 320). */
+  e621_per_page?: number;
 }
 
 export interface User {
@@ -353,12 +355,17 @@ export interface TempUpload {
   status: "pending" | "visual_match" | "completed" | "error";
   resolution: "" | "auto_md5" | "duplicate" | "linked" | "custom";
   e621_post_id: number | null;
-  e621_data: E621StoredPost | null;
+  /** Full post payload: only present on the detail endpoint. */
+  e621_data?: E621StoredPost | null;
   custom_rating: Rating;
-  custom_tags: string[];
-  custom_notes: string;
-  iqdb_data: E621IqdbCandidate[] | null;
-  visual_matches:
+  /** Only present on the detail endpoint. */
+  custom_tags?: string[];
+  /** Only present on the detail endpoint. */
+  custom_notes?: string;
+  /** Only present on the detail endpoint. */
+  iqdb_data?: E621IqdbCandidate[] | null;
+  /** Only present on the detail endpoint. */
+  visual_matches?:
     | {
         j_id: string;
         filename: string;
@@ -369,10 +376,57 @@ export interface TempUpload {
   library_j_id: string | null;
   file_url: string | null;
   preview_url: string | null;
+  /** Background pipeline state (see the UploadRun status endpoint). */
+  pipeline_error: string;
+  attempts: number;
+  md5_checked?: boolean;
+  visual_checked?: boolean;
+  iqdb_checked?: boolean;
+  processing?: boolean;
+  similar_count?: number;
   created_at: string;
   updated_at: string;
 }
 
+/** One upload the pipeline indexed while the page was watching. */
+export interface UploadCompletion {
+  id: string;
+  filename: string;
+  j_id: string;
+  resolution: string;
+  post_id: number | null;
+  thumbnail_url: string | null;
+  at: string;
+}
+
+/** Response of POST /api/uploads/ — a pending row or an instant completion. */
+export interface UploadStagingResult {
+  temp_id: string;
+  original_filename: string;
+  status: "pending" | "visual_match" | "completed" | "error";
+  resolution: string;
+  library_j_id: string | null;
+  preview_url: string | null;
+  e621_post_id?: number | null;
+}
+
+/** Progress of the server-side staged-upload pipeline. */
+export interface UploadStatus {
+  status: "idle" | "running" | "paused" | "error";
+  active: boolean;
+  phase: "" | "md5" | "visual" | "iqdb";
+  total: number;
+  processed: number;
+  matched: number;
+  failed: number;
+  error: string;
+  outstanding: number;
+  waiting: { md5: number; visual: number; iqdb: number };
+  /** Session notification feed: indexed uploads, newest first. */
+  recent_completions: UploadCompletion[];
+  updated_at: string | null;
+}
+
 export interface StatJob {
   kind: "download" | "match";
   id: string;

frontend/src/lib/uploadStatus.ts

@@ -0,0 +1,30 @@
+import { useQuery } from "@tanstack/react-query";
+
+import { api } from "@/lib/api";
+import { hasBackend } from "@/lib/backend";
+import type { UploadStatus } from "@/lib/types";
+import { useAuth } from "@/store/auth";
+
+export const uploadStatusQueryKey = ["upload-status"] as const;
+
+/**
+ * Poll the server-side upload pipeline while it has work and stop once it is
+ * idle. Shared by the Upload page and the shell indicator so both show the
+ * same state without extra requests.
+ */
+export function useUploadStatus(enabled = true) {
+  const user = useAuth((state) => state.user);
+  return useQuery({
+    queryKey: uploadStatusQueryKey,
+    queryFn: () => api<UploadStatus>("/api/uploads/status/"),
+    enabled: enabled && hasBackend() && Boolean(user?.can_upload),
+    // TanStack takes the smallest interval across the observers, so the
+    // Upload page and the shell pill can safely share this query.
+    refetchInterval: (query) => (query.state.data?.active ? 2_000 : false),
+  });
+}
+
+/** Ask the server to (re)start processing the caller's staged uploads. */
+export function postProcessUploads(): Promise<UploadStatus> {
+  return api<UploadStatus>("/api/uploads/process/", { method: "POST" });
+}

frontend/src/store/ui.ts

@@ -16,6 +16,9 @@ interface UiState {
   /** Minimum thumbnail width in px; media grids derive their column count. */
   zoom: number;
   setZoom: (zoom: number) => void;
+  /** Posts per e621 request for the Online browser and pool loading (max 320). */
+  e621PerPage: number;
+  setE621PerPage: (value: number) => void;
 }
 
 export const useUi = create<UiState>()(
@@ -39,6 +42,9 @@ export const useUi = create<UiState>()(
 
       zoom: 190,
       setZoom: (zoom) => set({ zoom }),
+
+      e621PerPage: 48,
+      setE621PerPage: (e621PerPage) => set({ e621PerPage }),
     }),
     { name: "j621.ui" },
   ),