ci: debounce dev image builds instead of building nightly (#1376 )

Replace the nightly cron and its check-changes job with a debounce. Every push to main starts dev-image-debounce.yml, which waits out the 60-minute wait timer on the dev-image-debounce environment, then dispatches the Docker workflow only if main still points at its commit. A burst of merges now publishes one dev image, an hour after the last merge. The Docker workflow keeps only its tag and workflow_dispatch triggers, so its history holds real builds only. The debounce workflow deletes its own finished runs, so no-op runs don't pile up either. Requires the dev-image-debounce environment with a 60-minute wait timer (Settings → Environments).
build(deps): bump the python-deps group with 4 updates (#1375 )
2026-09-24 18:50:19 +01:00 · 2026-09-21 02:38:06 -04:00 · 2026-09-21 00:44:08 -04:00 · 2026-09-21 00:15:41 -04:00 · 2026-09-21 00:10:10 -04:00 · 2026-09-21 00:00:42 -04:00
163 changed files with 10396 additions and 1853 deletions
@@ -3,10 +3,8 @@ on:
  push:
    tags:
      - 'v*'
-  schedule:
+  # Also dispatched on main by dev-image-debounce.yml, once main has been
-    # Nightly at 03:17 UTC — only builds if there are new commits on main
+  # quiet for an hour, to publish the dev image.
    # since the last successful run (see check-changes job).
    - cron: '17 3 * * *'
  workflow_dispatch:
 permissions: read-all
@@ -14,41 +12,7 @@ env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository_owner }}/shelfmark
 jobs:
  check-changes:
    runs-on: ubuntu-latest
    outputs:
      should_build: ${{ steps.check.outputs.should_build }}
    steps:
      - name: Check for new commits since last successful build
        id: check
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          EVENT_NAME: ${{ github.event_name }}
          CURRENT_SHA: ${{ github.sha }}
          REPO: ${{ github.repository }}
        run: |
          # Always build on tag pushes and manual dispatch.
          if [[ "$EVENT_NAME" != "schedule" ]]; then
            echo "Event is $EVENT_NAME — building unconditionally."
            echo "should_build=true" >> "$GITHUB_OUTPUT"
            exit 0
          fi
          # Scheduled run: only build if HEAD differs from the last successful build on main.
          LAST_SHA=$(gh api "/repos/${REPO}/actions/workflows/build-and-publish-docker-image.yml/runs?branch=main&status=success&per_page=1" --jq '.workflow_runs[0].head_sha' 2>/dev/null || true)
          echo "Last successful build SHA: ${LAST_SHA:-<none>}"
          echo "Current HEAD SHA:          ${CURRENT_SHA}"
          if [[ -z "$LAST_SHA" || "$LAST_SHA" != "$CURRENT_SHA" ]]; then
            echo "New commits detected — building."
            echo "should_build=true" >> "$GITHUB_OUTPUT"
          else
            echo "No new commits since last successful build — skipping."
            echo "should_build=false" >> "$GITHUB_OUTPUT"
          fi
  build-and-push-images:
    needs: check-changes
    if: needs.check-changes.outputs.should_build == 'true'
    runs-on: ubuntu-latest
    permissions:
      contents: read
@@ -96,11 +60,11 @@ jobs:
            type=ref,event=tag
      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@37fe631027851001ddb9b187196cc803df7f5f0e # v4.3.0
+        uses: docker/setup-buildx-action@594f3bf4285d9ea8dc53c9a0c9c4092420091003 # v4.4.0
      - name: Build and push ${{ matrix.target }} Docker image
        id: push
-        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
+        uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7.4.0
        with:
          platforms: linux/amd64,linux/arm64
          context: .
@@ -141,7 +105,7 @@ jobs:
          password: ${{ secrets.GITHUB_TOKEN }}
      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@37fe631027851001ddb9b187196cc803df7f5f0e # v4.3.0
+        uses: docker/setup-buildx-action@594f3bf4285d9ea8dc53c9a0c9c4092420091003 # v4.4.0
      - name: Create legacy aliases
        run: |
@@ -16,7 +16,7 @@ jobs:
        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
      - name: Install uv and Python
-        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
        with:
          version: "0.11.3"
          python-version: "3.14"
@@ -42,7 +42,7 @@ jobs:
        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
      - name: Install uv and Python
-        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
        with:
          version: "0.11.3"
          python-version: "3.14"
@@ -62,7 +62,7 @@ jobs:
        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
      - name: Install uv and Python
-        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
        with:
          version: "0.11.3"
          python-version: "3.14"
@@ -81,10 +81,10 @@ jobs:
        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@37fe631027851001ddb9b187196cc803df7f5f0e # v4.3.0
+        uses: docker/setup-buildx-action@594f3bf4285d9ea8dc53c9a0c9c4092420091003 # v4.4.0
      - name: Build shelfmark-lite image
-        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
+        uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7.4.0
        with:
          context: .
          target: shelfmark-lite
@@ -25,14 +25,14 @@ jobs:
        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
      - name: Initialize CodeQL
-        uses: github/codeql-action/init@db488ddef3bf6cb639b32c2e9a7c0a7ea8271d28 # v3
+        uses: github/codeql-action/init@b96794f015dfd88f77b49b1c93e0fa7110f94c63 # v3
        with:
          languages: ${{ matrix.language }}
      - name: Autobuild
-        uses: github/codeql-action/autobuild@db488ddef3bf6cb639b32c2e9a7c0a7ea8271d28 # v3
+        uses: github/codeql-action/autobuild@b96794f015dfd88f77b49b1c93e0fa7110f94c63 # v3
      - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@db488ddef3bf6cb639b32c2e9a7c0a7ea8271d28 # v3
+        uses: github/codeql-action/analyze@b96794f015dfd88f77b49b1c93e0fa7110f94c63 # v3
        with:
          category: "/language:${{ matrix.language }}"
@@ -0,0 +1,51 @@
 name: Debounce dev image
 # A burst of merges to main should publish one dev image, not one per commit.
 # Each push to main waits out the 60-minute wait timer on the
 # dev-image-debounce environment (Settings → Environments; waiting holds no
 # runner), then dispatches the Docker workflow only if main still points at
 # its commit. So only the last push of a burst builds, and the Docker
 # workflow's history holds real builds only.
 on:
  push:
    branches:
      - main
 permissions: {}
 jobs:
  debounce:
    runs-on: ubuntu-latest
    environment:
      name: dev-image-debounce
      deployment: false
    permissions:
      actions: write # dispatch the build, delete finished debounce runs
      contents: read
    env:
      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      GH_REPO: ${{ github.repository }}
    steps:
      - name: Dispatch the dev build if main is still at this commit
        env:
          CURRENT_SHA: ${{ github.sha }}
        run: |
          HEAD_SHA=$(gh api "repos/${GH_REPO}/git/ref/heads/main" --jq '.object.sha')
          echo "This run's commit: ${CURRENT_SHA}"
          echo "main HEAD now:     ${HEAD_SHA}"
          if [[ "$HEAD_SHA" == "$CURRENT_SHA" ]]; then
            echo "No newer commits on main — dispatching the dev build."
            gh workflow run build-and-publish-docker-image.yml --ref main
          else
            echo "main has moved on — the newer push's run will build it."
          fi
      # A finished debounce run is noise: it either did nothing or its build
      # run is the record. Best effort, since runs from the same burst race to
      # delete the same runs.
      - name: Delete finished debounce runs
        run: |
          # On an HTTP error gh prints the error body to stdout, so bail out
          # rather than loop over it.
          ids=$(gh api "repos/${GH_REPO}/actions/workflows/dev-image-debounce.yml/runs?status=success&per_page=100" --jq '.workflow_runs[].id') || exit 0
          for id in $ids; do
            gh api -X DELETE "repos/${GH_REPO}/actions/runs/${id}" || true
          done
@@ -72,7 +72,7 @@ jobs:
      - name: Checkout
        uses: actions/checkout@v7
      - name: Install uv and Python
-        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
        with:
          python-version: "3.14"
          enable-cache: true
@@ -97,7 +97,7 @@ jobs:
      - name: Checkout
        uses: actions/checkout@v7
      - name: Install uv and Python
-        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
        with:
          python-version: "3.14"
          enable-cache: true
@@ -4,7 +4,7 @@ ARG BUILDPLATFORM
 ARG BUILDARCH
 # Frontend build stage.
-FROM --platform=$BUILDPLATFORM node:24-alpine@sha256:d32cdf619f63fe0471182d08996dd516c6275bb5fd31ae06e55a570bd9e1ad43 AS frontend-builder
+FROM --platform=$BUILDPLATFORM node:24-alpine@sha256:ebfe2f90462722a7a4de65e91990e97fe0d401c70e0e762c5b53302f905ec1c1 AS frontend-builder
 # Helpful debug output to see what platforms BuildKit thinks it's using
 RUN echo "BUILDPLATFORM=$BUILDPLATFORM BUILDARCH=$BUILDARCH TARGETPLATFORM=$TARGETPLATFORM TARGETARCH=$TARGETARCH"
@@ -28,10 +28,10 @@ RUN npm run build
 # than copied into the image. A COPY here would land ~24 MB in a `base` layer that
 # every published image inherits, and a later `rm` cannot take it back out again --
 # a RUN adds a layer, it does not rewrite the one underneath.
-FROM ghcr.io/astral-sh/uv:0.12.5@sha256:e85be844203885286c60ffad8a858d48afb6c5a5c237ca0e67f12e74b8f174b1 AS uv
+FROM ghcr.io/astral-sh/uv:0.12.16@sha256:adc68cd785ca65ea25c0611043b0a00b4ea3a22e1b54102fc084406d888082ee AS uv
 # Use python-slim as the base image
-FROM python:3.14.7-slim@sha256:cae66f2ef0ec51a9891263eeee7f987dacf0a9879e8aa9353d5606e0530619a5 AS base
+FROM python:3.14.7-slim@sha256:cad9a2c871761c413caa6fdd6441c783451e740a48aaeba60ae62a8b53525ef6 AS base
 # Add build argument for version
 ARG BUILD_VERSION
@@ -0,0 +1,72 @@
 # API access with an API key
 Shelfmark's web interface is driven entirely by a JSON API under `/api/`. Set
 the `SHELFMARK_API_KEY` environment variable and scripts, dashboards and assistants can
 call the same API without a browser session. Browser logins keep working
 exactly as before: it is cookie **or** key.
 ## Set the key
 ```yaml
 environment:
  SHELFMARK_API_KEY: "a-long-random-secret"
 ```
 Generate something long and random (for example `openssl rand -base64 32`).
 A request carrying the key acts as an **admin**: the first admin user in
 Shelfmark's user database. Create an admin before relying on the key in any
 install that has none yet (for example an OIDC-only install). Without an
 admin user, the key still authenticates as an admin identity with no user
 row, and routes that need one (requests, activity) answer 403. To rotate,
 change the variable and restart. Unset it and the feature is off. When the
 instance runs with no authentication configured (`AUTH_METHOD=none`), the
 key is simply unnecessary.
 ## Send the key
 Either header works, and both are checked, so the key can be sent in
 `X-Api-Key` behind a reverse proxy that sets its own `Authorization` header.
 ```bash
 curl -s -H "Authorization: Bearer $SHELFMARK_API_KEY" https://shelfmark.example.com/api/downloads/active
 curl -s -H "X-Api-Key: $SHELFMARK_API_KEY" https://shelfmark.example.com/api/downloads/active
 ```
 A request that carries the key is authenticated by the key alone. Session
 cookies are ignored and none are set. A bearer value that is not the configured
 key is ignored and the request continues with normal session authentication,
 so reverse proxies that forward their own tokens are unaffected; without a valid
 session such a request gets the usual `401 {"error": "Unauthorized"}`. A
 database error while resolving the admin returns
 `500 {"error": "Authentication error"}` — never anonymous access.
 `/api/auth/check` reflects the browser session only and ignores the key, so
 use `/api/status` to verify a key.
 ## Examples
 Search, then look up releases, then queue one (the same calls the web UI makes):
 ```bash
 curl -s -H "Authorization: Bearer $SHELFMARK_API_KEY" \
  "https://shelfmark.example.com/api/metadata/search?query=dune%20frank%20herbert"
 # -> {"books":[{"provider":"hardcover","provider_id":"427363", ...}]}
 curl -s -H "Authorization: Bearer $SHELFMARK_API_KEY" \
  "https://shelfmark.example.com/api/releases?provider=hardcover&book_id=427363&content_type=ebook"
 # -> {"releases":[{"source":"direct_download","source_id":"...", ...}], ...}
 curl -s -X POST -H "Authorization: Bearer $SHELFMARK_API_KEY" -H "Content-Type: application/json" \
  -d @release.json https://shelfmark.example.com/api/releases/download
 # release.json = one object from "releases" (source and source_id are required)
 curl -s -H "Authorization: Bearer $SHELFMARK_API_KEY" https://shelfmark.example.com/api/status
 ```
 ## Security notes
 - The key is compared in constant time and is never logged.
 - Keyed requests never set cookies and ignore any cookie sent with them.
 - WebSocket (live activity) connections do not accept the key; poll `/api/status` instead.
 - The key is a root-equivalent credential: an admin can configure a custom
  post-download script that the server executes, so treat it like a root
  password and send it only over HTTPS.
@@ -47,6 +47,7 @@ These environment variables are used at startup before the settings system loads
 | `CWA_DB_PATH` | Path to the Calibre-Web database for authentication integration. | string (path) | `/auth/app.db` |
 | `HIDE_LOCAL_AUTH` | Hide the username/password login form when OIDC is active. | boolean | `false` |
 | `DISABLE_LOCAL_AUTH` | Disable username/password login and remove the local-admin prerequisite for OIDC. Implies HIDE_LOCAL_AUTH; with AUTH_METHOD=builtin, everyone is locked out until auth env vars are changed. | boolean | `false` |
 | `SHELFMARK_API_KEY` | Optional static API key. When set, requests carrying it as 'Authorization: Bearer <key>' (or X-Api-Key) are authenticated as an admin; browser sessions keep working. Unset = off. | string | `unset` |
 | `OIDC_AUTO_REDIRECT` | Automatically redirect to the OIDC provider instead of showing the login page. | boolean | `false` |
 | `DOCKERMODE` | Indicates the application is running inside a Docker container. | boolean | `false` |
 | `ONBOARDING` | Show the onboarding wizard on first run. Set to false to skip (useful for ephemeral storage). | boolean | `true` |
@@ -124,6 +125,13 @@ Disable username/password login and remove the local-admin prerequisite for OIDC
 - **Type:** boolean
 - **Default:** `false`
 #### `SHELFMARK_API_KEY`
 Optional static API key. When set, requests carrying it as 'Authorization: Bearer <key>' (or X-Api-Key) are authenticated as an admin; browser sessions keep working. Unset = off.
 - **Type:** string
 - **Default:** `unset`
 #### `OIDC_AUTO_REDIRECT`
 Automatically redirect to the OIDC provider instead of showing the login page.
@@ -434,8 +442,9 @@ The release source tab to open by default in the release modal for audiobooks. U
 | `BOOKS_OUTPUT_MODE` | Choose where completed book files are sent. | string (choice) | `folder` |
 | `INGEST_DIR` | Directory where downloaded files are saved. Use {User} for per-user folders (e.g. /books/{User}). | string | `/books` |
 | `FILE_ORGANIZATION` | Choose how downloaded book files are named and organized. | string (choice) | `rename` |
-| `TEMPLATE_RENAME` | Variables: {Author}, {Title}, {Year}, {Language}, {User}, {OriginalName} (source filename without extension). Universal adds: {Series}, {SeriesPosition}, {Subtitle}, {PrimaryTitle}. Use arbitrary prefix/suffix: {Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty. Rename templates are filename-only (no '/' or '\'); use Organize for folders. Applies to single-file downloads. | string | `{Author} - {Title} ({Year})` |
+| `NAMING_WORD_SEPARATOR` | Replaces spaces inside naming template values (e.g. 'Conan Doyle' -> 'Conan.Doyle' with '.'). Applies to books and audiobooks, rename and organize templates alike. Literal characters typed into a template (like the '-' in '{Author} - {Title}') are left as-is. Leave empty to keep spaces as-is. | string | _empty string_ |
-| `TEMPLATE_ORGANIZE` | Use / to create folders. Variables: {Author}, {Title}, {Year}, {Language}, {User}, {OriginalName} (source filename without extension). Universal adds: {Series}, {SeriesPosition}, {Subtitle}, {PrimaryTitle}. Use arbitrary prefix/suffix: {Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty. | string | `{Author}/{Title} ({Year})` |
+| `TEMPLATE_RENAME` | Variables: {Author}, {FirstAuthor} (first of several authors), {Title}, {Year}, {Language}, {User}, {OriginalName} (source filename without extension). Universal adds: {Series}, {SeriesPosition}, {Subtitle}, {PrimaryTitle}. Use arbitrary prefix/suffix: {Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty. Rename templates are filename-only (no '/' or '\'); use Organize for folders. Applies to single-file downloads. | string | `{Author} - {Title} ({Year})` |
 | `TEMPLATE_ORGANIZE` | Use / to create folders. Variables: {Author}, {FirstAuthor} (first of several authors), {Title}, {Year}, {Language}, {User}, {OriginalName} (source filename without extension). Universal adds: {Series}, {SeriesPosition}, {Subtitle}, {PrimaryTitle}. Use arbitrary prefix/suffix: {Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty. | string | `{Author}/{Title} ({Year})` |
 | `HARDLINK_TORRENTS` | Create hardlinks instead of copying. Preserves seeding but archives won't be extracted. Don't use if destination is a library ingest folder. | boolean | `false` |
 | `BOOKLORE_HOST` | Base URL of your Grimmory instance | string | _none_ |
 | `BOOKLORE_USERNAME` | Grimmory account username | string | _none_ |
@@ -456,8 +465,8 @@ The release source tab to open by default in the release modal for audiobooks. U
 | `EMAIL_ALLOW_UNVERIFIED_TLS` | Disable TLS certificate verification (not recommended). | boolean | `false` |
 | `DESTINATION_AUDIOBOOK` | Directory where downloaded audiobook files are saved. Leave empty to use the Books destination. | string | _none_ |
 | `FILE_ORGANIZATION_AUDIOBOOK` | Choose how downloaded audiobook files are named and organized. | string (choice) | `rename` |
-| `TEMPLATE_AUDIOBOOK_RENAME` | Variables: {Author}, {Title}, {Year}, {Language}, {User}, {OriginalName} (source filename without extension), {Series}, {SeriesPosition}, {Subtitle}, {PrimaryTitle}, {PartNumber}. Use arbitrary prefix/suffix: {Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty. Rename templates are filename-only (no '/' or '\'); use Organize for folders. Applies to single-file downloads. | string | `{Author} - {Title}` |
+| `TEMPLATE_AUDIOBOOK_RENAME` | Variables: {Author}, {FirstAuthor} (first of several authors), {Title}, {Year}, {Language}, {User}, {OriginalName} (source filename without extension), {Series}, {SeriesPosition}, {Subtitle}, {PrimaryTitle}, {PartNumber}. Use arbitrary prefix/suffix: {Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty. Rename templates are filename-only (no '/' or '\'); use Organize for folders. Applies to single-file downloads. | string | `{Author} - {Title}` |
-| `TEMPLATE_AUDIOBOOK_ORGANIZE` | Use / to create folders. Variables: {Author}, {Title}, {Year}, {Language}, {User}, {OriginalName} (source filename without extension), {Series}, {SeriesPosition}, {Subtitle}, {PrimaryTitle}, {PartNumber}. Use arbitrary prefix/suffix: {Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty. | string | `{Author}/{Title}/{Title}` |
+| `TEMPLATE_AUDIOBOOK_ORGANIZE` | Use / to create folders. Variables: {Author}, {FirstAuthor} (first of several authors), {Title}, {Year}, {Language}, {User}, {OriginalName} (source filename without extension), {Series}, {SeriesPosition}, {Subtitle}, {PrimaryTitle}, {PartNumber}. Use arbitrary prefix/suffix: {Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty. | string | `{Author}/{Title}/{Title}` |
 | `HARDLINK_TORRENTS_AUDIOBOOK` | Create hardlinks instead of copying. Preserves seeding but archives won't be extracted. Don't use if destination is a library ingest folder. | boolean | `true` |
 | `AUTO_OPEN_DOWNLOADS_SIDEBAR` | Automatically open the downloads sidebar when a new download is queued. | boolean | `false` |
 | `DOWNLOAD_TO_BROWSER_CONTENT_TYPES` | Automatically download completed files to your browser for the selected content types. | string (comma-separated) | _empty list_ |
@@ -497,11 +506,20 @@ Choose how downloaded book files are named and organized.
 - **Default:** `rename`
 - **Options:** `none` (None), `rename` (Rename Only), `organize` (Rename and Organize)
 #### `NAMING_WORD_SEPARATOR`
 **Word Separator**
 Replaces spaces inside naming template values (e.g. 'Conan Doyle' -> 'Conan.Doyle' with '.'). Applies to books and audiobooks, rename and organize templates alike. Literal characters typed into a template (like the '-' in '{Author} - {Title}') are left as-is. Leave empty to keep spaces as-is.
 - **Type:** string
 - **Default:** _empty string_
 #### `TEMPLATE_RENAME`
 **Naming Template**
-Variables: {Author}, {Title}, {Year}, {Language}, {User}, {OriginalName} (source filename without extension). Universal adds: {Series}, {SeriesPosition}, {Subtitle}, {PrimaryTitle}. Use arbitrary prefix/suffix: {Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty. Rename templates are filename-only (no '/' or '\'); use Organize for folders. Applies to single-file downloads.
+Variables: {Author}, {FirstAuthor} (first of several authors), {Title}, {Year}, {Language}, {User}, {OriginalName} (source filename without extension). Universal adds: {Series}, {SeriesPosition}, {Subtitle}, {PrimaryTitle}. Use arbitrary prefix/suffix: {Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty. Rename templates are filename-only (no '/' or '\'); use Organize for folders. Applies to single-file downloads.
 - **Type:** string
 - **Default:** `{Author} - {Title} ({Year})`
@@ -510,7 +528,7 @@ Variables: {Author}, {Title}, {Year}, {Language}, {User}, {OriginalName} (source
 **Path Template**
-Use / to create folders. Variables: {Author}, {Title}, {Year}, {Language}, {User}, {OriginalName} (source filename without extension). Universal adds: {Series}, {SeriesPosition}, {Subtitle}, {PrimaryTitle}. Use arbitrary prefix/suffix: {Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty.
+Use / to create folders. Variables: {Author}, {FirstAuthor} (first of several authors), {Title}, {Year}, {Language}, {User}, {OriginalName} (source filename without extension). Universal adds: {Series}, {SeriesPosition}, {Subtitle}, {PrimaryTitle}. Use arbitrary prefix/suffix: {Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty.
 - **Type:** string
 - **Default:** `{Author}/{Title} ({Year})`
@@ -711,7 +729,7 @@ Choose how downloaded audiobook files are named and organized.
 **Naming Template**
-Variables: {Author}, {Title}, {Year}, {Language}, {User}, {OriginalName} (source filename without extension), {Series}, {SeriesPosition}, {Subtitle}, {PrimaryTitle}, {PartNumber}. Use arbitrary prefix/suffix: {Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty. Rename templates are filename-only (no '/' or '\'); use Organize for folders. Applies to single-file downloads.
+Variables: {Author}, {FirstAuthor} (first of several authors), {Title}, {Year}, {Language}, {User}, {OriginalName} (source filename without extension), {Series}, {SeriesPosition}, {Subtitle}, {PrimaryTitle}, {PartNumber}. Use arbitrary prefix/suffix: {Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty. Rename templates are filename-only (no '/' or '\'); use Organize for folders. Applies to single-file downloads.
 - **Type:** string
 - **Default:** `{Author} - {Title}`
@@ -720,7 +738,7 @@ Variables: {Author}, {Title}, {Year}, {Language}, {User}, {OriginalName} (source
 **Path Template**
-Use / to create folders. Variables: {Author}, {Title}, {Year}, {Language}, {User}, {OriginalName} (source filename without extension), {Series}, {SeriesPosition}, {Subtitle}, {PrimaryTitle}, {PartNumber}. Use arbitrary prefix/suffix: {Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty.
+Use / to create folders. Variables: {Author}, {FirstAuthor} (first of several authors), {Title}, {Year}, {Language}, {User}, {OriginalName} (source filename without extension), {Series}, {SeriesPosition}, {Subtitle}, {PrimaryTitle}, {PartNumber}. Use arbitrary prefix/suffix: {Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty.
 - **Type:** string
 - **Default:** `{Author}/{Title}/{Title}`
@@ -784,6 +802,7 @@ How long to keep completed/failed downloads in the queue display.
 | `PROXY_AUTH_USER_HEADER` | The HTTP header your proxy uses to pass the authenticated username. | string | `X-Auth-User` |
 | `PROXY_AUTH_LOGOUT_URL` | The URL to redirect users to for logging out. Leave empty to disable logout functionality. | string | _empty string_ |
 | `PROXY_AUTH_ADMIN_GROUP_HEADER` | Optional: header your proxy uses to pass user groups/roles. | string | `X-Auth-Groups` |
 | `PROXY_AUTH_DEFAULT_ROLE` | Role for users the proxy authenticates for the first time when no admin group is configured. The first account is always an admin so the instance is never left without one. | string (choice) | `user` |
 | `PROXY_AUTH_ADMIN_GROUP_NAME` | Optional: users in this group are treated as admins. Leave blank to skip group-based admin detection. | string | _empty string_ |
 | `OIDC_DISCOVERY_URL` | OpenID Connect discovery endpoint URL. Usually ends with /.well-known/openid-configuration. | string | _none_ |
 | `OIDC_CLIENT_ID` | OAuth2 client ID from your identity provider. | string | _none_ |
@@ -843,6 +862,16 @@ Optional: users in this group are treated as admins. Leave blank to skip group-b
 - **Type:** string
 - **Default:** _empty string_
 #### `PROXY_AUTH_DEFAULT_ROLE`
 **Proxy Auth Default Role**
 Role for users the proxy authenticates for the first time when no admin group is configured. The first account is always an admin so the instance is never left without one.
 - **Type:** string (choice)
 - **Default:** `user`
 - **Options:** `user` (User), `admin` (Admin)
 #### `OIDC_DISCOVERY_URL`
@@ -1572,6 +1601,7 @@ How long to keep cached search results before they expire.
 | `PROWLARR_TORRENT_CLIENT` | Choose which torrent client to use | string (choice) | _empty string_ |
 | `ALLDEBRID_API_KEY` | AllDebrid API Key (apiv4) from your AllDebrid account settings | string (secret) | _none_ |
 | `REALDEBRID_API_KEY` | Real-Debrid API Key (Secret Token) from your Real-Debrid account settings | string (secret) | _none_ |
 | `TORBOX_API_KEY` | TorBox API Key from your TorBox account settings | string (secret) | _none_ |
 | `QBITTORRENT_URL` | Web UI URL of your qBittorrent instance | string | _none_ |
 | `QBITTORRENT_USERNAME` | qBittorrent Web UI username | string | _none_ |
 | `QBITTORRENT_PASSWORD` | qBittorrent Web UI password | string (secret) | _none_ |
@@ -1623,7 +1653,7 @@ Choose which torrent client to use
 - **Type:** string (choice)
 - **Default:** _empty string_
- **Options:** `""` (None), `alldebrid` (AllDebrid), `qbittorrent` (qBittorrent), `realdebrid` (Real-Debrid), `transmission` (Transmission), `deluge` (Deluge), `rtorrent` (rTorrent)
+- **Options:** `""` (None), `alldebrid` (AllDebrid), `qbittorrent` (qBittorrent), `realdebrid` (Real-Debrid), `torbox` (TorBox), `transmission` (Transmission), `deluge` (Deluge), `rtorrent` (rTorrent)
 #### `ALLDEBRID_API_KEY`
@@ -1643,6 +1673,15 @@ Real-Debrid API Key (Secret Token) from your Real-Debrid account settings
 - **Type:** string (secret)
 - **Default:** _none_
 #### `TORBOX_API_KEY`
 **API Key**
 TorBox API Key from your TorBox account settings
 - **Type:** string (secret)
 - **Default:** _none_
 #### `QBITTORRENT_URL`
 **qBittorrent URL**
@@ -15,6 +15,7 @@ Use the guides below to set up the app, connect your library tools, and understa
 - [Users & Requests](users-and-requests.md)
 - [Reverse Proxy](reverse-proxy.md)
 - [OIDC](oidc.md)
 - [API Access](api-access.md)
 - [URL Search Parameters](url-search-parameters.md)
 - [Custom Scripts](custom-scripts.md)
@@ -87,6 +87,7 @@ Configure in Settings → Security:
 | Proxy Auth Logout URL | `https://auth.example.com/logout` |
 | Proxy Auth Admin Group Header | `Remote-Groups` |
 | Proxy Auth Admin Group Name | `admins` (or your admin group) |
 | Proxy Auth Default Role | `User` — first-time users are regular users; the very first account is still made admin. Only consulted when no admin group is set |
 #### Nginx Configuration with Authelia
@@ -1,71 +1,79 @@
 # URL Search Parameters
-You can trigger searches directly via URL by adding query parameters. This enables bookmarking searches and sharing links.
+You can trigger searches directly via URL. This enables bookmarking searches and sharing links.
 Parameters live in the URL **hash** (`#…`), so they stay in the browser and are never sent to
 the server. Shelfmark also keeps the hash in sync as you search, so the address bar always
 holds a shareable link to what you're looking at.
 ## Basic Usage
 ```
-http://your-server:8084/?q=harry+potter
+http://your-server:8084/#q=harry+potter
 ```
 Older query-string links (`/?q=harry+potter`) still work: they're read once on load and
 rewritten to the hash form.
 ## Supported Parameters
 | Parameter | Description | Example |
 |-----------|-------------|---------|
-| `q` or `query` | Main search query | `/?q=dune` |
+| `q` or `query` | Main search query | `/#q=dune` |
-| `author` | Filter by author name | `/?author=frank+herbert` |
+| `author` | Filter by author name | `/#author=frank+herbert` |
-| `title` | Filter by book title | `/?title=foundation` |
+| `title` | Filter by book title | `/#title=foundation` |
-| `isbn` | Filter by ISBN | `/?isbn=978-0747532699` |
+| `isbn` | Filter by ISBN | `/#isbn=978-0747532699` |
-| `lang` | Filter by language (ISO 639-1 code) | `/?lang=en` |
+| `lang` | Filter by language (ISO 639-1 code) | `/#lang=en` |
-| `format` | Filter by file format | `/?format=epub` |
+| `format` | Filter by file format | `/#format=epub` |
-| `content` | Filter by content type | `/?content=fiction` |
+| `content` | Filter by content type | `/#content=fiction` |
-| `content_type` | Select media type (`ebook`, `audiobook`, or `combined`) in Universal mode only | `/?q=dune&content_type=audiobook` |
+| `content_type` | Select media type (`ebook`, `audiobook`, or `combined`) in Universal mode only | `/#q=dune&content_type=audiobook` |
-| `sort` | Sort order for results | `/?sort=newest` |
+| `sort` | Sort order for results | `/#sort=newest` |
 | `search_by` | "Search By" target the query applies to (`general`, `author`, `title`, `isbn`, a metadata provider field like `series`, or `manual`) | `/#search_by=author&q=frank+herbert` |
 ## Multiple Values
 Some parameters support multiple values by repeating the parameter:
 ```
-/?lang=en&lang=de&lang=fr
+/#lang=en&lang=de&lang=fr
-/?format=epub&format=mobi&format=azw3
+/#format=epub&format=mobi&format=azw3
 ```
 ## Examples
 **Simple search:**
 ```
-/?q=lord+of+the+rings
+/#q=lord+of+the+rings
 ```
 **Search with author filter:**
 ```
-/?q=dune&author=frank+herbert
+/#q=dune&author=frank+herbert
 ```
 **Search with format and language:**
 ```
-/?q=harry+potter&format=epub&lang=en
+/#q=harry+potter&format=epub&lang=en
 ```
 **Author search with multiple formats:**
 ```
-/?author=stephen+king&format=epub&format=mobi
+/#author=stephen+king&format=epub&format=mobi
 ```
 **Search with sort order:**
 ```
-/?q=science+fiction&sort=newest
+/#q=science+fiction&sort=newest
 ```
 **Universal search as audiobook:**
 ```
-/?q=dune&content_type=audiobook
+/#q=dune&content_type=audiobook
 ```
 **Universal search forcing combined (ebook + audiobook):**
 ```
-/?q=dune&content_type=combined
+/#q=dune&content_type=combined
 ```
 ## Search Mode Behavior
@@ -77,13 +85,28 @@ When Search Mode is set to Direct, all parameters are used to filter results fro
 ### Universal Mode
-`q`, `sort`, and `content_type` are used. Other parameters (author, title, format, etc.) are silently ignored since metadata providers have their own search capabilities.
+`q`, `search_by`, `sort`, and `content_type` are used. Other parameters (author, title, format, etc.) are silently ignored since metadata providers have their own search capabilities — except when `search_by` names one of the provider's own search fields, in which case `q` is sent as that field's value.
 `content_type=combined` forces combined mode (search ebook and audiobook providers together), overriding the last-used preference. It is silently ignored if combined mode is unavailable (e.g. the combined selector is disabled in settings, or either content type is blocked by request policy).
 ## Search By
 `search_by` picks which target the `q` value is applied to, matching the selector next to the
 search box. It can be deep-linked on its own (`/#search_by=manual`) to open the app in that
 mode with an empty query.
 `search_by=manual` fills the search box but does not auto-run: manual search opens the release
 browser from an explicit submit.
 A `search_by` naming a target that isn't available (wrong search mode, or a metadata provider
 that doesn't offer that field) is ignored, and the query falls back to a general search.
 ## Notes
- URL parameters are read once on page load
+- URL parameters are read once on page load, and again if the hash is replaced in an open tab
- The URL is not updated when you perform searches manually
+  (e.g. pasting a shared link into the address bar)
 - The hash is kept in sync with the search box, Search By target and filters as you search
 - Spaces should be encoded as `+` or `%20`
 - Invalid or unknown parameters are silently ignored
 - Your last-used Search By target is remembered in browser storage and used when a link
  doesn't specify one
@@ -21,8 +21,8 @@ dependencies = [
    "rarfile",
    "qbittorrent-api>=2026.8.1",
    "transmission-rpc",
-    "authlib>=1.7.2,<1.8",
+    "authlib>=1.8.0,<1.9",
-    "apprise>=1.13.0",
+    "apprise>=1.13.1",
    # HTTP/2 client for RFC 8484 DoH: quad9 rejects HTTP/1.1 outright (505), which
    # requests cannot speak. See shelfmark/download/doh_wireformat.py.
    "httpx[http2]>=0.28.1",
@@ -32,18 +32,18 @@ dependencies = [
 browser = [
    "pyvirtualdisplay",
    "pyautogui",
-    "seleniumbase==4.53.5",
+    "seleniumbase==4.54.9",
    "python-xlib",
 ]
 [dependency-groups]
 dev = [
-    "basedpyright>=1.39.10",
+    "basedpyright>=1.40.1",
    "prek",
    "pytest",
    "pytest-cov",
    "pytest-xdist>=3.8.0",
-    "ruff==0.16.5",
+    "ruff==0.16.8",
    "vulture>=2.14",
 ]
@@ -248,6 +248,8 @@ volumes:
 With any authentication method enabled, Shelfmark supports multi-user management with admin/user roles. Users can have per-user settings for download destinations, email recipients, and notification preferences. Non-admin users only see their own downloads and can submit book requests for admin review. Admins can configure request policies per source to control whether users can download directly, must submit a request, or are blocked entirely.
 See [API Access](docs/api-access.md) to call the API with a static key from scripts and integrations.
 ## Project Scope
 Shelfmark is a manual search and download tool, the entry point to your book library, not a library manager. It finds books, downloads them, and sends them to a configured destination. That's the full scope.
@@ -184,6 +184,12 @@ def _generate_bootstrap_env_docs() -> list[str]:
            "type": "boolean",
            "default": "false",
        },
        {
            "name": "SHELFMARK_API_KEY",
            "description": "Optional static API key. When set, requests carrying it as 'Authorization: Bearer <key>' (or X-Api-Key) are authenticated as an admin; browser sessions keep working. Unset = off.",
            "type": "string",
            "default": "unset",
        },
        {
            "name": "OIDC_AUTO_REDIRECT",
            "description": "Automatically redirect to the OIDC provider instead of showing the login page.",
@@ -38,6 +38,10 @@ DDG_COOKIE_NAMES = {
    "ddg_last_challenge",
 }
 # Anna's Archive's own pass for its ?check=1 hop. Without it the hop 302s back
 # forever, however good the __ddg* clearance is.
 AA_COOKIE_NAMES = {"aa_ddg_check"}
 # DDoS-Guard cookies that describe *one* check rather than granting clearance, and so
 # must never be replayed on a later request. Observed live on Anna's Archive:
 #
@@ -88,7 +92,8 @@ def _should_extract_cookie(name: str, *, extract_all: bool) -> bool:
        return True
    is_cf = name in CF_COOKIE_NAMES or name.startswith("cf_")
    is_ddg = name in DDG_COOKIE_NAMES or name.startswith("__ddg")
-    return is_cf or is_ddg
+    is_aa = name in AA_COOKIE_NAMES
    return is_cf or is_ddg or is_aa
 def _cookie_field(cookie: Any, name: str) -> Any:
@@ -37,6 +37,7 @@ from shelfmark.bypass.cookie_store import (
    store_extracted_cookies,
 )
 from shelfmark.bypass.fingerprint import get_screen_size
 from shelfmark.bypass.waiting_room import WaitingRoomTimeoutError, is_aa_waiting_room
 from shelfmark.config import env
 from shelfmark.config.env import LOG_DIR
 from shelfmark.config.settings import RECORDING_DIR
@@ -85,11 +86,22 @@ _HELPER_IDLE_TIMEOUT_DEFAULT = 180.0
 # How long to wait for a solved page to produce its document before the attempt is
 # abandoned. SeleniumBase's own get_page_source() allows one second; see _read_page_source.
 _PAGE_SOURCE_TIMEOUT_DEFAULT = 20.0
 # Leave time inside the existing browser watchdog for challenge solving and cleanup.
 _AA_WAITING_ROOM_TIMEOUT_SECONDS = 300.0
 _AA_WAITING_ROOM_POLL_SECONDS = 1.0
 _PARENT_WATCHDOG_INTERVAL_SECONDS = 5.0
 # How much of ffmpeg's stderr to quote when reporting that it died.
 _FFMPEG_ERROR_TAIL_CHARS = 500
 class _WaitingRoomSnapshot(TypedDict):
    html: str
    title: str
    body: str
    url: str
    waiting: bool
 class _DisplayState(TypedDict):
    ffmpeg: subprocess.Popen[bytes] | None
    ffmpeg_output: Path | None
@@ -454,6 +466,14 @@ async def _detect_challenge_type(page: Any) -> str:
 async def _is_bypassed(page: Any, *, escape_emojis: bool = True) -> bool:
    """Check if the protection has been bypassed."""
    title, body, current_url = await _get_page_info(page)
    return _is_bypassed_content(title, body, current_url, escape_emojis=escape_emojis)
 def _is_bypassed_content(
    title: str, body: str, current_url: str, *, escape_emojis: bool = True
 ) -> bool:
    """Apply the same protection checks to one consistent page snapshot."""
    title, body = title.lower(), body.lower()
    body_len = len(body.strip())
    # Long page content = probably bypassed
@@ -831,6 +851,75 @@ async def _read_page_source(page: Any) -> str:
    return await element.get_html_async()
 async def _read_waiting_room_snapshot(
    page: Any, cancel_flag: Event | None
 ) -> _WaitingRoomSnapshot | None:
    """Read one DOM snapshot while still checking cancellation during a stalled read."""
    task = asyncio.create_task(
        page.evaluate("""({
        html: document.documentElement?.outerHTML || '',
        title: document.title,
        body: document.body?.innerText || '',
        url: location.href,
        waiting: !!document.querySelector('.js-partner-countdown')
    })""")
    )
    try:
        while not task.done():
            _check_cancellation(cancel_flag, "Bypass cancelled in Anna's waiting room")
            # Keep a slow CDP request alive. Cancelling and reissuing it on every
            # poll can break the listener when a late response targets a cancelled
            # SeleniumBase transaction. Cancel only when this browser is unwinding.
            await asyncio.wait({task}, timeout=_AA_WAITING_ROOM_POLL_SECONDS)
        _check_cancellation(cancel_flag, "Bypass cancelled in Anna's waiting room")
        return task.result()
    finally:
        task.cancel()
        await asyncio.gather(task, return_exceptions=True)
 async def _wait_for_aa_download_page(
    page: Any, url: str, html: str, cancel_flag: Event | None = None
 ) -> str:
    """Let the waiting room's own JavaScript countdown and navigation finish.
    Returning the timer HTML closes this incognito browser. Sleeping in the HTTP
    downloader and fetching again then starts a different session, losing queue state.
    Keep the original tab alive, including through zero and automatic page reloads.
    """
    if not is_aa_waiting_room(url, html):
        return html
    logger.info("Waiting for Anna's Archive queue in the same browser session...")
    started = time.monotonic()
    try:
        async with asyncio.timeout(_AA_WAITING_ROOM_TIMEOUT_SECONDS):
            while True:
                try:
                    # Read readiness and HTML atomically: navigation between separate
                    # CDP reads could validate a new page but return an old interstitial.
                    snapshot = await _read_waiting_room_snapshot(page, cancel_flag)
                except _CDP_OPERATION_ERRORS:
                    # A frame/context can disappear during automatic navigation.
                    snapshot = None
                if (
                    snapshot
                    and not snapshot["waiting"]
                    and _is_bypassed_content(snapshot["title"], snapshot["body"], snapshot["url"])
                ):
                    logger.info(
                        "Anna's Archive waiting room finished after %.0fs",
                        time.monotonic() - started,
                    )
                    return snapshot["html"]
                # A zero timer, empty document, or protection page is not completion.
                await asyncio.sleep(_AA_WAITING_ROOM_POLL_SECONDS)
    except TimeoutError as exc:
        raise WaitingRoomTimeoutError(
            f"Anna's Archive waiting room did not finish within {_AA_WAITING_ROOM_TIMEOUT_SECONDS:g}s"
        ) from exc
 async def _get(url: str, driver: Any, cancel_flag: Event | None = None) -> str:
    """Fetch URL with Cloudflare bypass using a CDP browser."""
    _check_cancellation(cancel_flag, "Bypass cancelled before starting")
@@ -853,8 +942,10 @@ async def _get(url: str, driver: Any, cancel_flag: Event | None = None) -> str:
    logger.debug("Starting bypass process...")
    if await _bypass(page, cancel_flag=cancel_flag):
        html = await _read_page_source(page)
        html = await _wait_for_aa_download_page(page, url, html, cancel_flag)
        await _extract_cookies_from_cdp(driver, page, url)
-        return await _read_page_source(page)
+        return html
    logger.warning("Bypass completed but page still shows protection")
    try:
@@ -904,7 +995,8 @@ def _run_bypass_in_current_process(url: str, retry: int, cancel_flag: Event | No
                    result = await _get(url, driver, cancel_flag)
                    if result:
                        return result
-                except BypassCancelledError:
+                except BypassCancelledError, WaitingRoomTimeoutError:
                    # Retrying would restart the same queue in another browser.
                    raise
                except _CDP_OPERATION_ERRORS as e:
                    error_details = f"{type(e).__name__}: {e}"
@@ -1215,6 +1307,8 @@ def _get_via_subprocess(url: str, retry: int, cancel_flag: Event | None = None)
        trace = result.get("traceback")
        if trace:
            logger.debug("Internal bypasser helper traceback: %s", trace)
        if error_type == WaitingRoomTimeoutError.__name__:
            raise WaitingRoomTimeoutError(error)
        msg = f"{error_type}: {error}"
        raise RuntimeError(msg)
@@ -1397,17 +1491,16 @@ def _start_ffmpeg_recording(display: str) -> None:
    timestamp = datetime.now(UTC).strftime("%y%m%d-%H%M%S")
    output_file = RECORDING_DIR / f"screen_recording_{timestamp}.mp4"
-    screen_width, screen_height = get_screen_size()
+    # No -video_size: x11grab then captures the whole screen, whatever size it is. The
-    display_width = screen_width + 100
+    # size we ask SeleniumBase for (xvfb_metrics) is not the size we get. It builds that
-    display_height = screen_height + 150
+    # display with use_xauth=True, the image ships no xauth binary, so it falls back to a
-
+    # fixed 1440x1880 Xvfb. Asking ffmpeg for the fingerprint size plus margin then asked
    # for an area larger than the screen, and every recording died at startup (#1364).
    ffmpeg_cmd = [
        "ffmpeg",
        "-y",
        "-f",
        "x11grab",
        "-video_size",
        f"{display_width}x{display_height}",
        "-i",
        display,
        "-c:v",
@@ -1534,6 +1627,10 @@ def _try_with_cached_cookies(url: str, hostname: str) -> str | None:
            verify=get_ssl_verify(url),
        )
        if response.status_code == HTTPStatus.OK:
            if is_aa_waiting_room(url, response.text):
                # Clearance is valid, but HTTP cannot run the queue's JavaScript.
                # Enforce this here for both cache checks, including the locked one.
                return None
            logger.debug("Cached cookies worked, skipped Chrome bypass")
            return response.text
        if response.status_code == HTTPStatus.TOO_MANY_REQUESTS:
@@ -1606,7 +1703,7 @@ def get_bypassed_page(
    try:
        response_html = get(attempt_url, cancel_flag=cancel_flag)
-    except BypassCancelledError:
+    except BypassCancelledError, WaitingRoomTimeoutError:
        raise
    except _CDP_OPERATION_ERRORS + _REQUEST_OPERATION_ERRORS:
        _check_cancellation(cancel_flag, "Bypass cancelled")
@@ -0,0 +1,16 @@
 """Recognize Anna's Archive pages that require a live JavaScript timer."""
 from urllib.parse import urlparse
 from bs4 import BeautifulSoup
 class WaitingRoomTimeoutError(TimeoutError):
    """The source waiting room did not finish within the browser session budget."""
 def is_aa_waiting_room(url: str, html: str) -> bool:
    """Match the download route and actual timer element, not a script reference."""
    return urlparse(url).path.startswith("/slow_download/") and bool(
        BeautifulSoup(html, "html.parser").select_one(".js-partner-countdown")
    )
@@ -166,6 +166,9 @@ SESSION_COOKIE_NAME = "shelfmark_session"
 CWA_DB_PATH = _resolve_cwa_db_path()
 HIDE_LOCAL_AUTH = string_to_bool(os.getenv("HIDE_LOCAL_AUTH", "false"))
 DISABLE_LOCAL_AUTH = string_to_bool(os.getenv("DISABLE_LOCAL_AUTH", "false"))
 # Optional static API key. When set, requests carrying it as a Bearer token
 # (or X-Api-Key) are authenticated as an admin for that request only.
 SHELFMARK_API_KEY = os.getenv("SHELFMARK_API_KEY", "").strip()
 OIDC_AUTO_REDIRECT = string_to_bool(os.getenv("OIDC_AUTO_REDIRECT", "false"))
@@ -179,6 +179,18 @@ def security_settings() -> list[SettingsField]:
            placeholder="e.g. admins",
            default="",
        ),
        _auth_field(
            SelectField,
            "proxy",
            key="PROXY_AUTH_DEFAULT_ROLE",
            label="Proxy Auth Default Role",
            description="Role for users the proxy authenticates for the first time when no admin group is configured. The first account is always an admin so the instance is never left without one.",
            options=[
                {"value": "user", "label": "User"},
                {"value": "admin", "label": "Admin"},
            ],
            default="user",
        ),
    ]
    fields.append(
@@ -204,6 +204,7 @@ register_group(
 # Direct mode sort options
 _AA_SORT_OPTIONS = [
    {"value": "", "label": "Most downloads"},
    {"value": "relevance", "label": "Most relevant"},
    {"value": "newest", "label": "Newest (publication year)"},
    {"value": "oldest", "label": "Oldest (publication year)"},
@@ -483,7 +484,7 @@ def search_mode_settings() -> list[SettingsField]:
            label="Default Sort Order",
            description="Default sort order for search results.",
            options=_AA_SORT_OPTIONS,
-            default="relevance",
+            default="",
            show_when={"field": "SEARCH_MODE", "value": "direct"},
        ),
        CheckboxField(
@@ -1023,12 +1024,30 @@ def download_settings() -> list[SettingsField]:
                "value": "folder",
            },
        ),
        TextField(
            key="NAMING_WORD_SEPARATOR",
            label="Word Separator",
            description=(
                "Replaces spaces inside naming template values (e.g. 'Conan Doyle' -> "
                "'Conan.Doyle' with '.'). Applies to books and audiobooks, rename and "
                "organize templates alike. Literal characters typed into a template "
                "(like the '-' in '{Author} - {Title}') are left as-is. Leave empty to "
                "keep spaces as-is."
            ),
            default="",
            placeholder=".",
            max_length=5,
            show_when={
                "field": "BOOKS_OUTPUT_MODE",
                "value": "folder",
            },
        ),
        # Rename mode template - filename only
        _naming_template_field(
            key="TEMPLATE_RENAME",
            label="Naming Template",
            description=(
-                "Variables: {Author}, {Title}, {Year}, {Language}, {User}, {OriginalName} "
+                "Variables: {Author}, {FirstAuthor} (first of several authors), {Title}, {Year}, {Language}, {User}, {OriginalName} "
                "(source filename without extension). Universal adds: {Series}, "
                "{SeriesPosition}, {Subtitle}, {PrimaryTitle}. Use arbitrary prefix/suffix: "
                "{Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty. "
@@ -1047,7 +1066,7 @@ def download_settings() -> list[SettingsField]:
            key="TEMPLATE_ORGANIZE",
            label="Path Template",
            description=(
-                "Use / to create folders. Variables: {Author}, {Title}, {Year}, {Language}, {User}, "
+                "Use / to create folders. Variables: {Author}, {FirstAuthor} (first of several authors), {Title}, {Year}, {Language}, {User}, "
                "{OriginalName} (source filename without extension). Universal adds: {Series}, "
                "{SeriesPosition}, {Subtitle}, {PrimaryTitle}. Use arbitrary prefix/suffix: "
                "{Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty."
@@ -1315,7 +1334,7 @@ def download_settings() -> list[SettingsField]:
            key="TEMPLATE_AUDIOBOOK_RENAME",
            label="Naming Template",
            description=(
-                "Variables: {Author}, {Title}, {Year}, {Language}, {User}, {OriginalName} "
+                "Variables: {Author}, {FirstAuthor} (first of several authors), {Title}, {Year}, {Language}, {User}, {OriginalName} "
                "(source filename without extension), {Series}, {SeriesPosition}, {Subtitle}, "
                "{PrimaryTitle}, {PartNumber}. Use arbitrary prefix/suffix: "
                "{Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty. "
@@ -1335,7 +1354,7 @@ def download_settings() -> list[SettingsField]:
            key="TEMPLATE_AUDIOBOOK_ORGANIZE",
            label="Path Template",
            description=(
-                "Use / to create folders. Variables: {Author}, {Title}, {Year}, {Language}, {User}, "
+                "Use / to create folders. Variables: {Author}, {FirstAuthor} (first of several authors), {Title}, {Year}, {Language}, {User}, "
                "{OriginalName} (source filename without extension), {Series}, {SeriesPosition}, "
                "{Subtitle}, {PrimaryTitle}, {PartNumber}. Use arbitrary prefix/suffix: "
                "{Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty."
@@ -280,6 +280,7 @@ def register_admin_routes(app: Flask, user_db: UserDB) -> None:
        # Handle optional password update
        password = data.get("password", "")
        password_hash: str | None = None
        if password:
            if not capabilities["canSetPassword"]:
                return jsonify(
@@ -292,7 +293,7 @@ def register_admin_routes(app: Flask, user_db: UserDB) -> None:
                return jsonify(
                    {"error": f"Password must be at least {MIN_PASSWORD_LENGTH} characters"}
                ), 400
-            user_db.update_user(user_id, password_hash=generate_password_hash(password))
+            password_hash = generate_password_hash(password)
        # Update user fields
        user_fields = {}
@@ -358,10 +359,8 @@ def register_admin_routes(app: Flask, user_db: UserDB) -> None:
            if field in user_fields and user_fields[field] == user.get(field):
                user_fields.pop(field)
-        if user_fields:
+        # Validate per-user settings
-            user_db.update_user(user_id, **user_fields)
+        validated_settings: dict[str, Any] | None = None
        # Update per-user settings
        if "settings" in data:
            if not isinstance(data["settings"], dict):
                return jsonify({"error": "Settings must be an object"}), 400
@@ -375,6 +374,14 @@ def register_admin_routes(app: Flask, user_db: UserDB) -> None:
                    }
                ), 400
        # Apply the writes only once the whole payload has been accepted.
        if password_hash is not None:
            user_fields["password_hash"] = password_hash
        if user_fields:
            user_db.update_user(user_id, **user_fields)
        if validated_settings is not None:
            user_db.set_user_settings(user_id, validated_settings)
            # Ensure runtime reads see updated per-user overrides immediately.
            try:
@@ -0,0 +1,39 @@
 """Static API-key authentication backed by the SHELFMARK_API_KEY environment variable.
 When ``SHELFMARK_API_KEY`` is set, a request carrying that value as a Bearer token or in
 ``X-Api-Key`` is treated as an admin for that request only. Both headers are
 checked, since a reverse proxy in front of Shelfmark may set its own
 ``Authorization`` header, which would otherwise shadow an operator-supplied
 ``X-Api-Key``. A candidate that matches neither is ignored so that bearer
 tokens forwarded by reverse proxies keep working. The key is never logged.
 """
 from __future__ import annotations
 import hmac
 from shelfmark.config.env import SHELFMARK_API_KEY
 def extract_api_key_candidates(
    authorization_header: str | None, api_key_header: str | None
 ) -> list[str]:
    """Return the non-empty credentials a client presented, Bearer token first."""
    candidates: list[str] = []
    if authorization_header:
        scheme, _, token = authorization_header.strip().partition(" ")
        token = token.strip()
        if scheme.lower() == "bearer" and token:
            candidates.append(token)
    if api_key_header:
        token = api_key_header.strip()
        if token:
            candidates.append(token)
    return candidates
 def matches_api_key(candidate: str) -> bool:
    """Constant-time comparison against the configured key. False when unset."""
    if not SHELFMARK_API_KEY or not candidate:
        return False
    return hmac.compare_digest(candidate.encode("utf-8"), SHELFMARK_API_KEY.encode("utf-8"))
@@ -0,0 +1,112 @@
 """Comparing and trimming author names for release search.
 Lives in core because more than one release source needs it: Prowlarr ranks
 results on author agreement (#1293), and IRC both trims the name it searches
 for and ranks what comes back.
 """
 import re
 _AUTHOR_TOKEN_PATTERN = re.compile(r"\w+", re.UNICODE)
 _AUTHOR_NOISE_TOKENS = frozenset(
    {"jr", "sr", "ii", "iii", "iv", "phd", "md", "dr", "mr", "mrs", "ms", "et", "al", "and", "the"}
 )
 # Ordering tiers for author agreement between the requested book and what an
 # indexer reported. Lower sorts first.
 AUTHOR_MATCH = 0
 AUTHOR_PARTIAL = 1
 AUTHOR_UNKNOWN = 2
 AUTHOR_MISMATCH = 3
 # A mononym ("Homer") can only ever agree on one token; a longer name needs a
 # given name and a surname to agree before it counts as the same person.
 _AUTHOR_TOKENS_REQUIRED = 2
 def _author_tokens(value: object) -> list[str]:
    """Split an author string into comparable lowercase name tokens."""
    if not isinstance(value, str):
        return []
    tokens = [token.lower() for token in _AUTHOR_TOKEN_PATTERN.findall(value)]
    return [token for token in tokens if token not in _AUTHOR_NOISE_TOKENS]
 def _author_tokens_compatible(wanted: str, offered: str) -> bool:
    """Treat an abbreviated given name as the name it abbreviates."""
    return wanted == offered or wanted.startswith(offered) or offered.startswith(wanted)
 def author_affinity(wanted: object, offered: object) -> int:
    """Rank how far an indexer's author field is from the requested author.
    Shelfmark ranks on this rather than filtering on it, so a wrong verdict only
    costs a release its position in the list, never its visibility. That is what
    makes the loose token comparison safe: "Tim"/"Timothy" and "T."/"Timothy"
    agree, while a transliteration ("Dostoevsky"/"Dostoyevsky") is merely sorted
    last instead of being hidden.
    Graded, not binary, because the ways of falling short are not equally bad.
    An indexer that reports no author at all must not sort below one that reports
    a wrong author, so "no metadata" ranks between agreement and disagreement. And
    a name that merely says *less* than the one asked for is not evidence of a
    different person: "Petrie" contradicts nothing about "David Petrie", while
    "Gordon Petrie" does. That gap matters most where a source is searched by
    surname alone (#1331) - the filenames such a search is meant to reach are
    exactly the ones filed under a bare surname, and ranking them as wrong put
    them below every result that named someone else entirely.
    """
    wanted_tokens = _author_tokens(wanted)
    offered_tokens = _author_tokens(offered)
    if not wanted_tokens or not offered_tokens:
        return AUTHOR_UNKNOWN
    matched = sum(
        1
        for wanted_token in wanted_tokens
        if any(
            _author_tokens_compatible(wanted_token, offered_token)
            for offered_token in offered_tokens
        )
    )
    required = min(_AUTHOR_TOKENS_REQUIRED, len(wanted_tokens))
    if matched >= required:
        return AUTHOR_MATCH
    # Too little agreement to call it the same person, so the question is whether
    # what was offered *disagrees*. A name every token of which fits the wanted
    # name is an abbreviation of it; one carrying a token that fits nothing is a
    # different name that happens to share a surname.
    if all(
        any(
            _author_tokens_compatible(wanted_token, offered_token) for wanted_token in wanted_tokens
        )
        for offered_token in offered_tokens
    ):
        return AUTHOR_PARTIAL
    return AUTHOR_MISMATCH
 def search_surname(author: object) -> str:
    """The one name token worth sending to a source that matches conjunctively.
    Given names are where catalogues disagree - "David Petrie" is filed as
    "D. Petrie", "Timothy" as "Tim" - so a query carrying one matches nothing on
    a source that requires every term to appear. The surname is the token both
    spellings share.
    Keeps the author's own capitalisation, because the result is posted to a
    public channel, and returns "" when no usable token is left so the caller
    searches by title alone rather than by noise.
    """
    if not isinstance(author, str):
        return ""
    tokens = [
        token
        for token in _AUTHOR_TOKEN_PATTERN.findall(author)
        if token.lower() not in _AUTHOR_NOISE_TOKENS
    ]
    if not tokens:
        return ""
    return tokens[-1]
@@ -207,6 +207,7 @@ class DownloadHistoryService:
            "content_type": row.get("content_type"),
            "source": row.get("source"),
            "source_display_name": row.get("source_display_name"),
            "downloads": row.get("downloads"),
            "status_message": row.get("status_message"),
            "download_path": DownloadHistoryService._resolve_existing_download_path(
                row.get("download_path")
@@ -272,6 +273,7 @@ class DownloadHistoryService:
        size: str | None,
        preview: str | None,
        content_type: str | None,
        downloads: int | None,
        origin: str,
        retry_payload: dict[str, Any] | None = None,
    ) -> None:
@@ -307,15 +309,16 @@ class DownloadHistoryService:
                    title, author, format, size, preview, content_type,
                    origin, final_status,
                    status_message, download_path, retry_payload,
-                    queued_at, terminal_at
+                    queued_at, terminal_at, downloads
                )
-                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'active', NULL, NULL, ?, ?, ?)
+                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'active', NULL, NULL, ?, ?, ?, ?)
                ON CONFLICT(task_id) DO UPDATE SET
                    final_status = 'active',
                    status_message = NULL,
                    download_path = NULL,
                    retry_payload = excluded.retry_payload,
-                    terminal_at = ?
+                    terminal_at = ?,
                    downloads = excluded.downloads
                """,
                    (
                        normalized_task_id,
@@ -334,6 +337,7 @@ class DownloadHistoryService:
                        normalized_retry_payload,
                        recorded_at,
                        recorded_at,
                        downloads,
                        recorded_at,
                    ),
                )
@@ -4,6 +4,7 @@ import logging
 import sys
 from collections.abc import Mapping
 from logging.handlers import RotatingFileHandler
 from threading import Lock
 from typing import TYPE_CHECKING
 from shelfmark.config.env import ENABLE_LOGGING, LOG_FILE, LOG_LEVEL
@@ -12,6 +13,10 @@ if TYPE_CHECKING:
    from pathlib import Path
 _file_handlers: dict[Path, RotatingFileHandler] = {}
 _file_handlers_lock = Lock()
 class CustomLogger(logging.Logger):
    """Custom logger class with additional error_trace method."""
@@ -122,6 +127,22 @@ def _normalize_log_extra(value: object) -> Mapping[str, object] | None:
    return None
 def _get_file_handler(log_file: Path, formatter: logging.Formatter) -> RotatingFileHandler:
    """Return the process-wide rotating handler for a log file."""
    with _file_handlers_lock:
        handler = _file_handlers.get(log_file)
        if handler is None:
            log_file.parent.mkdir(parents=True, exist_ok=True)
            handler = RotatingFileHandler(
                log_file,
                maxBytes=10485760,  # 10MB
                backupCount=5,
            )
            handler.setFormatter(formatter)
            _file_handlers[log_file] = handler
        return handler
 def setup_logger(name: str, log_file: Path = LOG_FILE) -> CustomLogger:
    """Set up and configure a logger instance.
@@ -163,16 +184,7 @@ def setup_logger(name: str, log_file: Path = LOG_FILE) -> CustomLogger:
    # File handler if log file is specified
    try:
        if ENABLE_LOGGING:
-            # Create log directory if it doesn't exist
+            logger.addHandler(_get_file_handler(log_file, formatter))
            log_dir = log_file.parent
            log_dir.mkdir(parents=True, exist_ok=True)
            file_handler = RotatingFileHandler(
                log_file,
                maxBytes=10485760,  # 10MB
                backupCount=5,
            )
            file_handler.setFormatter(formatter)
            logger.addHandler(file_handler)
    except (OSError, TypeError, ValueError) as e:
        logger.error_trace(f"Failed to create log file: {e}", exc_info=True)
@@ -97,6 +97,7 @@ class DownloadTask:
    year: str | None = None
    format: str | None = None
    size: str | None = None
    downloads: int | None = None  # Download count from source
    preview: str | None = None
    content_type: str | None = None  # "book (fiction)", "audiobook", "magazine", etc.
    source_url: str | None = None  # Original release URL used by source-specific handlers
@@ -14,11 +14,12 @@ logger = setup_logger(__name__)
 # Known variable tokens, sorted longest-first to avoid partial matches
-# e.g., "SeriesPosition" must match before "Series"
+# e.g., "SeriesPosition" must match before "Series", "FirstAuthor" before "Author"
 KNOWN_TOKENS = [
    "seriesposition",
    "primarytitle",
    "originalname",
    "firstauthor",
    "partnumber",
    "language",
    "subtitle",
@@ -29,12 +30,22 @@ KNOWN_TOKENS = [
    "user",
 ]
 # Authors reach naming already joined as "First Author, Second Author, ...".
 # {FirstAuthor} keeps only the first entry. A single name written "Last, First"
 # is split on the comma too and renders as "Last" -- the source metadata does
 # not mark which form it is (see #930).
 AUTHOR_LIST_SEPARATOR = re.compile(r"\s*[,;]\s*")
 # Match any {...} block for template parsing
 BRACE_PATTERN = re.compile(r"\{([^}]+)\}")
 # Characters that are invalid in filenames on various filesystems
 INVALID_CHARS = re.compile(r'[\\/:*?"<>|]')
 # Runs of whitespace inside a single placeholder's rendered value, e.g. "Conan Doyle"
 # -- collapsed to the configured word separator (see `parse_naming_template`).
 WHITESPACE_RUN = re.compile(r"\s+")
 def _sanitize(name: str | None, max_length: int = 245) -> str:
    """Sanitize a string for filesystem use."""
@@ -56,6 +67,14 @@ def sanitize_filename(name: str | None, max_length: int = 245) -> str:
 sanitize_path_component = sanitize_filename
 def first_author(value: object) -> str:
    """Return the first entry from an author string joined with ',' or ';'."""
    text = " ".join(str(value or "").split())
    if not text:
        return ""
    return AUTHOR_LIST_SEPARATOR.split(text, maxsplit=1)[0].strip()
 def format_series_position(position: str | float | None) -> str:
    """Format a series position for naming templates."""
    if position is None:
@@ -143,8 +162,16 @@ def parse_naming_template(
    metadata: Mapping[str, str | int | float | None],
    *,
    allow_path_separators: bool = True,
    word_separator: str = " ",
 ) -> str:
-    """Render a naming template with Shelfmark metadata placeholders."""
+    """Render a naming template with Shelfmark metadata placeholders.
    `word_separator` replaces whitespace *inside* each placeholder's rendered
    value (e.g. "Conan Doyle" -> "Conan.Doyle" for a "." separator). It never
    touches literal characters typed into the template itself, so a template
    like "{Author}.-.{Title}" keeps its own dots regardless of this setting.
    The default (" ") leaves values untouched, matching prior behavior.
    """
    if not template:
        return ""
@@ -163,6 +190,8 @@ def parse_naming_template(
        value = normalized.get(placeholder_name)
        if placeholder_name == "seriesposition":
            value = format_series_position(value)
        elif placeholder_name == "firstauthor" and not value:
            value = first_author(normalized.get("author"))
        if value is None:
            return ""
        return str(value).strip()
@@ -178,6 +207,8 @@ def parse_naming_template(
        if not value:
            return ""
        if word_separator != " ":
            value = WHITESPACE_RUN.sub(word_separator, value)
        if not allow_path_separators:
            value = value.replace("/", "_")
        value = sanitize_filename(value)
@@ -243,9 +274,13 @@ def build_library_path(
    template: str,
    metadata: Mapping[str, str | int | float | None],
    extension: str | None = None,
    *,
    word_separator: str = " ",
 ) -> Path:
    """Build a final library path from a template and metadata."""
-    relative = parse_naming_template(template, metadata, allow_path_separators=True)
+    relative = parse_naming_template(
        template, metadata, allow_path_separators=True, word_separator=word_separator
    )
    if not relative:
        # Fallback to title if template produces empty result
@@ -109,7 +109,7 @@ def _normalize_return_to(raw_return_to: object) -> str | None:
        return None
    parsed = urlsplit(value)
-    if parsed.scheme or parsed.netloc:
+    if parsed.scheme or parsed.netloc or "\\" in parsed.path:
        return None
    script_root = request.script_root.rstrip("/")
@@ -145,28 +145,36 @@ class BookQueue:
        with self._lock:
            self._queue_hook = hook
-    def update_status(self, book_id: str, status: QueueStatus) -> None:
+    def _apply_status_locked(
-        """Update status of a book in the queue."""
+        self, book_id: str, status: QueueStatus
    ) -> tuple[Callable[[str, QueueStatus, DownloadTask], None] | None, DownloadTask | None]:
        """Apply a status change; returns the terminal hook to run after releasing the lock."""
        hook: Callable[[str, QueueStatus, DownloadTask], None] | None = None
        hook_task: DownloadTask | None = None
        previous_status = self._status.get(book_id)
        self._update_status(book_id, status)
        if (
            status in TERMINAL_QUEUE_STATUSES
            and previous_status != status
            and self._terminal_status_hook is not None
        ):
            current_task = self._task_data.get(book_id)
            if current_task is not None:
                hook = self._terminal_status_hook
                hook_task = current_task
        # Clean up active download tracking when finished
        if status in TERMINAL_QUEUE_STATUSES:
            self._active_downloads.pop(book_id, None)
            self._cancel_flags.pop(book_id, None)
        return hook, hook_task
    def update_status(self, book_id: str, status: QueueStatus) -> None:
        """Update status of a book in the queue."""
        with self._lock:
-            previous_status = self._status.get(book_id)
+            hook, hook_task = self._apply_status_locked(book_id, status)
            self._update_status(book_id, status)
            if (
                status in TERMINAL_QUEUE_STATUSES
                and previous_status != status
                and self._terminal_status_hook is not None
            ):
                current_task = self._task_data.get(book_id)
                if current_task is not None:
                    hook = self._terminal_status_hook
                    hook_task = current_task
            # Clean up active download tracking when finished
            if status in TERMINAL_QUEUE_STATUSES:
                self._active_downloads.pop(book_id, None)
                self._cancel_flags.pop(book_id, None)
        if hook is not None and hook_task is not None:
            hook(book_id, status, hook_task)
@@ -257,7 +265,11 @@ class BookQueue:
                # Not in a cancellable state
                return False
-        self.update_status(task_id, QueueStatus.CANCELLED)
+            # Write under the same lock so a download that finishes first is not overwritten
            hook, hook_task = self._apply_status_locked(task_id, QueueStatus.CANCELLED)
        if hook is not None and hook_task is not None:
            hook(task_id, QueueStatus.CANCELLED, hook_task)
        return True
    def set_priority(self, task_id: str, new_priority: int) -> bool:
@@ -0,0 +1,93 @@
 """Shared release-search helpers.
 Extracted from the ``/api/releases`` route so the same per-source search logic can
 be reused outside the HTTP route (for example by background automation) without
 going through Flask. Behaviour for the HTTP route is preserved: the route delegates
 its inner per-source search to :func:`search_source_releases`.
 """
 from __future__ import annotations
 import sqlite3
 from typing import TYPE_CHECKING
 from shelfmark.core.logger import setup_logger
 from shelfmark.core.search_plan import build_release_search_plan
 if TYPE_CHECKING:
    from shelfmark.core.models import SearchFilters
    from shelfmark.metadata_providers import BookMetadata
    from shelfmark.release_sources import Release, ReleaseSource
 logger = setup_logger(__name__)
 # Mirror of main._OPERATIONAL_ERRORS so a misbehaving source can't crash a caller.
 _OPERATIONAL_ERRORS = (OSError, RuntimeError, TypeError, ValueError, sqlite3.Error)
 def search_source_releases(
    source_name: str,
    search_book: BookMetadata,
    *,
    languages: list[str] | None = None,
    manual_query: str | None = None,
    indexers: list[str] | None = None,
    expand_search: bool = False,
    content_type: str = "ebook",
    source_filters: SearchFilters | None = None,
    user_id: int | None = None,
 ) -> tuple[ReleaseSource | None, list[Release], str | None]:
    """Search a single release source, returning any error instead of raising.
    Returns ``(source, releases, error_message)``. On failure ``source`` is ``None``
    and ``error_message`` describes the problem. ``user_id`` lets the search plan
    pick up that user's default languages when no explicit filter is given.
    """
    from shelfmark.release_sources import SourceUnavailableError, get_source
    try:
        source = get_source(source_name)
        plan = build_release_search_plan(
            search_book,
            languages=languages,
            manual_query=manual_query,
            indexers=indexers,
            source_filters=source_filters,
            user_id=user_id,
        )
        if plan.source_filters is not None:
            planned_query = plan.manual_query or plan.primary_query
            planned_query_type = "query"
        elif plan.manual_query:
            planned_query = plan.manual_query
            planned_query_type = "manual"
        elif not expand_search and plan.isbn_candidates:
            planned_query = plan.isbn_candidates[0]
            planned_query_type = "isbn"
        else:
            planned_query = plan.primary_query
            planned_query_type = "title_author"
        logger.debug(
            "Searching %s: %s='%s' (title='%s', authors=%s, expand=%s, content_type=%s)",
            source_name,
            planned_query_type,
            planned_query,
            search_book.title,
            search_book.authors,
            expand_search,
            content_type,
        )
        releases = source.search(
            search_book, plan, expand_search=expand_search, content_type=content_type
        )
    except ValueError:
        return None, [], f"Unknown source: {source_name}"
    except (SourceUnavailableError, *_OPERATIONAL_ERRORS) as exc:
        logger.warning("Release search failed for source %s: %s", source_name, exc)
        return None, [], f"{source_name}: {exc!s}"
    else:
        return source, releases, None
@@ -715,6 +715,8 @@ def register_request_routes(
        raw_requests = data.get("requests")
        if not isinstance(raw_requests, list) or len(raw_requests) == 0:
            return jsonify({"error": "requests must contain at least one request"}), 400
        if not all(isinstance(raw_request, dict) for raw_request in raw_requests):
            return jsonify({"error": "requests must contain objects"}), 400
        try:
            prepared_requests = [
@@ -302,6 +302,7 @@ def register_self_user_routes(app: Flask, user_db: UserDB) -> None:
        auth_source = capabilities["authSource"]
        password = data.get("password", "")
        password_hash: str | None = None
        if password:
            if not capabilities["canSetPassword"]:
                return jsonify(
@@ -314,7 +315,7 @@ def register_self_user_routes(app: Flask, user_db: UserDB) -> None:
                return jsonify(
                    {"error": f"Password must be at least {MIN_PASSWORD_LENGTH} characters"}
                ), 400
-            user_db.update_user(user_id, password_hash=generate_password_hash(password))
+            password_hash = generate_password_hash(password)
        user_fields: dict[str, Any] = {}
        if "email" in data:
@@ -363,9 +364,7 @@ def register_self_user_routes(app: Flask, user_db: UserDB) -> None:
            if field in user_fields and user_fields[field] == user.get(field):
                user_fields.pop(field)
-        if user_fields:
+        validated_settings: dict[str, Any] | None = None
            user_db.update_user(user_id, **user_fields)
        if "settings" in data:
            settings_payload = data["settings"]
            if not isinstance(settings_payload, dict):
@@ -397,6 +396,14 @@ def register_self_user_routes(app: Flask, user_db: UserDB) -> None:
                    }
                ), 400
        # Apply the writes only once the whole payload has been accepted.
        if password_hash is not None:
            user_fields["password_hash"] = password_hash
        if user_fields:
            user_db.update_user(user_id, **user_fields)
        if validated_settings is not None:
            user_db.set_user_settings(user_id, validated_settings)
            try:
                app_config.refresh(force=True)
@@ -87,7 +87,8 @@ CREATE TABLE IF NOT EXISTS download_history (
    download_path TEXT,
    retry_payload TEXT,
    queued_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
-    terminal_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
+    terminal_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    downloads INTEGER
 );
 CREATE INDEX IF NOT EXISTS idx_download_history_user_status
@@ -203,6 +204,7 @@ class UserDB:
                self._migrate_request_delivery_columns(conn)
                self._migrate_download_history_queued_at(conn)
                self._migrate_download_history_retry_payload(conn)
                self._migrate_download_history_downloads(conn)
                conn.commit()
                # WAL mode must be changed outside an open transaction.
                conn.execute("PRAGMA journal_mode=WAL")
@@ -270,6 +272,13 @@ class UserDB:
        if "retry_payload" not in column_names:
            conn.execute("ALTER TABLE download_history ADD COLUMN retry_payload TEXT")
    def _migrate_download_history_downloads(self, conn: sqlite3.Connection) -> None:
        """Ensure download_history.downloads exists for download count persistence."""
        columns = conn.execute("PRAGMA table_info(download_history)").fetchall()
        column_names = {str(col["name"]) for col in columns}
        if "downloads" not in column_names:
            conn.execute("ALTER TABLE download_history ADD COLUMN downloads INTEGER")
    def create_user(
        self,
        username: str,
@@ -424,6 +433,26 @@ class UserDB:
        finally:
            conn.close()
    def get_first_admin(self) -> dict[str, Any] | None:
        """Return the lowest-id admin user, or None. Used as the identity for SHELFMARK_API_KEY requests."""
        conn = self._connect()
        try:
            row = conn.execute(
                "SELECT * FROM users WHERE role = 'admin' ORDER BY id LIMIT 1"
            ).fetchone()
            return dict(row) if row else None
        finally:
            conn.close()
    def has_admin(self) -> bool:
        """Return True when at least one admin user exists."""
        conn = self._connect()
        try:
            row = conn.execute("SELECT 1 FROM users WHERE role = 'admin' LIMIT 1").fetchone()
            return row is not None
        finally:
            conn.close()
    def has_admin_with_password(self) -> bool:
        """Return True when at least one admin user with a password hash exists."""
        conn = self._connect()
@@ -190,6 +190,8 @@ class DownloadClient(ABC):
    # Class attributes that subclasses must define
    protocol: str
    name: str
    handoff_only = False
    prefers_torrent_file = False
    def _log_error(self, method: str, e: Exception, level: str = "error") -> str:
        """Log a client error with consistent formatting.
@@ -375,12 +377,14 @@ _CLIENTS: dict[str, list[type[DownloadClient]]] = {}
 ClientType = TypeVar("ClientType", bound=DownloadClient)
 _BUILTIN_CLIENT_MODULES = (
    "shelfmark.download.clients.alldebrid",
    "shelfmark.download.clients.blackhole",
    "shelfmark.download.clients.deluge",
    "shelfmark.download.clients.nzbget",
    "shelfmark.download.clients.qbittorrent",
    "shelfmark.download.clients.realdebrid",
    "shelfmark.download.clients.rtorrent",
    "shelfmark.download.clients.sabnzbd",
    "shelfmark.download.clients.torbox",
    "shelfmark.download.clients.transmission",
 )
 _builtin_client_state = {"loaded": False}
@@ -467,6 +471,15 @@ def list_configured_clients() -> list[str]:
    return result
 def client_prefers_torrent_file(protocol: str) -> bool:
    """Whether the active client needs a fetched .torrent file instead of a magnet."""
    _ensure_builtin_clients_registered()
    return any(
        client_cls.prefers_torrent_file and client_cls.is_configured()
        for client_cls in _CLIENTS.get(protocol, [])
    )
 def get_all_clients() -> dict[str, list[type[DownloadClient]]]:
    """Get all registered client classes.
@@ -24,7 +24,7 @@ from shelfmark.download.clients import (
 )
 from shelfmark.download.fs import run_blocking_io
 from shelfmark.download.permissions_debug import log_path_permission_context
-from shelfmark.release_sources import DownloadHandler
+from shelfmark.release_sources import DownloadHandler, HandoffResult
 if TYPE_CHECKING:
    from collections.abc import Callable
@@ -762,8 +762,8 @@ class ExternalClientHandler(DownloadHandler, ABC):
        cancel_flag: Event,
        progress_callback: Callable[[float], None],
        status_callback: Callable[[str, str | None], None],
-    ) -> str | None:
+    ) -> str | HandoffResult | None:
-        """Execute download via configured torrent/usenet client. Returns file path or None."""
+        """Execute download via configured torrent/usenet client."""
        try:
            if cancel_flag.is_set():
                status_callback("cancelled", "Cancelled")
@@ -871,6 +871,33 @@ class ExternalClientHandler(DownloadHandler, ABC):
                logger.info(
                    "Added to %s: %s for '%s'", client.name, download_id, request.release_name
                )
                if getattr(client, "handoff_only", False) is True:
                    if cancel_flag.is_set():
                        # The file is published and unpublishing it would race a watcher
                        # that may already have consumed it, so the handoff stands even
                        # though the task is cancelled. Say so rather than leaving a bare
                        # "Cancelled" the user cannot act on.
                        logger.info(
                            "Cancelled after handoff to %s; leaving publication in place: %s",
                            client.name,
                            download_id,
                        )
                        status_callback(
                            "cancelled",
                            f"Cancelled, but the torrent was already handed off to {client.name}",
                        )
                        return None
                    # A watcher can consume the publication as soon as add_download returns,
                    # so the handoff completes here rather than in the poll loop. The
                    # orchestrator deliberately does not check that this path still exists:
                    # a consumed publication is indistinguishable from a bogus one, and
                    # treating it as an error is the failure this avoids (#1345).
                    progress_callback(100)
                    self._on_download_complete(task)
                    return HandoffResult(
                        path=download_id,
                        message=f"Torrent file saved to {download_id}",
                    )
            # Poll for progress
            return self._poll_and_complete(
@@ -0,0 +1,113 @@
 """Blackhole download client that saves torrent files for an external watcher."""
 from __future__ import annotations
 import os
 import tempfile
 from pathlib import Path
 from shelfmark.core.config import config
 from shelfmark.core.naming import sanitize_filename
 from shelfmark.download.clients import (
    DownloadClient,
    DownloadState,
    DownloadStatus,
    register_client,
 )
 from shelfmark.download.clients._coercion import config_text
 from shelfmark.download.clients.torrent_utils import extract_torrent_info
@register_client("torrent")
 class BlackholeClient(DownloadClient):
    """Write fetched torrent files to a directory watched by another downloader."""
    protocol = "torrent"
    name = "blackhole"
    handoff_only = True
    prefers_torrent_file = True
    def __init__(self) -> None:
        directory = config_text(config.get("BLACKHOLE_DIRECTORY", ""))
        if not directory:
            msg = "BLACKHOLE_DIRECTORY is required"
            raise ValueError(msg)
        self._directory = Path(directory)
    @staticmethod
    def is_configured() -> bool:
        return config_text(config.get("PROWLARR_TORRENT_CLIENT", "")) == "blackhole" and bool(
            config_text(config.get("BLACKHOLE_DIRECTORY", ""))
        )
    def test_connection(self) -> tuple[bool, str]:
        try:
            self._directory.mkdir(parents=True, exist_ok=True)
        except OSError as error:
            return False, f"Could not create Blackhole directory: {error}"
        return True, f"Blackhole directory is ready: {self._directory}"
    def add_download(
        self,
        url: str,
        name: str,
        category: str | None = None,
        expected_hash: str | None = None,
        **kwargs: object,
    ) -> str:
        torrent_info = extract_torrent_info(url, expected_hash=expected_hash)
        if not torrent_info.torrent_data:
            msg = "Blackhole requires a .torrent file; this release only provides a magnet link"
            raise ValueError(msg)
        self._directory.mkdir(parents=True, exist_ok=True)
        filename = f"{sanitize_filename(name) or 'torrent'}.torrent"
        destination = self._next_destination(filename)
        file_descriptor, temporary_path = tempfile.mkstemp(
            dir=self._directory,
            prefix=".blackhole-",
            suffix=".tmp",
        )
        try:
            with os.fdopen(file_descriptor, "wb") as temporary_file:
                temporary_file.write(torrent_info.torrent_data)
                temporary_file.flush()
                os.fsync(temporary_file.fileno())
            Path(temporary_path).replace(destination)
        except Exception:
            Path(temporary_path).unlink(missing_ok=True)
            raise
        return str(destination)
    def get_status(self, download_id: str) -> DownloadStatus:
        file_path = Path(download_id)
        if file_path.is_file():
            return DownloadStatus(
                progress=100,
                state=DownloadState.COMPLETE,
                message="Torrent file saved",
                complete=True,
                file_path=str(file_path),
            )
        return DownloadStatus.error("Blackhole torrent file was not created")
    def remove(self, download_id: str, *, delete_files: bool = False) -> bool:
        return False
    def get_download_path(self, download_id: str) -> str | None:
        return download_id if Path(download_id).is_file() else None
    def _next_destination(self, filename: str) -> Path:
        candidate = self._directory / filename
        if not candidate.exists():
            return candidate
        stem = Path(filename).stem
        suffix = Path(filename).suffix
        index = 1
        while True:
            candidate = self._directory / f"{stem}_{index}{suffix}"
            if not candidate.exists():
                return candidate
            index += 1
@@ -292,11 +292,14 @@ class DelugeClient(DownloadClient):
            # Per-torrent seeding limits from indexer
            seeding_time_limit = coerce_optional_int(kwargs.get("seeding_time_limit"))
            if seeding_time_limit is not None:
-                options["seed_time_limit"] = seeding_time_limit
+                logger.debug(
                    "Deluge has no per-torrent seeding time limit, ignoring %s minutes",
                    seeding_time_limit,
                )
            ratio_limit = coerce_optional_float(kwargs.get("ratio_limit"))
            if ratio_limit is not None:
-                options["stop_at_ratio"] = ratio_limit
+                options["stop_ratio"] = ratio_limit
-                options["stop_at_ratio_enabled"] = True
+                options["stop_at_ratio"] = True
            if torrent_info.is_magnet:
                magnet_url = torrent_info.magnet_url or url
@@ -50,6 +50,7 @@ _STATUS_DOWNLOADING = frozenset(
    {
        "magnet_conversion",
        "waiting_files_selection",
        "queued",
        "downloading",
        "compressing",
        "uploading",
@@ -565,6 +565,23 @@ def _test_realdebrid_connection(current_values: dict[str, Any] | None = None) ->
    return {"success": success, "message": message}
 def _test_torbox_connection(current_values: dict[str, Any] | None = None) -> dict[str, Any]:
    """Test the TorBox API connection using current form values."""
    from shelfmark.core.config import config
    from shelfmark.download.clients.torbox import TorBoxClient
    current_values = current_values or {}
    api_key = _resolve_string_setting(current_values, config.get, "TORBOX_API_KEY")
    if not api_key:
        return {"success": False, "message": "TorBox API Key is required"}
    client = TorBoxClient()
    client._api_key = api_key
    success, message = client.test_connection()
    return {"success": success, "message": message}
 # ==================== Download Clients Tab ====================
@@ -590,14 +607,23 @@ def prowlarr_clients_settings() -> list[SettingsField]:
            options=[
                {"value": "", "label": "None"},
                {"value": "alldebrid", "label": "AllDebrid"},
                {"value": "blackhole", "label": "Blackhole"},
                {"value": "qbittorrent", "label": "qBittorrent"},
                {"value": "realdebrid", "label": "Real-Debrid"},
                {"value": "torbox", "label": "TorBox"},
                {"value": "transmission", "label": "Transmission"},
                {"value": "deluge", "label": "Deluge"},
                {"value": "rtorrent", "label": "rTorrent"},
            ],
            default="",
        ),
        TextField(
            key="BLACKHOLE_DIRECTORY",
            label="Blackhole Directory",
            description="Directory where Shelfmark saves .torrent files for another downloader",
            placeholder="/blackhole",
            show_when={"field": "PROWLARR_TORRENT_CLIENT", "value": "blackhole"},
        ),
        # --- AllDebrid Settings ---
        PasswordField(
            key="ALLDEBRID_API_KEY",
@@ -628,6 +654,21 @@ def prowlarr_clients_settings() -> list[SettingsField]:
            callback=_test_realdebrid_connection,
            show_when={"field": "PROWLARR_TORRENT_CLIENT", "value": "realdebrid"},
        ),
        # --- TorBox Settings ---
        PasswordField(
            key="TORBOX_API_KEY",
            label="API Key",
            description="TorBox API Key from your TorBox account settings",
            show_when={"field": "PROWLARR_TORRENT_CLIENT", "value": "torbox"},
        ),
        ActionButton(
            key="test_torbox",
            label="Test Connection",
            description="Verify your TorBox configuration",
            style="primary",
            callback=_test_torbox_connection,
            show_when={"field": "PROWLARR_TORRENT_CLIENT", "value": "torbox"},
        ),
        # --- qBittorrent Settings ---
        TextField(
            key="QBITTORRENT_URL",
@@ -0,0 +1,618 @@
 """TorBox debrid service client for Shelfmark."""
 from __future__ import annotations
 import math
 import shutil
 import threading
 from dataclasses import dataclass, field
 from pathlib import Path, PurePosixPath, PureWindowsPath
 from typing import Any, ClassVar, NoReturn
 from urllib.parse import urlparse
 import requests
 from shelfmark.config.env import TMP_DIR
 from shelfmark.core.config import config
 from shelfmark.core.logger import setup_logger
 from shelfmark.download.clients import (
    DownloadClient,
    DownloadState,
    DownloadStatus,
    register_client,
 )
 from shelfmark.download.clients._coercion import config_text
 from shelfmark.download.clients.torrent_utils import (
    DebridMagnet,
    DebridUpload,
    resolve_debrid_upload,
 )
 from shelfmark.download.http import download_url
 from shelfmark.download.network import get_ssl_verify
 logger = setup_logger(__name__)
 _API_BASE = "https://api.torbox.app/v1/api"
 _API_TIMEOUT = 30
 _STATUS_TIMEOUT = 15
 _WORKER_JOIN_TIMEOUT = 5.0
 _BOOK_EXTENSIONS = (
    ".aac",
    ".azw",
    ".azw3",
    ".cbr",
    ".cbz",
    ".djvu",
    ".doc",
    ".docx",
    ".epub",
    ".fb2",
    ".flac",
    ".lit",
    ".m4a",
    ".m4b",
    ".mobi",
    ".mp3",
    ".mp4",
    ".ogg",
    ".opus",
    ".pdf",
    ".rtf",
    ".txt",
    ".wma",
 )
 _TERMINAL_STATES = frozenset({"error", "failed", "missingfiles", "dead"})
 _PLAN_NAMES = {0: "Free", 1: "Essential", 2: "Pro", 3: "Standard"}
 def _raise_runtime_error(message: str) -> NoReturn:
    raise RuntimeError(message)
@dataclass
 class _DownloadState:
    """Internal mutable state for an in-progress TorBox download."""
    torrent_id: str
    name: str
    target_dir: Path
    phase: str = "waiting_torbox"
    error_message: str | None = None
    progress: float = 0.0
    download_thread: threading.Thread | None = None
    cancel_event: threading.Event = field(default_factory=threading.Event)
    lock: threading.Lock = field(default_factory=threading.Lock)
@register_client("torrent")
 class TorBoxClient(DownloadClient):
    """Download torrent content through TorBox and its CDN."""
    protocol = "torrent"
    name = "torbox"
    prefers_torrent_file = True
    _downloads: ClassVar[dict[str, _DownloadState]] = {}
    _downloads_lock = threading.Lock()
    def __init__(self) -> None:
        self._api_key = config_text(config.get("TORBOX_API_KEY", ""))
    def _auth_headers(self) -> dict[str, str]:
        """Return the authorization headers used by TorBox API calls."""
        return {"Authorization": f"Bearer {self._api_key}"}
    @staticmethod
    def is_configured() -> bool:
        """Return True when TorBox is selected and an API key exists."""
        client = config_text(config.get("PROWLARR_TORRENT_CLIENT", ""))
        api_key = config_text(config.get("TORBOX_API_KEY", ""))
        return client == "torbox" and bool(api_key)
    def test_connection(self) -> tuple[bool, str]:
        """Validate the API key and report the connected TorBox plan."""
        if not self._api_key:
            return False, "TorBox API Key is required"
        try:
            user = self._request_data(
                "GET",
                "/user/me",
                operation="account lookup",
                params={"settings": "false"},
                timeout=_STATUS_TIMEOUT,
            )
            if not isinstance(user, dict):
                _raise_runtime_error("TorBox account lookup returned invalid user data")
        except (
            OSError,
            requests.exceptions.RequestException,
            RuntimeError,
            TypeError,
            ValueError,
        ) as e:
            return False, f"Connection failed: {e}"
        plan_value = user.get("plan")
        plan = _PLAN_NAMES.get(plan_value, "Unknown") if isinstance(plan_value, int) else "Unknown"
        email = user.get("email")
        account = f" as '{email}'" if isinstance(email, str) and email else ""
        return True, f"Connected to TorBox{account} ({plan} plan)"
    def add_download(
        self,
        url: str,
        name: str,
        category: str | None = None,
        expected_hash: str | None = None,
        **kwargs: Any,
    ) -> str:
        """Send a magnet or torrent file to TorBox and return its torrent ID."""
        if not self._api_key:
            _raise_runtime_error("TorBox API key is not configured")
        try:
            upload = resolve_debrid_upload(url, expected_hash=expected_hash)
            data = self._send_torrent(upload, name)
            torrent_id = self._normalize_torrent_id(data.get("torrent_id"))
            target_dir = TMP_DIR / f"torbox_{torrent_id}"
            target_dir.mkdir(parents=True, exist_ok=True)
            state = _DownloadState(torrent_id=torrent_id, name=name, target_dir=target_dir)
            with self._downloads_lock:
                self._downloads[torrent_id] = state
            logger.info(
                "Added torrent to TorBox: ID %s", torrent_id, extra={"torrent_id": torrent_id}
            )
        except Exception:
            logger.exception("Failed to add torrent to TorBox")
            raise
        else:
            return torrent_id
    def _send_torrent(self, upload: DebridUpload, name: str) -> dict[str, Any]:
        """Create a TorBox torrent from a magnet link or torrent file."""
        endpoint = "/torrents/createtorrent"
        data: dict[str, str] = {"name": name}
        files: dict[str, tuple[str, bytes, str]] | None = None
        if isinstance(upload, DebridMagnet):
            data["magnet"] = upload.magnet_url
        else:
            files = {
                "file": (
                    "release.torrent",
                    upload.torrent_data,
                    "application/x-bittorrent",
                )
            }
        result = self._request_data(
            "POST",
            endpoint,
            operation="torrent creation",
            data=data,
            files=files,
            timeout=_API_TIMEOUT,
        )
        if not isinstance(result, dict):
            _raise_runtime_error("TorBox torrent creation returned invalid data")
        return result
    def get_status(self, download_id: str) -> DownloadStatus:
        """Poll TorBox for torrent status and drive local file retrieval."""
        download_id = self._normalize_torrent_id(download_id)
        state = self._ensure_state(download_id)
        with state.lock:
            if state.phase == "error":
                return DownloadStatus.error(state.error_message or "TorBox download failed")
            if state.phase == "complete":
                return DownloadStatus(
                    progress=100.0,
                    state=DownloadState.COMPLETE,
                    message="Complete",
                    complete=True,
                    file_path=str(state.target_dir),
                )
            if state.phase == "downloading_http":
                return DownloadStatus(
                    progress=state.progress,
                    state=DownloadState.DOWNLOADING,
                    message="Downloading files via TorBox...",
                    complete=False,
                    file_path=None,
                )
        try:
            data = self._request_data(
                "GET",
                "/torrents/mylist",
                operation="torrent status lookup",
                params={"id": download_id, "bypass_cache": "true"},
                timeout=_STATUS_TIMEOUT,
            )
            torrent = self._extract_torrent(data, download_id)
            return self._handle_torrent_status(torrent, state)
        except Exception as e:
            logger.exception(
                "Failed to check TorBox torrent status",
                extra={"torrent_id": download_id},
            )
            return DownloadStatus.error(f"TorBox status check failed: {e}")
    def remove(self, download_id: str, *, delete_files: bool = False) -> bool:
        """Delete the remote torrent and clean up its local temporary directory."""
        download_id = self._normalize_torrent_id(download_id)
        remote_removed = True
        try:
            self._request_data(
                "POST",
                "/torrents/controltorrent",
                operation="torrent deletion",
                json={"torrent_id": int(download_id), "operation": "delete"},
                timeout=_STATUS_TIMEOUT,
                require_data=False,
            )
        except OSError, requests.exceptions.RequestException, RuntimeError, TypeError, ValueError:
            remote_removed = False
            logger.warning("Failed to delete TorBox torrent", extra={"torrent_id": download_id})
        with self._downloads_lock:
            state = self._downloads.get(download_id)
        if state:
            with state.lock:
                state.cancel_event.set()
            if state.download_thread and state.download_thread is not threading.current_thread():
                state.download_thread.join(_WORKER_JOIN_TIMEOUT)
                if state.download_thread.is_alive():
                    logger.warning(
                        "TorBox retrieval thread did not stop; deferring cleanup",
                        extra={"torrent_id": download_id},
                    )
                    return False
            with self._downloads_lock:
                state = self._downloads.pop(download_id, None)
        target_dir = state.target_dir if state else TMP_DIR / f"torbox_{download_id}"
        local_removed = True
        if target_dir.exists():
            try:
                shutil.rmtree(target_dir)
            except OSError:
                local_removed = False
                logger.warning(
                    "Failed to remove TorBox temporary files",
                    extra={"torrent_id": download_id},
                )
        return remote_removed and local_removed
    def get_download_path(self, download_id: str) -> str | None:
        """Return the local directory once TorBox files have been retrieved."""
        download_id = self._normalize_torrent_id(download_id)
        with self._downloads_lock:
            state = self._downloads.get(download_id)
        if state and state.phase == "complete":
            return str(state.target_dir)
        return None
    def _request_data(
        self,
        method: str,
        endpoint: str,
        *,
        operation: str,
        require_data: bool = True,
        **kwargs: object,
    ) -> Any:
        """Send a TorBox request and validate its JSON response envelope."""
        url = f"{_API_BASE}{endpoint}"
        request_kwargs: Any = {
            "headers": self._auth_headers(),
            "verify": get_ssl_verify(url),
            **kwargs,
        }
        request: Any = requests.get if method == "GET" else requests.post
        try:
            response = request(url, **request_kwargs)
        except requests.exceptions.RequestException as e:
            raise RuntimeError(f"TorBox {operation} failed: {type(e).__name__}") from None
        try:
            payload = response.json()
        except (AttributeError, TypeError, ValueError) as e:
            _raise_runtime_error(f"TorBox {operation} returned invalid JSON: {e}")
        if not isinstance(payload, dict):
            _raise_runtime_error(f"TorBox {operation} returned an invalid response")
        error = payload.get("error")
        detail = payload.get("detail")
        status_code = getattr(response, "status_code", 200)
        if not isinstance(status_code, int) or not 200 <= status_code < 300:
            message = detail if isinstance(detail, str) and detail else f"HTTP {status_code}"
            code = f" [{error}]" if isinstance(error, str) and error else ""
            _raise_runtime_error(f"TorBox {operation} failed{code}: {message}")
        if payload.get("success") is not True or error:
            message = detail if isinstance(detail, str) and detail else "Unknown TorBox error"
            code = f" [{error}]" if isinstance(error, str) and error else ""
            _raise_runtime_error(f"TorBox {operation} failed{code}: {message}")
        data = payload.get("data")
        if require_data and data is None:
            _raise_runtime_error(f"TorBox {operation} returned no data")
        return data
    def _ensure_state(self, download_id: str) -> _DownloadState:
        """Get or create download state for a TorBox torrent ID."""
        download_id = self._normalize_torrent_id(download_id)
        with self._downloads_lock:
            state = self._downloads.get(download_id)
            if state is None:
                state = _DownloadState(
                    torrent_id=download_id,
                    name=f"Download {download_id}",
                    target_dir=TMP_DIR / f"torbox_{download_id}",
                )
                self._downloads[download_id] = state
        return state
    @staticmethod
    def _normalize_torrent_id(value: object) -> str:
        """Return a canonical positive decimal TorBox torrent ID."""
        torrent_id = str(value) if value is not None else ""
        if not torrent_id.isascii() or not torrent_id.isdecimal():
            _raise_runtime_error("TorBox returned an invalid torrent ID")
        normalized = str(int(torrent_id))
        if normalized == "0":
            _raise_runtime_error("TorBox returned an invalid torrent ID")
        return normalized
    @staticmethod
    def _extract_torrent(data: Any, download_id: str) -> dict[str, Any]:
        """Extract the requested torrent from TorBox's object or list response."""
        if isinstance(data, dict):
            return data
        if isinstance(data, list):
            for torrent in data:
                if isinstance(torrent, dict) and str(torrent.get("id", "")) == download_id:
                    return torrent
        _raise_runtime_error(f"TorBox torrent {download_id} was not found")
    def _handle_torrent_status(
        self,
        torrent: dict[str, Any],
        state: _DownloadState,
    ) -> DownloadStatus:
        """Map a TorBox torrent object into Shelfmark download status."""
        remote_state = str(torrent.get("download_state", "unknown"))
        normalized_state = remote_state.lower()
        if normalized_state in _TERMINAL_STATES:
            message = torrent.get("tracker_message") or f"TorBox status error: {remote_state}"
            self._set_error(state, str(message))
            return DownloadStatus.error(str(message))
        finished = torrent.get("download_finished") is True
        present = torrent.get("download_present") is True
        if finished and not present:
            message = "TorBox finished processing but the download is unavailable"
            self._set_error(state, message)
            return DownloadStatus.error(message)
        if finished and present:
            files = torrent.get("files")
            if not isinstance(files, list):
                message = "TorBox returned no file list for a completed torrent"
                self._set_error(state, message)
                return DownloadStatus.error(message)
            self._maybe_start_download_thread(state, files)
            return DownloadStatus(
                progress=50.0,
                state=DownloadState.DOWNLOADING,
                message="TorBox ready, retrieving files...",
                complete=False,
                file_path=None,
            )
        progress = self._normalize_remote_progress(torrent.get("progress")) * 0.5
        speed = self._integer_value(torrent.get("download_speed"))
        eta = self._integer_value(torrent.get("eta"))
        name = torrent.get("name") or state.name
        return DownloadStatus(
            progress=progress,
            state=DownloadState.DOWNLOADING,
            message=f"TorBox processing torrent ({name}: {remote_state})",
            complete=False,
            file_path=None,
            download_speed=speed,
            eta=eta,
        )
    @staticmethod
    def _normalize_remote_progress(value: object) -> float:
        """Normalize fractional or percentage TorBox progress to 0 through 100."""
        if not isinstance(value, int | float | str):
            return 0.0
        try:
            progress = float(value)
        except TypeError, ValueError:
            return 0.0
        if not math.isfinite(progress):
            return 0.0
        if 0.0 <= progress <= 1.0:
            progress *= 100.0
        return max(0.0, min(100.0, progress))
    @staticmethod
    def _integer_value(value: object) -> int | None:
        """Return an integer metric when TorBox provided a numeric value."""
        if not isinstance(value, int | float | str):
            return None
        try:
            return int(value)
        except TypeError, ValueError:
            return None
    def _maybe_start_download_thread(
        self,
        state: _DownloadState,
        files: list[dict[str, Any]],
    ) -> None:
        """Start exactly one background worker to retrieve TorBox files."""
        with state.lock:
            already_running = state.phase in {"downloading_http", "complete"}
            thread_alive = state.download_thread is not None and state.download_thread.is_alive()
            if already_running or thread_alive:
                return
            state.phase = "downloading_http"
            state.progress = 50.0
            state.download_thread = threading.Thread(
                target=self._process_and_download,
                args=(state, files),
                daemon=True,
            )
            state.download_thread.start()
    def _process_and_download(self, state: _DownloadState, files: list[dict[str, Any]]) -> None:
        """Request direct file links from TorBox and download supported content."""
        try:
            if state.cancel_event.is_set():
                return
            relevant = [
                file_info
                for file_info in files
                if self._file_name(file_info).lower().endswith(_BOOK_EXTENSIONS)
            ]
            if not relevant:
                _raise_runtime_error("TorBox torrent contains no supported book or audiobook files")
            with state.lock:
                if state.cancel_event.is_set():
                    return
                state.target_dir.mkdir(parents=True, exist_ok=True)
            for index, file_info in enumerate(relevant, start=1):
                if state.cancel_event.is_set():
                    return
                file_id = self._file_id(file_info)
                relative_path = self._safe_relative_path(file_info, state.target_dir)
                direct_url = self._request_download_link(state.torrent_id, file_id)
                buffer = download_url(
                    direct_url,
                    referer="https://torbox.app/",
                    cancel_flag=state.cancel_event,
                )
                if state.cancel_event.is_set():
                    return
                if not buffer:
                    _raise_runtime_error(
                        f"TorBox file download failed for torrent {state.torrent_id}, file {file_id}"
                    )
                destination = state.target_dir / relative_path
                destination.parent.mkdir(parents=True, exist_ok=True)
                with destination.open("wb") as output:
                    buffer.seek(0)
                    shutil.copyfileobj(buffer, output)
                with state.lock:
                    state.progress = 50.0 + index / len(relevant) * 50.0
            with state.lock:
                if state.cancel_event.is_set():
                    return
                state.phase = "complete"
                state.progress = 100.0
            logger.info(
                "TorBox download complete: ID %s",
                state.torrent_id,
                extra={"torrent_id": state.torrent_id},
            )
        except Exception as e:
            if state.cancel_event.is_set():
                logger.info(
                    "TorBox file retrieval cancelled",
                    extra={"torrent_id": state.torrent_id},
                )
                return
            logger.exception(
                "TorBox file retrieval failed",
                extra={"torrent_id": state.torrent_id},
            )
            self._set_error(state, str(e) or "TorBox file retrieval failed")
    def _request_download_link(self, torrent_id: str, file_id: int) -> str:
        """Request a temporary direct link without exposing the token in messages."""
        data = self._request_data(
            "GET",
            "/torrents/requestdl",
            operation="file-link request",
            params={
                "token": self._api_key,
                "torrent_id": torrent_id,
                "file_id": file_id,
                "redirect": "false",
                "append_name": "true",
            },
            timeout=_API_TIMEOUT,
        )
        if not isinstance(data, str):
            _raise_runtime_error(
                f"TorBox returned an invalid download link for torrent {torrent_id}, file {file_id}"
            )
        parsed = urlparse(data)
        if parsed.scheme != "https" or not parsed.hostname:
            _raise_runtime_error(
                f"TorBox returned an invalid download link for torrent {torrent_id}, file {file_id}"
            )
        return data
    @staticmethod
    def _file_name(file_info: dict[str, Any]) -> str:
        """Return the provider path, falling back to its shortened name."""
        name = file_info.get("name")
        if isinstance(name, str) and name.strip():
            return name
        short_name = file_info.get("short_name")
        return short_name.strip() if isinstance(short_name, str) else ""
    @staticmethod
    def _file_id(file_info: dict[str, Any]) -> int:
        """Return a validated TorBox file ID."""
        try:
            return int(file_info["id"])
        except (KeyError, TypeError, ValueError) as e:
            _raise_runtime_error(f"TorBox returned an invalid file ID: {e}")
    @classmethod
    def _safe_relative_path(cls, file_info: dict[str, Any], target_dir: Path) -> Path:
        """Validate external file metadata before writing below ``target_dir``."""
        name = cls._file_name(file_info)
        if not name:
            _raise_runtime_error("TorBox returned a file without a name")
        normalized = name.replace("\\", "/")
        relative_path = PurePosixPath(normalized)
        windows_path = PureWindowsPath(name)
        if (
            relative_path.is_absolute()
            or windows_path.is_absolute()
            or windows_path.drive
            or ".." in relative_path.parts
        ):
            _raise_runtime_error(f"TorBox returned an unsafe file path: {name}")
        if relative_path == PurePosixPath("."):
            _raise_runtime_error("TorBox returned a file without a usable name")
        destination = (target_dir / Path(*relative_path.parts)).resolve()
        try:
            destination.relative_to(target_dir.resolve())
        except ValueError:
            _raise_runtime_error(f"TorBox returned an unsafe file path: {name}")
        return Path(*relative_path.parts)
    @staticmethod
    def _set_error(state: _DownloadState, message: str) -> None:
        """Record a terminal local error for later polling calls."""
        with state.lock:
            state.phase = "error"
            state.error_message = message
@@ -9,7 +9,7 @@ import time
 from binascii import Error as BinasciiError
 from dataclasses import dataclass
 from threading import Lock
-from urllib.parse import ParseResult, parse_qs, urljoin, urlparse
+from urllib.parse import ParseResult, parse_qs, urljoin, urlparse, urlunparse
 import requests
@@ -51,6 +51,28 @@ _torrent_fetch_cache: dict[str, tuple[float, TorrentInfo]] = {}
 type BencodeValue = dict[str | bytes, BencodeValue] | list[BencodeValue] | int | bytes | str
 def _safe_url(url: str, *, limit: int = 120) -> str:
    """Return a log-safe URL: scheme/host/path kept, query and fragment dropped.
    Torrent download URLs commonly carry credentials in their query string
    (Prowlarr's ``apikey=...`` proxy links among them), so raw URLs must never
    reach logs or exception messages.
    """
    parsed = urlparse(url)
    if not parsed.scheme or not parsed.netloc:
        return f"<unparsed url: {type(url).__name__}>"
    safe = urlunparse(parsed._replace(query="", fragment=""))
    return safe[:limit]
 _URL_IN_TEXT_PATTERN = re.compile(r"https?://\S+")
 def _redact_urls_in_text(text: str) -> str:
    """Scrub credential-bearing URLs out of free-form text such as exception messages."""
    return _URL_IN_TEXT_PATTERN.sub(lambda match: _safe_url(match.group(0)), text)
@dataclass
 class TorrentInfo:
    """Parsed information from a torrent URL."""
@@ -133,7 +155,7 @@ def resolve_debrid_upload(url: str, *, expected_hash: str | None = None) -> Debr
        return DebridMagnet(magnet_url=f"magnet:?xt=urn:btih:{info.info_hash}")
    reason = info.fetch_error or "no magnet link, info hash, or torrent file was available"
-    msg = f"Could not resolve a torrent to send from {url[:120]} ({reason})"
+    msg = f"Could not resolve a torrent to send from {_safe_url(url)} ({reason})"
    raise ValueError(msg)
@@ -185,7 +207,7 @@ def _get_cached_torrent_fetch(url: str) -> TorrentInfo | None:
        if time.monotonic() - fetched_at > _TORRENT_FETCH_CACHE_TTL_SECONDS:
            del _torrent_fetch_cache[url]
            return None
-    logger.debug("Reusing recently fetched torrent data for: %s...", url[:80])
+    logger.debug("Reusing recently fetched torrent data for: %s...", _safe_url(url))
    return info
@@ -231,7 +253,7 @@ def _fetch_torrent_info(url: str) -> TorrentInfo:
        return urljoin(current, location)
    try:
-        logger.debug("Fetching torrent file from: %s...", url[:80])
+        logger.debug("Fetching torrent file from: %s...", _safe_url(url))
        # Redirects are followed manually: some indexers redirect download URLs
        # to magnet links, and each hop must decide anew whether it may see the
@@ -264,7 +286,7 @@ def _fetch_torrent_info(url: str) -> TorrentInfo:
                    magnet_url=redirect_url,
                )
            if redirects_remaining <= 0:
-                logger.warning("Too many redirects fetching torrent file: %s...", url[:80])
+                logger.warning("Too many redirects fetching torrent file: %s...", _safe_url(url))
                return TorrentInfo(
                    info_hash=None,
                    torrent_data=None,
@@ -272,7 +294,7 @@ def _fetch_torrent_info(url: str) -> TorrentInfo:
                    fetch_error="too many redirects",
                )
            redirects_remaining -= 1
-            logger.debug("Following redirect to: %s...", redirect_url[:80])
+            logger.debug("Following redirect to: %s...", _safe_url(redirect_url))
            current_url = redirect_url
        resp.raise_for_status()
@@ -298,8 +320,11 @@ def _fetch_torrent_info(url: str) -> TorrentInfo:
            logger.warning("Could not extract hash from torrent file")
        return TorrentInfo(info_hash=info_hash, torrent_data=torrent_data, is_magnet=False)
    except _TORRENT_FETCH_ERRORS as e:
-        logger.warning("Could not fetch torrent file: %s", e)
+        # Exception messages can repeat the source or redirect URL, including its
-        return TorrentInfo(info_hash=None, torrent_data=None, is_magnet=False, fetch_error=str(e))
+        # credentials; scrub them before logging or storing the reason.
        message = _redact_urls_in_text(str(e))
        logger.warning("Could not fetch torrent file: %s: %s", type(e).__name__, message)
        return TorrentInfo(info_hash=None, torrent_data=None, is_magnet=False, fetch_error=message)
 def _is_trusted_torrent_fetch_url(url: str) -> bool:
@@ -12,6 +12,7 @@ from tqdm import tqdm
 from shelfmark.bypass import BypassCancelledError, ChallengeNotSolvedError, cookie_store
 from shelfmark.bypass.challenge import challenge_marker
 from shelfmark.bypass.waiting_room import WaitingRoomTimeoutError, is_aa_waiting_room
 from shelfmark.core import search_deadline
 from shelfmark.core.config import config as app_config
 from shelfmark.core.logger import setup_logger
@@ -325,10 +326,10 @@ def _try_rotation(
        )
        if action in ("mirror", "dns") and new_base:
            new_url = selector.rewrite(original_url)
-            logger.info("[%s] switching to: %s", action, new_url)
+            logger.info("[%s] switching mirror", action)
            return new_url
    elif network.should_rotate_dns_for_url(current_url) and network.rotate_dns_provider():
-        logger.info("[dns-rotate] retrying: %s", original_url)
+        logger.info("[dns-rotate] retrying download")
        return original_url
    return None
@@ -440,6 +441,9 @@ def html_get_page(
                except _STATUS_CALLBACK_ERRORS:
                    logger.debug("Rate-limit status callback failed", exc_info=True)
            return _fail(str(e), bypass_url)
        except WaitingRoomTimeoutError as e:
            logger.info("Waiting room timed out: %s", e)
            return _fail(str(e), bypass_url)
        except ChallengeNotSolvedError as e:
            # Not a bypasser malfunction: it ran, and the host answered with something it
            # cannot clear - DDoS-Guard's manual CAPTCHA, typically. Must precede the
@@ -705,6 +709,14 @@ def html_get_page(
                    continue
                response.raise_for_status()
                if (
                    _bypass_handoff_allowed()
                    and not _is_using_external_bypasser()
                    and is_aa_waiting_room(current_url, response.text)
                ):
                    # A successful HTTP response can still need a live browser: the
                    # queue's JavaScript must finish in the session that entered it.
                    return _run_bypasser(current_url)
                if success_delay > 0:
                    time.sleep(success_delay)
                return _result(response.text, response.url)
@@ -868,12 +880,7 @@ def download_url(
                    f"Connecting (Attempt {attempt + 1}/{MAX_DOWNLOAD_RETRIES})",
                )
-            logger.info(
+            logger.info("Downloading (attempt %s/%s)", attempt + 1, MAX_DOWNLOAD_RETRIES)
                "Downloading: %s (attempt %s/%s)",
                current_url,
                attempt + 1,
                MAX_DOWNLOAD_RETRIES,
            )
            # Try with CF cookies/UA if available
            cookies = _apply_cf_bypass(current_url, headers)
            response = requests.get(
@@ -911,7 +918,7 @@ def download_url(
                and bytes_downloaded < total_size * 0.9
                and response.headers.get("content-type", "").startswith("text/html")
            ):
-                logger.warning("Received HTML instead of file: %s", current_url)
+                logger.warning("Received HTML instead of file")
                return None
            logger.debug("Download completed: %s bytes", bytes_downloaded)
@@ -929,18 +936,21 @@ def download_url(
                parsed = urlparse(current_url)
                if _is_configured_zlib_host(parsed.hostname) and referer:
                    zlib_cookie_refresh_attempted = True
-                    logger.info("Z-Library 403 - refreshing cookies via referer: %s", referer)
+                    logger.info("Z-Library 403 - refreshing cookies via referer")
                    try:
                        get_bypassed_page(referer, selector, cancel_flag)
                        time.sleep(0.5)
                        # Retry with fresh cookies (don't increment attempt)
                        continue
                    except _BYPASSER_ERRORS as cookie_err:
-                        logger.warning("Z-Library cookie refresh failed: %s", cookie_err)
+                        logger.warning(
                            "Z-Library cookie refresh failed: %s",
                            type(cookie_err).__name__,
                        )
            # Non-retryable errors
            if status in _HTTP_STATUS_NON_RETRYABLE:
-                logger.warning("Download failed (%s): %s", status, current_url)
+                logger.warning("Download failed (%s)", status)
                return None
            # Rate limited - skip to next source immediately
@@ -954,7 +964,7 @@ def download_url(
            # Timeout - don't retry, server likely overloaded
            if isinstance(e, requests.exceptions.Timeout):
-                logger.warning("Timeout: %s - skipping to next source", current_url)
+                logger.warning("Timeout - skipping to next source")
                if status_callback:
                    status_callback("resolving", "Server timed out, trying next")
                return None
@@ -981,14 +991,14 @@ def download_url(
                    attempt += 1
                    continue
-            logger.warning("Download error: %s: %s", type(e).__name__, e)
+            logger.warning("Download error: %s", type(e).__name__)
            if attempt < MAX_DOWNLOAD_RETRIES - 1:
                time.sleep(_backoff_delay(attempt + 1))
            attempt += 1
        else:
            return buffer
-    logger.error("Download failed after %s attempts: %s", MAX_DOWNLOAD_RETRIES, link)
+    logger.error("Download failed after %s attempts", MAX_DOWNLOAD_RETRIES)
    return None
@@ -1078,7 +1088,7 @@ def _try_resume(
            logger.info("Resume completed: %s bytes", start_byte)
        except requests.exceptions.RequestException as e:
-            logger.debug("Resume attempt %s failed: %s", attempt + 1, e)
+            logger.debug("Resume attempt %s failed: %s", attempt + 1, type(e).__name__)
        else:
            return buffer
@@ -1094,5 +1104,7 @@ def get_absolute_url(base_url: str, url: str) -> str:
    parsed = urlparse(url)
    base = urlparse(base_url)
    if not parsed.netloc or not parsed.scheme:
-        parsed = parsed._replace(netloc=base.netloc, scheme=base.scheme)
+        parsed = parsed._replace(
            netloc=parsed.netloc or base.netloc, scheme=parsed.scheme or base.scheme
        )
    return parsed.geturl()
@@ -29,6 +29,7 @@ from shelfmark.download.fs import run_blocking_io
 from shelfmark.download.postprocess.pipeline import is_torrent_source, safe_cleanup_path
 from shelfmark.download.postprocess.router import post_process_download
 from shelfmark.release_sources import (
    HandoffResult,
    get_handler,
    get_source,
    get_source_display_name,
@@ -295,6 +296,7 @@ def queue_release(
            year=year,
            format=release_data.get("format"),
            size=release_data.get("size"),
            downloads=release_data.get("downloads") or extra.get("downloads"),
            preview=preview,
            content_type=content_type,
            source_url=source_url,
@@ -318,7 +320,14 @@ def queue_release(
            logger.info("Release already in queue: %s", task.title)
            return False, "Release is already in the download queue"
-        logger.info("Release queued with priority %s: %s", priority, task.title)
+        logger.info(
            "Release queued with priority %s: %s (downloads=%s, release_data.downloads=%s, extra=%s)",
            priority,
            task.title,
            task.downloads,
            release_data.get("downloads"),
            extra,
        )
        # Broadcast status update via WebSocket
        if ws_manager:
@@ -520,6 +529,7 @@ def _restore_task_from_retry_payload(payload: object) -> DownloadTask | None:
        year=normalize_optional_text(payload.get("year")),
        format=normalize_optional_text(payload.get("format")),
        size=normalize_optional_text(payload.get("size")),
        downloads=int(payload["downloads"]) if payload.get("downloads") is not None else None,
        preview=normalize_optional_text(payload.get("preview")),
        content_type=normalize_optional_text(payload.get("content_type")),
        source_url=normalize_optional_text(payload.get("source_url")),
@@ -616,6 +626,7 @@ def _task_to_dict(
        "author": task.author,
        "format": task.format,
        "size": task.size,
        "downloads": task.downloads,
        "preview": preview,
        "content_type": task.content_type,
        "source": task.source,
@@ -750,6 +761,13 @@ def _download_task(task_id: str, cancel_flag: Event) -> str | None:
        if not temp_path:
            return None
        if isinstance(temp_path, HandoffResult):
            handoff_path = Path(temp_path.path)
            status_callback("complete", temp_path.message)
            handler.post_process_cleanup(task, success=True)
            _clear_task_error_state(task)
            return str(handoff_path)
        temp_file = Path(temp_path)
        if not run_blocking_io(temp_file.exists):
            logger.error("Handler returned non-existent path: %s", temp_path)
@@ -414,10 +414,29 @@ def match_plan_to_files(
            )
    unmatched = [p for p in book_files if p not in claimed]
-    if unmatched:
+    still_unmatched: list[Path] = []
    for p in unmatched:
        p_ext = p.suffix.lower().lstrip(".")
        is_chaptered = p_ext in _CHAPTERED_AUDIO_EXTENSIONS
        matching_groups = [g for g in groups if any(f.parent == p.parent for f in g.files)]
        target_group: BookGroup | None = None
        if len(matching_groups) == 1 and is_chaptered:
            target_group = matching_groups[0]
        elif len(plan) == 1 and len(groups) == 1 and is_chaptered:
            target_group = groups[0]
        if target_group is not None:
            target_group.files.append(p)
            claimed.add(p)
        else:
            still_unmatched.append(p)
    if still_unmatched:
        groups.extend(
            group_files_into_books(
-                unmatched, series_name=series_name, author_name=author_name, root=root
+                still_unmatched, series_name=series_name, author_name=author_name, root=root
            )
        )
    return groups
@@ -55,6 +55,17 @@ def get_file_organization(*, is_audiobook: bool) -> str:
    return mode if mode in ("none", "rename", "rename_and_group", "organize") else "rename"
 def get_word_separator() -> str:
    """Get the configured word separator for naming template values.
    Replaces whitespace inside each placeholder's rendered value (e.g. "Conan
    Doyle" -> "Conan.Doyle"). The setting holds the separator character
    directly (e.g. "." or "_"); empty means a plain space, which leaves
    values unchanged.
    """
    return _config_text(core_config.config.get("NAMING_WORD_SEPARATOR", "")) or " "
 def get_template(*, is_audiobook: bool, organization_mode: str) -> str:
    """Get the template for the content type and organization mode."""
    if is_audiobook:
@@ -187,7 +187,9 @@ def scan_directory_tree(
                file_path = Path(root) / filename
                suffix = file_path.suffix.lower()
-                if suffix in supported_exts:
+                # zip/rar can also be enabled as supported formats. Keep archives
                # out of book_files so they are extracted rather than imported whole.
                if suffix in supported_exts and not is_archive(file_path):
                    book_files.append(file_path)
                elif suffix in trackable_exts:
                    rejected_files.append(file_path)
@@ -25,7 +25,11 @@ from shelfmark.download.fs import (
    atomic_move,
    run_blocking_io,
 )
-from shelfmark.download.postprocess.policy import get_file_organization, get_template
+from shelfmark.download.postprocess.policy import (
    get_file_organization,
    get_template,
    get_word_separator,
 )
 from .packs import BookGroup, PackBook, group_files_into_books, match_plan_to_files
 from .scan import collect_directory_files, scan_directory_tree
@@ -198,6 +202,7 @@ def transfer_book_files(
    is_audiobook = check_audiobook(task.content_type)
    organization_mode = organization_mode or get_file_organization(is_audiobook=is_audiobook)
    word_separator = get_word_separator()
    groups = resolve_book_groups(task, book_files, organization_mode=organization_mode)
    if groups is not None:
@@ -229,6 +234,7 @@ def transfer_book_files(
                template,
                file_metadata,
                extension=ext or None,
                word_separator=word_separator,
            )
            run_blocking_io(dest_path.parent.mkdir, parents=True, exist_ok=True)
@@ -256,6 +262,7 @@ def transfer_book_files(
                    template,
                    file_metadata,
                    extension=ext or None,
                    word_separator=word_separator,
                )
                run_blocking_io(dest_path.parent.mkdir, parents=True, exist_ok=True)
@@ -289,7 +296,9 @@ def transfer_book_files(
            metadata = build_file_metadata(task, book_file)
            extension = book_file.suffix.lstrip(".") or task.format or ""
-            filename = parse_naming_template(template, metadata, allow_path_separators=False)
+            filename = parse_naming_template(
                template, metadata, allow_path_separators=False, word_separator=word_separator
            )
            filename = Path(filename).name if filename else ""
            if filename and extension:
                filename = f"{sanitize_filename(filename)}.{extension}"
@@ -483,7 +492,12 @@ def transfer_file_to_library(
    template_metadata = dict(metadata)
    template_metadata.setdefault("OriginalName", source_path.stem)
    dest_path = run_blocking_io(
-        build_library_path, library_base, template, template_metadata, extension
+        build_library_path,
        library_base,
        template,
        template_metadata,
        extension,
        word_separator=get_word_separator(),
    )
    run_blocking_io(dest_path.parent.mkdir, parents=True, exist_ok=True)
@@ -538,12 +552,14 @@ def transfer_directory_to_library(
            safe_cleanup_path(temp_file, task)
        return None
    word_separator = get_word_separator()
    base_library_path = run_blocking_io(
        build_library_path,
        library_base,
        template,
        metadata,
        extension=None,
        word_separator=word_separator,
    )
    run_blocking_io(base_library_path.parent.mkdir, parents=True, exist_ok=True)
@@ -574,7 +590,12 @@ def transfer_directory_to_library(
            ext = source_file.suffix.lstrip(".")
            file_metadata = {**metadata, "PartNumber": part_number}
            file_path = run_blocking_io(
-                build_library_path, library_base, template, file_metadata, extension=ext
+                build_library_path,
                library_base,
                template,
                file_metadata,
                extension=ext,
                word_separator=word_separator,
            )
            run_blocking_io(file_path.parent.mkdir, parents=True, exist_ok=True)
@@ -114,7 +114,7 @@ def run_warmup() -> bool:
        from shelfmark.core.models import SearchFilters
        from shelfmark.release_sources.direct_download import search_books
-        results = search_books(query, SearchFilters())
+        results, _ = search_books(query, SearchFilters())
    except Exception:
        # Broad by design: a warm-up must never take the app down, and the source
        # raises everything from network errors to parse failures.
@@ -14,7 +14,7 @@ from importlib import import_module
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, Callable, NoReturn, cast
-from flask import Flask, jsonify, request, send_file, send_from_directory, session
+from flask import Flask, g, jsonify, request, send_file, send_from_directory, session
 from flask_cors import CORS
 from flask_socketio import SocketIO, emit
 from werkzeug.middleware.proxy_fix import ProxyFix
@@ -42,6 +42,7 @@ from shelfmark.config.settings import (
    _SUPPORTED_BOOK_LANGUAGE,
    migrate_audiobook_format_settings,
 )
 from shelfmark.core import api_key as api_key_module  # module access lets tests monkeypatch the key
 from shelfmark.core import search_deadline
 from shelfmark.core.activity_view_state_service import ActivityViewStateService
 from shelfmark.core.auth_modes import (
@@ -398,7 +399,7 @@ def _resolve_policy_mode_for_current_user(*, source: Any, content_type: Any) ->
    auth_mode = get_auth_mode()
    if auth_mode == "none":
        return None
-    if session.get("is_admin", True):
+    if session.get("is_admin", False):
        return None
    if user_db is None:
        return None
@@ -550,7 +551,7 @@ if _is_debug_enabled():
            r"/*": {
                "origins": ["http://localhost:5173", "http://127.0.0.1:5173"],
                "supports_credentials": True,
-                "allow_headers": ["Content-Type", "Authorization"],
+                "allow_headers": ["Content-Type", "Authorization", "X-Api-Key"],
                "methods": ["GET", "POST", "PUT", "DELETE", "OPTIONS"],
            }
        },
@@ -658,6 +659,73 @@ logger.info(
 logger.info("Session cookie name: %s", SESSION_COOKIE_NAME)
 def _proxy_default_is_admin(db: UserDB) -> bool:
    """Role for a proxy user seen for the first time when no admin group is configured.
    The first account ever provisioned is an admin so the instance is never left without
    one; later accounts follow PROXY_AUTH_DEFAULT_ROLE (default: user).
    """
    if not db.has_admin():
        return True
    role = str(app_config.get("PROXY_AUTH_DEFAULT_ROLE", "user") or "user").strip().lower()
    return role == "admin"
 _API_KEY_EXEMPT_PREFIXES = ("/api/auth/",)
 _API_KEY_EXEMPT_PATHS = frozenset({"/api/health"})
@app.before_request
 def api_key_auth_middleware() -> Response | tuple[Response, int] | None:
    """Authenticate requests that present the configured SHELFMARK_API_KEY.
    Both Authorization: Bearer and X-Api-Key are checked, and either
    matching authenticates the request as an admin for this request only:
    any session cookie is ignored and none is written back. Checking both
    means a reverse proxy's own Authorization header never shadows an
    operator-supplied X-Api-Key. No matching candidate is ignored so bearer
    tokens forwarded by reverse proxies keep working; the request then
    continues on the normal session path.
    """
    if not request.path.startswith("/api/"):
        return None
    if request.path in _API_KEY_EXEMPT_PATHS or request.path.startswith(_API_KEY_EXEMPT_PREFIXES):
        return None
    if not api_key_module.SHELFMARK_API_KEY:
        return None
    candidates = api_key_module.extract_api_key_candidates(
        request.headers.get("Authorization"), request.headers.get("X-Api-Key")
    )
    if not candidates:
        return None
    if not any(api_key_module.matches_api_key(candidate) for candidate in candidates):
        return None
    if get_auth_mode() == "none":
        return None
    # Mark the request as keyed before the lookup so the after-request cookie
    # reset also covers the error path below.
    g.api_key_auth = True
    try:
        admin = user_db.get_first_admin() if user_db is not None else None
    except _OPERATIONAL_ERRORS:
        logger.exception("API key auth middleware error")
        return jsonify({"error": "Authentication error"}), 500
    session.clear()
    session["user_id"] = admin["username"] if admin else "api"
    session["is_admin"] = True
    if admin:
        session["db_user_id"] = admin["id"]
    session.permanent = False
    # Identity is per request; never persist it as a cookie.
    session.modified = False
    return None
@app.before_request
 def proxy_auth_middleware() -> Response | tuple[Response, int] | None:
    """Middleware to handle proxy authentication.
@@ -671,6 +739,10 @@ def proxy_auth_middleware() -> Response | tuple[Response, int] | None:
    if auth_mode != "proxy":
        return None
    # A request already authenticated by SHELFMARK_API_KEY needs no proxy headers.
    if g.get("api_key_auth"):
        return None
    # Skip for public endpoints that don't need auth
    if request.path == "/api/health":
        return None
@@ -710,8 +782,9 @@ def proxy_auth_middleware() -> Response | tuple[Response, int] | None:
        # Resolve admin role for proxy sessions.
        # If an admin group is configured, derive from groups header.
-        # Otherwise preserve existing DB role for known users and default
+        # Otherwise preserve the existing DB role for known users; a first-time user
-        # first-time users to admin (to avoid lockouts).
+        # is an admin only while the instance has none (so nobody is locked out),
        # after that PROXY_AUTH_DEFAULT_ROLE decides (default: user).
        admin_group_header = (
            normalize_optional_text(
                app_config.get("PROXY_AUTH_ADMIN_GROUP_HEADER", "X-Auth-Groups")
@@ -734,6 +807,8 @@ def proxy_auth_middleware() -> Response | tuple[Response, int] | None:
            existing_db_user = user_db.get_user(username=username)
            if existing_db_user:
                is_admin = existing_db_user.get("role") == "admin"
            else:
                is_admin = _proxy_default_is_admin(user_db)
        # Create or update session
        previous_username = session.get("user_id")
@@ -800,6 +875,17 @@ def set_security_headers(response: Response) -> Response:
    return response
@app.after_request
 def strip_cookie_for_api_key_requests(response: Response) -> Response:
    """Keyed requests never mint or refresh a session cookie, even if a handler dirties the session."""
    if g.get("api_key_auth"):
        # Setting `permanent` mutates the session dict (re-marking it
        # modified), so it must be reset before `modified`, not after.
        session.permanent = False
        session.modified = False
    return response
 def login_required(
    f: Callable[..., Response | tuple[Response, int]],
 ) -> Callable[..., Response | tuple[Response, int]]:
@@ -1073,6 +1159,13 @@ def api_download_release() -> Response | tuple[Response, int]:
            release_payload = dict(data)
            release_payload["content_type"] = resolved_content_type
        logger.info(
            "Download request received. keys=%s downloads=%s extra.downloads=%s",
            list(data.keys()),
            data.get("downloads"),
            data.get("extra", {}).get("downloads") if isinstance(data.get("extra"), dict) else None,
        )
        priority = data.get("priority", 0)
        # Per-user download overrides
        db_user_id = session.get("db_user_id")
@@ -1190,8 +1283,8 @@ def api_config() -> Response | tuple[Response, int]:
            "onboarding_complete": _get_onboarding_complete(),
            # Default sort orders
            "default_sort": app_config.get(
-                "AA_DEFAULT_SORT", "relevance"
+                "AA_DEFAULT_SORT", ""
-            ),  # For direct mode (Anna's Archive)
+            ),  # For direct mode (Anna's Archive) — empty means use local downloads sort
            "metadata_default_sort": get_provider_default_sort(
                metadata_ui_provider
            ),  # For universal mode
@@ -1354,6 +1447,7 @@ def _record_download_queued(task_id: str, task: Any) -> None:
            size=normalize_optional_text(getattr(task, "size", None)),
            preview=normalize_optional_text(getattr(task, "preview", None)),
            content_type=normalize_optional_text(getattr(task, "content_type", None)),
            downloads=getattr(task, "downloads", None),
            origin=origin,
            retry_payload=backend.serialize_task_for_retry(task),
        )
@@ -1626,6 +1720,17 @@ def api_local_download() -> Response | tuple[Response, int]:
            # Book data not found or not available
            return jsonify({"error": "File not found"}), 404
        is_admin, db_user_id, can_access_status = _resolve_status_scope()
        if not is_admin:
            actor_username = session.get("user_id")
            if not can_access_status or not _task_owned_by_actor(
                book_info,
                actor_user_id=db_user_id,
                actor_username=actor_username if isinstance(actor_username, str) else None,
            ):
                return jsonify({"error": "File not found"}), 404
        file_name = book_info.get_filename() if book_info is not None else Path(book_id).name
        # Prepare the file for sending to the client
        data = io.BytesIO(file_data)
@@ -2821,7 +2926,7 @@ def api_releases() -> Response | tuple[Response, int]:
    try:
        from dataclasses import asdict
-        from shelfmark.core.search_plan import build_release_search_plan
+        from shelfmark.core.release_search import search_source_releases
        from shelfmark.metadata_providers import (
            BookMetadata,
            get_provider,
@@ -2840,54 +2945,17 @@ def api_releases() -> Response | tuple[Response, int]:
            source_name: str, search_book: BookMetadata
        ) -> tuple[Any | None, list[Any], str | None]:
            """Search one source and return any error message instead of raising."""
-            try:
+            return search_source_releases(
-                source = get_source(source_name)
+                source_name,
-
+                search_book,
-                plan = build_release_search_plan(
+                languages=(browse_filters.lang if source_query_filters is not None else languages),
-                    search_book,
+                manual_query=(query_text if source_query_filters is not None else manual_query),
-                    languages=browse_filters.lang
+                indexers=indexers,
-                    if source_query_filters is not None
+                expand_search=expand_search,
-                    else languages,
+                content_type=content_type,
-                    manual_query=query_text if source_query_filters is not None else manual_query,
+                source_filters=source_query_filters,
-                    indexers=indexers,
+                user_id=db_user_id,
-                    source_filters=source_query_filters,
+            )
                    user_id=db_user_id,
                )
                if plan.source_filters is not None:
                    planned_query = plan.manual_query or plan.primary_query
                    planned_query_type = "query"
                elif plan.manual_query:
                    planned_query = plan.manual_query
                    planned_query_type = "manual"
                elif not expand_search and plan.isbn_candidates:
                    planned_query = plan.isbn_candidates[0]
                    planned_query_type = "isbn"
                else:
                    planned_query = plan.primary_query
                    planned_query_type = "title_author"
                logger.debug(
                    "Searching %s: %s='%s' (title='%s', authors=%s, expand=%s, content_type=%s)",
                    source_name,
                    planned_query_type,
                    planned_query,
                    search_book.title,
                    search_book.authors,
                    expand_search,
                    content_type,
                )
                releases = source.search(
                    search_book, plan, expand_search=expand_search, content_type=content_type
                )
            except ValueError:
                return None, [], f"Unknown source: {source_name}"
            except (SourceUnavailableError, *_OPERATIONAL_ERRORS) as e:
                logger.warning("Release search failed for source %s: %s", source_name, e)
                return None, [], f"{source_name}: {e!s}"
            else:
                return source, releases, None
        provider = request.args.get("provider", "").strip()
        book_id = request.args.get("book_id", "").strip()
@@ -3052,8 +3120,13 @@ def api_releases() -> Response | tuple[Response, int]:
        search_info = {}
        for source_name, source_instance in source_instances.items():
            info: dict[str, str | int | None] = {}
            if hasattr(source_instance, "last_search_type") and source_instance.last_search_type:
-                search_info[source_name] = {"search_type": source_instance.last_search_type}
+                info["search_type"] = source_instance.last_search_type
            if hasattr(source_instance, "total_results"):
                info["total_results"] = source_instance.total_results
            if info:
                search_info[source_name] = info
        response = {
            "releases": releases_data,
@@ -158,10 +158,11 @@ class GoogleBooksProvider(MetadataProvider):
        query = "+".join(query_parts)
        # Build request params
        page_size = min(options.limit, 40)  # Google max is 40
        params: dict[str, Any] = {
            "q": query,
-            "maxResults": min(options.limit, 40),  # Google max is 40
+            "maxResults": page_size,
-            "startIndex": (options.page - 1) * options.limit,
+            "startIndex": (options.page - 1) * page_size,
            "printType": "books",  # Exclude magazines
        }
@@ -46,6 +46,7 @@ class BrowseRecord:
    content: str | None = None
    format: str | None = None
    size: str | None = None
    downloads: int | None = None
    info: dict[str, list[str]] | None = None
    description: str | None = None
    download_urls: list[str] = field(default_factory=list)
@@ -368,12 +369,21 @@ class ReleaseSource(ABC):
        return None
@dataclass(frozen=True)
 class HandoffResult:
    """An external handoff that completed without a Shelfmark book payload."""
    path: str
    message: str
 class DownloadHandler(ABC):
    """Interface for executing downloads.
    A handler may either:
    - download directly into ``TMP_DIR`` (managed by Shelfmark), or
    - return a path owned by an external client (e.g. torrent/usenet).
    - finish an external handoff without producing a book payload.
    The orchestrator is responsible for post-processing (archive extraction, output mode
    handling) and transferring files into their final destination.
@@ -386,8 +396,8 @@ class DownloadHandler(ABC):
        cancel_flag: Event,
        progress_callback: Callable[[float], None],
        status_callback: Callable[[str, str | None], None],
-    ) -> str | None:
+    ) -> str | HandoffResult | None:
-        """Execute download and return a path to the downloaded payload."""
+        """Execute download and return a payload path or completed external handoff."""
    def post_process_cleanup(self, task: DownloadTask, *, success: bool) -> None:
        """Run optional cleanup after orchestrator post-processing.
@@ -422,6 +432,7 @@ _BUILTIN_SOURCE_MODULES = (
    "shelfmark.release_sources.audiobookbay",
    "shelfmark.release_sources.direct_download",
    "shelfmark.release_sources.irc",
    "shelfmark.release_sources.libgen",
    "shelfmark.release_sources.newznab",
    "shelfmark.release_sources.prowlarr",
 )
@@ -0,0 +1,20 @@
 """Direct Download release source and public entry points.
 Importing the source and handler classes registers them with Shelfmark.
 """
 from shelfmark.release_sources.direct_download.annas_archive import search_books
 from shelfmark.release_sources.direct_download.common import DirectDownloadUnavailableError
 from shelfmark.release_sources.direct_download.handler import DirectDownloadHandler
 from shelfmark.release_sources.direct_download.source import DirectDownloadSource
 __all__ = [
    "DirectDownloadUnavailableError",
    "DirectDownloadHandler",
    "DirectDownloadSource",
    "SearchUnavailableError",
    "search_books",
 ]
 # Compatibility alias for integrations that imported the old module-level name.
 SearchUnavailableError = DirectDownloadUnavailableError
@@ -0,0 +1,272 @@
 """Shared contracts and result normalization for Direct Download websites."""
 import hashlib
 import re
 import threading
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, Protocol, runtime_checkable
 from bs4 import BeautifulSoup, Tag
 from shelfmark.core.config import config
 from shelfmark.core.languages import language_alias_map
 from shelfmark.release_sources import BrowseRecord, SourceUnavailableError
 if TYPE_CHECKING:
    from collections.abc import Callable, Iterable
    from pathlib import Path
    from threading import Event
    from shelfmark.core.models import SearchFilters
    from shelfmark.core.search_plan import ReleaseSearchPlan
    from shelfmark.metadata_providers import BookMetadata
 _LANGUAGE_ALIAS_TO_CODE: dict[str, str] | None = None
 _LANGUAGE_ALIAS_LOCK = threading.Lock()
 _SIZE_UNIT_PATTERN = re.compile(r"(kb|mb|gb|tb)", re.IGNORECASE)
 MIN_VALID_FILE_SIZE = 10 * 1024
 class DirectDownloadUnavailableError(SourceUnavailableError):
    """Raised when the composite Direct Download source cannot be reached."""
 def coerce_str_list(value: object) -> list[str]:
    """Return only string items from a config value."""
    if not isinstance(value, list | tuple):
        return []
    return [item for item in value if isinstance(item, str)]
 def get_supported_formats() -> list[str]:
    """Return configured supported formats as a clean string list."""
    return coerce_str_list(config.SUPPORTED_FORMATS)
 def html_response_text(response: str | tuple[str, str]) -> str:
    """Extract the HTML body from downloader responses."""
    if isinstance(response, tuple):
        return response[0]
    return response
 def attr_to_str(value: object) -> str | None:
    """Convert a BeautifulSoup attribute value to a plain string."""
    if isinstance(value, str):
        return value
    if isinstance(value, list):
        for item in value:
            if isinstance(item, str):
                return item
    return None
 def get_attr(tag: Tag, attr: str) -> str | None:
    """Safely fetch a tag attribute as a string."""
    return attr_to_str(tag.get(attr))
@dataclass(frozen=True)
 class ParsedSearchResult:
    """Provider-neutral fields extracted from one search-result element."""
    key: str
    title: str
    formats: tuple[str, ...]
    record_id: str | None = None
    author: str | None = None
    publisher: str | None = None
    year: str | None = None
    language: str | None = None
    content: str | None = None
    size: str | None = None
    preview: str | None = None
    source_url: str | None = None
    download_path: str | None = None
 class DirectDownloadProvider(Protocol):
    """Provider lifecycle used by the composite Direct Download source."""
    id: str
    display_name: str
    def is_enabled(self) -> bool: ...
    def handles(self, url: str) -> bool: ...
    def search(
        self,
        book: BookMetadata,
        plan: ReleaseSearchPlan,
        *,
        expand_search: bool = False,
        content_type: str = "ebook",
    ) -> list[BrowseRecord]: ...
    def download(
        self,
        book_info: BrowseRecord,
        book_path: Path,
        progress_callback: Callable[[float], None] | None,
        cancel_flag: Event | None,
        status_callback: Callable[[str, str | None], None] | None,
    ) -> str | None: ...
@runtime_checkable
 class RecordLookupProvider(Protocol):
    """Optional capability for providers that can reopen source-native records."""
    def get_record(
        self, record_id: str, *, fetch_download_count: bool = True
    ) -> BrowseRecord | None: ...
 def normalize_language_token(value: str) -> str:
    normalized = value.strip().lower()
    for dash in ("‑", "–", "—", "−"):
        normalized = normalized.replace(dash, "-")
    return normalized
 def language_alias_to_code() -> dict[str, str]:
    """Alias to code map, delegating to the shared language data."""
    global _LANGUAGE_ALIAS_TO_CODE
    cached = _LANGUAGE_ALIAS_TO_CODE
    if cached is not None:
        return cached
    with _LANGUAGE_ALIAS_LOCK:
        cached = _LANGUAGE_ALIAS_TO_CODE
        if cached is not None:
            return cached
        _LANGUAGE_ALIAS_TO_CODE = language_alias_map()
        return _LANGUAGE_ALIAS_TO_CODE
 def normalize_requested_languages(languages: list[str] | None) -> set[str]:
    if not languages:
        return set()
    aliases = language_alias_to_code()
    normalized: set[str] = set()
    for value in languages:
        token = normalize_language_token(str(value))
        if not token or token == "all":  # noqa: S105 - "all" is a language sentinel
            continue
        normalized.add(aliases.get(token, token))
    return normalized
 def book_matches_requested_languages(book_language: str | None, requested: set[str]) -> bool:
    """Return True when a book's language matches the requested filter.
    Books with unknown/missing language always pass — the server-side &lang= filter
    already narrowed the result set, so dropping unlabelled rows hides valid results.
    """
    if not requested:
        return True
    if not book_language:
        return True
    aliases = language_alias_to_code()
    normalized_book = aliases.get(
        normalize_language_token(book_language),
        normalize_language_token(book_language),
    )
    return normalized_book in requested
 def normalize_size(size_str: str) -> str:
    """Normalize size string by uppercasing units (e.g., '5.2 mb' -> '5.2 MB')."""
    return _SIZE_UNIT_PATTERN.sub(lambda m: m.group(1).upper(), size_str.strip())
 def parse_search_items(
    items: Iterable[Tag],
    filters: SearchFilters | None,
    *,
    provider_id: str,
    extract_item: Callable[[Tag], ParsedSearchResult | None],
    filter_languages: bool = True,
 ) -> list[BrowseRecord]:
    """Normalize provider-specific HTML elements into Direct Download records.
    Providers only describe how fields are extracted from their DOM. Language and
    format filtering, stable IDs, and BrowseRecord construction stay shared.
    Pass ``filter_languages=False`` when the site already filtered by language: its
    language cells are free text, and re-matching them locally drops rows it matched.
    """
    requested_languages = (
        normalize_requested_languages(filters.lang) if filters and filter_languages else set()
    )
    requested_formats = (
        {value.casefold() for value in (filters.format or get_supported_formats())}
        if filters
        else set()
    )
    records: list[BrowseRecord] = []
    for item in items:
        parsed = extract_item(item)
        if parsed is None:
            continue
        normalized_language = normalize_language_token(parsed.language) if parsed.language else ""
        language = language_alias_to_code().get(normalized_language, normalized_language) or None
        if not book_matches_requested_languages(language, requested_languages):
            continue
        formats = parsed.formats or ("",)
        for book_format in formats:
            normalized_format = book_format.casefold()
            if (
                normalized_format
                and requested_formats
                and normalized_format not in requested_formats
            ):
                continue
            record_id = parsed.record_id
            if not record_id or len(formats) > 1:
                source_key = f"{parsed.key}#{normalized_format}"
                digest = hashlib.blake2b(source_key.encode(), digest_size=16).hexdigest()
                record_id = f"{provider_id}:{digest}"
            records.append(
                BrowseRecord(
                    id=record_id,
                    title=parsed.title,
                    source="direct_download",
                    author=parsed.author,
                    publisher=parsed.publisher,
                    year=parsed.year,
                    language=language,
                    format=normalized_format or None,
                    size=parsed.size,
                    preview=parsed.preview,
                    content=parsed.content,
                    source_url=parsed.source_url,
                    download_path=parsed.download_path,
                )
            )
    return records
 def parse_search_page(
    page: str | BeautifulSoup | Tag,
    filters: SearchFilters | None,
    *,
    provider_id: str,
    item_selector: str,
    extract_item: Callable[[Tag], ParsedSearchResult | None],
    filter_languages: bool = True,
 ) -> list[BrowseRecord]:
    """Parse a result page using provider-specific selectors and extraction."""
    root = BeautifulSoup(page, "html.parser") if isinstance(page, str) else page
    return parse_search_items(
        (item for item in root.select(item_selector) if isinstance(item, Tag)),
        filters,
        provider_id=provider_id,
        extract_item=extract_item,
        filter_languages=filter_languages,
    )
@@ -0,0 +1,177 @@
 """Direct Download routing, staging, and cancellation."""
 from pathlib import Path
 from typing import TYPE_CHECKING
 from shelfmark.config.env import TMP_DIR
 from shelfmark.core.config import config
 from shelfmark.core.logger import setup_logger
 from shelfmark.core.models import DownloadTask, build_filename
 from shelfmark.download import network
 from shelfmark.release_sources import (
    BrowseRecord,
    DownloadHandler,
    register_handler,
 )
 from shelfmark.release_sources.direct_download import registry
 if TYPE_CHECKING:
    from collections.abc import Callable
    from pathlib import Path
    from threading import Event
 logger = setup_logger(__name__)
 def _download_book(
    book_info: BrowseRecord,
    book_path: Path,
    progress_callback: Callable[[float], None] | None = None,
    cancel_flag: Event | None = None,
    status_callback: Callable[[str, str | None], None] | None = None,
 ) -> str | None:
    """Route a website record or an Anna's Archive MD5 to its download flow."""
    provider = registry.provider_for_record(book_info)
    if provider is None:
        msg = f"No Direct Download provider owns record {book_info.id!r}"
        raise RuntimeError(msg)
    return provider.download(book_info, book_path, progress_callback, cancel_flag, status_callback)
@register_handler("direct_download")
 class DirectDownloadHandler(DownloadHandler):
    """Route and stage downloads from registered Direct Download providers."""
    def download(
        self,
        task: DownloadTask,
        cancel_flag: Event,
        progress_callback: Callable[[float], None],
        status_callback: Callable[[str, str | None], None],
    ) -> str | None:
        """Execute a provider-owned direct HTTP download.
        Args:
            task: Download task with a provider-owned source ID
            cancel_flag: Event to check for cancellation
            progress_callback: Called with progress percentage (0-100)
            status_callback: Called with (status, message) for status updates
        Returns:
            Path to downloaded file if successful, None otherwise
        """
        try:
            # Check for cancellation before starting
            if cancel_flag.is_set():
                logger.info("Download cancelled before starting: %s", task.task_id)
                status_callback("cancelled", "Cancelled")
                return None
            # Reconstruct the provider-owned record without resolving it again.
            book_info = BrowseRecord(
                id=task.task_id,
                title=task.title,
                source="direct_download",
                author=task.author,
                year=task.year,
                format=task.format,
                size=task.size,
                preview=task.preview,
                source_url=task.source_url,
            )
            return self._execute_download(
                book_info, cancel_flag, progress_callback, status_callback
            )
        except Exception as e:
            if cancel_flag.is_set():
                logger.info("Download cancelled during error handling: %s", task.task_id)
                status_callback("cancelled", "Cancelled")
            else:
                logger.exception("Error downloading book")
                status_callback("error", str(e))
            return None
    def _execute_download(
        self,
        book_info: BrowseRecord,
        cancel_flag: Event,
        progress_callback: Callable[[float], None],
        status_callback: Callable[[str, str | None], None],
    ) -> str | None:
        """Execute the direct-download flow with a fetched browse record.
        This contains the core download logic: cascade through sources,
        handle bypass, move to final location.
        """
        try:
            logger.debug("Starting download: %s", book_info.title)
            # Prepare paths - use descriptive staging filename, orchestrator will rename
            # based on FILE_ORGANIZATION setting
            file_org = config.get("FILE_ORGANIZATION", "rename")
            if file_org == "none":
                book_name = f"{book_info.id}.{book_info.format or 'bin'}"
            else:
                book_name = build_filename(
                    book_info.title,
                    book_info.author,
                    book_info.year,
                    book_info.format,
                )
            book_path = TMP_DIR / book_name
            # Check cancellation before download
            if cancel_flag.is_set():
                logger.info("Download cancelled before download call: %s", book_info.id)
                status_callback("cancelled", "Cancelled")
                return None
            # Execute download via _download_book (handles cascade and bypass)
            status_callback("resolving", "Finding download source")
            success_url = _download_book(
                book_info, book_path, progress_callback, cancel_flag, status_callback
            )
            # Check for cancellation after download
            if cancel_flag.is_set():
                logger.info("Download cancelled during download: %s", book_info.id)
                if book_path.exists():
                    book_path.unlink()
                status_callback("cancelled", "Cancelled")
                return None
            if not success_url:
                if network.dns_interference_detected():
                    status_callback(
                        "error",
                        "All sources failed - your network/ISP appears to be blocking "
                        "Anna's Archive. Enable DNS-over-HTTPS in settings.",
                    )
                else:
                    status_callback("error", "All download sources failed")
                return None
            # Return temp path - orchestrator handles post-processing (archive extraction, ingest)
            return str(book_path)
        except Exception:
            if cancel_flag.is_set():
                logger.info("Download cancelled during error handling: %s", book_info.id)
                status_callback("cancelled", "Cancelled")
            else:
                logger.exception("Error downloading book")
            return None
    def cancel(self, task_id: str) -> bool:
        """Cancel an in-progress download.
        Cancellation is handled via the cancel_flag passed to download().
        This method exists for the interface but actual cancellation
        happens through the Event flag mechanism.
        """
        # Cancellation is handled by the orchestrator via cancel_flag
        return False
@@ -0,0 +1,93 @@
 """Provider composition and dispatch for the Direct Download release source."""
 import re
 from typing import TYPE_CHECKING
 from shelfmark.core.config import config
 from shelfmark.release_sources.direct_download.annas_archive import AnnasArchiveProvider
 if TYPE_CHECKING:
    from collections.abc import Sequence
    from shelfmark.release_sources import BrowseRecord
    from shelfmark.release_sources.direct_download.common import DirectDownloadProvider
 PROVIDER_TYPES = (AnnasArchiveProvider,)
 _AA_MD5_PATTERN = re.compile(r"^[0-9a-f]{32}$", re.IGNORECASE)
 def create_providers() -> tuple[DirectDownloadProvider, ...]:
    """Create request-local providers so mutable search state is not shared."""
    return tuple(provider_type() for provider_type in PROVIDER_TYPES)
 def enabled_providers(
    providers: Sequence[DirectDownloadProvider] | None = None,
 ) -> tuple[DirectDownloadProvider, ...]:
    if not config.get("DIRECT_DOWNLOAD_ENABLED", False):
        return ()
    candidates = providers if providers is not None else create_providers()
    return tuple(provider for provider in candidates if provider.is_enabled())
 def get_unavailable_reason(
    providers: Sequence[DirectDownloadProvider] | None = None,
 ) -> str | None:
    if not config.get("DIRECT_DOWNLOAD_ENABLED", False):
        return "Direct Download is disabled. Enable the source in Settings."
    if not enabled_providers(providers):
        return (
            "Direct Download is not configured. Enable and configure at least one "
            "download provider in Settings."
        )
    return None
 def provider_by_id(
    provider_id: str | None,
    providers: Sequence[DirectDownloadProvider] | None = None,
 ) -> DirectDownloadProvider | None:
    if not provider_id:
        return None
    candidates = providers if providers is not None else create_providers()
    return next((provider for provider in candidates if provider.id == provider_id), None)
 def provider_for_record(
    record: BrowseRecord,
    providers: Sequence[DirectDownloadProvider] | None = None,
 ) -> DirectDownloadProvider | None:
    """Resolve a record explicitly, retaining safe compatibility with legacy tasks."""
    candidates = providers if providers is not None else create_providers()
    prefix, separator, _remainder = record.id.partition(":")
    if separator:
        provider = provider_by_id(prefix, candidates)
        if provider is not None:
            return provider
    if record.source_url:
        provider = next(
            (provider for provider in candidates if provider.handles(record.source_url)),
            None,
        )
        if provider is not None:
            return provider
    # Anna's Archive records historically carried only their raw MD5. Preserve those
    # persisted tasks without treating arbitrary unknown URLs as Anna's Archive.
    if _AA_MD5_PATTERN.fullmatch(record.id):
        return provider_by_id("annas_archive", candidates)
    return None
 def provider_for_record_id(
    record_id: str,
    providers: Sequence[DirectDownloadProvider] | None = None,
 ) -> DirectDownloadProvider | None:
    candidates = providers if providers is not None else create_providers()
    prefix, separator, _remainder = record_id.partition(":")
    if separator:
        return provider_by_id(prefix, candidates)
    # Record lookup predates provider-qualified IDs, so unqualified IDs are AA IDs.
    return provider_by_id("annas_archive", candidates)
@@ -0,0 +1,236 @@
 """Direct Download search and release-source integration."""
 import contextlib
 from pathlib import Path
 from typing import TYPE_CHECKING, ClassVar
 import requests
 from shelfmark.core.logger import setup_logger
 from shelfmark.core.utils import get_aa_content_type_dir
 from shelfmark.core.utils import is_audiobook as check_audiobook
 from shelfmark.release_sources import (
    BrowseRecord,
    ColumnAlign,
    ColumnColorHint,
    ColumnRenderType,
    ColumnSchema,
    Release,
    ReleaseColumnConfig,
    ReleaseProtocol,
    ReleaseSource,
    SourceUnavailableError,
    register_source,
 )
 from shelfmark.release_sources.direct_download import registry
 from shelfmark.release_sources.direct_download.common import (
    DirectDownloadUnavailableError,
    RecordLookupProvider,
 )
 if TYPE_CHECKING:
    from pathlib import Path
    from shelfmark.core.models import DownloadTask
    from shelfmark.core.search_plan import ReleaseSearchPlan
    from shelfmark.metadata_providers import BookMetadata
 logger = setup_logger(__name__)
 def _extract_downloads(record: BrowseRecord) -> int | None:
    """Extract download count from record info for Release.extra.downloads."""
    downloads = None
    if record.info and "Downloads" in record.info:
        downloads_value = record.info["Downloads"]
        if isinstance(downloads_value, list) and len(downloads_value) > 0:
            with contextlib.suppress(ValueError, TypeError):
                downloads = int(downloads_value[0])
        elif isinstance(downloads_value, (int, float)):
            downloads = int(downloads_value)
    return downloads
 def _browse_record_to_release(record: BrowseRecord) -> Release:
    """Convert a browse record to a Release object.
    This bridges the direct source's browse data to the generic release model.
    """
    provider = registry.provider_for_record(record)
    provider_id = provider.id if provider is not None else None
    return Release(
        source=record.source,
        source_id=record.id,
        title=record.title,
        format=record.format,
        language=record.language,  # Top-level language for filtering
        size=record.size,
        download_url=record.source_url
        or (record.download_urls[0] if record.download_urls else None),
        info_url=record.source_url,
        protocol=ReleaseProtocol.HTTP,
        indexer="Direct Download",
        content_type=record.content,  # Preserve content type from source
        extra={
            "author": record.author,
            "publisher": record.publisher,
            "year": record.year,
            "language": record.language,
            "preview": record.preview,
            "description": record.description,
            "download_urls": record.download_urls,
            "info": record.info,
            "direct_download_provider": provider_id,
            "downloads": _extract_downloads(record),
            # Kept for older frontends and persisted request payloads.
            "web_provider": provider_id if provider_id != "annas_archive" else None,
        },
    )
@register_source("direct_download")
 class DirectDownloadSource(ReleaseSource):
    """Direct download source - searches web sources for books.
    This wraps the search_books() functionality to provide releases
    via the plugin interface.
    """
    name = "direct_download"
    display_name = "Direct Download"
    supported_content_types: ClassVar[list[str]] = ["ebook"]  # Direct downloads only support ebooks
    def __init__(self) -> None:
        """Initialize per-instance search state for direct downloads."""
        self._providers = registry.create_providers()
    @property
    def last_search_type(self) -> str:
        """Returns the search type used in the last search() call."""
        provider = registry.provider_by_id("annas_archive", self._providers)
        return str(getattr(provider, "last_search_type", "title_author"))
    @property
    def total_results(self) -> int | None:
        """Returns the total result count from the last search."""
        provider = registry.provider_by_id("annas_archive", self._providers)
        return getattr(provider, "total_results", None)
    def get_column_config(self) -> ReleaseColumnConfig:
        """Column configuration for Direct Download source.
        Shows language, format, size, and downloads for each release.
        Language, format, size, and downloads are all shown on mobile.
        """
        return ReleaseColumnConfig(
            columns=[
                ColumnSchema(
                    key="extra.language",
                    label="Language",
                    render_type=ColumnRenderType.BADGE,
                    align=ColumnAlign.CENTER,
                    width="60px",
                    hide_mobile=False,  # Language shown on mobile
                    color_hint=ColumnColorHint(type="map", value="language"),
                    uppercase=True,
                ),
                ColumnSchema(
                    key="format",
                    label="Format",
                    render_type=ColumnRenderType.BADGE,
                    align=ColumnAlign.CENTER,
                    width="80px",
                    hide_mobile=False,  # Format shown on mobile
                    color_hint=ColumnColorHint(type="map", value="format"),
                    uppercase=True,
                ),
                ColumnSchema(
                    key="size",
                    label="Size",
                    render_type=ColumnRenderType.SIZE,
                    align=ColumnAlign.CENTER,
                    width="80px",
                    hide_mobile=False,  # Size shown on mobile
                ),
                ColumnSchema(
                    key="extra.downloads",
                    label="Downloads",
                    render_type=ColumnRenderType.NUMBER,
                    align=ColumnAlign.CENTER,
                    width="80px",
                    hide_mobile=False,  # Downloads shown on mobile
                ),
            ],
            grid_template="minmax(0,2fr) 60px 80px 80px 80px",
            supported_filters=["format", "language"],  # AA has reliable language metadata
        )
    def get_record(
        self,
        record_id: str,
        *,
        fetch_download_count: bool = True,
    ) -> BrowseRecord | None:
        """Resolve a direct-download record for direct-mode info/download flows."""
        provider = registry.provider_for_record_id(record_id, self._providers)
        if provider is None or not isinstance(provider, RecordLookupProvider):
            return None
        native_id = record_id.partition(":")[2] or record_id
        return provider.get_record(native_id, fetch_download_count=fetch_download_count)
    def search_results_are_releases(self) -> bool:
        """Direct search results already represent concrete downloadable releases."""
        return True
    def get_destination_override(self, task: DownloadTask) -> Path | None:
        """Apply Anna's Archive content-type routing when configured."""
        if check_audiobook(task.content_type):
            return None
        return get_aa_content_type_dir(task.content_type)
    def search(
        self,
        book: BookMetadata,
        plan: ReleaseSearchPlan,
        *,
        expand_search: bool = False,
        content_type: str = "ebook",
    ) -> list[Release]:
        """Search every enabled provider through the shared provider lifecycle."""
        unavailable_reason = registry.get_unavailable_reason(self._providers)
        if unavailable_reason:
            raise DirectDownloadUnavailableError(unavailable_reason)
        releases: list[Release] = []
        failures: list[Exception] = []
        for provider in registry.enabled_providers(self._providers):
            try:
                records = provider.search(
                    book,
                    plan,
                    expand_search=expand_search,
                    content_type=content_type,
                )
            except SourceUnavailableError as exc:
                failures.append(exc)
                continue
            except (
                RuntimeError,
                TypeError,
                ValueError,
                requests.exceptions.RequestException,
            ) as exc:
                logger.warning("%s search failed: %s", provider.display_name, exc)
                failures.append(exc)
                continue
            releases.extend(_browse_record_to_release(record) for record in records)
        # A provider failure is only quiet when another provider answered. Otherwise the
        # caller has to see it, or a failed search reads as a search with no hits.
        if failures and not releases:
            raise failures[0]
        return releases
    def is_available(self) -> bool:
        """Check if Direct Download has been explicitly enabled and configured."""
        return registry.get_unavailable_reason(self._providers) is None
@@ -13,9 +13,9 @@ if TYPE_CHECKING:
    from shelfmark.metadata_providers import BookMetadata
 from shelfmark.api.websocket import ws_manager
 from shelfmark.core.author_match import author_affinity, search_surname
 from shelfmark.core.config import config
 from shelfmark.core.logger import setup_logger
 from shelfmark.core.search_plan import pick_search_author
 from shelfmark.core.utils import is_audiobook
 from shelfmark.release_sources import (
    ColumnColorHint,
@@ -86,6 +86,18 @@ def _emit_status(message: str, phase: str = "searching") -> None:
    )
 def _reported_author(release: Release) -> str:
    """The author a result actually claims, with the parser's sentinel read as none.
    A filename with no " - " separator has no author to report and parser.py:168
    fills in "Unknown". Ranked literally that sorts as a wrong author, below every
    result that named someone else; as absent it sorts between agreement and
    disagreement, which is what the tier was built for.
    """
    author = release.extra.get("author", "")
    return "" if author == "Unknown" else author
 # Rate limiting to avoid server throttling
 MIN_SEARCH_INTERVAL = 15.0
 _last_search_time: float = 0
@@ -227,12 +239,15 @@ class IRCReleaseSource(ReleaseSource):
            logger.debug("IRC source is disabled, skipping search")
            return []
-        # Build search query
+        query = self._build_query(book, plan)
        query = plan.primary_query or self._build_query(book)
        if not query:
            logger.warning("No search query could be built")
            return []
        # A manual query is the user's own words; ranking it against the metadata
        # author would second-guess what they typed.
        wanted_author = "" if plan.manual_query else plan.author
        # Get IRC settings
        server = _config_text("IRC_SERVER")
        port = _config_port("IRC_PORT", 6697)
@@ -277,7 +292,9 @@ class IRCReleaseSource(ReleaseSource):
            if cached:
                _emit_status("Using cached results", phase="complete")
                self._online_servers = set(cached.get("online_servers", []))
-                return self._filter_by_content_type(cached["releases"], requested)
+                return self._rank_by_author(
                    self._filter_by_content_type(cached["releases"], requested), wanted_author
                )
        # Anti-spam cap: the exact same query may only be POSTED a limited number of times
        # per window, even via refresh. Beyond that, serve whatever is cached rather than
@@ -294,7 +311,9 @@ class IRCReleaseSource(ReleaseSource):
            cached = get_cached_results(query_key)
            if cached:
                self._online_servers = set(cached.get("online_servers", []))
-                return self._filter_by_content_type(cached["releases"], requested)
+                return self._rank_by_author(
                    self._filter_by_content_type(cached["releases"], requested), wanted_author
                )
            return []
        logger.info("IRC search: %s", query)
@@ -370,7 +389,12 @@ class IRCReleaseSource(ReleaseSource):
                ebook_releases + audiobook_releases,
                online_servers=online_servers,
            )
-            releases = audiobook_releases if requested == "audiobook" else ebook_releases
+            # Ranked on the way out, never before the cache: one query identity is
            # shared by every book that produced the same query, so the order has to
            # follow the author asked for now, not the one that filled the cache.
            releases = self._rank_by_author(
                audiobook_releases if requested == "audiobook" else ebook_releases, wanted_author
            )
        except DCCError as e:
            logger.exception("DCC error during search")
@@ -388,24 +412,48 @@ class IRCReleaseSource(ReleaseSource):
        else:
            return releases
-    def _build_query(self, book: BookMetadata) -> str:
+    def _build_query(self, book: BookMetadata, plan: ReleaseSearchPlan) -> str:
-        """Build search query from book metadata."""
+        """Build the line posted to the channel: a title, plus a surname.
        parts = []
-        if book.search_title or book.title:
+        Both come off the variant rather than the plan: an ISBN fallback variant
-            parts.append(book.search_title or book.title)
+        carries `author=""` on purpose (search_plan.py:246), and so does a manual
-
+        query, so reading `plan.author` here would append a surname to searches
-        # Only ever the first author: both metadata fields can arrive holding every
+        that deliberately have none.
        # contributor joined with ", ", and an IRC query carrying an author plus two
        # translators matches nothing. The choice between them - and the narrowing - is
        # `pick_search_author`, shared with the search plan so this cannot drift from it
        # again. See issue #1252.
        author = pick_search_author(book)
        if author:
            parts.append(author)
        Returns "" without a title, so the caller reports "no query" rather than
        posting one. A surname on its own is not a search: `@search Petrie` asks
        the bot for every Petrie on the channel, and a bare over-broad line is the
        kind of post `is_available` refuses queries to avoid being banned for.
        """
        variant = plan.title_variants[0] if plan.title_variants else None
        title = variant.title if variant else (book.search_title or book.title)
        if not title:
            return ""
        author = variant.author if variant else plan.author
        parts = [part for part in (title, search_surname(author)) if part]
        return " ".join(parts)
    def _rank_by_author(self, releases: list[Release], wanted_author: str) -> list[Release]:
        """Order releases by author agreement, under the server's availability.
        A surname is a weak filter - it also matches a different author who shares
        it - so the full name decides the order while the search bot decides the
        set. Availability stays the outer key: downloading asks one named bot and
        waits 120s for it (handler.py:133-139), so a release from a bot that is not
        in the channel must not outrank one that can actually answer. Sorting is
        stable, so format and server order survive inside each tier.
        """
        if not wanted_author:
            return releases
        online = self._online_servers or set()
        return sorted(
            releases,
            key=lambda release: (
                0 if release.extra.get("server", "") in online else 1,
                author_affinity(wanted_author, _reported_author(release)),
            ),
        )
    # Format priority for sorting (lower = higher priority)
    EBOOK_FORMAT_PRIORITY: ClassVar[dict[str, int]] = {
        "epub": 0,
@@ -0,0 +1,6 @@
 """Libgen release source - direct catalogue search over the libgen.li family."""
 # Import to trigger registration
 from shelfmark.release_sources.libgen import handler as handler
 from shelfmark.release_sources.libgen import settings as settings
 from shelfmark.release_sources.libgen import source as source
@@ -0,0 +1,114 @@
 """Libgen download handler - resolves an md5 to a file via the ads.php cascade.
 Selected by ``get_handler(task.source)`` for ``source == "libgen"``. It mirrors
 DirectDownloadHandler's shape (stage into TMP_DIR, let the orchestrator post-process) but
 only knows the libgen ``ads.php?md5= -> get.php`` path, keyed on the md5 the search source
 put in ``source_id``.
 """
 from typing import TYPE_CHECKING
 from shelfmark.config.env import TMP_DIR
 from shelfmark.core.config import config
 from shelfmark.core.logger import setup_logger
 from shelfmark.core.models import build_filename
 from shelfmark.download import http as downloader
 from shelfmark.release_sources import DownloadHandler, register_handler
 from shelfmark.release_sources.libgen import scraper
 if TYPE_CHECKING:
    from collections.abc import Callable
    from threading import Event
    from shelfmark.core.models import DownloadTask
 logger = setup_logger(__name__)
 # Files under this size are almost certainly an error/challenge page, not a book. Same
 # threshold direct_download uses; duplicated to keep the package self-contained.
 _MIN_VALID_FILE_SIZE = 10 * 1024
@register_handler("libgen")
 class LibgenHandler(DownloadHandler):
    """Download handler for Libgen search releases."""
    def download(
        self,
        task: DownloadTask,
        cancel_flag: Event,
        progress_callback: Callable[[float], None],
        status_callback: Callable[[str, str | None], None],
    ) -> str | None:
        """Resolve the md5 through each configured mirror and download the file.
        Returns the staged temp path on success (orchestrator handles post-processing) or
        None if every mirror fails.
        """
        from shelfmark.core import mirrors
        try:
            if cancel_flag.is_set():
                status_callback("cancelled", "Cancelled")
                return None
            # source_id was namespaced "libgen:<md5>" to avoid a queue-key collision with
            # direct_download; strip it back to the bare (lowercase) md5 the download page expects.
            md5 = task.task_id.split(":", 1)[-1].lower()
            if config.get("FILE_ORGANIZATION", "rename") == "none":
                book_name = f"{md5}.{task.format or 'bin'}"
            else:
                book_name = build_filename(task.title, task.author, task.year, task.format)
            book_path = TMP_DIR / book_name
            for base in mirrors.get_libgen_mirrors():
                if cancel_flag.is_set():
                    status_callback("cancelled", "Cancelled")
                    return None
                ads_url = f"{base.rstrip('/')}/ads.php?md5={md5}"
                status_callback("resolving", "Resolving Libgen")
                ads_html = scraper.fetch_page(ads_url, (5, 10))
                if not ads_html:
                    continue
                get_url = scraper.resolve_download_url(ads_html, base)
                if not get_url:
                    continue
                # _selector=None: download_url builds its own AAMirrorSelector (a no-op for
                # non-AA URLs), so we avoid initialising dead AA-mirror state here.
                data = downloader.download_url(
                    get_url,
                    task.size or "",
                    progress_callback,
                    cancel_flag,
                    None,
                    status_callback,
                    referer=ads_url,
                )
                if not data:
                    continue
                if data.tell() < _MIN_VALID_FILE_SIZE:
                    logger.warning("Libgen file too small from %s, treating as failure", base)
                    continue
                data.seek(0)
                with book_path.open("wb") as file:
                    file.write(data.getbuffer())
                return str(book_path)
        except Exception as exc:
            if cancel_flag.is_set():
                status_callback("cancelled", "Cancelled")
            else:
                logger.exception("Error downloading from Libgen")
                status_callback("error", str(exc))
            return None
        else:
            # Loop exhausted without returning: every mirror failed to resolve/download.
            status_callback("error", "All Libgen mirrors failed")
            return None
    def cancel(self, task_id: str) -> bool:
        """Cancellation is handled by the orchestrator via the cancel_flag."""
        return False
@@ -0,0 +1,257 @@
 """Libgen catalogue scraping: search results and download-link resolution.
 This is the pure fetch+parse core of the Libgen source. It talks to the libgen.li
 family of mirrors (``index.php?req=`` search, ``ads.php?md5=`` download pages) using
 plain HTTP -- these mirrors are not behind DDoS-Guard, so no browser/bypasser is
 needed. All shelfmark-stateful behaviour lives in source.py/handler.py.
 """
 import re
 from http import HTTPStatus
 from urllib.parse import quote, urlsplit
 import requests
 from bs4 import BeautifulSoup, Tag
 from shelfmark.core.languages import normalize_language
 from shelfmark.core.logger import setup_logger
 from shelfmark.download import http as downloader
 from shelfmark.download import network
 from shelfmark.release_sources import BrowseRecord
 logger = setup_logger(__name__)
 # The libgen.li results table. Both full (9-cell) and compact (5-cell) rows live in it.
 _RESULTS_TABLE_ID = "tablelibgen"
 # md5 appears in the row's Mirrors cell as get.php?md5=<hash> and an AA /md5/<hash> link.
 _MD5_RE = re.compile(r"md5=([0-9a-f]{32})", re.IGNORECASE)
 # Patterns for the keyed GET link on an ads.php page. Kept in sync with the resolution
 # libgen download has always used (direct_download._LIBGEN_GET_PATTERNS); duplicated here
 # on purpose so the Libgen source stays self-contained and does not import that module's
 # internals (which an in-flight upstream refactor is relocating).
 _GET_KEY_PATTERNS = [
    re.compile(
        r'<a\s+href=["\']([^"\']*get\.php\?md5=[^"\']+&key=[^"\']+)["\'][^>]*>\s*'
        r"<h2[^>]*>GET</h2>\s*</a>",
        re.IGNORECASE,
    ),
    re.compile(
        r'<a[^>]+href=["\']([^"\']*get\.php\?md5=[^"\']+&(?:amp;)?key=[^"\']+)["\']',
        re.IGNORECASE,
    ),
    re.compile(
        r'<a\s+href=["\']([^"\']*get\.php[^"\']*)["\'][^>]*>[\s\S]*?<h2[^>]*>GET</h2>',
        re.IGNORECASE,
    ),
    re.compile(
        r'href=["\']([^"\']*get\.php\?[^"\']*md5=[^"\']*&[^"\']*key=[^"\']+)["\']',
        re.IGNORECASE,
    ),
 ]
 # Labels that terminate a metadata value on an ads.php page, so e.g. "Year: 2003 ISBN: ..."
 # stops Year at "ISBN:" rather than swallowing it. We only emit a subset (see _parse_ads_metadata).
 _METADATA_STOP_LABELS = [
    "Title",
    "Series",
    "Author(s)",
    "Publisher",
    "Year",
    "Language",
    "Pages",
    "ISBN",
    "Edition",
    "Extension",
    "Size",
    "Time added",
    "ID",
    "Filename",
    "Description",
 ]
 def fetch_page(url: str, timeout: tuple[int, int] = (5, 15)) -> str | None:
    """GET a libgen page, returning its text on HTTP 200 or None on any failure.
    Public (not underscore-prefixed) because handler.py fetches ads.php pages through it
    and tests patch it. Uses the app's proxy/SSL/DNS configuration so egress stays on
    whatever network the container is bound to (the VPN namespace, in the deployed stack).
    """
    # libgen.li's ads.php returns an empty 200 body to requests without a Referer (an
    # anti-hotlinking check the mirrors added). A same-origin Referer is enough and is
    # harmless for the search page, so send one for every fetch.
    parts = urlsplit(url)
    headers = {**downloader.DOWNLOAD_HEADERS, "Referer": f"{parts.scheme}://{parts.netloc}/"}
    try:
        response = requests.get(
            url,
            headers=headers,
            timeout=timeout,
            allow_redirects=True,
            proxies=network.get_proxies(url),
            verify=network.get_ssl_verify(url),
        )
    except requests.exceptions.RequestException as exc:
        logger.debug("Libgen fetch failed for %s: %s", url, exc)
        return None
    if response.status_code != HTTPStatus.OK:
        logger.debug("Libgen fetch %s returned %s", url, response.status_code)
        return None
    return response.text
 def search_libgen(
    query: str,
    mirrors: list[str],
    *,
    max_results: int,
    timeout: tuple[int, int] = (5, 15),
 ) -> list[BrowseRecord]:
    """Search each mirror's catalogue until one answers with a results table.
    The first mirror that returns a parseable ``#tablelibgen`` wins -- including when that
    table is empty ([] is returned as final). Mirrors can lag independently, but falling
    through on every empty result would multiply latency under the shared search deadline,
    so an empty-but-well-formed answer is trusted rather than re-queried elsewhere.
    """
    for base in mirrors:
        url = f"{base.rstrip('/')}/index.php?req={quote(query)}&res={max_results}"
        html = fetch_page(url, timeout)
        if html is None:
            continue
        records = _parse_results(html, base)
        if records is not None:
            return records
    return []
 def fetch_record_by_md5(
    md5: str,
    mirrors: list[str],
    *,
    timeout: tuple[int, int] = (5, 10),
 ) -> BrowseRecord | None:
    """Resolve a single record from its md5 by parsing an ads.php page's metadata.
    libgen's ``index.php?req=<md5>`` does not match on md5 (req= indexes title/author/
    description), so md5 -> record must go through the ads.php page instead.
    """
    for base in mirrors:
        html = fetch_page(f"{base.rstrip('/')}/ads.php?md5={md5}", timeout)
        if html is None:
            continue
        record = _parse_ads_metadata(html, md5, base)
        if record is not None:
            return record
    return None
 def resolve_download_url(ads_html: str, base_url: str) -> str | None:
    """Extract the keyed get.php download URL from an ads.php page, or None."""
    if "get.php" not in ads_html:
        return None
    for pattern in _GET_KEY_PATTERNS:
        match = pattern.search(ads_html)
        if not match:
            continue
        url = match.group(1).replace("&amp;", "&").replace("&gt;", ">").replace("&lt;", "<")
        if not url.startswith("http"):
            url = f"{base_url.rstrip('/')}/{url.lstrip('/')}"
        return url
    return None
 def _cell_text(cell: Tag) -> str:
    """Cell text with runs of whitespace (incl. &nbsp; / \\xa0) collapsed to single spaces."""
    return re.sub(r"\s+", " ", cell.get_text(" ", strip=True)).strip()
 def _parse_results(html: str, base_url: str) -> list[BrowseRecord] | None:
    """Parse a libgen search page.
    Returns None when the page has no results table (a challenge/error page -> the caller
    tries the next mirror), or a list (possibly empty) when the table is present.
    Row shapes vary and carry NO rowspans: full rows have 9 cells
    ``[Title, Author, Publisher, Year, Language, Pages, Size, Ext, Mirrors]`` and compact
    rows (extra files under one edition) have 5 ``[Title, Pages, Size, Ext, Mirrors]``. The
    file-level columns are stable from the right, so index from the end: Mirrors[-1] (md5),
    Ext[-2], Size[-3]. Title is always [0]. Author/Language exist only on full rows.
    The two shapes are the only ones libgen.li is known to emit; an unexpected width just
    fails safe (author/language read as None) rather than mis-columning.
    """
    soup = BeautifulSoup(html, "html.parser")
    table = soup.find("table", id=_RESULTS_TABLE_ID)
    if not isinstance(table, Tag):
        return None
    records: list[BrowseRecord] = []
    for row in table.find_all("tr")[1:]:  # skip the header row
        cells = row.find_all("td")
        if len(cells) < 5:
            continue
        # Scope the md5 to the Mirrors cell (last column): scanning the whole row could match
        # an md5-shaped string elsewhere (e.g. a cover-image URL) and misattribute it.
        md5_match = _MD5_RE.search(str(cells[-1]))
        if not md5_match:
            continue  # spacer/section rows carry no md5
        md5 = md5_match.group(1).lower()
        title = _cell_text(cells[0])
        fmt = _cell_text(cells[-2]).lower() or None
        size = _cell_text(cells[-3]) or None
        author = None
        language = None
        if len(cells) >= 9:  # full row: middle metadata columns are present
            author = _cell_text(cells[1]) or None
            language = normalize_language(_cell_text(cells[4]))
        records.append(
            BrowseRecord(
                id=md5,
                title=title,
                source="libgen",
                author=author,
                language=language,
                size=size,
                format=fmt,
                source_url=f"{base_url.rstrip('/')}/ads.php?md5={md5}",
            )
        )
    return records
 def _parse_ads_metadata(html: str, md5: str, base_url: str) -> BrowseRecord | None:
    """Build a BrowseRecord from an ads.php page's labelled metadata.
    The page's metadata lives in a deeply nested table, so read it from the visible text by
    label rather than by cell position -- the labels (Title:, Series:, Author(s): ...) are
    stable even though the surrounding markup is not. Returns None if the page has no title.
    """
    text = re.sub(r"\s+", " ", BeautifulSoup(html, "html.parser").get_text(" ", strip=True))
    def field(name: str) -> str | None:
        others = "|".join(
            re.escape(other) + r":" for other in _METADATA_STOP_LABELS if other != name
        )
        match = re.search(re.escape(name) + r":\s*(.*?)\s*(?:" + others + r"|$)", text)
        value = match.group(1).strip() if match else ""
        return value or None
    title = field("Title")
    if not title:
        return None
    return BrowseRecord(
        id=md5,
        title=title,
        source="libgen",
        author=field("Author(s)"),
        publisher=field("Publisher"),
        year=field("Year"),
        language=normalize_language(field("Language") or ""),
        source_url=f"{base_url.rstrip('/')}/ads.php?md5={md5}",
    )
@@ -0,0 +1,34 @@
 """Libgen search settings registration."""
 from shelfmark.core.settings_registry import (
    CheckboxField,
    NumberField,
    SettingsField,
    register_settings,
 )
@register_settings("libgen_config", "Libgen Search", icon="download", order=46)
 def libgen_config_settings() -> list[SettingsField]:
    """Libgen search configuration settings."""
    return [
        CheckboxField(
            key="LIBGEN_SEARCH_ENABLED",
            label="Enable Libgen Search",
            description=(
                "Search the Libgen catalogue directly, including CBZ/CBR comics and manga "
                "that Anna's Archive does not index. Uses the Libgen mirrors configured "
                "under Mirrors for both search and download."
            ),
            default=False,
        ),
        NumberField(
            key="LIBGEN_SEARCH_MAX_RESULTS",
            label="Max Results",
            description="Maximum number of results to request per search (1-100).",
            default=25,
            min_value=1,
            max_value=100,
            show_when={"field": "LIBGEN_SEARCH_ENABLED", "value": True},
        ),
    ]
@@ -0,0 +1,198 @@
 """Libgen release source - searches the libgen catalogue directly.
 Anna's Archive is shelfmark's only other web search source, and libgen appears there
 purely as a download mirror keyed by an AA md5. This source searches libgen's own
 catalogue, which surfaces content AA does not index -- most visibly CBZ/CBR comics and
 manga volumes. Downloads reuse the existing ``ads.php?md5=`` resolution (see handler.py).
 """
 from typing import TYPE_CHECKING, ClassVar
 from shelfmark.core import mirrors
 from shelfmark.core.config import config
 from shelfmark.core.logger import setup_logger
 from shelfmark.release_sources import (
    BrowseRecord,
    ColumnAlign,
    ColumnColorHint,
    ColumnRenderType,
    ColumnSchema,
    Release,
    ReleaseColumnConfig,
    ReleaseProtocol,
    ReleaseSource,
    register_source,
 )
 from shelfmark.release_sources.libgen import scraper
 if TYPE_CHECKING:
    from shelfmark.core.models import DownloadTask  # noqa: F401
    from shelfmark.core.search_plan import ReleaseSearchPlan
    from shelfmark.metadata_providers import BookMetadata
 logger = setup_logger(__name__)
 _DEFAULT_MAX_RESULTS = 25
 def _coerce_positive_int(value: object, default: int) -> int:
    """Return a positive integer config value or the provided default."""
    if isinstance(value, bool):
        return default
    if isinstance(value, int) and value > 0:
        return value
    return default
 def _build_query_candidates(plan: ReleaseSearchPlan, book: BookMetadata) -> list[str]:
    """Build ordered, de-duplicated search queries from the plan (mirrors AudiobookBay)."""
    candidates: list[str] = []
    if plan.manual_query:
        candidates.append(plan.manual_query.strip())
    elif plan.title_variants:
        variant = plan.title_variants[0]
        combined = f"{variant.title} {variant.author}".strip()
        title_only = (variant.title or "").strip()
        if combined:
            candidates.append(combined)
        if title_only and title_only.lower() != combined.lower():
            candidates.append(title_only)
    elif book.title:
        candidates.append(book.title.strip())
    deduped: list[str] = []
    seen: set[str] = set()
    for candidate in candidates:
        normalized = candidate.strip()
        if not normalized or normalized.lower() in seen:
            continue
        seen.add(normalized.lower())
        deduped.append(normalized)
    return deduped
@register_source("libgen")
 class LibgenSource(ReleaseSource):
    """Release source that searches the libgen catalogue for downloadable files."""
    name = "libgen"
    display_name = "Libgen"
    supported_content_types: ClassVar[list[str]] = ["ebook"]  # incl. comics/manga (cbz/cbr)
    def is_available(self) -> bool:
        """Available only when explicitly enabled and libgen mirrors are configured.
        ``is True`` rather than ``bool(...)`` matches the AudiobookBay idiom and avoids a
        truthy string ever enabling network egress to an unmoderated site.
        """
        return (
            config.get("LIBGEN_SEARCH_ENABLED", False) is True
            and mirrors.has_libgen_mirror_configuration()
        )
    def search(
        self,
        book: BookMetadata,
        plan: ReleaseSearchPlan,
        *,
        expand_search: bool = False,
        content_type: str = "ebook",
    ) -> list[Release]:
        """Search libgen for releases of a book."""
        if content_type != "ebook":
            return []
        if not self.is_available():
            return []
        queries = _build_query_candidates(plan, book)
        if not queries:
            return []
        max_results = _coerce_positive_int(
            config.get("LIBGEN_SEARCH_MAX_RESULTS", _DEFAULT_MAX_RESULTS), _DEFAULT_MAX_RESULTS
        )
        mirror_list = mirrors.get_libgen_mirrors()
        # One search_libgen call per candidate; it already retries every mirror internally.
        # Worst case (all mirrors dead) stays within the shared search deadline.
        for query in queries:
            logger.info("Searching Libgen for: %s", query)
            records = scraper.search_libgen(query, mirror_list, max_results=max_results)
            if records:
                return [self._record_to_release(record) for record in records]
        return []
    def _record_to_release(self, record: BrowseRecord) -> Release:
        """Normalize a libgen catalogue record into a Release.
        ``source_id`` is namespaced ``libgen:<md5>`` so the download queue key never
        collides with a direct_download release for the same md5 (Anna's Archive heavily
        indexes libgen, so the same md5 routinely appears from both sources). The handler
        strips the prefix back to the bare md5.
        """
        return Release(
            source="libgen",
            source_id=f"libgen:{record.id}",
            title=record.title,
            format=record.format,
            language=record.language,
            size=record.size,
            download_url=None,  # handler builds ads.php?md5= from the md5
            info_url=record.source_url,
            protocol=ReleaseProtocol.HTTP,
            indexer="Libgen",
            content_type="ebook",
            extra={
                "author": record.author,
                "year": record.year,
                "md5": record.id,
                "language": record.language,
            },
        )
    def search_results_are_releases(self) -> bool:
        """Libgen search rows are concrete, directly downloadable releases."""
        return True
    def get_record(
        self,
        record_id: str,
        *,
        fetch_download_count: bool = True,
    ) -> BrowseRecord | None:
        """Resolve a libgen record by (possibly prefixed) md5, or None if not found."""
        md5 = record_id.split(":", 1)[-1].lower()
        return scraper.fetch_record_by_md5(md5, mirrors.get_libgen_mirrors())
    def get_column_config(self) -> ReleaseColumnConfig:
        """Language, format and size badges -- same layout as Direct Download."""
        return ReleaseColumnConfig(
            columns=[
                ColumnSchema(
                    key="extra.language",
                    label="Language",
                    render_type=ColumnRenderType.BADGE,
                    align=ColumnAlign.CENTER,
                    width="60px",
                    color_hint=ColumnColorHint(type="map", value="language"),
                    uppercase=True,
                ),
                ColumnSchema(
                    key="format",
                    label="Format",
                    render_type=ColumnRenderType.BADGE,
                    align=ColumnAlign.CENTER,
                    width="80px",
                    color_hint=ColumnColorHint(type="map", value="format"),
                    uppercase=True,
                ),
                ColumnSchema(
                    key="size",
                    label="Size",
                    render_type=ColumnRenderType.SIZE,
                    align=ColumnAlign.CENTER,
                    width="80px",
                ),
            ],
            grid_template="minmax(0,2fr) 60px 80px 80px",
            supported_filters=["format", "language"],
        )
@@ -9,7 +9,12 @@ if TYPE_CHECKING:
 from shelfmark.core.logger import setup_logger
 from shelfmark.core.request_helpers import normalize_optional_text
-from shelfmark.download.clients import DownloadClient, get_client, list_configured_clients
+from shelfmark.download.clients import (
    DownloadClient,
    client_prefers_torrent_file,
    get_client,
    list_configured_clients,
 )
 from shelfmark.download.clients.base_handler import (
    COMPLETED_PATH_MAX_ATTEMPTS as _DEFAULT_COMPLETED_PATH_MAX_ATTEMPTS,
 )
@@ -54,13 +59,15 @@ def _get_protocol(result: dict) -> str:
    return "usenet"
-def _get_download_url(result: dict) -> str:
+def _get_download_url(result: dict, *, prefer_torrent_file: bool = False) -> str:
    """Pick the best URL to hand to a download client."""
    protocol = _get_protocol(result)
    magnet_url = str(result.get("magnetUrl") or "").strip()
    download_url = str(result.get("downloadUrl") or "").strip()
    if protocol == "torrent":
        if prefer_torrent_file:
            return download_url or magnet_url
        return magnet_url or download_url
    return download_url or magnet_url
@@ -93,9 +100,15 @@ class NewznabHandler(ExternalClientHandler):
        if result is None:
            return {}
        protocol = _get_protocol(result)
        return {
-            "retry_download_url": normalize_optional_text(_get_download_url(result)),
+            "retry_download_url": normalize_optional_text(
-            "retry_download_protocol": normalize_optional_text(_get_protocol(result)),
+                _get_download_url(
                    result,
                    prefer_torrent_file=client_prefers_torrent_file(protocol),
                )
            ),
            "retry_download_protocol": normalize_optional_text(protocol),
        }
    @classmethod
@@ -137,16 +150,19 @@ class NewznabHandler(ExternalClientHandler):
            status_callback("error", "Release not found in cache (may have expired)")
            return None
        download_url = _get_download_url(result)
        if not download_url:
            status_callback("error", "No download URL available")
            return None
        protocol = _get_protocol(result)
        if protocol not in ("torrent", "usenet"):
            status_callback("error", "Could not determine download protocol")
            return None
        download_url = _get_download_url(
            result,
            prefer_torrent_file=client_prefers_torrent_file(protocol),
        )
        if not download_url:
            status_callback("error", "No download URL available")
            return None
        release_name = result.get("title") or task.title or "Unknown"
        expected_hash = str(result.get("infoHash") or "").strip() or None
@@ -2,6 +2,7 @@
 from collections.abc import Mapping
 from contextlib import suppress
 from datetime import UTC, datetime
 from http import HTTPStatus
 from typing import Any, TypedDict
@@ -235,6 +236,34 @@ class ProwlarrClient:
            logger.exception("Failed to get indexers")
            return []
    def get_disabled_indexers(self, *, now: datetime | None = None) -> dict[int, str]:
        """Get indexers in failure back-off, keyed by ID with their disabledTill value."""
        try:
            entries = _normalize_json_object_list(
                self._request("GET", "/api/v1/indexerstatus"),
                context="Prowlarr indexer status",
            )
        except _PROWLARR_CLIENT_ERRORS:
            logger.exception("Failed to get indexer status")
            return {}
        current = now or datetime.now(UTC)
        disabled: dict[int, str] = {}
        for entry in entries:
            indexer_id = coerce_int_like(entry.get("indexerId"))
            disabled_till_raw = entry.get("disabledTill")
            if indexer_id is None or not disabled_till_raw:
                continue
            try:
                disabled_till = datetime.fromisoformat(str(disabled_till_raw))
            except ValueError:
                continue
            if disabled_till.tzinfo is None:
                disabled_till = disabled_till.replace(tzinfo=UTC)
            if disabled_till > current:
                disabled[indexer_id] = str(disabled_till_raw)
        return disabled
    def get_enabled_indexers_detailed(
        self, *, raise_on_error: bool = False
    ) -> list[dict[str, Any]]:
@@ -12,6 +12,7 @@ from shelfmark.core.search_plan import build_release_search_plan
 from shelfmark.core.utils import normalize_http_url
 from shelfmark.download.clients import (
    DownloadClient,
    client_prefers_torrent_file,
    get_client,
    list_configured_clients,
 )
@@ -247,18 +248,20 @@ class ProwlarrHandler(ExternalClientHandler):
                status_callback("error", EXPIRED_LINK_REFRESH_ERROR)
                return None
        # Extract download URL
        download_url = get_preferred_download_url(prowlarr_result)
        if not download_url:
            status_callback("error", "No download URL available")
            return None
        # Determine protocol
        protocol = get_protocol(prowlarr_result)
        if protocol == "unknown":
            status_callback("error", "Could not determine download protocol")
            return None
        download_url = get_preferred_download_url(
            prowlarr_result,
            prefer_torrent_file=client_prefers_torrent_file(protocol),
        )
        if not download_url:
            status_callback("error", "No download URL available")
            return None
        release_name = prowlarr_result.get("title") or task.title or "Unknown"
        expected_hash = str(prowlarr_result.get("infoHash") or "").strip() or None
@@ -12,6 +12,7 @@ if TYPE_CHECKING:
    from shelfmark.core.search_plan import ReleaseSearchPlan
    from shelfmark.metadata_providers import BookMetadata
 from shelfmark.core.author_match import AUTHOR_UNKNOWN, author_affinity
 from shelfmark.core.config import config
 from shelfmark.core.languages import normalize_language
 from shelfmark.core.logger import setup_logger
@@ -41,8 +42,6 @@ from shelfmark.release_sources.prowlarr.api import (
 )
 from shelfmark.release_sources.prowlarr.cache import cache_release
 from shelfmark.release_sources.prowlarr.utils import (
    AUTHOR_UNKNOWN,
    author_affinity,
    build_source_id,
    coerce_float_like,
    coerce_int_like,
@@ -297,6 +296,7 @@ class _IndexerSearchOutcome:
    results: list[dict]
    attempted: int = 0
    failed: int = 0
    skipped: int = 0
    last_error: str | None = None
@@ -1010,6 +1010,22 @@ class ProwlarrSource(ReleaseSource):
                if time.monotonic() > deadline:
                    _raise_timeout_error(f"Prowlarr search timed out after {int(search_budget)}s")
            # Prowlarr's own search skips an indexer in failure back-off; the
            # per-indexer Torznab endpoint answers 429 instead.
            try:
                disabled_indexers = client.get_disabled_indexers()
            except _PROWLARR_SOURCE_ERRORS as e:
                logger.warning("Failed to load Prowlarr indexer status: %s", e)
                disabled_indexers = {}
            if disabled_indexers:
                logger.info(
                    "Prowlarr: skipping indexer(s) in failure back-off: %s",
                    ", ".join(
                        f"{indexer_id} (till {till})"
                        for indexer_id, till in sorted(disabled_indexers.items())
                    ),
                )
            def search_indexers(query: str, cats: list[int] | None) -> _IndexerSearchOutcome:
                """Search indexers with given categories via Torznab/Newznab.
@@ -1027,6 +1043,9 @@ class ProwlarrSource(ReleaseSource):
                    return outcome
                for indexer_id in target_indexer_ids:
                    if indexer_id in disabled_indexers:
                        outcome.skipped += 1
                        continue
                    _check_timeout()
                    outcome.attempted += 1
                    try:
@@ -1052,6 +1071,7 @@ class ProwlarrSource(ReleaseSource):
            all_results: list[dict] = []
            attempted_searches = 0
            failed_searches = 0
            skipped_searches = 0
            last_search_error: str | None = None
            for idx, variant in enumerate(variants, start=1):
@@ -1070,6 +1090,7 @@ class ProwlarrSource(ReleaseSource):
                if (
                    not outcome.results
                    and not outcome.failed
                    and outcome.attempted
                    and categories
                    and auto_expand_enabled
                ):
@@ -1082,11 +1103,13 @@ class ProwlarrSource(ReleaseSource):
                    outcome.results = expanded.results
                    outcome.attempted += expanded.attempted
                    outcome.failed += expanded.failed
                    outcome.skipped += expanded.skipped
                    outcome.last_error = expanded.last_error or outcome.last_error
                    self.last_search_type = "expanded"
                attempted_searches += outcome.attempted
                failed_searches += outcome.failed
                skipped_searches += outcome.skipped
                last_search_error = outcome.last_error or last_search_error
                for r in outcome.results:
@@ -1192,6 +1215,10 @@ class ProwlarrSource(ReleaseSource):
                    f"({last_search_error})"
                )
                raise SourceUnavailableError(msg)
            if not results and not attempted_searches and skipped_searches:
                until = max(disabled_indexers.values(), default="later")
                msg = f"every indexer is disabled by Prowlarr after recent failures (until {until})"
                raise SourceUnavailableError(msg)
            return results
    def is_available(self) -> bool:
@@ -14,20 +14,6 @@ if TYPE_CHECKING:
 _INTEGER_LIKE_PATTERN = re.compile(r"^[+-]?\d+$")
 _FLOAT_LIKE_PATTERN = re.compile(r"^[+-]?(?:\d+(?:\.\d*)?|\.\d+)$")
 _AUTHOR_TOKEN_PATTERN = re.compile(r"\w+", re.UNICODE)
 _AUTHOR_NOISE_TOKENS = frozenset(
    {"jr", "sr", "ii", "iii", "iv", "phd", "md", "dr", "mr", "mrs", "ms", "et", "al", "and", "the"}
 )
 # Ordering tiers for author agreement between the requested book and what an
 # indexer reported. Lower sorts first.
 AUTHOR_MATCH = 0
 AUTHOR_UNKNOWN = 1
 AUTHOR_MISMATCH = 2
 # A mononym ("Homer") can only ever agree on one token; a longer name needs a
 # given name and a surname to agree before it counts as the same person.
 _AUTHOR_TOKENS_REQUIRED = 2
 def coerce_int_like(value: object) -> int | None:
@@ -46,49 +32,6 @@ def coerce_int_like(value: object) -> int | None:
    return int(normalized)
 def _author_tokens(value: object) -> list[str]:
    """Split an author string into comparable lowercase name tokens."""
    if not isinstance(value, str):
        return []
    tokens = [token.lower() for token in _AUTHOR_TOKEN_PATTERN.findall(value)]
    return [token for token in tokens if token not in _AUTHOR_NOISE_TOKENS]
 def _author_tokens_compatible(wanted: str, offered: str) -> bool:
    """Treat an abbreviated given name as the name it abbreviates."""
    return wanted == offered or wanted.startswith(offered) or offered.startswith(wanted)
 def author_affinity(wanted: object, offered: object) -> int:
    """Rank how far an indexer's author field is from the requested author.
    Shelfmark ranks on this rather than filtering on it, so a wrong verdict only
    costs a release its position in the list, never its visibility. That is what
    makes the loose token comparison safe: "Tim"/"Timothy" and "T."/"Timothy"
    agree, while a transliteration ("Dostoevsky"/"Dostoyevsky") is merely sorted
    last instead of being hidden.
    Three-way on purpose: an indexer that reports no author at all must not sort
    below one that reports a wrong author, so "no metadata" ranks between
    agreement and disagreement rather than counting as either.
    """
    wanted_tokens = _author_tokens(wanted)
    offered_tokens = _author_tokens(offered)
    if not wanted_tokens or not offered_tokens:
        return AUTHOR_UNKNOWN
    matched = sum(
        1
        for wanted_token in wanted_tokens
        if any(
            _author_tokens_compatible(wanted_token, offered_token)
            for offered_token in offered_tokens
        )
    )
    required = min(_AUTHOR_TOKENS_REQUIRED, len(wanted_tokens))
    return AUTHOR_MATCH if matched >= required else AUTHOR_MISMATCH
 def build_source_id(result: dict) -> str:
    """Build the Release.source_id for a raw Prowlarr result.
@@ -149,17 +92,19 @@ def get_protocol(result: dict) -> str:
    return "unknown"
-def get_preferred_download_url(result: dict) -> str:
+def get_preferred_download_url(result: dict, *, prefer_torrent_file: bool = False) -> str:
    """Pick the best URL to hand to a download client.
-    For torrent results, prefer magnetUrl when available (downloadUrl may be a
+    For torrent results, prefer magnetUrl when available unless the configured
-    Prowlarr proxy URL that needs auth/headers).
+    client needs the fetched .torrent bytes.
    """
    protocol = str(result.get("protocol", "")).lower()
    magnet_url = str(result.get("magnetUrl") or "").strip()
    download_url = sanitize_download_url(str(result.get("downloadUrl") or "").strip())
    if protocol == "torrent":
        if prefer_torrent_file:
            return download_url or magnet_url
        return magnet_url or download_url
    if protocol == "usenet":
        return download_url or magnet_url
@@ -0,0 +1,196 @@
 ---
 name: shelfmark
 description: Tool for downloading books.
 license: Complete terms in LICENSE.txt
 ---
 # Shelfmark Book Download Skill
 Use this skill to search for and download books from a local Shelfmark instance using Playwright.
 ## Prerequisites
 - Shelfmark must be running at `http://localhost:8084/`
 - Use `playwright-cli` skill for browser automation capabilities
 - Python 3.10+ with `playwright` package installed
 ## Quick Start
 ```bash
 # Show help information for download script
 python3 /home/username/.agents/skills/shelfmark/download_books.py -h
 # Download a single book
 python3 /home/username/.agents/skills/shelfmark/download_books.py '[{"title": "The Great Gatsby", "author": "F. Scott Fitzgerald"}]'
 # Download multiple books
 python3 /home/username/.agents/skills/shelfmark/download_books.py '[{"title": "The Great Gatsby", "author": "F. Scott Fitzgerald"}, {"title": "Oliver Twist", "author": "Charles Dickens"}, {"title": "Frankenstein", "author": "Marry Shelley"}]'
 # Check calibre database before downloading (skip if already present)
 python3 /home/username/.agents/skills/shelfmark/download_books.py --check-calibre '[{"title": "Frankenstein", "author": "Marry Shelley"}]'
 # Load books from a JSON file
 python3 /home/username/.agents/skills/shelfmark/download_books.py --file books.json
 ```
 The JSON file (`books.json`) should contain an array of book objects:
 ```json
 [
  {"title": "The Great Gatsby", "author": "F. Scott Fitzgerald"},
  {"title": "Frankenstein", "author": "Mary Shelley"},
  {"title": "Oliver Twist", "author": "Charles Dickens"}
 ]
 ```
 Array format is also supported: `[["The Great Gatsby", "F. Scott Fitzgerald"], ["Oliver Twist", "Charles Dickens"], ["Frankenstein", "Marry Shelley"]]`
 Title-only (no author) is supported: `["Frankenstein"]`
 ## Key Characteristics
 - **Shelfmark is a React SPA** — raw HTML is a shell; JavaScript dynamically populates the DOM
 - **Desktop viewport required** (`1280x900`) — download buttons use `hidden sm:flex` and won't render on mobile
 - **Download count pattern** in HTML: `<span>•</span> <span>NUMBER</span> </div>` (the last number before the download button)
 - **Download button selector**: `<button ... data-action="download" ...>Download</button>`
 - **Search input**: `<input type="search" placeholder="Search Books">`
 - **Results indicator**: `<span class="text-sm font-medium whitespace-nowrap">Most relevant</span>`
 ## How It Works
 ### 1. Search for a Book
 The script navigates to the main page, enters the search query, and waits for "Most relevant" to appear:
 ```python
 # Navigate to main page first to reset SPA state
 page.goto('http://localhost:8084/')
 page.wait_for_load_state('networkidle')
 # Enter search query and submit
 page.fill('input[type="search"]', f'{title} {author}')
 page.press('input[type="search"]', 'Enter')
 # Wait for "Most relevant" to appear (indicates search results are fully rendered)
 page.wait_for_selector('span.text-sm.font-medium:has-text("Most relevant")', timeout=60000)
 ```
 - Always navigate to the main page before each search to reset React SPA state
 - Include both title and author in the search query
 - Wait for `span.text-sm.font-medium:has-text("Most relevant")` to appear — this indicates search results are fully loaded
 - **Do not use timers** to wait for results — always wait for a specific page element
 ### 2. Find and Parse Download Buttons
 ```python
 def parse_books(page):
    btns = page.query_selector_all('button[data-action="download"]')
    books = []
    for i, btn in enumerate(btns):
        content = btn.evaluate_handle('el => el.parentElement.parentElement').inner_html()
        title_match = re.search(r'<h3[^>]*>(.*?)</h3>', content, re.IGNORECASE | re.DOTALL)
        title = title_match.group(1).strip() if title_match else 'Unknown'
        author_match = re.search(r'class="min-w-0 truncate text-xs[^"]*"[^>]*>(.*?)<', content, re.IGNORECASE | re.DOTALL)
        author = author_match.group(1).strip() if author_match else 'Unknown'
        dl_match = re.search(r'<span>•</span>\s*<span>([\d,]+)</span>', content)
        downloads = int(dl_match.group(1).replace(',', '')) if dl_match else 0
        books.append({'index': i, 'title': title, 'author': author, 'downloads': downloads})
    return books
 ```
 ### 3. Select and Download the Book with Most Downloads
 ```python
 # Filter books matching the search criteria
 matching_books = [b for b in books if matches_search(b['title'], b['author'], title, author)]
 if matching_books:
    best = max(matching_books, key=lambda x: x['downloads'])
    # CRITICAL: Click on the article h3 to open detail view
    h3s = page.query_selector_all('article h3')
    if best['index'] < len(h3s):
        h3s[best['index']].click()
        page.wait_for_timeout(300)
    # Then click the download button
    btn = page.query_selector_all('button[data-action="download"]')[best['index']]
    btn.click()
    page.wait_for_timeout(500)
 ```
 **Important**: The React SPA requires clicking on the article's `<h3>` element first to open the detail view. Simply clicking the download button directly often fails silently.
 ### 4. Wait for Download to Complete
 ```python
 for i in range(60):
    page.wait_for_timeout(5000)
    activity_text = page.inner_text('aside')
    if 'IN PROGRESS' in activity_text:
        print("Download started!")
    elif 'Complete' in activity_text or 'Saved' in activity_text:
        print("Download complete!")
        break
    elif 'No activity' in activity_text:
        print("Download not started")
        break
 ```
 ### 5. Clear Completed Downloads
 ```python
 # Click "Clear Completed" using JavaScript
 page.evaluate('''
    () => {
        for (const b of document.querySelectorAll('button')) {
            if (b.textContent.includes('Clear Completed')) {
                b.click();
                return;
            }
        }
    }
 ''')
 page.wait_for_timeout(2000)
 ```
 ### Checking Calibre Database
 Use `--check-calibre` (or `-c`) to check if books are already in your calibre database before downloading:
 ```bash
 python3 download_books.py --check-calibre '[{"title": "Frankenstein", "author": "Mary Shelley"}]'
 ```
 Books found in calibre are skipped with a message. If all books are already present, the script exits early without launching the browser.
 ## Important Notes
 - **Always click the article element first** before clicking the download button — the React SPA requires this to properly initialize the download workflow
 - **Wait for "Most relevant" text** to appear after search — this indicates results are fully loaded (don't use timers)
 - **Navigate to main page** (`http://localhost:8084/`) before each new search to reset React SPA state
 - **Some books may have different authors listed** than what's in your source file — the script falls back to title-only search if author search fails
 - **The download count** is the last number in the format `• NUMBER` before the download button
 - **Book titles may include series info** in brackets, e.g., `(The Locked Tomb Trilogy)`
 - **Use `page.evaluate_handle`** to get parent element HTML for parsing — the button's `parentElement.parentElement` contains the card content
 - **Title matching** prefers exact matches over partial matches (e.g., "Yesteryear" matches "Yesteryear: A Novel" but not "The Piers of Yesteryear")
 - **Books are passed as JSON** — use `--check-calibre` to optionally skip books already in your calibre database
 ## Common Issues
 | Issue | Solution |
 |-------|----------|
 | No download buttons found | Use desktop viewport (1280x900), wait for `span.text-sm.font-medium:has-text("Most relevant")` |
 | Download button click does nothing | Click the article's `<h3>` element first, then click the download button |
 | Search returns no results | The script falls back to title-only search automatically |
 | Download count shows 0 | The parsing regex may need adjustment — check the HTML structure |
 | Sidebar shows "No activity" after click | Ensure you clicked the `<h3>` element first, and wait at least 2 seconds before checking |
 | Search results don't update between books | Navigate to `http://localhost:8084/` before each new search to reset SPA state |
 | Book downloaded is wrong title | The script prefers exact title matches — if the title is ambiguous, the author search will help narrow it down |
 | Books passed incorrectly | Books must be valid JSON — use `{"title": "...", "author": "..."}` format, not `Title: Author` |
@@ -0,0 +1,353 @@
 #!/usr/bin/env python3
 """Shelfmark Book Downloader - Downloads books from a local Shelfmark instance."""
 from playwright.sync_api import sync_playwright
 import re, time, sys, argparse, json
 from urllib.parse import quote
 SHELFMARK_URL = 'http://localhost:8084/'
 def parse_books(page):
    btns = page.query_selector_all('button[data-action="download"]')
    books = []
    for i, btn in enumerate(btns):
        content = btn.evaluate_handle('el => el.parentElement.parentElement').inner_html()
        title_match = re.search(r'<h3[^>]*>(.*?)</h3>', content, re.IGNORECASE | re.DOTALL)
        title = title_match.group(1).strip() if title_match else 'Unknown'
        author_match = re.search(r'class="min-w-0 truncate text-xs[^"]*"[^>]*>(.*?)<', content, re.IGNORECASE | re.DOTALL)
        author = author_match.group(1).strip() if author_match else 'Unknown'
        dl_match = re.search(r'<span>•</span>\s*<span>([\d,]+)</span>', content)
        downloads = int(dl_match.group(1).replace(',', '')) if dl_match else 0
        books.append({'index': i, 'title': title, 'author': author, 'downloads': downloads})
    return books
 def do_search(page, title, author, search_type="author"):
    """Search with title+author, fall back to title only"""
    # Navigate to main page first to reset SPA state
    page.goto(SHELFMARK_URL)
    page.wait_for_load_state('networkidle')
    # Enter search query and submit
    search_query = f'{title} {author}' if search_type == "author" else title
    page.fill('input[type="search"]', search_query)
    page.press('input[type="search"]', 'Enter')
    # Wait for "Most relevant" to appear (indicates search results are fully rendered)
    try:
        page.wait_for_selector('span.text-sm.font-medium:has-text("Most relevant")', timeout=60000)
    except:
        if search_type == "author":
            print("  -> Trying title only...")
            sys.stdout.flush()
            return do_search(page, title, author, search_type="title")
        else:
            print("  >> Timeout waiting for search results")
            sys.stdout.flush()
            return None
    books = parse_books(page)
    def clean_title_for_match(book_title, search_title):
        """Clean book title to check if it matches the search title"""
        # Remove common subtitle patterns
        clean = re.sub(r'\s*[:–—]\s*(A Novel|Reese\'s Book Club.*?|The Hilarious.*?|A GMA Book Club Pick.*?|Movie Tie-In.*?|eBook.*?|\[.*?\].*?)$', '', book_title, flags=re.IGNORECASE)
        clean = clean.strip()
        # Remove trailing punctuation
        clean = clean.rstrip(':,;.')
        return clean.lower().strip() == search_title.lower().strip()
    def matches_search(book_title, book_author, search_title, search_author):
        """Check if book matches search criteria more strictly"""
        title_match = search_title.lower() in book_title.lower()
        author_match = search_author.lower() in book_author.lower()
        # For title+author search, ensure title starts with search title (not just contains it)
        if title_match and author_match:
            return clean_title_for_match(book_title, search_title) or book_title.lower().startswith(search_title.lower())
        # Also check if author name appears in reverse order (e.g., "Grann, David" matches "David Grann")
        if title_match:
            author_parts = search_author.lower().split()
            if len(author_parts) >= 2:
                reversed_author = f"{author_parts[-1]} {author_parts[0]}"
                if reversed_author in book_author.lower() or book_author.lower().startswith(reversed_author):
                    return clean_title_for_match(book_title, search_title) or book_title.lower().startswith(search_title.lower())
        return False
    if search_type == "author":
        matching = [b for b in books if matches_search(b['title'], b['author'], title, author)]
        print(f"  With author: {len(books)} total, {len(matching)} matching")
        for b in books[:3]:
            print(f"    [{b['index']}] '{b['title']}' by {b['author']} ({b['downloads']})")
        sys.stdout.flush()
        if matching:
            # Check if any matching book is already in the download queue
            try:
                sidebar_text = page.inner_text('aside')
                if 'IN PROGRESS' in sidebar_text:
                    # Get the title of the book currently downloading
                    current_download = sidebar_text.split('IN PROGRESS')[1].split('—')[0].strip().split('\n')[0].strip()
                    # Check if the current download matches our search
                    if title.lower() in current_download.lower():
                        print(f"  >> '{current_download}' already downloading, skipping")
                        sys.stdout.flush()
                        return None
            except:
                pass
        if matching:
            return matching, books
        # Fall back to title only
        print("  -> Trying title only...")
        sys.stdout.flush()
        return do_search(page, title, author, search_type="title")
    # Title-only search - prefer exact matches first
    matching = [b for b in books if title.lower() in b['title'].lower()]
    exact_matches = [b for b in matching if clean_title_for_match(b['title'], title)]
    if exact_matches:
        matching = exact_matches
    print(f"  Title-only: {len(books)} total, {len(matching)} matching ({len(exact_matches)} exact)")
    for b in books[:5]:
        print(f"    [{b['index']}] '{b['title']}' by {b['author']} ({b['downloads']})")
    sys.stdout.flush()
    if not matching:
        return None
    return (matching, books)
 def download_book(page, title, author):
    result = do_search(page, title, author)
    if not result:
        print("\n  >>> NOT FOUND")
        sys.stdout.flush()
        return
    matching, all_books = result
    if not matching:
        print("\n  >>> NOT FOUND")
        sys.stdout.flush()
        return
    # Find the best book that is not disabled
    btns = page.query_selector_all('button[data-action="download"]')
    best = None
    for b in sorted(matching, key=lambda x: x['downloads'], reverse=True):
        if b['index'] < len(btns) and not btns[b['index']].is_disabled():
            best = b
            break
    if not best:
        print("\n  >>> All matching books are already in download queue")
        sys.stdout.flush()
        return
    print(f"\n  >>> DOWNLOADING: '{best['title']}' by {best['author']} ({best['downloads']} dl) [idx={best['index']}]")
    sys.stdout.flush()
    # Click on the article h3 to open detail view (required for download to work)
    h3s = page.query_selector_all('article h3')
    if best['index'] < len(h3s):
        h3s[best['index']].click()
        page.wait_for_timeout(300)
    else:
        print(f"  >> Warning: h3 index {best['index']} out of range ({len(h3s)} h3s)")
        sys.stdout.flush()
    # Click the download button
    btn = btns[best['index']]
    btn.click()
    # Wait a moment for the click to register
    page.wait_for_timeout(500)
    print(f"  >> Click sent")
    sys.stdout.flush()
    # Check sidebar immediately
    time.sleep(2)
    try:
        txt = page.inner_text('aside')
        if 'IN PROGRESS' in txt:
            print(f"  >> Download started!")
            sys.stdout.flush()
        else:
            print(f"  >> Sidebar after 2s: {txt[:150]}")
            sys.stdout.flush()
    except:
        print(f"  >> Sidebar not visible after 2s")
        sys.stdout.flush()
    # Wait for download to complete - check sidebar every 2 seconds, max 5 minutes
    last_state = None
    for attempt in range(150):
        time.sleep(2)
        try:
            txt = page.inner_text('aside')
            if 'IN PROGRESS' in txt:
                state = 'downloading'
            elif 'Complete' in txt or 'Saved' in txt or 'No activity' in txt:
                state = 'done'
            else:
                state = 'other'
            if state != last_state:
                if state == 'downloading':
                    print(f"  >> Download started!")
                elif state == 'done':
                    if 'No activity' in txt:
                        print(f"  >> Download not started (no activity)")
                    else:
                        print(f"  >> Download complete!")
                last_state = state
                if state == 'done':
                    break
        except:
            if last_state is None:
                print(f"  >> Sidebar not visible yet")
                last_state = 'no_sidebar'
        sys.stdout.flush()
    else:
        if last_state != 'done':
            print("  >> Timeout waiting for download")
        sys.stdout.flush()
 def clear_completed_downloads(page):
    """Clear completed downloads from previous sessions"""
    page.evaluate('''
        () => {
            for (const b of document.querySelectorAll('button')) {
                if (b.textContent.includes('Clear Completed')) { b.click(); return; }
            }
        }
    ''')
    page.wait_for_timeout(2000)
 def check_calibre(title):
    """Check if a book is already in the calibre database."""
    import subprocess
    cmd = f'calibredb list --search title:="{title}"'
    result = subprocess.run(cmd, shell=True, capture_output=True, text=True)
    output = result.stdout.strip()
    # calibredb output has header line "id title authors", count non-header lines
    lines = [l.strip() for l in output.split('\n') if l.strip()]
    # Remove header if present (first line starts with 'id')
    if lines and lines[0].startswith('id'):
        lines = lines[1:]
    return len(lines) > 0
 def load_books_from_json(json_str, source):
    """Load books from a JSON string or file path."""
    try:
        data = json.loads(json_str)
    except json.JSONDecodeError as e:
        print(f"Error: Invalid JSON in {source}: {e}")
        sys.exit(1)
    if not isinstance(data, list):
        print(f"Error: JSON in {source} must be an array of book objects")
        sys.exit(1)
    books = []
    for item in data:
        if isinstance(item, dict):
            if 'title' not in item or 'author' not in item:
                print(f"Error: Each book object must have 'title' and 'author' keys: {item}")
                sys.exit(1)
            books.append((item['title'].strip(), item['author'].strip()))
        elif isinstance(item, list) and len(item) >= 2:
            books.append((str(item[0]).strip(), str(item[1]).strip()))
        elif isinstance(item, str):
            # Support plain strings as title-only (author will be searched separately)
            books.append((item.strip(), ""))
        else:
            print(f"Warning: Skipping unrecognized book entry: {item}")
    return books
 def main():
    parser = argparse.ArgumentParser(description='Download books from Shelfmark')
    parser.add_argument('books', nargs='*', help='Books as JSON array of [title, author] pairs or {"title": ..., "author": ...} objects')
    parser.add_argument('--file', '-f', help='Path to JSON file containing an array of books')
    parser.add_argument('-c', '--check-calibre', action='store_true', help='Check calibre database before downloading, skip if already present')
    args = parser.parse_args()
    # Load books from --file, positional JSON arg, or both
    BOOKS = []
    if args.file:
        try:
            with open(args.file, 'r') as f:
                BOOKS = load_books_from_json(f.read(), f"file '{args.file}'")
        except FileNotFoundError:
            print(f"Error: File not found: {args.file}")
            sys.exit(1)
        except IOError as e:
            print(f"Error reading file: {e}")
            sys.exit(1)
    for book_arg in args.books:
        BOOKS.extend(load_books_from_json(book_arg, 'command line argument'))
    if not BOOKS:
        print("Error: No books specified. Use positional JSON args or --file <path>")
        sys.exit(1)
    # Check calibre database if requested
    if args.check_calibre:
        print("\nChecking calibre database...")
        sys.stdout.flush()
        remaining = []
        for title, author in BOOKS:
            if check_calibre(title):
                print(f"  >> '{title}' already in calibre, skipping")
                sys.stdout.flush()
            else:
                remaining.append((title, author))
        BOOKS = remaining
        if not BOOKS:
            print("All books already in calibre, nothing to download.")
            sys.stdout.flush()
            return
    print(f"\n{'='*60}")
    print(f"Downloading {len(BOOKS)} book(s) from Shelfmark")
    print('='*60)
    sys.stdout.flush()
    with sync_playwright() as p:
        browser = p.chromium.launch()
        page = browser.new_page(viewport={'width': 1280, 'height': 900})
        page.goto(SHELFMARK_URL)
        page.wait_for_load_state('networkidle')
        # Clear completed downloads at start of batch
        print(f"\n{'='*60}")
        print("Clearing completed downloads from previous sessions...")
        print('='*60)
        sys.stdout.flush()
        clear_completed_downloads(page)
        for i, (title, author) in enumerate(BOOKS, 1):
            print(f"\n{'='*60}")
            print(f"[{i}/{len(BOOKS)}] '{title}' by {author}")
            print('='*60)
            sys.stdout.flush()
            download_book(page, title, author)
        browser.close()
        print("\nDone!")
        sys.stdout.flush()
 if __name__ == '__main__':
    main()
@@ -18,23 +18,23 @@
  },
  "dependencies": {
    "@tailwindcss/vite": "^4.3.3",
-    "react": "^19.2.8",
+    "react": "^19.3.0",
-    "react-dom": "^19.2.8",
+    "react-dom": "^19.3.0",
-    "react-router-dom": "^7.18.2",
+    "react-router-dom": "^7.18.3",
    "socket.io-client": "^4.7.5"
  },
  "devDependencies": {
-    "@types/node": "^26.3.0",
+    "@types/node": "^26.5.1",
-    "@types/react": "^19.2.18",
+    "@types/react": "^19.3.0",
-    "@types/react-dom": "^19.2.5",
+    "@types/react-dom": "^19.3.0",
-    "@vitejs/plugin-react": "^6.1.0",
+    "@vitejs/plugin-react": "^6.1.1",
-    "knip": "^6.32.2",
+    "knip": "^6.35.1",
-    "oxfmt": "^0.65.0",
+    "oxfmt": "^0.68.0",
-    "oxlint": "^1.80.0",
+    "oxlint": "^1.83.0",
    "oxlint-tsgolint": "^7.0.2001",
    "tailwindcss": "^4.2.2",
    "typescript": "^7.0.2",
-    "vite": "^8.2.2",
+    "vite": "^8.3.0",
-    "vitest": "^4.1.11"
+    "vitest": "^5.0.0"
  }
 }
@@ -41,7 +41,7 @@ import { useRequests } from './hooks/useRequests';
 import { useSearch } from './hooks/useSearch';
 import { primeSettingsCache } from './hooks/useSettings';
 import { useToast } from './hooks/useToast';
-import { useUrlSearch } from './hooks/useUrlSearch';
+import { useExternalHashChange, useSyncUrlSearchHash, useUrlSearch } from './hooks/useUrlSearch';
 import { primeUsersCache } from './hooks/useUsersFetch';
 import { LoginPage } from './pages/LoginPage';
 import {
@@ -93,7 +93,7 @@ import { getConfiguredMetadataProviderForContentType } from './utils/metadataPro
 import { getEffectiveMetadataSort } from './utils/metadataSort';
 import { isRecord } from './utils/objectHelpers';
 import { policyTrace } from './utils/policyTrace';
-import { buildQueryTargets, getDefaultQueryTargetKey } from './utils/queryTargets';
+import { buildQueryTargets, findQueryTarget, getDefaultQueryTargetKey } from './utils/queryTargets';
 import { buildReleaseDownloadPayload, type ReleaseDownloadOptions } from './utils/releasePayload';
 import { applyRequestNoteToPayload } from './utils/requestConfirmation';
 import { bookFromRequestData } from './utils/requestFulfil';
@@ -110,6 +110,8 @@ import {
  applyDirectPolicyModeToButtonState,
  applyUniversalPolicyModeToButtonState,
 } from './utils/requestPolicyUi';
 import { getSearchByPreference, setSearchByPreference } from './utils/searchByPreference';
 import { buildUrlSearchHash } from './utils/urlSearchHash';
 // eslint-disable-next-line import/no-unassigned-import -- global app stylesheet is loaded for side effects
 import './styles.css';
@@ -476,6 +478,7 @@ function App() {
    updateAdvancedFilters,
    handleSearch,
    handleResetSearch,
    reSortByDownloads,
    searchFieldValues,
    updateSearchFieldValue,
    searchFieldLabels,
@@ -484,6 +487,7 @@ function App() {
    isLoadingMore,
    loadMore,
    totalFound,
    directTotalResults,
    resultsSourceUrl,
  } = useSearch({
    showToast,
@@ -617,7 +621,12 @@ function App() {
  const [configuredCombinedMetadataProvider, setConfiguredCombinedMetadataProvider] = useState<
    string | null
  >(null);
-  const [activeQueryTarget, setActiveQueryTarget] = useState('general');
+  // Falls back to the stored "Search By" default from the user's last-used mode;
  // an invalid/stale value is harmless since effectiveActiveQueryTarget below re-validates
  // it against the current queryTargets once config/search fields are known.
  const [activeQueryTarget, setActiveQueryTarget] = useState(
    () => getSearchByPreference() || 'general',
  );
  const [downloadsSidebarOpen, setDownloadsSidebarOpen] = useState(false);
  const [sidebarPinnedOpen, setSidebarPinnedOpen] = useState<boolean>(() =>
    getInitialPinnedPreference(),
@@ -693,8 +702,22 @@ function App() {
  // URL-based search: parse URL params for automatic search on page load
  const urlSearchEnabled = isAuthenticated && config !== null;
-  const { parsedParams, wasProcessed } = useUrlSearch({ enabled: urlSearchEnabled });
+  // Bumped when the hash changes to something we didn't write - a shared link pasted into
  // an already-open tab. Re-parses the URL and remounts the bootstrap so it applies.
  const [urlSearchNonce, setUrlSearchNonce] = useState(0);
  const { parsedParams, wasProcessed } = useUrlSearch({
    enabled: urlSearchEnabled,
    nonce: urlSearchNonce,
  });
  const [hasExecutedUrlSearchBootstrap, setHasExecutedUrlSearchBootstrap] = useState(false);
  // Same fact as the state above, readable from loadConfig's async continuation, which
  // closes over the render it started in and would otherwise see a stale `false`.
  const urlSearchBootstrapAppliedRef = useRef(false);
  useExternalHashChange(() => {
    urlSearchBootstrapAppliedRef.current = false;
    setHasExecutedUrlSearchBootstrap(false);
    setUrlSearchNonce((value) => value + 1);
  });
  const prevSearchModeRef = useRef<string | undefined>(undefined);
@@ -825,12 +848,16 @@ function App() {
        // Determine the default sort based on search mode
        const defaultSort =
-          cfg.search_mode === 'universal'
+          cfg.search_mode === 'universal' ? resolvedMetadataDefaultSort : (cfg.default_sort ?? '');
            ? resolvedMetadataDefaultSort
            : cfg.default_sort || 'relevance';
        if (cfg?.supported_formats) {
-          if (mode === 'initial') {
+          // Seeding the defaults must not undo filters a shared link already applied.
          // The URL bootstrap is gated on config being loaded, so normally it runs after
          // this and wins on its own - but nothing guarantees this is the only 'initial'
          // load (React's StrictMode double-invokes the mount effect that triggers it in
          // development), and a late one would reset `formats` to the full supported list
          // and drop the link's own sort.
          if (mode === 'initial' && !urlSearchBootstrapAppliedRef.current) {
            setAdvancedFilters((prev) => ({
              ...prev,
              formats: cfg.supported_formats,
@@ -924,6 +951,7 @@ function App() {
      contentTypeOverride?: ContentType;
      searchModeOverride?: SearchMode;
      providerOverride?: string;
      sort?: string;
    }) => {
      void refreshRequestPolicy();
      void handleSearch({
@@ -933,6 +961,7 @@ function App() {
        contentTypeOverride: opts.contentTypeOverride,
        searchMode: opts.searchModeOverride,
        providerOverride: opts.providerOverride,
        sort: opts.sort,
      });
    },
    [refreshRequestPolicy, handleSearch, config],
@@ -1934,6 +1963,15 @@ function App() {
    return getDefaultQueryTargetKey(queryTargets);
  }, [queryTargets, activeQueryTarget]);
  // Persist only what the user explicitly picked in the selector. Persisting the derived
  // `effectiveActiveQueryTarget` instead would overwrite the stored default with `general`
  // every time it collapses for reasons the user didn't choose: a cold load before the
  // metadata search fields resolve, the logo reset, logout, or a `view_series` browse.
  const handleQueryTargetChange = useCallback((nextTarget: string) => {
    setActiveQueryTarget(nextTarget);
    setSearchByPreference(nextTarget);
  }, []);
  const activeQueryOption = useMemo(
    () =>
      queryTargets.find((target) => target.key === effectiveActiveQueryTarget) ?? queryTargets[0],
@@ -1986,6 +2024,40 @@ function App() {
    return searchFieldValues[activeQueryOption.field.key] ?? '';
  }, [activeQueryOption, searchInput, searchFieldValues]);
  // The sort the app applies with no user choice, mirroring what loadConfig seeds
  // advancedFilters.sort with - a sort equal to it is a default, not a shared intent.
  const urlHashDefaultSort =
    effectiveSearchMode === 'universal'
      ? resolvedMetadataDefaultSort
      : (config?.default_sort ?? '');
  // Keep the URL hash fragment live as search state changes. Gated until any URL-driven
  // bootstrap has applied (or there was nothing to apply), so we don't clobber a shared
  // link's params with the initial default state before they've been read.
  const readyToSyncUrlHash = wasProcessed && (!parsedParams || hasExecutedUrlSearchBootstrap);
  const urlSearchHash = useMemo(
    () =>
      buildUrlSearchHash({
        queryValue: activeQueryValue,
        searchBy: effectiveActiveQueryTarget,
        contentType,
        combinedMode,
        advancedFilters,
        defaultSort: urlHashDefaultSort,
        defaultFormats: supportedFormats,
      }),
    [
      activeQueryValue,
      effectiveActiveQueryTarget,
      contentType,
      combinedMode,
      advancedFilters,
      urlHashDefaultSort,
      supportedFormats,
    ],
  );
  useSyncUrlSearchHash({ enabled: readyToSyncUrlHash, hash: urlSearchHash });
  const activeQueryValueLabel = useMemo(() => {
    if (!activeQueryOption?.field) {
      return undefined;
@@ -2290,6 +2362,7 @@ function App() {
      fieldValues: request.fieldValues,
      searchModeOverride: effectiveSearchMode,
      providerOverride: request.providerOverride,
      sort: advancedFilters.sort,
    });
  }, [
    activeQueryOption,
@@ -2401,7 +2474,7 @@ function App() {
          onCombinedModeChange={combinedModeAllowed ? setCombinedMode : undefined}
          queryTargets={queryTargets}
          activeQueryTarget={effectiveActiveQueryTarget}
-          onQueryTargetChange={setActiveQueryTarget}
+          onQueryTargetChange={handleQueryTargetChange}
          activeQueryField={activeQueryField}
        />
      </div>
@@ -2468,7 +2541,7 @@ function App() {
            onQueryValueChange={handleActiveQueryValueChange}
            queryTargets={queryTargets}
            activeQueryTarget={effectiveActiveQueryTarget}
-            onQueryTargetChange={setActiveQueryTarget}
+            onQueryTargetChange={handleQueryTargetChange}
            showAdvanced={effectiveShowAdvanced}
            onAdvancedToggle={
              hasAdvancedContent ? () => setShowAdvanced(!effectiveShowAdvanced) : undefined
@@ -2513,11 +2586,19 @@ function App() {
                updateAdvancedFilters({ sort: request.appliedSort });
              }
              setActiveResultsSort(request.appliedSort);
              // "Most downloads" is a client-side sort — just re-sort existing books
              if (request.appliedSort === 'downloads' && effectiveSearchMode === 'direct') {
                reSortByDownloads();
                return;
              }
              runSearchWithPolicyRefresh({
                query: request.query,
                fieldValues: request.fieldValues,
                searchModeOverride: effectiveSearchMode,
                providerOverride: request.providerOverride,
                sort: request.appliedSort,
              });
            }}
            metadataSortOptions={resolvedMetadataSortOptions}
@@ -2527,6 +2608,7 @@ function App() {
              void loadMore(config, effectiveSearchMode);
            }}
            totalFound={totalFound}
            directTotalResults={directTotalResults}
            onShowToast={showToast}
            resultsSourceUrl={resultsSourceUrl}
          />
@@ -2749,14 +2831,31 @@ function App() {
  const adminSettingsWarmup = adminSettingsWarmupKey ? (
    <AdminSettingsWarmupMount key={adminSettingsWarmupKey} />
  ) : null;
  // A `search_by` deep link can name a metadata provider field that isn't in queryTargets
  // until the search-fields fetch resolves. Bootstrapping before then runs the search
  // against the wrong target *and* lets the sync effect rewrite the shared hash without
  // `search_by`, so hold the one-shot mount until the fields have settled (the session
  // resolves to null on failure, so this can't hang).
  const searchFieldsSettled =
    metadataConfigSessionKey === null ||
    activeMetadataConfigState?.sessionKey === metadataConfigSessionKey;
  const awaitingSearchByTarget = Boolean(
    parsedParams?.searchBy && !findQueryTarget(queryTargets, parsedParams.searchBy),
  );
  const urlSearchBootstrapMount =
-    wasProcessed && parsedParams && config && !hasExecutedUrlSearchBootstrap ? (
+    wasProcessed &&
    parsedParams &&
    config &&
    !hasExecutedUrlSearchBootstrap &&
    (searchFieldsSettled || !awaitingSearchByTarget) ? (
      <UrlSearchBootstrapMount
        key={urlSearchNonce}
        parsedParams={parsedParams}
        config={config}
        contentType={contentType}
        combinedMode={combinedMode}
        combinedModeAllowed={combinedModeAllowed}
        queryTargets={queryTargets}
        advancedFilters={advancedFilters}
        resolvedMetadataDefaultSort={resolvedMetadataDefaultSort}
        resolvedMetadataSortOptions={resolvedMetadataSortOptions}
@@ -2766,8 +2865,10 @@ function App() {
        setAdvancedFilters={setAdvancedFilters}
        setShowAdvanced={setShowAdvanced}
        setActiveQueryTarget={setActiveQueryTarget}
        setSearchFieldValue={updateSearchFieldValue}
        runSearchWithPolicyRefresh={runSearchWithPolicyRefresh}
        onComplete={() => {
          urlSearchBootstrapAppliedRef.current = true;
          setHasExecutedUrlSearchBootstrap(true);
        }}
      />
@@ -1,3 +1,5 @@
 import { shortBuildId } from '../utils/buildVersion';
 interface FooterProps {
  buildVersion?: string;
  releaseVersion?: string;
@@ -8,11 +10,7 @@ export const Footer = ({ buildVersion, releaseVersion, debug }: FooterProps) =>
  // Determine version display - show "dev" if no version is set
  const versionDisplay = releaseVersion && releaseVersion !== 'N/A' ? releaseVersion : 'dev';
-  // Truncate long build versions (e.g., git hashes) to 7 chars
+  const buildId = shortBuildId(buildVersion);
  let truncatedBuild: string | null = null;
  if (buildVersion && buildVersion !== 'N/A') {
    truncatedBuild = buildVersion.length > 7 ? buildVersion.slice(0, 7) : buildVersion;
  }
  return (
    <footer
@@ -35,7 +33,7 @@ export const Footer = ({ buildVersion, releaseVersion, debug }: FooterProps) =>
          title={buildVersion && buildVersion !== 'N/A' ? `Build: ${buildVersion}` : undefined}
        >
          {versionDisplay}
-          {truncatedBuild && ` (${truncatedBuild})`}
+          {buildId && ` (${buildId})`}
        </span>
        {debug && (
          <span
@@ -1769,7 +1769,7 @@ const ReleaseModalSession = ({
                </div>
              )}
              {!sourcesLoading && allTabs.length > 0 && (
-                <div className="flex items-center justify-between px-5">
+                <div className="flex items-center px-5">
                  {/* Tabs - scrollable on narrow screens */}
                  <div className="scrollbar-hide min-w-0 flex-1 overflow-x-auto">
                    <div className="relative flex gap-1">
@@ -1801,7 +1801,35 @@ const ReleaseModalSession = ({
                    </div>
                  </div>
-                  <div className="flex items-center gap-3 pr-1 pl-2">
+                  {/* Center: Results count from release sources */}
                  <div className="flex flex-1 justify-center">
                    {(() => {
                      const searchInfo = releasesBySource[activeTab]?.search_info?.[activeTab];
                      const totalCount = searchInfo?.total_results;
                      if (totalCount === undefined || totalCount === null || totalCount === 0)
                        return null;
                      const isCapped = totalCount === '500+';
                      const totalCountNum = isCapped ? 500 : Number(totalCount);
                      // AA-style: show page range + total
                      if (totalCountNum === 1) {
                        return (
                          <span className="mx-2 shrink-0 text-xs whitespace-nowrap text-gray-500 dark:text-gray-400">
                            Result 1 (1 Total)
                          </span>
                        );
                      }
                      const shownEnd = Math.min(totalCountNum, 50);
                      const totalStr = isCapped ? '500+' : String(totalCountNum);
                      return (
                        <span className="mx-2 shrink-0 text-xs whitespace-nowrap text-gray-500 dark:text-gray-400">
                          Results 1-{shownEnd} ({totalStr} Total)
                        </span>
                      );
                    })()}
                  </div>
                  {/* Right: Controls */}
                  <div className="ml-auto flex items-center gap-3 pr-1 pl-2">
                    {/* Multi-book pack toggle (fallback for releases that can't be inspected) */}
                    {!isCombinedMode && (
                      <button
@@ -33,6 +33,8 @@ interface ResultsSectionProps {
  isLoadingMore?: boolean;
  onLoadMore?: () => void;
  totalFound?: number;
  // Direct mode: total result count from release sources
  directTotalResults?: number | string | null;
  onShowToast?: (message: string, type: 'success' | 'error' | 'info') => void;
  resultsSourceUrl?: string;
 }
@@ -53,6 +55,7 @@ export const ResultsSection = ({
  isLoadingMore,
  onLoadMore,
  totalFound,
  directTotalResults,
  onShowToast,
  resultsSourceUrl,
 }: ResultsSectionProps) => {
@@ -88,34 +91,62 @@ export const ResultsSection = ({
  return (
    <section id="results-section" className="mb-4 w-full sm:mb-8">
-      <div className="relative z-10 mb-2 flex items-center justify-between sm:mb-3">
+      <div className="relative z-10 mb-2 flex items-center sm:mb-3">
-        {showSortControl && (
+        {/* Left: Sort control or Hardcover link */}
-          <SortControl
+        <div>
-            value={sortValue}
+          {showSortControl && (
-            onChange={onSortChange}
+            <SortControl
-            metadataSortOptions={metadataSortOptions}
+              value={sortValue}
-          />
+              onChange={onSortChange}
-        )}
+              metadataSortOptions={metadataSortOptions}
-        {!showSortControl && resultsSourceUrl && (
+            />
-          <a
+          )}
-            href={resultsSourceUrl}
+          {!showSortControl && resultsSourceUrl && (
-            target="_blank"
+            <a
-            rel="noopener noreferrer"
+              href={resultsSourceUrl}
-            className="animate-pop-up inline-flex items-center gap-1.5 px-3 py-2 text-sm font-medium text-gray-600 transition-colors hover:text-gray-900 dark:text-gray-400 dark:hover:text-gray-200"
+              target="_blank"
-          >
+              rel="noopener noreferrer"
-            View list on Hardcover
+              className="animate-pop-up inline-flex items-center gap-1.5 px-3 py-2 text-sm font-medium text-gray-600 transition-colors hover:text-gray-900 dark:text-gray-400 dark:hover:text-gray-200"
-            <svg className="h-3.5 w-3.5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+            >
-              <path
+              View list on Hardcover
-                strokeLinecap="round"
+              <svg className="h-3.5 w-3.5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-                strokeLinejoin="round"
+                <path
-                strokeWidth={2}
+                  strokeLinecap="round"
-                d="M10 6H6a2 2 0 00-2 2v10a2 2 0 002 2h10a2 2 0 002-2v-4M14 4h6m0 0v6m0-6L10 14"
+                  strokeLinejoin="round"
-              />
+                  strokeWidth={2}
-            </svg>
+                  d="M10 6H6a2 2 0 00-2 2v10a2 2 0 002 2h10a2 2 0 002-2v-4M14 4h6m0 0v6m0-6L10 14"
-          </a>
+                />
-        )}
+              </svg>
            </a>
          )}
        </div>
-        {/* View toggle buttons - Desktop: show all 3, Mobile: show Compact and List only */}
+        {/* Center: Results count */}
        <div className="flex flex-1 justify-center">
          {(() => {
            const count = directTotalResults ?? null;
            if (count === null || count === 0) return null;
            const isCapped = directTotalResults === '500+';
            const totalCount = isCapped ? 500 : Number(count);
            // AA-style: show page range + total
            if (totalCount === 1) {
              return (
                <span className="mx-2 mt-4 px-2 text-xs whitespace-nowrap text-gray-500 dark:text-gray-400">
                  Result 1 (1 Total)
                </span>
              );
            }
            const shownEnd = Math.min(totalCount, 50);
            const totalStr = isCapped ? '500+' : String(totalCount);
            return (
              <span className="mx-2 mt-4 px-2 text-xs whitespace-nowrap text-gray-500 dark:text-gray-400">
                Results 1-{shownEnd} ({totalStr} Total)
              </span>
            );
          })()}
        </div>
        {/* Right: View toggle buttons - Desktop: show all 3, Mobile: show Compact and List only */}
        <div className="ml-auto flex items-center gap-2">
          {isDesktop && (
            <button
@@ -1,11 +1,19 @@
 import type { Dispatch, SetStateAction } from 'react';
 import { useMountEffect } from '@/hooks/useMountEffect';
-import type { AppConfig, AdvancedFilterState, ContentType, SearchMode, SortOption } from '@/types';
+import type {
  AppConfig,
  AdvancedFilterState,
  ContentType,
  QueryTargetOption,
  SearchMode,
  SortOption,
 } from '@/types';
 import { buildSearchQuery } from '@/utils/buildSearchQuery';
 import { resolveDefaultLanguageCodes } from '@/utils/languageFilters';
 import { getEffectiveMetadataSort } from '@/utils/metadataSort';
 import type { ParsedUrlSearch } from '@/utils/parseUrlSearchParams';
 import { findQueryTarget } from '@/utils/queryTargets';
 const ADVANCED_FILTER_VISIBILITY_KEYS = ['content', 'lang', 'formats'] as const;
@@ -15,6 +23,7 @@ interface UrlSearchBootstrapMountProps {
  contentType: ContentType;
  combinedMode: boolean;
  combinedModeAllowed: boolean;
  queryTargets: QueryTargetOption[];
  advancedFilters: AdvancedFilterState;
  resolvedMetadataDefaultSort: string;
  resolvedMetadataSortOptions: SortOption[];
@@ -24,10 +33,13 @@ interface UrlSearchBootstrapMountProps {
  setAdvancedFilters: Dispatch<SetStateAction<AdvancedFilterState>>;
  setShowAdvanced: (value: boolean) => void;
  setActiveQueryTarget: (value: string) => void;
  setSearchFieldValue: (key: string, value: string | number | boolean, label?: string) => void;
  runSearchWithPolicyRefresh: (opts: {
    query: string;
    contentTypeOverride?: ContentType;
    searchModeOverride?: SearchMode;
    fieldValues?: Record<string, string | number | boolean>;
    sort?: string;
  }) => void;
  onComplete: () => void;
 }
@@ -38,6 +50,7 @@ export const UrlSearchBootstrapMount = ({
  contentType,
  combinedMode,
  combinedModeAllowed,
  queryTargets,
  advancedFilters,
  resolvedMetadataDefaultSort,
  resolvedMetadataSortOptions,
@@ -47,6 +60,7 @@ export const UrlSearchBootstrapMount = ({
  setAdvancedFilters,
  setShowAdvanced,
  setActiveQueryTarget,
  setSearchFieldValue,
  runSearchWithPolicyRefresh,
  onComplete,
 }: UrlSearchBootstrapMountProps) => {
@@ -69,6 +83,15 @@ export const UrlSearchBootstrapMount = ({
      setCombinedMode(false);
    }
    const urlSearchByTarget = findQueryTarget(queryTargets, parsedParams.searchBy);
    const urlSearchByOverride = urlSearchByTarget?.key;
    // Search By target can be deep-linked on its own (e.g. `#search_by=manual`, no query),
    // so apply it even when there's nothing else to search for.
    if (urlSearchByOverride) {
      setActiveQueryTarget(urlSearchByOverride);
    }
    if (!parsedParams.hasSearchParams) {
      return;
    }
@@ -79,12 +102,8 @@ export const UrlSearchBootstrapMount = ({
      bookLanguages,
    );
-    if (parsedParams.searchInput) {
+    let nextQueryTarget = urlSearchByOverride || 'general';
-      setSearchInput(parsedParams.searchInput);
+    if (parsedSearchMode === 'direct' && !urlSearchByOverride) {
    }
    let nextQueryTarget = 'general';
    if (parsedSearchMode === 'direct') {
      if (parsedParams.advancedFilters.isbn) {
        nextQueryTarget = 'isbn';
      } else if (parsedParams.advancedFilters.author) {
@@ -95,6 +114,39 @@ export const UrlSearchBootstrapMount = ({
    }
    setActiveQueryTarget(nextQueryTarget);
    // Route `q` through the active target, mirroring how the live search dispatch reads it:
    // direct fields and text fields are typed into searchInput, other provider fields are
    // dispatched as fieldValues. Legacy links carry the value under the field's own param
    // (`?author=herbert`) instead, so fall back to that.
    const targetKey = urlSearchByTarget?.field?.key ?? nextQueryTarget;
    const legacyDirectValue =
      targetKey === 'isbn' || targetKey === 'author' || targetKey === 'title'
        ? parsedParams.advancedFilters[targetKey]
        : undefined;
    const targetQueryValue = parsedParams.searchInput || legacyDirectValue || '';
    const usesProviderFieldValue =
      urlSearchByTarget?.source === 'provider-field' &&
      urlSearchByTarget.field !== undefined &&
      urlSearchByTarget.field.type !== 'TextSearchField';
    if (usesProviderFieldValue && urlSearchByTarget?.field && targetQueryValue) {
      setSearchFieldValue(urlSearchByTarget.field.key, targetQueryValue);
    } else if (targetQueryValue) {
      setSearchInput(targetQueryValue);
    }
    const urlFieldValues =
      urlSearchByTarget?.source === 'provider-field' && urlSearchByTarget.field && targetQueryValue
        ? { [urlSearchByTarget.field.key]: targetQueryValue }
        : undefined;
    // Manual mode opens the release browser off an explicit submit - it has no results
    // list to bootstrap, so a deep link fills the input and stops there.
    if (urlSearchByTarget?.source === 'manual') {
      return;
    }
    const resolvedUrlMetadataSort =
      parsedSearchMode === 'universal'
        ? getEffectiveMetadataSort({
@@ -134,16 +186,13 @@ export const UrlSearchBootstrapMount = ({
    };
    const query = buildSearchQuery({
-      searchInput:
+      searchInput: nextQueryTarget === 'general' ? targetQueryValue : '',
        parsedSearchMode === 'direct' && nextQueryTarget !== 'general'
          ? ''
          : parsedParams.searchInput,
      showAdvanced: true,
      advancedFilters: {
        ...mergedFilters,
-        isbn: nextQueryTarget === 'isbn' ? parsedParams.advancedFilters.isbn || '' : '',
+        isbn: nextQueryTarget === 'isbn' ? targetQueryValue : '',
-        author: nextQueryTarget === 'author' ? parsedParams.advancedFilters.author || '' : '',
+        author: nextQueryTarget === 'author' ? targetQueryValue : '',
-        title: nextQueryTarget === 'title' ? parsedParams.advancedFilters.title || '' : '',
+        title: nextQueryTarget === 'title' ? targetQueryValue : '',
      },
      bookLanguages,
      defaultLanguage: defaultLanguageCodes,
@@ -154,6 +203,8 @@ export const UrlSearchBootstrapMount = ({
      query,
      contentTypeOverride: urlContentTypeOverride,
      searchModeOverride: parsedSearchMode,
      fieldValues: urlFieldValues,
      sort: parsedParams?.advancedFilters?.sort,
    });
  });
@@ -1,4 +1,5 @@
 import type { Book, RequestRecord, StatusData } from '../../types';
 import { getDownloadsCount } from '../../types';
 import { STATUS_LABELS, isActiveDownloadStatus } from './activityStyles.js';
 import type { ActivityItem, ActivityVisualStatus } from './activityTypes';
@@ -87,10 +88,14 @@ export const downloadToActivityItem = (book: Book, statusKey: DownloadStatusKey)
    typeof book.request_id === 'number' && Number.isFinite(book.request_id) && book.request_id > 0
      ? Math.trunc(book.request_id)
      : undefined;
  const downloadsCount = getDownloadsCount(book);
  const downloadsText =
    downloadsCount != null ? `${downloadsCount.toLocaleString()} downloads` : undefined;
  const metaLine = joinMetaParts([
    toOptionalText(book.format)?.toUpperCase(),
    toOptionalText(book.size),
    toOptionalText(book.source_display_name) || toSourceLabel(book.source),
    downloadsText,
    toOptionalText(book.username),
  ]);
  const progress = getDownloadProgress(visualStatus, book.progress);
@@ -115,6 +120,7 @@ export const downloadToActivityItem = (book: Book, statusKey: DownloadStatusKey)
    downloadRetryAvailable,
    downloadPath: toOptionalText(book.download_path),
    sizeRaw: toOptionalText(book.size),
    downloads: downloadsCount ?? undefined,
    requestId,
  };
 };
@@ -32,6 +32,7 @@ export interface ActivityItem {
  progress?: number;
  progressAnimated?: boolean;
  sizeRaw?: string;
  downloads?: number;
  timestamp: number;
  username?: string;
@@ -2,6 +2,7 @@ import { useState } from 'react';
 import { useSearchMode } from '../../contexts/SearchModeContext';
 import type { Book, ButtonStateInfo } from '../../types';
 import { getDownloadsCount } from '../../types';
 import { bookSupportsTargets } from '../../utils/bookTargetLoader';
 import { BookActionButton } from '../BookActionButton';
 import { BookTargetDropdown } from '../BookTargetDropdown';
@@ -210,6 +211,16 @@ export const CardView = ({
                  <span>{book.size}</span>
                </>
              )}
              {searchMode !== 'universal' &&
                (() => {
                  const d = getDownloadsCount(book);
                  return d != null && d > 0 ? (
                    <>
                      {' '}
                      <span>•</span> <span>{d.toLocaleString()}</span>{' '}
                    </>
                  ) : null;
                })()}
            </div>
          )}
        </div>
@@ -2,6 +2,7 @@ import { useState } from 'react';
 import { useSearchMode } from '../../contexts/SearchModeContext';
 import type { Book, ButtonStateInfo } from '../../types';
 import { getDownloadsCount } from '../../types';
 import { bookSupportsTargets } from '../../utils/bookTargetLoader';
 import { BookActionButton } from '../BookActionButton';
 import { BookTargetDropdown } from '../BookTargetDropdown';
@@ -221,6 +222,15 @@ export const CompactView = ({
                  <span>{book.size}</span>
                </>
              )}
              {(() => {
                const d = getDownloadsCount(book);
                return d != null && d > 0 ? (
                  <>
                    {' '}
                    <span>•</span> <span>{d.toLocaleString()}</span>{' '}
                  </>
                ) : null;
              })()}
            </div>
          )}
@@ -2,6 +2,7 @@ import { useState } from 'react';
 import { useSearchMode } from '../../contexts/SearchModeContext';
 import type { Book, ButtonStateInfo, DisplayField } from '../../types';
 import { getDownloadsCount } from '../../types';
 import { bookSupportsTargets } from '../../utils/bookTargetLoader';
 import { getFormatColor, getLanguageColor } from '../../utils/colorMaps';
 import { BookActionButton } from '../BookActionButton';
@@ -167,7 +168,7 @@ export const ListView = ({
                className={`grid w-full items-center gap-2 sm:gap-x-0.5 sm:gap-y-1 ${
                  searchMode === 'universal'
                    ? 'grid-cols-[auto_minmax(0,1fr)_auto_auto] sm:grid-cols-[auto_minmax(0,2fr)_minmax(50px,0.25fr)_minmax(90px,0.5fr)_minmax(90px,0.5fr)_minmax(120px,0.7fr)_auto]'
-                    : 'grid-cols-[auto_minmax(0,1fr)_auto_auto] sm:grid-cols-[auto_minmax(0,2fr)_minmax(50px,0.25fr)_minmax(60px,0.3fr)_minmax(60px,0.3fr)_minmax(60px,0.3fr)_auto]'
+                    : 'grid-cols-[auto_minmax(0,1fr)_auto_auto] sm:grid-cols-[auto_minmax(0,2fr)_minmax(50px,0.25fr)_minmax(60px,0.3fr)_minmax(60px,0.3fr)_minmax(60px,0.3fr)_minmax(70px,0.35fr)_auto]'
                }`}
              >
                {/* Thumbnail */}
@@ -287,6 +288,16 @@ export const ListView = ({
                  </div>
                )}
                {/* Direct mode: Downloads - Desktop only */}
                {searchMode !== 'universal' && (
                  <div className="hidden justify-center text-xs text-gray-700 sm:flex dark:text-gray-200">
                    {(() => {
                      const d = getDownloadsCount(book);
                      return d != null && d > 0 ? d.toLocaleString() : '-';
                    })()}
                  </div>
                )}
                {/* Action Buttons */}
                <div className="flex flex-row justify-end gap-0.5 sm:gap-1 sm:pr-3">
                  {bookSupportsTargets(book) && targetProvider && targetBookId && (
@@ -4,6 +4,7 @@ import type { TextFieldConfig } from '../../../types/settings';
 import {
  buildNamingTemplatePreview,
  NAMING_TEMPLATE_TOKENS,
  resolveWordSeparator,
  type NamingTemplateContent,
  type NamingTemplateMode,
  type NamingTemplateToken,
@@ -66,7 +67,8 @@ export const NamingTemplateField = ({
    (token) => !token.audiobookOnly || content === 'audiobook',
  );
  const tokenGroups = groupTokens(availableTokens);
-  const preview = buildNamingTemplatePreview(value, mode, content);
+  const wordSeparator = resolveWordSeparator(values.NAMING_WORD_SEPARATOR);
  const preview = buildNamingTemplatePreview(value, mode, content, wordSeparator);
  const hasPathSeparatorInFilename = mode === 'filename' && /[\\/]/.test(value);
  const insertToken = (token: string) => {
@@ -1,6 +1,7 @@
 // Direct download mode sort options
 export const SORT_OPTIONS = [
-  { value: '', label: 'Most relevant' },
+  { value: 'downloads', label: 'Most downloads' },
  { value: 'relevance', label: 'Most relevant' },
  { value: 'newest', label: 'Newest (publication year)' },
  { value: 'oldest', label: 'Oldest (publication year)' },
  { value: 'largest', label: 'Largest (filesize)' },
@@ -288,6 +288,7 @@ export function useReleaseSearchSession(
              [tabName]: {
                ...existing,
                releases: [...existing.releases, ...mergedReleases],
                search_info: response.search_info,
              },
            };
          });
@@ -103,6 +103,7 @@ const parseHistoryBook = (value: unknown): Book | null => {
    ...(typeof value.retry_available === 'boolean'
      ? { retry_available: value.retry_available }
      : {}),
    ...(typeof value.downloads === 'number' ? { downloads: value.downloads } : {}),
  };
 };
@@ -39,9 +39,11 @@ interface UseSearchReturn {
    contentTypeOverride?: ContentType;
    searchMode?: SearchMode;
    providerOverride?: string;
    sort?: string;
  }) => Promise<void>;
  handleResetSearch: (config: AppConfig | null) => void;
  resetSortFilter: () => void;
  reSortByDownloads: () => void;
  // Universal mode search field values
  searchFieldValues: SearchFieldValues;
  updateSearchFieldValue: (key: string, value: string | number | boolean, label?: string) => void;
@@ -51,6 +53,8 @@ interface UseSearchReturn {
  isLoadingMore: boolean;
  loadMore: (config: AppConfig | null, searchMode?: SearchMode) => Promise<void>;
  totalFound: number;
  // Direct mode: total result count from release sources (e.g., "500+" for capped)
  directTotalResults: number | string | null;
  // Source URL and title for the current result set (e.g. Hardcover list page)
  resultsSourceUrl: string | undefined;
  resultsSourceTitle: string | undefined;
@@ -90,6 +94,8 @@ export function useSearch(options: UseSearchOptions): UseSearchReturn {
  const [hasMore, setHasMore] = useState(false);
  const [isLoadingMore, setIsLoadingMore] = useState(false);
  const [totalFound, setTotalFound] = useState(0);
  // Direct mode: total result count from release sources (e.g., Anna's Archive)
  const [directTotalResults, setDirectTotalResults] = useState<number | string | null>(null);
  const [resultsSourceUrl, setResultsSourceUrl] = useState<string | undefined>();
  const [resultsSourceTitle, setResultsSourceTitle] = useState<string | undefined>();
@@ -106,6 +112,24 @@ export function useSearch(options: UseSearchOptions): UseSearchReturn {
    setAdvancedFilters((prev) => ({ ...prev, ...updates }));
  }, []);
  // Sort books by downloads descending (no downloads go to the end)
  const sortBooksByDownloads = useCallback((bookList: Book[]): Book[] => {
    const sorted = bookList.toSorted((a, b) => {
      const aDownloads = a.downloads ?? 0;
      const bDownloads = b.downloads ?? 0;
      // Books with downloads come first, sorted by count descending
      if (aDownloads > 0 && bDownloads === 0) return -1;
      if (aDownloads === 0 && bDownloads > 0) return 1;
      return bDownloads - aDownloads;
    });
    return sorted;
  }, []);
  // Re-sort current books by downloads descending (client-side only, no search)
  const reSortByDownloads = useCallback(() => {
    setBooks((prev) => sortBooksByDownloads(prev));
  }, [sortBooksByDownloads]);
  const updateSearchFieldValue = useCallback(
    (key: string, value: string | number | boolean, label?: string) => {
      setSearchFieldValues((prev) => ({ ...prev, [key]: value }));
@@ -157,6 +181,7 @@ export function useSearch(options: UseSearchOptions): UseSearchReturn {
      contentTypeOverride,
      searchMode: searchModeOverride,
      providerOverride,
      sort,
    }: {
      query: string;
      config: AppConfig | null;
@@ -164,6 +189,7 @@ export function useSearch(options: UseSearchOptions): UseSearchReturn {
      contentTypeOverride?: ContentType;
      searchMode?: SearchMode;
      providerOverride?: string;
      sort?: string;
    }) => {
      const effectiveContentType = contentTypeOverride ?? contentType;
      const searchMode = (searchModeOverride ?? config?.search_mode) || 'universal';
@@ -177,7 +203,7 @@ export function useSearch(options: UseSearchOptions): UseSearchReturn {
        const hasFieldValues = Object.values(effectiveFieldValues).some(
          (v) => v !== '' && v !== false,
        );
-        const sort = params.get('sort') || 'relevance';
+        const sortOrder = params.get('sort') || 'relevance';
        if (!searchQuery && !hasFieldValues) {
          setBooks([]);
@@ -202,7 +228,7 @@ export function useSearch(options: UseSearchOptions): UseSearchReturn {
          const result = await searchMetadata(
            searchQuery,
            40,
-            sort,
+            sortOrder,
            effectiveFieldValues,
            1,
            effectiveContentType,
@@ -221,7 +247,7 @@ export function useSearch(options: UseSearchOptions): UseSearchReturn {
            // Store params for loadMore
            lastSearchParamsRef.current = {
              query: searchQuery,
-              sort,
+              sort: sortOrder,
              fieldValues: effectiveFieldValues,
              providerOverride,
              contentType: effectiveContentType,
@@ -252,12 +278,20 @@ export function useSearch(options: UseSearchOptions): UseSearchReturn {
      setLastSearchQuery(query);
      try {
-        const results = await searchBooks(query);
+        const { books: results, totalResults } = await searchBooks(query);
        if (results.length > 0) {
-          setBooks(results);
+          // When no explicit server-side sort is selected (empty or "downloads"),
          // sort locally by downloads descending so the most popular results
          // appear first.
          const effectiveSort = sort ?? advancedFilters.sort;
          const isDownloadsSort = !effectiveSort || effectiveSort === 'downloads';
          const sorted = isDownloadsSort ? sortBooksByDownloads(results) : results;
          setBooks(sorted);
          setDirectTotalResults(totalResults);
        } else {
          showToast('No results found', 'error');
          setDirectTotalResults(null);
        }
      } catch (error) {
        if (error instanceof AuthenticationError) {
@@ -270,7 +304,14 @@ export function useSearch(options: UseSearchOptions): UseSearchReturn {
        setIsSearching(false);
      }
    },
-    [showToast, searchFieldValues, handleSearchError, contentType],
+    [
      showToast,
      searchFieldValues,
      handleSearchError,
      contentType,
      advancedFilters,
      sortBooksByDownloads,
    ],
  );
  const handleResetSearch = useCallback(
@@ -300,6 +341,7 @@ export function useSearch(options: UseSearchOptions): UseSearchReturn {
      setCurrentPage(1);
      setHasMore(false);
      setTotalFound(0);
      setDirectTotalResults(null);
      setResultsSourceUrl(undefined);
      setResultsSourceTitle(undefined);
      lastSearchParamsRef.current = null;
@@ -367,6 +409,7 @@ export function useSearch(options: UseSearchOptions): UseSearchReturn {
    handleSearch,
    handleResetSearch,
    resetSortFilter,
    reSortByDownloads,
    // Universal mode search field values
    searchFieldValues,
    updateSearchFieldValue,
@@ -376,6 +419,7 @@ export function useSearch(options: UseSearchOptions): UseSearchReturn {
    isLoadingMore,
    loadMore,
    totalFound,
    directTotalResults,
    resultsSourceUrl,
    resultsSourceTitle,
  };
@@ -1,12 +1,18 @@
 import { useMemo } from 'react';
 import { useSearchParams } from 'react-router-dom';
 import type { ParsedUrlSearch } from '../utils/parseUrlSearchParams';
 import { parseUrlSearchParams } from '../utils/parseUrlSearchParams';
 import { useLatestCallback } from './useLatestCallback';
 import { useDependencyEffect, useMountEffect } from './useMountEffect';
 interface UseUrlSearchOptions {
  /** Only process URL params after auth check and config are loaded */
  enabled: boolean;
  /**
   * Bump to re-read the URL - used when the hash changes underneath us
   * (someone pastes a shared link into an already-open tab).
   */
  nonce?: number;
 }
 interface UseUrlSearchReturn {
@@ -16,11 +22,39 @@ interface UseUrlSearchReturn {
  wasProcessed: boolean;
 }
 /** Debounce for the write side: searchInput changes on every keystroke, and Safari
 *  throws SecurityError past ~100 replaceState calls per 30s. */
 const HASH_SYNC_DEBOUNCE_MS = 300;
 /**
- * Hook to parse URL search parameters on initial page load.
+ * Last hash this module wrote. Lets the hashchange listener tell "the user pasted a
 * new link" apart from "our own sync effect just ran".
 */
 let lastWrittenHash: string | null = null;
 const stripHash = (value: string): string => (value.startsWith('#') ? value.slice(1) : value);
 const readUrlSearchParams = (): { params: URLSearchParams; fromQueryString: boolean } => {
  const hash = stripHash(window.location.hash);
  if (hash) {
    return { params: new URLSearchParams(hash), fromQueryString: false };
  }
  const search = window.location.search.startsWith('?')
    ? window.location.search.slice(1)
    : window.location.search;
  return { params: new URLSearchParams(search), fromQueryString: Boolean(search) };
 };
 /**
 * Hook to parse the URL on initial page load.
 *
- * This is a read-only operation - URL params are parsed once when enabled,
+ * Search config lives in a hash fragment (e.g. `#q=dune&search_by=manual`)
- * and the URL is not updated when users perform searches.
+ * rather than query params, so it stays browser-side only and never looks
 * like a server-processed query string.
 *
 * Query-string links (`?q=dune`) shipped before the hash and are still honoured
 * when the hash is empty: they're read once and rewritten to `#…` so the two
 * can't drift as the live sync below updates the URL.
 *
 * @example
 * // In App.tsx:
@@ -33,19 +67,112 @@ interface UseUrlSearchReturn {
 *   // Trigger search with parsed params
 * }
 */
-export function useUrlSearch({ enabled }: UseUrlSearchOptions): UseUrlSearchReturn {
+export function useUrlSearch({ enabled, nonce = 0 }: UseUrlSearchOptions): UseUrlSearchReturn {
-  const [searchParams] = useSearchParams();
+  const read = useMemo(() => {
  const parsedParams = useMemo(() => {
    if (!enabled) {
      return null;
    }
-    const parsed = parseUrlSearchParams(searchParams);
+    const { params, fromQueryString } = readUrlSearchParams();
-    return parsed.hasSearchParams || parsed.contentType || parsed.combinedMode ? parsed : null;
+    const parsed = parseUrlSearchParams(params);
-  }, [enabled, searchParams]);
+    const hasAnything = Boolean(
      parsed.hasSearchParams || parsed.contentType || parsed.combinedMode || parsed.searchBy,
    );
    return { parsed: hasAnything ? parsed : null, fromQueryString, hasAnything };
    // Intentionally read once per enable/nonce - live updates come from useSyncUrlSearchHash.
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [enabled, nonce]);
  // Migrate a legacy query-string link to the hash form once, so the live sync has a single
  // source of truth and the URL the user re-shares is the one the app keeps updating.
  const shouldMigrate = Boolean(read?.fromQueryString && read.hasAnything);
  useDependencyEffect(() => {
    if (!shouldMigrate) {
      return;
    }
    const nextHash = new URLSearchParams(window.location.search).toString();
    lastWrittenHash = nextHash;
    try {
      window.history.replaceState(
        window.history.state,
        '',
        `${window.location.pathname}#${nextHash}`,
      );
    } catch {
      // replaceState is rate-limited in Safari - the parsed params still apply
    }
  }, [shouldMigrate]);
  return {
-    parsedParams,
+    parsedParams: read?.parsed ?? null,
    wasProcessed: enabled,
  };
 }
 interface UseSyncUrlSearchHashOptions {
  /** Only write once URL params (if any) have been applied to search state */
  enabled: boolean;
  /** Hash fragment (without leading `#`) that should reflect current search state */
  hash: string;
 }
 /**
 * Keeps the URL hash fragment in sync with the current search state.
 *
 * Uses history.replaceState (not pushState), so every keystroke or
 * Search By change updates the URL live without pushing a new browser
 * history entry per change. Debounced, because Safari throws SecurityError
 * past roughly 100 replaceState calls per 30 seconds.
 */
 export function useSyncUrlSearchHash({ enabled, hash }: UseSyncUrlSearchHashOptions): void {
  useDependencyEffect(() => {
    // Debounced, so a burst of keystrokes collapses into one history write.
    const timer = enabled
      ? window.setTimeout(() => {
          if (stripHash(window.location.hash) === hash) {
            lastWrittenHash = hash;
            return;
          }
          const url = `${window.location.pathname}${window.location.search}${hash ? `#${hash}` : ''}`;
          lastWrittenHash = hash;
          try {
            window.history.replaceState(window.history.state, '', url);
          } catch {
            // Rate-limited (Safari) or a sandboxed frame - the UI state is still correct,
            // only the shareable URL lags behind.
          }
        }, HASH_SYNC_DEBOUNCE_MS)
      : undefined;
    return () => {
      if (timer !== undefined) {
        window.clearTimeout(timer);
      }
    };
  }, [enabled, hash]);
 }
 /**
 * Calls `onExternalChange` when the hash changes to something this module didn't write -
 * i.e. someone pasted a shared link into an already-open tab, or used back/forward.
 */
 export function useExternalHashChange(onExternalChange: () => void): void {
  // The listener outlives the Effect that registers it and fires from a DOM event,
  // which is outside useEffectEvent's contract - see useLatestCallback.
  const notify = useLatestCallback(onExternalChange);
  useMountEffect(() => {
    const handleHashChange = () => {
      if (stripHash(window.location.hash) === lastWrittenHash) {
        return;
      }
      notify();
    };
    window.addEventListener('hashchange', handleHashChange);
    return () => window.removeEventListener('hashchange', handleHashChange);
  });
 }
@@ -279,14 +279,20 @@ async function fetchJSON<T>(
 }
 // API functions
-export const searchBooks = async (query: string): Promise<Book[]> => {
+export const searchBooks = async (
-  if (!query) return [];
+  query: string,
 ): Promise<{ books: Book[]; totalResults: number | string | null }> => {
  if (!query) return { books: [], totalResults: null };
  const response = await fetchJSON<ReleasesResponse>(
    `${API_BASE}/releases?source=direct_download&${query}`,
    {},
    searchTimeoutMs,
  );
-  return response.releases.map(transformReleaseToDirectBook);
+  // Extract total count from search_info if available
  const firstSource = response.sources_searched?.[0];
  const searchInfo = firstSource ? response.search_info?.[firstSource] : undefined;
  const totalResults = searchInfo?.total_results ?? null;
  return { books: response.releases.map(transformReleaseToDirectBook), totalResults };
 };
 // Metadata search response type (internal)
@@ -540,6 +546,7 @@ export type DownloadReleasePayload = {
  format?: string;
  size?: string;
  size_bytes?: number;
  downloads?: number;
  download_url?: string;
  protocol?: string;
  indexer?: string;
@@ -0,0 +1,30 @@
 import { describe, it, expect } from 'vitest';
 import { shortBuildId } from '../utils/buildVersion';
 const SHA = '1a5b37d0c2e4f6a8b0c2d4e6f8a0b2c4d6e8f0a2';
 describe('buildVersion.shortBuildId', () => {
  it('shows the commit of a date-stamped image, not the date', () => {
    expect(shortBuildId(`2026-09-20-${SHA}`)).toBe('1a5b37d');
  });
  it('shows the commit of a PR image', () => {
    expect(shortBuildId(`pr-${SHA}`)).toBe('1a5b37d');
  });
  it('shortens a bare commit sha', () => {
    expect(shortBuildId(SHA)).toBe('1a5b37d');
  });
  it('keeps any other stamp to its first seven characters', () => {
    expect(shortBuildId('local-build')).toBe('local-b');
    expect(shortBuildId('abc')).toBe('abc');
  });
  it('returns null for an unstamped build', () => {
    expect(shortBuildId(undefined)).toBe(null);
    expect(shortBuildId('')).toBe(null);
    expect(shortBuildId('N/A')).toBe(null);
  });
 });
@@ -4,6 +4,7 @@ import {
  buildNamingTemplatePreview,
  NAMING_TEMPLATE_TOKENS,
  renderNamingTemplate,
  resolveWordSeparator,
  SAMPLE_NAMING_METADATA,
 } from '../utils/namingTemplatePreview';
@@ -40,6 +41,23 @@ describe('namingTemplatePreview', () => {
    expect(preview.value).toBe('Arthur Conan Doyle/The Hound of the Baskervilles');
  });
  it('keeps only the first of several authors for FirstAuthor', () => {
    const preview = renderNamingTemplate(
      '{FirstAuthor}/{Year}',
      { ...SAMPLE_NAMING_METADATA, Author: 'Terry Pratchett, Neil Gaiman', FirstAuthor: '' },
      { allowPathSeparators: true },
    );
    expect(preview.value).toBe('Terry Pratchett/1902');
  });
  it('offers FirstAuthor as a core variable', () => {
    const token = NAMING_TEMPLATE_TOKENS.find((t) => t.token === 'FirstAuthor');
    expect(token?.group).toBe('Core');
    expect(token?.audiobookOnly).toBeFalsy();
  });
  it('reports unknown bare variables', () => {
    const preview = renderNamingTemplate('{Author}/{NotAThing}', SAMPLE_NAMING_METADATA, {
      allowPathSeparators: true,
@@ -80,6 +98,41 @@ describe('namingTemplatePreview', () => {
    expect(swedish.value).not.toBe(english.value);
  });
  it('replaces internal whitespace with the configured word separator', () => {
    const preview = renderNamingTemplate('{Author}/{PrimaryTitle}', SAMPLE_NAMING_METADATA, {
      allowPathSeparators: true,
      wordSeparator: '.',
    });
    expect(preview.value).toBe('Arthur.Conan.Doyle/The.Hound.of.the.Baskervilles');
  });
  it('leaves values unchanged for the default space separator', () => {
    const preview = renderNamingTemplate('{Author}', SAMPLE_NAMING_METADATA, {
      allowPathSeparators: true,
    });
    expect(preview.value).toBe('Arthur Conan Doyle');
  });
  it('never touches literal template characters, only placeholder values', () => {
    const preview = renderNamingTemplate('{Author}.-.{PrimaryTitle}', SAMPLE_NAMING_METADATA, {
      allowPathSeparators: true,
      wordSeparator: '.',
    });
    expect(preview.value).toBe('Arthur.Conan.Doyle.-.The.Hound.of.the.Baskervilles');
  });
  it('resolves the word separator setting like the backend policy module', () => {
    expect(resolveWordSeparator('.')).toBe('.');
    expect(resolveWordSeparator('_')).toBe('_');
    expect(resolveWordSeparator('-')).toBe('-');
    expect(resolveWordSeparator('~')).toBe('~');
    expect(resolveWordSeparator('')).toBe(' ');
    expect(resolveWordSeparator(undefined)).toBe(' ');
  });
  it('keeps the picker and the known-token list in lockstep', () => {
    // KNOWN_TOKENS is a hand-maintained duplicate of the Python list. A token
    // added to the picker but not to it would render as an unknown variable.
@@ -60,4 +60,32 @@ describe('parseUrlSearchParams', () => {
    expect(parsed.contentType).toBe(undefined);
    expect(parsed.combinedMode).toBe(true);
  });
  it('parses search_by as the Search By target', () => {
    const parsed = parseUrlSearchParams(new URLSearchParams('search_by=manual&q=dune'));
    expect(parsed.searchBy).toBe('manual');
    expect(parsed.searchInput).toBe('dune');
    expect(parsed.hasSearchParams).toBe(true);
  });
  it('trims search_by but keeps its casing for case-sensitive provider field keys', () => {
    const parsed = parseUrlSearchParams(new URLSearchParams('search_by=+MANUAL+'));
    expect(parsed.searchBy).toBe('MANUAL');
  });
  it('keeps search_by-only links from auto-triggering a blank search', () => {
    const parsed = parseUrlSearchParams(new URLSearchParams('search_by=manual'));
    expect(parsed.searchBy).toBe('manual');
    expect(parsed.searchInput).toBe('');
    expect(parsed.hasSearchParams).toBe(false);
  });
  it('leaves search_by undefined when absent', () => {
    const parsed = parseUrlSearchParams(new URLSearchParams('q=dune'));
    expect(parsed.searchBy).toBe(undefined);
  });
 });
@@ -1,6 +1,10 @@
 import { describe, it, expect } from 'vitest';
-import { buildQueryTargets, getDefaultQueryTargetKey } from '../utils/queryTargets';
+import {
  buildQueryTargets,
  findQueryTarget,
  getDefaultQueryTargetKey,
 } from '../utils/queryTargets';
 describe('queryTargets', () => {
  it('builds direct-mode query targets', () => {
@@ -44,3 +48,33 @@ describe('queryTargets', () => {
    expect(getDefaultQueryTargetKey([])).toBe('general');
  });
 });
 describe('findQueryTarget', () => {
  const targets = buildQueryTargets({ searchMode: 'direct' });
  it('returns undefined for a missing or empty key', () => {
    expect(findQueryTarget(targets, undefined)).toBeUndefined();
    expect(findQueryTarget(targets, '')).toBeUndefined();
    expect(findQueryTarget(targets, 'series')).toBeUndefined();
  });
  it('matches an exact key', () => {
    expect(findQueryTarget(targets, 'author')?.key).toBe('author');
  });
  it('falls back to a case-insensitive match for custom provider field keys', () => {
    const providerTargets = buildQueryTargets({
      searchMode: 'universal',
      metadataSearchFields: [
        {
          key: 'hardcoverList',
          label: 'List',
          type: 'TextSearchField',
        },
      ],
    });
    expect(findQueryTarget(providerTargets, 'hardcoverlist')?.key).toBe('hardcoverList');
    expect(findQueryTarget(providerTargets, 'hardcoverList')?.key).toBe('hardcoverList');
  });
 });
@@ -0,0 +1,60 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { getSearchByPreference, setSearchByPreference } from '../utils/searchByPreference';
 // No jsdom in this project's vitest setup, so stub the slice of localStorage this uses.
 const makeStorage = (impl?: Partial<Storage>) => {
  const store = new Map<string, string>();
  return {
    getItem: (key: string) => store.get(key) ?? null,
    setItem: (key: string, value: string) => {
      store.set(key, value);
    },
    ...impl,
  };
 };
 const stubWindow = (storage: unknown) => {
  vi.stubGlobal('window', { localStorage: storage });
 };
 describe('searchByPreference', () => {
  beforeEach(() => {
    stubWindow(makeStorage());
  });
  afterEach(() => {
    vi.unstubAllGlobals();
  });
  it('returns null when nothing is stored', () => {
    expect(getSearchByPreference()).toBe(null);
  });
  it('round-trips a value through set/get', () => {
    setSearchByPreference('manual');
    expect(getSearchByPreference()).toBe('manual');
  });
  it('overwrites a previously stored value', () => {
    setSearchByPreference('manual');
    setSearchByPreference('author');
    expect(getSearchByPreference()).toBe('author');
  });
  it('survives storage being unavailable', () => {
    stubWindow(
      makeStorage({
        getItem: () => {
          throw new Error('storage disabled');
        },
        setItem: () => {
          throw new Error('storage disabled');
        },
      }),
    );
    expect(() => setSearchByPreference('author')).not.toThrow();
    expect(getSearchByPreference()).toBe(null);
  });
 });
@@ -0,0 +1,216 @@
 import { describe, expect, it } from 'vitest';
 import { buildUrlSearchHash } from '../utils/urlSearchHash';
 describe('buildUrlSearchHash', () => {
  it('builds a hash reflecting query, search_by and a non-default content_type', () => {
    const hash = buildUrlSearchHash({
      queryValue: 'dune',
      searchBy: 'manual',
      contentType: 'audiobook',
      combinedMode: false,
      advancedFilters: {},
    });
    expect(new URLSearchParams(hash).get('q')).toBe('dune');
    expect(new URLSearchParams(hash).get('search_by')).toBe('manual');
    expect(new URLSearchParams(hash).get('content_type')).toBe('audiobook');
  });
  it('omits content_type when it is the ebook default', () => {
    const hash = buildUrlSearchHash({
      queryValue: 'dune',
      searchBy: 'general',
      contentType: 'ebook',
      combinedMode: false,
      advancedFilters: {},
    });
    expect(new URLSearchParams(hash).has('content_type')).toBe(false);
  });
  it('omits search_by when it is the general default', () => {
    const hash = buildUrlSearchHash({
      queryValue: 'dune',
      searchBy: 'general',
      contentType: 'ebook',
      combinedMode: false,
      advancedFilters: {},
    });
    expect(new URLSearchParams(hash).has('search_by')).toBe(false);
  });
  it('sets content_type=combined when combinedMode is true', () => {
    const hash = buildUrlSearchHash({
      queryValue: 'dune',
      searchBy: 'general',
      contentType: 'ebook',
      combinedMode: true,
      advancedFilters: {},
    });
    expect(new URLSearchParams(hash).get('content_type')).toBe('combined');
  });
  it('mirrors advanced filters (isbn/author/title/sort/content/lang/format)', () => {
    const hash = buildUrlSearchHash({
      queryValue: '',
      searchBy: 'author',
      contentType: 'ebook',
      combinedMode: false,
      advancedFilters: {
        author: 'frank herbert',
        lang: ['en', 'de'],
        formats: ['epub'],
        sort: 'newest',
      },
    });
    const params = new URLSearchParams(hash);
    expect(params.get('author')).toBe('frank herbert');
    expect(params.get('sort')).toBe('newest');
    expect(params.getAll('lang')).toEqual(['en', 'de']);
    expect(params.getAll('format')).toEqual(['epub']);
  });
  it('produces an empty string when there is nothing to reflect', () => {
    const hash = buildUrlSearchHash({
      queryValue: '',
      searchBy: 'general',
      contentType: 'ebook',
      combinedMode: false,
      advancedFilters: {},
    });
    expect(hash).toBe('');
  });
  it('serializes a non-text provider field value so the target round-trips', () => {
    const hash = buildUrlSearchHash({
      queryValue: 'id:1234',
      searchBy: 'series',
      contentType: 'ebook',
      combinedMode: false,
      advancedFilters: {},
    });
    expect(new URLSearchParams(hash).get('q')).toBe('id:1234');
    expect(new URLSearchParams(hash).get('search_by')).toBe('series');
  });
  it('serializes numeric and checkbox field values', () => {
    const numeric = buildUrlSearchHash({
      queryValue: 2024,
      searchBy: 'year',
      contentType: 'ebook',
      combinedMode: false,
      advancedFilters: {},
    });
    expect(new URLSearchParams(numeric).get('q')).toBe('2024');
    const checked = buildUrlSearchHash({
      queryValue: true,
      searchBy: 'signed',
      contentType: 'ebook',
      combinedMode: false,
      advancedFilters: {},
    });
    expect(new URLSearchParams(checked).get('q')).toBe('1');
    const unchecked = buildUrlSearchHash({
      queryValue: false,
      searchBy: 'signed',
      contentType: 'ebook',
      combinedMode: false,
      advancedFilters: {},
    });
    expect(new URLSearchParams(unchecked).has('q')).toBe(false);
  });
  it('omits filters still sitting at their defaults', () => {
    const hash = buildUrlSearchHash({
      queryValue: 'dune',
      searchBy: 'general',
      contentType: 'ebook',
      combinedMode: false,
      defaultSort: 'relevance',
      defaultFormats: ['epub', 'mobi', 'azw3'],
      advancedFilters: {
        sort: 'relevance',
        lang: ['default'],
        formats: ['epub', 'mobi', 'azw3'],
      },
    });
    expect(hash).toBe('q=dune');
  });
  it('treats a reordered default selection as the default', () => {
    const hash = buildUrlSearchHash({
      queryValue: 'dune',
      searchBy: 'general',
      contentType: 'ebook',
      combinedMode: false,
      defaultFormats: ['epub', 'mobi', 'azw3'],
      advancedFilters: { formats: ['azw3', 'epub', 'mobi'] },
    });
    expect(hash).toBe('q=dune');
  });
  it('keeps filters the user actually changed', () => {
    const params = new URLSearchParams(
      buildUrlSearchHash({
        queryValue: 'dune',
        searchBy: 'general',
        contentType: 'ebook',
        combinedMode: false,
        defaultSort: 'relevance',
        defaultFormats: ['epub', 'mobi', 'azw3'],
        advancedFilters: {
          sort: 'newest',
          lang: ['en', 'de'],
          formats: ['epub'],
        },
      }),
    );
    expect(params.get('sort')).toBe('newest');
    expect(params.getAll('lang')).toEqual(['en', 'de']);
    expect(params.getAll('format')).toEqual(['epub']);
  });
  it('keeps a narrowed selection that happens to be the same length', () => {
    const params = new URLSearchParams(
      buildUrlSearchHash({
        queryValue: 'dune',
        searchBy: 'general',
        contentType: 'ebook',
        combinedMode: false,
        defaultFormats: ['epub', 'mobi', 'azw3'],
        advancedFilters: { formats: ['epub', 'mobi', 'pdf'] },
      }),
    );
    expect(params.getAll('format')).toEqual(['epub', 'mobi', 'pdf']);
  });
  it('leaves a plain default-state search with no hash at all', () => {
    const hash = buildUrlSearchHash({
      queryValue: '',
      searchBy: 'general',
      contentType: 'ebook',
      combinedMode: false,
      defaultSort: 'relevance',
      defaultFormats: ['epub', 'mobi', 'azw3'],
      advancedFilters: {
        sort: 'relevance',
        lang: ['default'],
        formats: ['epub', 'mobi', 'azw3'],
      },
    });
    expect(hash).toBe('');
  });
 });
@@ -56,6 +56,23 @@ export interface Book {
  titles_by_language?: Record<string, string>;
  username?: string;
  retry_available?: boolean;
  downloads?: number;
  extra?: Record<string, unknown>;
 }
 /**
 * Extract download count from a book's data.
 * Checks both the direct `downloads` field and the `extra.downloads` fallback.
 */
 export function getDownloadsCount(book: Book): number | null {
  if (book.downloads != null && book.downloads > 0) {
    return book.downloads;
  }
  const extraDownloads = book.extra?.downloads;
  if (extraDownloads != null && typeof extraDownloads === 'number' && extraDownloads > 0) {
    return extraDownloads;
  }
  return null;
 }
 // Status response types
@@ -458,6 +475,7 @@ export interface Release {
 // Search info returned by release sources
 export interface SourceSearchInfo {
  search_type: 'isbn' | 'title_author' | 'categories' | 'expanded' | 'manual' | 'query';
  total_results?: number | string | null;
 }
 // Response from /api/releases endpoint
@@ -62,6 +62,7 @@ interface SourceBackedBookData {
  language?: unknown;
  format?: unknown;
  size?: unknown;
  downloads?: unknown;
  preview?: unknown;
  publisher?: unknown;
  info?: Record<string, string | string[]>;
@@ -157,6 +158,7 @@ const transformSourceBackedDataToBook = (data: SourceBackedBookData): Book => {
    language: toOptionalText(data.language),
    format: toOptionalText(data.format),
    size: toOptionalText(data.size),
    downloads: typeof data.downloads === 'number' ? data.downloads : undefined,
    preview: toOptionalText(data.preview),
    publisher: toOptionalText(data.publisher),
    info: data.info,
@@ -181,6 +183,7 @@ export function transformReleaseToDirectBook(release: Release): Book {
    language: release.language || extra.language,
    format: release.format,
    size: release.size,
    downloads: extra.downloads,
    preview: extra.preview,
    publisher: extra.publisher,
    info: parseBookInfo(extra.info),
@@ -47,8 +47,11 @@ export const buildSearchQuery = ({
  if (content) queryParts.push(`content=${encodeURIComponent(content)}`);
  formats.forEach((format) => queryParts.push(`format=${encodeURIComponent(format)}`));
-  if (advancedFilters.sort) {
+  // "downloads" is a client-side-only sort — send empty string so the server
-    queryParts.push(`sort=${encodeURIComponent(advancedFilters.sort)}`);
+  // doesn't receive an invalid sort parameter.
  const serverSort = advancedFilters.sort === 'downloads' ? '' : advancedFilters.sort;
  if (serverSort) {
    queryParts.push(`sort=${encodeURIComponent(serverSort)}`);
  }
  return queryParts.join('&');
@@ -0,0 +1,15 @@
 const COMMIT_SHA = /[0-9a-f]{40}$/i;
 /**
 * The short commit id a build was made from, or null when the build is unstamped.
 *
 * CI stamps BUILD_VERSION as `<yyyy-mm-dd>-<sha>` for published images and `pr-<sha>` for
 * PR images, so its first seven characters are the date ("2026-09"), not the commit.
 */
 export const shortBuildId = (buildVersion?: string): string | null => {
  if (!buildVersion || buildVersion === 'N/A') {
    return null;
  }
  const sha = COMMIT_SHA.exec(buildVersion)?.[0];
  return (sha ?? buildVersion).slice(0, 7);
 };
@@ -12,6 +12,8 @@ export interface NamingTemplateToken {
 interface RenderOptions {
  allowPathSeparators: boolean;
  /** Mirrors `word_separator` in shelfmark/core/naming.py. Defaults to ' ' (no change). */
  wordSeparator?: string;
 }
 interface RenderResult {
@@ -27,6 +29,13 @@ export const NAMING_TEMPLATE_TOKENS: NamingTemplateToken[] = [
    value: 'Arthur Conan Doyle',
    group: 'Core',
  },
  {
    token: 'FirstAuthor',
    label: 'First author',
    description: 'First author only, when metadata lists several',
    value: 'Arthur Conan Doyle',
    group: 'Core',
  },
  {
    token: 'Title',
    label: 'Full title',
@@ -104,6 +113,7 @@ const KNOWN_TOKENS = [
  'seriesposition',
  'primarytitle',
  'originalname',
  'firstauthor',
  'partnumber',
  'language',
  'subtitle',
@@ -114,8 +124,13 @@ const KNOWN_TOKENS = [
  'user',
 ];
 // Mirrors AUTHOR_LIST_SEPARATOR in shelfmark/core/naming.py: authors arrive
 // pre-joined with ',' or ';' and {FirstAuthor} keeps only the first entry.
 const firstAuthor = (value: string): string => value.split(/\s*[,;]\s*/)[0]?.trim() ?? '';
 const BRACE_PATTERN = /\{([^}]+)\}/g;
 const INVALID_CHARS_PATTERN = /[\\/:*?"<>|]/g;
 const WHITESPACE_RUN_PATTERN = /\s+/g;
 export const SAMPLE_NAMING_METADATA = NAMING_TEMPLATE_TOKENS.reduce<Record<string, string>>(
  (metadata, token) => {
@@ -163,6 +178,9 @@ export const renderNamingTemplate = (
  const unknownTokens: string[] = [];
  const placeholderValue = (placeholderName: string): string => {
    if (placeholderName === 'firstauthor' && !normalized['firstauthor']) {
      return firstAuthor(normalized['author'] ?? '');
    }
    return (normalized[placeholderName] ?? '').trim();
  };
@@ -178,11 +196,16 @@ export const renderNamingTemplate = (
    const prefix = content.slice(0, index);
    const suffix = content.slice(index + name.length);
-    const rawValue = placeholderValue(name);
+    let rawValue = placeholderValue(name);
    if (!rawValue) {
      return '';
    }
    const wordSeparator = options.wordSeparator ?? ' ';
    if (wordSeparator !== ' ') {
      rawValue = rawValue.replace(WHITESPACE_RUN_PATTERN, wordSeparator);
    }
    const value = sanitizeFilename(
      options.allowPathSeparators ? rawValue : rawValue.replace(/\//g, '_'),
    );
@@ -238,13 +261,20 @@ export const renderNamingTemplate = (
  return { value: result, unknownTokens };
 };
 // Mirrors get_word_separator() in shelfmark/download/postprocess/policy.py.
 export const resolveWordSeparator = (value: unknown): string => {
  return (typeof value === 'string' ? value : '') || ' ';
 };
 export const buildNamingTemplatePreview = (
  template: string,
  mode: NamingTemplateMode,
  content: NamingTemplateContent,
  wordSeparator = ' ',
 ): RenderResult => {
  const rendered = renderNamingTemplate(template, SAMPLE_NAMING_METADATA, {
    allowPathSeparators: mode === 'path',
    wordSeparator,
  });
  const fallback = SAMPLE_NAMING_METADATA.PrimaryTitle;
  const extension = content === 'audiobook' ? 'mp3' : 'epub';
--- a/Show More
+++ b/Show More