fix(bypass): stop handing solvers DDoS-Guard's ?check=1 probe URL (#1300 )

html_get_page follows Anna's Archive redirects by hand, and DDoS-Guard's gate answers /search with a 302 to the same path plus `check=1`. The follower walks that handshake by reassigning `current_url`, so every downstream handoff - the 403 branch, the 503-challenge branch, both redirect-loop rescues - passed the *probe* URL to the bypasser rather than the page we actually wanted. A solver opens that in a fresh browser holding none of the cookies the probe exists to collect, so DDoS-Guard cannot verify it automatically and serves the manual CAPTCHA page that nothing can solve. The #1292 log is exactly that: a 403 handed off on `&check=1`, FlareSolverr answering "Challenge solved!", and a 4721-byte DDOS-GUARD captcha page coming back. - `_solvable_url()` strips the probe parameter, applied at the single choke point in `_run_bypasser` so all four handoffs are covered. Scoped to the hosts whose redirects we follow manually; a URL without the parameter is returned by identity, so nothing else is re-encoded. The same reports showed three further defects, all of which stand whatever the host was reacting to: - The external bypasser logged that the solve had not cleared the protection and then returned the challenge page as a success. That skipped the one recovery left - get_bypassed_page's retry-and-rotate loop, where the next mirror is a different DDoS-Guard host - and filed the captcha page's own __ddg cookies as that host's clearance, to be replayed on every later request. It now raises ChallengeNotSolvedError before storing anything. - "Check that the bypasser is reachable and working" was the one piece of advice guaranteed to waste the reporter's time: it was reachable, it ran a full solve, and it returned a captcha. ChallengeNotSolvedError carries the marker so the search layer can name the host as the cause instead of the bypasser. - The untabled-page fingerprint logged `attempt_url`, which html_get_page has since rotated past. The #1298 bundle reported the page against annas-archive.gl when the body had come from .pk - the triage cost #1289 added the line to remove. The search now asks for the response URL and logs that. Its give-up shape is the tuple ("", url), which is truthy, so the exhaustion check reads the body rather than the response. Regression fixtures are built from the pages in the reports. The two behavioural handoff tests were checked against the unfixed code: both fail there, reproducing the reporter's log line verbatim. Refs #1292 Refs #1298
seleniumbase==4.53.5 (#1299 )
2026-09-24 22:05:20 +01:00 · 2026-09-02 16:12:52 -04:00 · 2026-09-02 15:48:48 -04:00 · 2026-09-01 12:59:33 -04:00 · 2026-09-01 12:38:57 -04:00 · 2026-09-01 11:19:01 -04:00
172 changed files with 14619 additions and 2112 deletions
@@ -96,7 +96,7 @@ jobs:
            type=ref,event=tag

      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4.2.0
+        uses: docker/setup-buildx-action@37fe631027851001ddb9b187196cc803df7f5f0e # v4.3.0

      - name: Build and push ${{ matrix.target }} Docker image
        id: push
@@ -141,7 +141,7 @@ jobs:
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4.2.0
+        uses: docker/setup-buildx-action@37fe631027851001ddb9b187196cc803df7f5f0e # v4.3.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@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
        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@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
        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@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
        with:
          version: "0.11.3"
          python-version: "3.14"
@@ -81,7 +81,7 @@ jobs:
        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0

      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4.2.0
+        uses: docker/setup-buildx-action@37fe631027851001ddb9b187196cc803df7f5f0e # v4.3.0

      - name: Build shelfmark-lite image
        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
@@ -25,14 +25,14 @@ jobs:
        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0

      - name: Initialize CodeQL
-        uses: github/codeql-action/init@5595ccaf912efad79be6eef63a5619ff05969be3 # v3
+        uses: github/codeql-action/init@db488ddef3bf6cb639b32c2e9a7c0a7ea8271d28 # v3
        with:
          languages: ${{ matrix.language }}

      - name: Autobuild
-        uses: github/codeql-action/autobuild@5595ccaf912efad79be6eef63a5619ff05969be3 # v3
+        uses: github/codeql-action/autobuild@db488ddef3bf6cb639b32c2e9a7c0a7ea8271d28 # v3

      - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@5595ccaf912efad79be6eef63a5619ff05969be3 # v3
+        uses: github/codeql-action/analyze@db488ddef3bf6cb639b32c2e9a7c0a7ea8271d28 # v3
        with:
          category: "/language:${{ matrix.language }}"
@@ -72,7 +72,7 @@ jobs:
      - name: Checkout
        uses: actions/checkout@v7
      - name: Install uv and Python
-        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
        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@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
        with:
          python-version: "3.14"
          enable-cache: true
@@ -236,6 +236,7 @@ pyrightconfig.json
 *.local.*
 AGENTS.md
 .claude/
+CLAUDE.md
 .nvmrc
 .playwright-mcp/
 frontend-dist/
@@ -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.11.3@sha256:90bbb3c16635e9627f49eec6539f956d70746c409209041800a0280b93152823 AS uv
+FROM ghcr.io/astral-sh/uv:0.12.5@sha256:e85be844203885286c60ffad8a858d48afb6c5a5c237ca0e67f12e74b8f174b1 AS uv

 # Use python-slim as the base image
-FROM python:3.14.7-slim@sha256:ce40764625a4ff50df3548277632e7f96c4e77fe75fa848aae9885476e7df5a4 AS base
+FROM python:3.14.7-slim@sha256:cae66f2ef0ec51a9891263eeee7f987dacf0a9879e8aa9353d5606e0530619a5 AS base

 # Add build argument for version
 ARG BUILD_VERSION
@@ -152,9 +152,14 @@ RUN mkdir -p \
 EXPOSE ${FLASK_PORT}

 # Add healthcheck for container status
-# Uses /api/health which doesn't require authentication
-HEALTHCHECK --interval=60s --timeout=60s --start-period=60s --retries=3 \
-    CMD curl -s http://localhost:${FLASK_PORT}/api/health > /dev/null || exit 1
+# Uses /api/health which doesn't require authentication.
+# curl needs -f so an HTTP error status fails the probe instead of passing it:
+# plain `curl -s` exits 0 on a 500, which reported a broken app as healthy.
+# timeout stays well under interval so a hung probe cannot occupy a whole cycle.
+# --start-interval matches the daemon default (5s), made explicit so startup
+# probing does not depend on that default staying put.
+HEALTHCHECK --interval=30s --timeout=10s --start-period=90s --start-interval=5s --retries=3 \
+    CMD curl -fsS http://localhost:${FLASK_PORT}/api/health > /dev/null || exit 1

 # Use dumb-init as the entrypoint to handle signals properly
 ENTRYPOINT ["/usr/bin/dumb-init", "--"]
@@ -276,6 +276,27 @@ class DownloadHandler(ABC):
        pass
 ```

+### Optional: Listing Files Before Download
+
+Some releases bundle several books (a whole-series torrent). Shelfmark inspects a
+release before queueing it so the user can review how it will be split into books.
+Override `list_files` when your source can enumerate a release's files without
+downloading it; the default returns `None`, which the UI reports as "can't inspect":
+
+```python
+from shelfmark.download.postprocess.packs import PackFile
+
+def list_files(self, release_data: dict[str, Any]) -> list[PackFile] | None:
+    """Return the release's files (release-relative paths + sizes), or None."""
+    torrent_bytes = ...  # e.g. fetch the .torrent, or scrape the indexer's detail page
+    return extract_file_list_from_torrent(torrent_bytes)  # from download.clients.torrent_utils
+```
+
+`release_data` is the same payload the frontend sends to `/api/releases/download`
+(`source_id`, `download_url`, `content_type`, `series_name`, ...). Built-in examples:
+Prowlarr parses the `.torrent` it already fetches (magnet-only releases return
+`None`), and AudiobookBay reads the file table off its detail page.
+
 ### Download Method Parameters

 | Parameter | Type | Description |
@@ -247,7 +247,7 @@ Seconds since the last WireGuard handshake before the healthcheck bounces the tu
 | `CALIBRE_WEB_URL` | Adds a navigation button to your book library (Calibre-Web Automated, Grimmory, etc). | string | _none_ |
 | `AUDIOBOOK_LIBRARY_URL` | Adds a separate navigation button for your audiobook library (Audiobookshelf, Plex, etc). When both URLs are set, icons are shown instead of text. | string | _none_ |
 | `SUPPORTED_FORMATS` | Book formats to include in search results. ZIP/RAR archives are extracted automatically and book files are used if found. | string (comma-separated) | `epub,mobi,azw3,fb2,djvu,cbz,cbr` |
-| `SUPPORTED_AUDIOBOOK_FORMATS` | Audiobook formats to include in search results. ZIP/RAR archives are extracted automatically and audiobook files are used if found. | string (comma-separated) | `m4b,mp3,m4a,flac,ogg,wma,aac,wav,opus,zip,rar` |
+| `SUPPORTED_AUDIOBOOK_FORMATS` | Audiobook formats to include in search results. ZIP/RAR archives are extracted automatically and audiobook files are used if found. | string (comma-separated) | `m4b,mp3,m4a,mp4,flac,ogg,wma,aac,wav,opus,zip,rar` |
 | `BOOK_LANGUAGE` | Default language filter for searches. | string (comma-separated) | `en` |

 <details>
@@ -296,16 +296,7 @@ Book formats to include in search results. ZIP/RAR archives are extracted automa
 Audiobook formats to include in search results. ZIP/RAR archives are extracted automatically and audiobook files are used if found.

 - **Type:** string (comma-separated)
- **Default:** `m4b,mp3,m4a,flac,ogg,wma,aac,wav,opus,zip,rar`
-
-#### `BOOK_LANGUAGE`
-
-**Default Book Languages**
-
-Default language filter for searches.
-
- **Type:** string (comma-separated)
- **Default:** `en`
+- **Default:** `m4b,mp3,m4a,mp4,flac,ogg,wma,aac,wav,opus,zip,rar`

 </details>

@@ -314,6 +305,7 @@ Default language filter for searches.
 | Variable | Description | Type | Default |
 |----------|-------------|------|---------|
 | `SEARCH_MODE` | How you want to search for and download books. | string (choice) | `universal` |
+| `BOOK_LANGUAGE` | Default language filter for searches. Users can override this for their own account. | string (comma-separated) | `en` |
 | `AA_DEFAULT_SORT` | Default sort order for search results. | string (choice) | `relevance` |
 | `SHOW_RELEASE_SOURCE_LINKS` | Show clickable release-source links in release and details modals. Metadata provider links stay enabled. | boolean | `true` |
 | `SHOW_COMBINED_SELECTOR` | Show the option to search for and download both a book and audiobook together. | boolean | `true` |
@@ -337,6 +329,15 @@ How you want to search for and download books.
 - **Default:** `universal`
 - **Options:** `direct` (Direct), `universal` (Universal)

+#### `BOOK_LANGUAGE`
+
+**Default Book Languages**
+
+Default language filter for searches. Users can override this for their own account.
+
+- **Type:** string (comma-separated)
+- **Default:** `en`
+
 #### `AA_DEFAULT_SORT`

 **Default Sort Order**
@@ -704,7 +705,7 @@ Choose how downloaded audiobook files are named and organized.

 - **Type:** string (choice)
 - **Default:** `rename`
- **Options:** `none` (None), `rename` (Rename Only), `organize` (Rename and Organize)
+- **Options:** `none` (None), `rename` (Rename Only), `organize` (Rename and Organize), `rename_and_group` (Rename and Group)

 #### `TEMPLATE_AUDIOBOOK_RENAME`

@@ -749,6 +750,7 @@ Automatically open the downloads sidebar when a new download is queued.
 Automatically download completed files to your browser for the selected content types.

 - **Type:** string (comma-separated)
+  
 - **Default:** _empty list_

 #### `MAX_CONCURRENT_DOWNLOADS`
@@ -1223,6 +1225,7 @@ How long to cache individual book details. Default: 600 (10 minutes). Max: 60480
 | `PROWLARR_URL` | Base URL of your Prowlarr instance | string | _none_ |
 | `PROWLARR_API_KEY` | Found in Prowlarr: Settings > General > API Key | string (secret) | _none_ |
 | `PROWLARR_INDEXERS` | Select which indexers to search. 📚 = has book categories. Leave empty to search all. | string (comma-separated) | _empty list_ |
+| `PROWLARR_INDEXER_TIMEOUT` | How long to wait for a single indexer to answer a search. Indexers behind FlareSolverr can need 90 seconds or more while a cold Cloudflare challenge is solved; raise this if searches come back empty and the Prowlarr log shows the search still running. | number | `90` |
 | `PROWLARR_AUTO_EXPAND` | Automatically retry search without category filtering if no results are found | boolean | `false` |
 | `PROWLARR_COLLAPSE_DUPLICATES` | Collapse a release that several indexer entries returned down to a single row, keeping the entry with the best Prowlarr priority. Turn this off to see every entry that carried it, which is what makes results from filter-specific entries (freeleech and the like) visible. | boolean | `true` |
 | `PROWLARR_USE_SEED_PREFERENCES` | Apply per-indexer seed time and ratio preferences from Prowlarr when sending torrents to the download client | boolean | `false` |
@@ -1268,6 +1271,16 @@ Select which indexers to search. 📚 = has book categories. Leave empty to sear
 - **Type:** string (comma-separated)
 - **Default:** _empty list_

+#### `PROWLARR_INDEXER_TIMEOUT`
+
+**Indexer Search Timeout (seconds)**
+
+How long to wait for a single indexer to answer a search. Indexers behind FlareSolverr can need 90 seconds or more while a cold Cloudflare challenge is solved; raise this if searches come back empty and the Prowlarr log shows the search still running.
+
+- **Type:** number
+- **Default:** `90`
+- **Constraints:** min: 5, max: 300
+
 #### `PROWLARR_AUTO_EXPAND`

 **Auto-expand search on no results**
@@ -1302,8 +1315,9 @@ Apply per-indexer seed time and ratio preferences from Prowlarr when sending tor
 | Variable | Description | Type | Default |
 |----------|-------------|------|---------|
 | `NEWZNAB_ENABLED` | Enable searching for books via a Newznab-compatible indexer | boolean | `false` |
-| `NEWZNAB_URL` | Base URL of your Newznab indexer or aggregator | string | _none_ |
-| `NEWZNAB_API_KEY` | Your Newznab API key (leave blank if not required) | string (secret) | _none_ |
+| `NEWZNAB_INDEXERS` | Named Newznab connections. Each row accepts `name`, `url`, and `api_key`. | JSON array | `[]` |
+| `NEWZNAB_URL` | Legacy single-indexer URL, used when `NEWZNAB_INDEXERS` is empty | string | _none_ |
+| `NEWZNAB_API_KEY` | Legacy single-indexer API key | string (secret) | _none_ |
 | `NEWZNAB_EBOOK_CATEGORIES` | Newznab category IDs searched for ebooks. Most indexers use the standard 7000, but some use custom IDs. Leave empty to use 7000. | string (comma-separated) | `7000` |
 | `NEWZNAB_AUDIOBOOK_CATEGORIES` | Newznab category IDs searched for audiobooks. Most indexers use the standard 3030, but some use custom IDs. Leave empty to use 3030. | string (comma-separated) | `3030` |
 | `NEWZNAB_AUTO_EXPAND` | Automatically retry search without category filtering if no results are found | boolean | `false` |
@@ -1320,21 +1334,36 @@ Enable searching for books via a Newznab-compatible indexer
 - **Type:** boolean
 - **Default:** `false`

+#### `NEWZNAB_INDEXERS`
+
+**Named Indexers**
+
+Configure multiple named Newznab-compatible indexers. The name is shown beside each search result. For environment-based configuration, provide a JSON array:
+
+```json
+[
+  {"name":"NZBGeek","url":"https://api.nzbgeek.info","api_key":"..."},
+  {"name":"DrunkenSlug","url":"https://drunkenslug.com","api_key":"..."}
+]
+```
+
+- **Type:** JSON array
+- **Default:** `[]`
+
 #### `NEWZNAB_URL`

-**Newznab URL**
+**Legacy Newznab URL**

-Base URL of your Newznab indexer or aggregator
+Single-indexer fallback used only when `NEWZNAB_INDEXERS` is empty.

 - **Type:** string
 - **Default:** _none_
- **Required:** Yes

 #### `NEWZNAB_API_KEY`

-**API Key**
+**Legacy API Key**

-Your Newznab API key (leave blank if not required)
+API key for the legacy Newznab URL.

 - **Type:** string (secret)
 - **Default:** _none_
@@ -1977,7 +2006,7 @@ Move deletes the job from your usenet client after import; Copy keeps it in the
 | Variable | Description | Type | Default |
 |----------|-------------|------|---------|
 | `HARDCOVER_ENABLED` | Enable Hardcover as a metadata provider for book searches | boolean | `false` |
-| `HARDCOVER_API_KEY` | Get your API key from hardcover.app/account/api | string (secret) | _none_ |
+| `HARDCOVER_API_KEY` | Get your API key from hardcover.app/account/api (starts with hc_pat_) | string (secret) | _none_ |
 | `HARDCOVER_DEFAULT_SORT` | Default sort order for Hardcover search results. | string (choice) | `relevance` |
 | `HARDCOVER_EXCLUDE_COMPILATIONS` | Filter out compilations, anthologies, and omnibus editions from search results | boolean | `false` |
 | `HARDCOVER_EXCLUDE_UNRELEASED` | Filter out books with a release year in the future | boolean | `false` |
@@ -1999,7 +2028,7 @@ Enable Hardcover as a metadata provider for book searches

 **API Key**

-Get your API key from hardcover.app/account/api
+Get your API key from hardcover.app/account/api (starts with hc_pat_)

 - **Type:** string (secret)
 - **Default:** _none_
@@ -2150,6 +2179,7 @@ Enable Moly.hu as a metadata provider for book searches
 | `SOURCE_PRIORITY` | Fallback sources, may have waiting. Requires bypasser. Drag to reorder. | JSON array | _see UI for defaults_ |
 | `MAX_RETRY` | Maximum retry attempts for failed downloads. | number | `10` |
 | `DEFAULT_SLEEP` | Wait time between download retry attempts. | number | `5` |
+| `RELEASE_SEARCH_TIMEOUT` | How long one release search may run before it gives up and reports why. A first search on a cold start pays for a browser solve, so leave room for one. If you use a reverse proxy, its read timeout should be at least this high or it will cut the search off with a 504 first. | number | `300` |
 | `AA_CONTENT_TYPE_ROUTING` | Override destination based on content type metadata. | boolean | `false` |
 | `AA_CONTENT_TYPE_DIR_FICTION` | Fiction Books | string | _none_ |
 | `AA_CONTENT_TYPE_DIR_NON_FICTION` | Non-Fiction Books | string | _none_ |
@@ -2228,6 +2258,16 @@ Wait time between download retry attempts.
 - **Default:** `5`
 - **Constraints:** min: 1, max: 60

+#### `RELEASE_SEARCH_TIMEOUT`
+
+**Release Search Timeout (seconds)**
+
+How long one release search may run before it gives up and reports why. A first search on a cold start pays for a browser solve, so leave room for one. If you use a reverse proxy, its read timeout should be at least this high or it will cut the search off with a 504 first.
+
+- **Type:** number
+- **Default:** `300`
+- **Constraints:** min: 30, max: 1800
+
 #### `AA_CONTENT_TYPE_ROUTING`

 **Enable Content-Type Routing**
@@ -2304,6 +2344,8 @@ Override destination based on content type metadata.
 | `EXT_BYPASSER_URL` | URL of the external bypasser service (e.g., FlareSolverr). | string | `http://flaresolverr:8191` |
 | `EXT_BYPASSER_PATH` | API path for the external bypasser. | string | `/v1` |
 | `EXT_BYPASSER_TIMEOUT` | Timeout for external bypasser requests in milliseconds. | number | `60000` |
+| `BYPASS_PAGE_SOURCE_TIMEOUT` | How long to wait for a solved page to produce its content before the bypass is retried. Raise it if solves succeed but searches still fail. | number | `20` |
+| `BYPASS_BROWSER_IDLE_TIMEOUT` | How long the bypass helper process may sit unused before it is shut down. Higher keeps more searches fast, lower frees memory sooner. | number | `180` |

 <details>
 <summary>Detailed descriptions</summary>
@@ -2359,6 +2401,27 @@ Timeout for external bypasser requests in milliseconds.
 - **Requires restart:** Yes
 - **Constraints:** min: 10000, max: 300000

+#### `BYPASS_PAGE_SOURCE_TIMEOUT`
+
+**Page Read Timeout (seconds)**
+
+How long to wait for a solved page to produce its content before the bypass is retried. Raise it if solves succeed but searches still fail.
+
+- **Type:** number
+- **Default:** `20`
+- **Constraints:** min: 1, max: 120
+
+#### `BYPASS_BROWSER_IDLE_TIMEOUT`
+
+**Bypasser Idle Timeout (seconds)**
+
+How long the bypass helper process may sit unused before it is shut down. Higher keeps more searches fast, lower frees memory sooner.
+
+- **Type:** number
+- **Default:** `180`
+- **Requires restart:** Yes
+- **Constraints:** min: 30, max: 3600
+
 </details>

 ### Direct Download: Mirrors
@@ -30,7 +30,7 @@ Requires mounting your Calibre-Web `app.db` to `/auth/app.db`.

 Admins can configure per-user settings by editing a user in the user management panel. Non-admin users can also edit their own settings through **My Account** (accessible from the user menu). Admins control which sections are visible in My Account via the **Visible Self-Settings Sections** option.

-There are three categories of per-user settings:
+There are four categories of per-user settings:

 ### Delivery Preferences

@@ -42,6 +42,15 @@ Override where a user's downloads are sent. Options depend on the global output
 - **BookLore library/path** — Per-user BookLore target (when using BookLore output mode)
 - **Email recipient** — Per-user email address (when using Email output mode)

+### Search Preferences
+
+Override how a user searches, on top of the global search defaults:
+
+- **Search mode** — Direct or Universal for this user
+- **Default book languages** — The languages a user's searches fall back to when they don't pick one themselves. Useful for a shared instance where readers want different languages.
+- **Metadata providers** — Book, audiobook, and combined-mode provider for this user
+- **Default release sources** — The release tab opened first for books and audiobooks
+
 ### Notifications

 Users can configure personal notification routes, separate from the global notification settings. Each route targets a URL (e.g. an Apprise-compatible endpoint) and can be scoped to specific event types or all events.
@@ -19,31 +19,31 @@ dependencies = [
    "psutil",
    "emoji",
    "rarfile",
-    "qbittorrent-api>=2026.8.0",
+    "qbittorrent-api>=2026.8.1",
    "transmission-rpc",
    "authlib>=1.7.2,<1.8",
-    "apprise>=1.12.0",
+    "apprise>=1.13.0",
    # 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.27",
+    "httpx[http2]>=0.28.1",
 ]

 [project.optional-dependencies]
 browser = [
    "pyvirtualdisplay",
    "pyautogui",
-    "seleniumbase==4.51.12",
+    "seleniumbase==4.53.5",
    "python-xlib",
 ]

 [dependency-groups]
 dev = [
-    "basedpyright>=1.39.9",
+    "basedpyright>=1.39.10",
    "prek",
    "pytest",
    "pytest-cov",
    "pytest-xdist>=3.8.0",
-    "ruff==0.16.2",
+    "ruff==0.16.5",
    "vulture>=2.14",
 ]

@@ -3,7 +3,7 @@
 <img src="src/frontend/public/logo.png" alt="Shelfmark" width="200">

 > [!NOTE]
-> This project is in a stable state as of May 2026 but is not under active maintenance. 
+> Shelfmark is feature stable and maintained on a best-effort basis. Bug fixes, security updates, and small quality-of-life improvements are still shipped, and pull requests are reviewed — including new features. There is no roadmap for new features for now.

 Shelfmark is a self-hosted web interface for searching and requesting books and audiobooks across multiple sources. Bring your own sources, metadata providers, and download clients to build a single hub for your digital library. Supports multiple users with a built-in request system, so you can share your instance with others and let them browse and request books on their own.

@@ -95,6 +95,30 @@ volumes:
 - Aggregates releases from multiple configured sources
 - Full audiobook support

+### Hardcover API Key
+
+Hardcover powers metadata search in Universal mode. Create a token at
+[hardcover.app/account/api](https://hardcover.app/account/api) — current keys start with `hc_pat_`
+and are far shorter than the JWTs Hardcover issued before August 2026.
+
+Tick these seven scopes on the token screen:
+
+| Scope | Used for |
+|-------|----------|
+| `read:catalog` | Metadata search, plus book, edition, author and series lookups |
+| `read:library` | Your reading status and shelf counts |
+| `read:lists` | Your lists and the books on them |
+| `read:me:content` | Test Connection and the "Connected as" label |
+| `read:users` | Usernames shown alongside lists |
+| `write:library` | Setting a book's reading status from Shelfmark |
+| `write:lists` | Adding and removing books from lists, including auto-remove on download |
+
+The two `write:` scopes matter only if you set reading status from Shelfmark or leave
+**Auto-Remove from List on Download** enabled (it is on by default) — without them those actions
+fail silently. Everything else Hardcover offers (journal, goals, reviews, prompts, notifications,
+account) can stay unticked. The `all` scope works too, but it grants full account access including
+deletion, so prefer the list above.
+
 ### Environment Variables

 Environment variables work for initial setup and Docker deployments. They serve as defaults that can be overridden in the web interface.
@@ -123,6 +147,7 @@ See the full [Environment Variables Reference](docs/environment-variables.md) fo
 Some of the additional options available in Settings:
 - **Prowlarr** - Configure indexers and download clients to download books and audiobooks
 - **Additional audiobook sources** - Configure additional sources for audiobook discovery
+- **Direct Download mirrors** - Supply your own Anna's Archive mirror URLs; Auto mode tries them in the order listed. The `annas-archive.is` domain does not currently work as a source — use `annas-archive.gl` instead (checked August 2026; mirror availability changes)
 - **IRC** - Add details for IRC book sources and download directly from the UI. Most networks serve audiobooks from the same channel as ebooks (on `irc.irchighway.net` that's `#ebooks`, while `#bookz` is effectively inactive), so leave the separate audiobook channel blank unless your network actually indexes one. IRC audiobooks usually arrive as ZIP/RAR archives — keep those enabled under Supported Audiobook Formats or the releases are filtered out of results
 - **Library Link** - Add a link to your Calibre-Web or Grimmory instance in the UI header
 - **File processing** - Customiseable download paths, file renaming and directory creation with template-based renaming
@@ -238,9 +263,11 @@ These are non-goals, not missing features.

 ## Contributing

-Shelfmark's core feature set is complete. Development focuses on stability, bug fixes, quality-of-life improvements, and refining the search experience. Contributions in these areas are welcome, please file issues or submit pull requests on GitHub.
+Shelfmark's core feature set is complete.

-Feature requests that fall outside the project scope (library integration, automation, collection management) will be closed. If you're unsure whether something fits, open a discussion first.
+Pull requests are welcome and all of them get reviewed, new features included. If you want a feature, the fastest path is to send a PR for it rather than to file a request.
+
+Feature requests that fall outside the project scope (library integration, automation, collection management) will be closed, and PRs implementing them won't be merged. If you're unsure whether something fits, open a discussion first.

 ## Health Monitoring

@@ -3,3 +3,14 @@

 class BypassCancelledError(Exception):
    """Raised when a bypass operation is cancelled."""
+
+
+class ChallengeNotSolvedError(Exception):
+    """Raised when a bypasser ran but the site still answered with a challenge.
+
+    Distinct from a bypasser that is broken or unreachable, which is what every
+    "the bypass failed" message used to say. A solver can do its job perfectly and
+    still be handed something it cannot clear - DDoS-Guard's manual CAPTCHA page is
+    the case from #1292 - and telling the user to go check that FlareSolverr is
+    reachable sends them to fix a service that is working.
+    """
@@ -0,0 +1,52 @@
+"""Challenge-page detection shared by the bypassers and the HTTP retry path.
+
+Kept out of `internal_bypasser` so the HTTP layer can recognise an interstitial
+without importing SeleniumBase: that module is imported lazily precisely because its
+browser dependencies are optional, and external-bypasser setups run without them.
+"""
+
+# Matched against lowercased text, so every entry must be lowercase.
+CLOUDFLARE_INDICATORS = [
+    "just a moment",
+    "verify you are human",
+    "verifying you are human",
+    "cloudflare.com/products/turnstile",
+]
+
+DDOS_GUARD_INDICATORS = [
+    "ddos-guard",
+    "ddos guard",
+    "checking your browser before accessing",
+    "complete the manual check to continue",
+    "could not verify your browser automatically",
+]
+
+# Markers that exist only in raw markup: the bypassers scan rendered innerText, where
+# a script src or a <title> never appears. The title match is scoped to the tag on
+# purpose - hosts word the rest of that sentence differently, and matching "checking
+# your browser" as free text would trip on any page that merely discusses a challenge.
+_RAW_HTML_MARKERS = (
+    "<title>checking your browser",
+    "/cdn-cgi/challenge-platform",
+    "/.well-known/ddos-guard/",
+)
+
+# An interstitial is a few KB of markup. Past that it is a real page that happens to
+# mention a marker - a protected site links its own DDoS-Guard endpoints on every page.
+MAX_CHALLENGE_HTML_CHARS = 64 * 1024
+
+
+def challenge_marker(html: str) -> str | None:
+    """Return the marker proving `html` is an unsolved challenge page, or None.
+
+    Only meaningful for a response that already carries a challenge status: the
+    markers appear on protected sites' real pages too, so the status is what
+    separates "blocked" from "served".
+    """
+    if not html or len(html) > MAX_CHALLENGE_HTML_CHARS:
+        return None
+    lowered = html.lower()
+    for marker in (*_RAW_HTML_MARKERS, *DDOS_GUARD_INDICATORS, *CLOUDFLARE_INDICATORS):
+        if marker in lowered:
+            return marker
+    return None
@@ -0,0 +1,281 @@
+"""Clearance cookies won by a bypass, shared by every bypasser implementation.
+
+Kept in its own module rather than inside a bypasser because both of them feed it and
+both read from it. The internal bypasser cannot host it: it imports seleniumbase at
+module scope, which is exactly the dependency an external-bypasser deployment is
+entitled not to have installed.
+"""
+
+import threading
+import time
+from collections.abc import Mapping
+from typing import Any
+from urllib.parse import urlparse
+
+from shelfmark.core.logger import setup_logger
+
+logger = setup_logger(__name__)
+
+# Cookie storage - shared with requests library for Cloudflare bypass
+# Nested mapping of domain to cookie name to cookie metadata.
+_cf_cookies: dict[str, dict] = {}
+_cf_cookies_lock = threading.Lock()
+
+# User-Agent storage - Cloudflare ties cf_clearance to the UA that solved the challenge
+_cf_user_agents: dict[str, str] = {}
+
+# Protection cookie names we care about (Cloudflare and DDoS-Guard)
+CF_COOKIE_NAMES = {"cf_clearance", "__cf_bm", "cf_chl_2", "cf_chl_prog"}
+DDG_COOKIE_NAMES = {
+    "__ddg1_",
+    "__ddg2_",
+    "__ddg5_",
+    "__ddg8_",
+    "__ddg9_",
+    "__ddg10_",
+    "__ddgid_",
+    "__ddgmark_",
+    "ddg_last_challenge",
+}
+
+# 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:
+#
+#   __ddg9_   the client IP address
+#   __ddg10_  the unix timestamp the check was issued
+#   __ddg8_   an opaque token issued with them, same ~40 minute expiry
+#
+# Clearance itself lives in __ddg1_/__ddg2_/__ddgid_ (roughly a year) and __ddg5_.
+# Replaying the trio is actively harmful: once the timestamp ages out - or the egress
+# IP changes, which happens routinely behind a VPN - the values no longer describe the
+# caller, DDoS-Guard re-arms its check and answers every request with a ?check=1
+# redirect. That is the redirect loop, and it is self-inflicted. Dropping them simply
+# lets DDoS-Guard issue a fresh set, exactly as it does for a browser.
+DDG_EPHEMERAL_COOKIE_NAMES = {
+    "__ddg8_",
+    "__ddg9_",
+    "__ddg10_",
+    "ddg_last_challenge",
+}
+
+
+def _get_base_domain(domain: str) -> str:
+    """Extract base domain from hostname (e.g., 'www.example.com' -> 'example.com')."""
+    return ".".join(domain.split(".")[-2:]) if "." in domain else domain
+
+
+def _get_full_cookie_domains() -> set[str]:
+    """Return mirror domains that need full-session cookie extraction."""
+    from shelfmark.core.mirrors import get_zlib_cookie_domains
+
+    return {_get_base_domain(domain) for domain in get_zlib_cookie_domains()}
+
+
+def _replay_per_check_cookies() -> bool:
+    """Whether the per-check trio is kept rather than dropped (see env.py)."""
+    from shelfmark.config import env
+
+    return env.DDG_REPLAY_PER_CHECK_COOKIES
+
+
+def _should_extract_cookie(name: str, *, extract_all: bool) -> bool:
+    """Determine if a cookie should be extracted based on its name."""
+    # Checked before extract_all: a per-check token is wrong to replay for every
+    # domain, including the full-session ones.
+    if name in DDG_EPHEMERAL_COOKIE_NAMES and not _replay_per_check_cookies():
+        return False
+    if extract_all:
+        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
+
+
+def _cookie_field(cookie: Any, name: str) -> Any:
+    """Read one field from a cookie in either shape we are handed.
+
+    The internal bypasser extracts CDP cookie objects; an external bypasser returns
+    the same fields as JSON objects, so the difference is attribute versus key access.
+    """
+    if isinstance(cookie, Mapping):
+        return cookie.get(name)
+    return getattr(cookie, name, None)
+
+
+def _cookie_expiry(cookie: Any) -> float | None:
+    """A cookie's absolute expiry, or None when it is a session cookie.
+
+    The two spellings are not interchangeable and both reach this store. CDP and
+    Playwright cookies carry `expires`; the WebDriver cookie object - what a
+    Selenium-based solver such as FlareSolverr returns - carries `expiry`. Reading
+    only one silently turns every cookie from the other into a never-expiring one,
+    which is exactly how dead clearance ends up replayed forever (see
+    get_cf_cookies_for_domain).
+
+    The value is coerced rather than trusted: it arrives as JSON from a service we
+    do not control, and a string here used to raise straight out of the store.
+    """
+    for field in ("expires", "expiry"):
+        raw = _cookie_field(cookie, field)
+        if raw is None:
+            continue
+        try:
+            expiry = float(raw)
+        except TypeError, ValueError:
+            logger.debug("Unreadable cookie expiry %r; treating as a session cookie", raw)
+            return None
+        # <= 0 is how both shapes spell "session cookie", not "expired in 1970".
+        return expiry if expiry > 0 else None
+    return None
+
+
+def store_extracted_cookies(
+    *,
+    url: str,
+    cookies: list[Any],
+    user_agent: str | None = None,
+) -> None:
+    """Store filtered bypass cookies (and optional UA) for a URL domain."""
+    parsed = urlparse(url)
+    domain = parsed.hostname or ""
+    if not domain:
+        return
+
+    base_domain = _get_base_domain(domain)
+    extract_all = base_domain in _get_full_cookie_domains()
+
+    cookies_found: dict[str, dict[str, Any]] = {}
+    dropped: list[str] = []
+    for cookie in cookies:
+        name = _cookie_field(cookie, "name") or ""
+        if not _should_extract_cookie(name, extract_all=extract_all):
+            dropped.append(name)
+            continue
+        secure = _cookie_field(cookie, "secure")
+        cookies_found[name] = {
+            "value": _cookie_field(cookie, "value") or "",
+            "domain": _cookie_field(cookie, "domain") or domain,
+            "path": _cookie_field(cookie, "path") or "/",
+            "expiry": _cookie_expiry(cookie),
+            "secure": True if secure is None else bool(secure),
+            "httpOnly": True,
+        }
+
+    # Names only, never values. Which cookies a solve won, and which of them were held
+    # back, is the evidence needed to settle what DDoS-Guard actually treats as clearance
+    # (issue #1276) - and without it a debug log shows a solve succeeding and the next
+    # request being challenged with nothing in between to explain why.
+    logger.debug(
+        "Solve on %s won %s; keeping %s; dropping %s",
+        base_domain,
+        sorted({_cookie_field(c, "name") or "" for c in cookies}),
+        sorted(cookies_found),
+        sorted(set(dropped)) or "nothing",
+    )
+
+    if not cookies_found:
+        return
+
+    with _cf_cookies_lock:
+        _cf_cookies[base_domain] = cookies_found
+        if user_agent:
+            _cf_user_agents[base_domain] = user_agent
+            logger.debug("Stored UA for %s: %s...", base_domain, str(user_agent)[:60])
+        else:
+            logger.debug("No UA captured for %s", base_domain)
+
+    cookie_type = "all" if extract_all else "protection"
+    logger.debug("Extracted %s %s cookies for %s", len(cookies_found), cookie_type, base_domain)
+
+
+def _is_cookie_expired(cookie: dict[str, Any]) -> bool:
+    """Whether a stored cookie's expiry has passed. Session cookies never expire here."""
+    expiry = cookie.get("expiry")
+    if expiry is None:
+        expiry = cookie.get("expires")
+    if not expiry or expiry <= 0:
+        return False
+    return time.time() > expiry
+
+
+def get_cf_cookies_for_domain(domain: str) -> dict[str, str]:
+    """Get stored cookies for a domain. Returns empty dict if none available."""
+    if not domain:
+        return {}
+
+    base_domain = _get_base_domain(domain)
+
+    with _cf_cookies_lock:
+        cookies = _cf_cookies.get(base_domain, {})
+        if not cookies:
+            return {}
+
+        cf_clearance = cookies.get("cf_clearance", {})
+        if cf_clearance and _is_cookie_expired(cf_clearance):
+            logger.debug("CF cookies expired for %s", base_domain)
+            _cf_cookies.pop(base_domain, None)
+            return {}
+
+        # Expiry applies to every cookie, not just Cloudflare's. DDoS-Guard domains
+        # have no cf_clearance, so the check above never fired for them and dead
+        # cookies were replayed indefinitely - the server answers those with a
+        # challenge, which is indistinguishable from having sent nothing at all.
+        live = {name: c for name, c in cookies.items() if not _is_cookie_expired(c)}
+        if len(live) != len(cookies):
+            expired = sorted(set(cookies) - set(live))
+            logger.debug("Dropping expired cookies for %s: %s", base_domain, expired)
+            if live:
+                _cf_cookies[base_domain] = live
+            else:
+                _cf_cookies.pop(base_domain, None)
+
+        return {name: c["value"] for name, c in live.items()}
+
+
+def has_valid_cf_cookies(domain: str) -> bool:
+    """Check if we have valid Cloudflare cookies for a domain."""
+    return bool(get_cf_cookies_for_domain(domain))
+
+
+def get_cf_user_agent_for_domain(domain: str) -> str | None:
+    """Get the User-Agent that was used during bypass for a domain."""
+    if not domain:
+        return None
+    with _cf_cookies_lock:
+        return _cf_user_agents.get(_get_base_domain(domain))
+
+
+def export_store() -> tuple[dict[str, dict], dict[str, str]]:
+    """Snapshot the whole store, for handing to another process.
+
+    The internal bypasser's Docker helper solves in a subprocess, so the clearance it
+    wins has to be serialized back to the parent or the solve is lost with the child.
+    """
+    with _cf_cookies_lock:
+        return (
+            {domain: dict(cookies) for domain, cookies in _cf_cookies.items()},
+            dict(_cf_user_agents),
+        )
+
+
+def import_store(cookies: object, user_agents: object) -> None:
+    """Merge a snapshot produced by :func:`export_store` into this process's store."""
+    with _cf_cookies_lock:
+        if isinstance(cookies, dict):
+            _cf_cookies.update(cookies)
+        if isinstance(user_agents, dict):
+            _cf_user_agents.update(
+                {str(domain): str(agent) for domain, agent in user_agents.items()}
+            )
+
+
+def clear_cf_cookies(domain: str | None = None) -> None:
+    """Clear stored Cloudflare cookies and User-Agent. If domain is None, clear all."""
+    with _cf_cookies_lock:
+        if domain:
+            base_domain = _get_base_domain(domain)
+            _cf_cookies.pop(base_domain, None)
+            _cf_user_agents.pop(base_domain, None)
+        else:
+            _cf_cookies.clear()
+            _cf_user_agents.clear()
@@ -2,17 +2,20 @@

 import random
 import time
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any

 import requests

-from shelfmark.bypass import BypassCancelledError
+from shelfmark.bypass import BypassCancelledError, ChallengeNotSolvedError
+from shelfmark.bypass.challenge import challenge_marker
+from shelfmark.bypass.cookie_store import store_extracted_cookies
 from shelfmark.core.config import config
 from shelfmark.core.logger import setup_logger
 from shelfmark.core.utils import normalize_http_url
 from shelfmark.download.network import get_ssl_verify

 if TYPE_CHECKING:
+    from collections.abc import Mapping
    from threading import Event

    from shelfmark.download import network
@@ -63,8 +66,39 @@ def max_duration_seconds() -> float:
    return MAX_RETRY * read_timeout + backoff_total


+def _store_solution_clearance(target_url: str, solution: Mapping[str, Any]) -> None:
+    """Keep the clearance the solver won, so later requests do not re-solve.
+
+    A solve is the expensive part of an external bypass - tens of seconds of real
+    browser - and FlareSolverr-compatible services hand back the cookies and the
+    User-Agent that earned it. Dropping them meant every single request paid a 403
+    plus a full solve, and a file download (which the solver cannot proxy, being
+    binary) never presented clearance at all.
+
+    The UA matters as much as the cookies: Cloudflare ties cf_clearance to the UA
+    that solved the challenge, so replaying the cookie under our own UA is rejected.
+    """
+    cookies = solution.get("cookies") or []
+    if not isinstance(cookies, list):
+        logger.debug("External bypasser returned no usable cookie list for '%s'", target_url)
+        return
+
+    user_agent = solution.get("userAgent")
+    store_extracted_cookies(
+        url=target_url,
+        cookies=cookies,
+        user_agent=user_agent if isinstance(user_agent, str) else None,
+    )
+
+
 def _fetch_via_bypasser(target_url: str) -> str | None:
-    """Make a single request to the external bypasser service. Returns HTML or None."""
+    """Make a single request to the external bypasser service. Returns HTML or None.
+
+    Raises:
+        ChallengeNotSolvedError: the service answered with a page that is still a
+            challenge, whatever verdict it reported on itself.
+
+    """
    raw_bypasser_url = _coerce_config_str(
        config.get("EXT_BYPASSER_URL", "http://flaresolverr:8191"),
        "http://flaresolverr:8191",
@@ -116,6 +150,41 @@ def _fetch_via_bypasser(target_url: str) -> str | None:
            logger.warning("External bypasser returned empty response for '%s'", target_url)
            return None

+        # "Challenge solved!" is the solver's verdict on its own work, and #1289 showed
+        # it can be reported alongside a page the caller then rejects. Say what actually
+        # came back, so a later report does not have to infer it from downstream errors.
+        marker = challenge_marker(html)
+        logger.debug(
+            "External bypasser page for '%s': %d bytes, challenge_marker=%r",
+            target_url,
+            len(html),
+            marker,
+        )
+        if marker:
+            # The solver's verdict is not evidence; the page is. Returning this one as a
+            # success is what made #1292 unrecoverable: the retry-and-rotate loop that
+            # could still have saved the search - the next mirror is a different
+            # DDoS-Guard host, in its own state - was never entered, and the challenge
+            # page's own __ddg cookies were filed as this host's clearance and replayed
+            # on every later request.
+            logger.warning(
+                "External bypasser reported success but returned a challenge page for "
+                "'%s' (%d bytes, marker=%r) - the solve did not clear the protection",
+                target_url,
+                len(html),
+                marker,
+            )
+            raise ChallengeNotSolvedError(marker)
+
+        try:
+            _store_solution_clearance(target_url, solution)
+        except AttributeError, KeyError, TypeError, ValueError:
+            # Storing clearance is an optimisation; the page is the product. The
+            # solution JSON comes from a service we do not control, so a surprise in
+            # its cookie shape must not discard HTML that already cost a ~30s solve
+            # and send the caller round for up to MAX_RETRY more of them.
+            logger.debug("Could not store bypass clearance for '%s'", target_url, exc_info=True)
+
    except requests.exceptions.Timeout:
        logger.warning(
            "External bypasser timed out for '%s' (connect: %ss, read: %.0fs)",
@@ -156,16 +225,33 @@ def get_bypassed_page(
    selector: network.AAMirrorSelector | None = None,
    cancel_flag: Event | None = None,
 ) -> str | None:
-    """Fetch HTML via external bypasser with retries and mirror rotation."""
+    """Fetch HTML via external bypasser with retries and mirror rotation.
+
+    Raises:
+        ChallengeNotSolvedError: every attempt came back still carrying a challenge.
+            Reported apart from returning None because the two ask the user for
+            opposite things: None means go and check the bypasser, this means the
+            bypasser is fine and the host is the one refusing.
+        BypassCancelledError: the caller's cancel flag was set.
+
+    """
    from shelfmark.download import network as network_module

    sel = selector or network_module.AAMirrorSelector()
+    unsolved_marker: str | None = None

    for attempt in range(1, MAX_RETRY + 1):
        _check_cancelled(cancel_flag, "by user")

        attempt_url = sel.rewrite(url)
-        result = _fetch_via_bypasser(attempt_url)
+        try:
+            result = _fetch_via_bypasser(attempt_url)
+        except ChallengeNotSolvedError as e:
+            # Worth the remaining attempts rather than an immediate give-up: the retry
+            # rotates onto the next mirror, and that is a different DDoS-Guard host with
+            # its own idea of whether this caller needs a CAPTCHA.
+            unsolved_marker = str(e) or unsolved_marker
+            result = None
        if result:
            return result

@@ -186,4 +272,11 @@ def get_bypassed_page(
        if action in ("mirror", "dns") and new_base:
            logger.info("Rotated %s for retry", action)

+    if unsolved_marker:
+        msg = (
+            "The bypasser ran, but the site kept answering with a protection challenge "
+            f"(marker={unsolved_marker!r}). That is usually a manual CAPTCHA, which no "
+            "bypasser can answer - the bypasser itself is working. Try again shortly."
+        )
+        raise ChallengeNotSolvedError(msg)
    return None
@@ -203,6 +203,21 @@ ONBOARDING = string_to_bool(os.getenv("ONBOARDING", "true"))
 _DEBUG_SKIP_SOURCES_RAW = os.getenv("DEBUG_SKIP_SOURCES", "").strip().lower()
 DEBUG_SKIP_SOURCES = {s.strip() for s in _DEBUG_SKIP_SOURCES_RAW.split(",") if s.strip()}

+# Debug: keep DDoS-Guard's __ddg8_/__ddg9_/__ddg10_ in the clearance store instead of
+# dropping them after a solve.
+#
+# Which of DDoS-Guard's cookies actually *are* clearance is not settled. The store treats
+# the trio as describing one check (client IP, timestamp, token) and drops them, on the
+# reasoning that replaying a stale IP/timestamp is what re-arms the ?check=1 loop - see
+# shelfmark.bypass.cookie_store. Field reports on issue #1276 point the other way: every
+# request after a successful solve was challenged again, which is only consistent with
+# what the store keeps not being sufficient clearance on its own.
+#
+# Deliberately env-only and off by default: this is a knob for reproducing the question
+# against a live host, not a setting to offer users. Set it to true, solve once, and watch
+# whether the next search still logs "Redirect loop detected".
+DDG_REPLAY_PER_CHECK_COOKIES = string_to_bool(os.getenv("DDG_REPLAY_PER_CHECK_COOKIES", "false"))
+

 # =============================================================================
 # Legacy migration support - will be removed in future version
@@ -430,13 +430,6 @@ def general_settings() -> list[SettingsField]:
            options=_AUDIOBOOK_FORMAT_OPTIONS,
            default=[*AUDIOBOOK_FORMATS, *ARCHIVE_FORMATS],
        ),
-        MultiSelectField(
-            key="BOOK_LANGUAGE",
-            label="Default Book Languages",
-            description="Default language filter for searches.",
-            options=_LANGUAGE_OPTIONS,
-            default=["en"],
-        ),
    ]


@@ -474,6 +467,17 @@ def search_mode_settings() -> list[SettingsField]:
            default="universal",
            user_overridable=True,
        ),
+        MultiSelectField(
+            key="BOOK_LANGUAGE",
+            label="Default Book Languages",
+            description=(
+                "Default language filter for searches. Users can override this for their "
+                "own account."
+            ),
+            options=_LANGUAGE_OPTIONS,
+            default=["en"],
+            user_overridable=True,
+        ),
        SelectField(
            key="AA_DEFAULT_SORT",
            label="Default Sort Order",
@@ -766,7 +770,10 @@ def _on_save_downloads(values: dict[str, Any]) -> dict[str, Any]:
            }

    # Audiobooks are always folder output.
-    if effective.get("FILE_ORGANIZATION_AUDIOBOOK", "rename") == "rename":
+    if effective.get("FILE_ORGANIZATION_AUDIOBOOK", "rename") in {
+        "rename",
+        "rename_and_group",
+    }:
        template = effective.get("TEMPLATE_AUDIOBOOK_RENAME", "")
        if _contains_path_separators(template):
            return {
@@ -1294,6 +1301,11 @@ def download_settings() -> list[SettingsField]:
                    "label": "Rename and Organize",
                    "description": "Create folders and rename files using a template. Recommended for Audiobookshelf. Do not use with ingest folders.",
                },
+                {
+                    "value": "rename_and_group",
+                    "label": "Rename and Group",
+                    "description": "Rename single-file downloads; keep multi-file downloads grouped in their source folder. Do not use with ingest folders.",
+                },
            ],
            default="rename",
            universal_only=True,
@@ -1312,7 +1324,10 @@ def download_settings() -> list[SettingsField]:
            ),
            default="{Author} - {Title}",
            placeholder="{Author} - {Title}{ - Part }{PartNumber}",
-            show_when={"field": "FILE_ORGANIZATION_AUDIOBOOK", "value": "rename"},
+            show_when={
+                "field": "FILE_ORGANIZATION_AUDIOBOOK",
+                "value": ["rename", "rename_and_group"],
+            },
            universal_only=True,
        ),
        # Organize mode template - folders allowed
@@ -1545,6 +1560,19 @@ def download_source_settings() -> list[SettingsField]:
            min_value=1,
            max_value=60,
        ),
+        NumberField(
+            key="RELEASE_SEARCH_TIMEOUT",
+            label="Release Search Timeout (seconds)",
+            description=(
+                "How long one release search may run before it gives up and reports why. "
+                "A first search on a cold start pays for a browser solve, so leave room "
+                "for one. If you use a reverse proxy, its read timeout should be at least "
+                "this high or it will cut the search off with a 504 first."
+            ),
+            default=300,
+            min_value=30,
+            max_value=1800,
+        ),
        HeadingField(
            key="content_type_routing_heading",
            title="Content-Type Routing",
@@ -1655,6 +1683,31 @@ def cloudflare_bypass_settings() -> list[SettingsField]:
            requires_restart=True,
            show_when={"field": "USING_EXTERNAL_BYPASSER", "value": True},
        ),
+        NumberField(
+            key="BYPASS_PAGE_SOURCE_TIMEOUT",
+            label="Page Read Timeout (seconds)",
+            description=(
+                "How long to wait for a solved page to produce its content before the "
+                "bypass is retried. Raise it if solves succeed but searches still fail."
+            ),
+            default=20,
+            min_value=1,
+            max_value=120,
+            show_when={"field": "USING_EXTERNAL_BYPASSER", "value": False},
+        ),
+        NumberField(
+            key="BYPASS_BROWSER_IDLE_TIMEOUT",
+            label="Bypasser Idle Timeout (seconds)",
+            description=(
+                "How long the bypass helper process may sit unused before it is shut down. "
+                "Higher keeps more searches fast, lower frees memory sooner."
+            ),
+            default=180,
+            min_value=30,
+            max_value=3600,
+            requires_restart=True,
+            show_when={"field": "USING_EXTERNAL_BYPASSER", "value": False},
+        ),
    ]


@@ -7,6 +7,7 @@ that talks to /api/admin/users endpoints.

 from typing import Any

+from shelfmark.core.languages import normalize_language
 from shelfmark.core.request_policy import (
    get_source_content_type_capabilities,
    parse_policy_mode,
@@ -61,7 +62,7 @@ _SELF_SETTINGS_SECTION_OPTIONS = [
    {
        "value": "search",
        "label": "Search Preferences",
-        "description": "Show personal search mode and provider settings.",
+        "description": "Show personal search mode, language, and provider settings.",
    },
    {
        "value": "notifications",
@@ -77,8 +78,9 @@ _SEARCH_PREFERENCE_PROVIDER_KEYS = {
    "METADATA_PROVIDER_AUDIOBOOK",
    "METADATA_PROVIDER_COMBINED",
 }
-_SEARCH_PREFERENCE_VALIDATABLE_KEYS = {
+SEARCH_PREFERENCE_VALIDATABLE_KEYS = {
    "SEARCH_MODE",
+    "BOOK_LANGUAGE",
    "DEFAULT_RELEASE_SOURCE",
    "DEFAULT_RELEASE_SOURCE_AUDIOBOOK",
    "SHOW_COMBINED_SELECTOR",
@@ -178,14 +180,43 @@ def _get_request_policy_rule_columns() -> list[dict[str, object]]:
    ]


+def _validate_book_languages(value: Any) -> tuple[Any, str | None]:
+    """Validate a per-user default language list against the known languages.
+
+    Accepts the list the settings UI sends as well as a comma-separated string, so an
+    API client can spell the value the way the env var does. Blank entries are skipped
+    rather than rejected, which makes "" and "en," mean the same as [] and ["en"]. An
+    empty result is a deliberate override meaning "no default language filter", so it
+    is kept as-is; ``None`` clears the override further up the chain.
+    """
+    entries = value.split(",") if isinstance(value, str) else value
+    if not isinstance(entries, (list, tuple)):
+        return value, "BOOK_LANGUAGE must be a list of language codes"
+
+    normalized: list[str] = []
+    for entry in entries:
+        if entry is None or (isinstance(entry, str) and not entry.strip()):
+            continue
+        code = normalize_language(entry)
+        if code is None:
+            return value, f"BOOK_LANGUAGE contains an unsupported language: {entry}"
+        if code not in normalized:
+            normalized.append(code)
+
+    return normalized, None
+
+
 def validate_search_preference_value(key: str, value: Any) -> tuple[Any, str | None]:
    """Validate and normalize a search preference value for user overrides."""
-    if key not in _SEARCH_PREFERENCE_VALIDATABLE_KEYS:
+    if key not in SEARCH_PREFERENCE_VALIDATABLE_KEYS:
        return value, None

    if value is None:
        return None, None

+    if key == "BOOK_LANGUAGE":
+        return _validate_book_languages(value)
+
    normalized_value = str(value).strip()

    if key == "SEARCH_MODE":
@@ -298,7 +329,7 @@ def _on_save_users(values: dict[str, object]) -> dict[str, object]:
            }
        values["REQUEST_POLICY_RULES"] = normalized_rules

-    for key in _SEARCH_PREFERENCE_VALIDATABLE_KEYS:
+    for key in SEARCH_PREFERENCE_VALIDATABLE_KEYS:
        if key not in values:
            continue
        normalized_value, validation_error = validate_search_preference_value(key, values[key])
@@ -11,7 +11,10 @@ from shelfmark.config.notifications_settings import (
    is_valid_notification_url,
    normalize_notification_routes,
 )
-from shelfmark.config.users_settings import validate_search_preference_value
+from shelfmark.config.users_settings import (
+    SEARCH_PREFERENCE_VALIDATABLE_KEYS,
+    validate_search_preference_value,
+)
 from shelfmark.core.config import config as app_config
 from shelfmark.core.request_policy import parse_policy_mode, validate_policy_rules
 from shelfmark.core.settings_registry import load_config_file
@@ -91,13 +94,9 @@ def validate_user_settings(
            if search_validation_error:
                errors.append(search_validation_error)
                continue
-            if key in {
-                "SEARCH_MODE",
-                "METADATA_PROVIDER",
-                "METADATA_PROVIDER_AUDIOBOOK",
-                "DEFAULT_RELEASE_SOURCE",
-                "DEFAULT_RELEASE_SOURCE_AUDIOBOOK",
-            }:
+            # Every key the search validator recognises keeps its normalized value;
+            # a hand-maintained subset here silently dropped normalization for the rest.
+            if key in SEARCH_PREFERENCE_VALIDATABLE_KEYS:
                valid[key] = normalized_search_value
                continue

@@ -136,6 +136,12 @@ class DownloadTask:
        default_factory=dict
    )  # Per-output parameters (e.g. email recipient)

+    # Multi-book packs: one release holding several books. `book_plan` is the split the
+    # user approved before download (list of {title, series_position, year, files});
+    # `multi_book` asks post-processing to split heuristically when no plan exists.
+    multi_book: bool = False
+    book_plan: list[dict[str, Any]] | None = None
+
    # User association (multi-user support)
    user_id: int | None = None  # DB user ID who queued this download
    username: str | None = None  # Username for {User} template variable
@@ -0,0 +1,102 @@
+"""Pre-download release inspection: list a release's files and plan a multi-book split."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from flask import jsonify, request
+
+from shelfmark.core.logger import setup_logger
+from shelfmark.core.utils import is_audiobook
+from shelfmark.download.postprocess.packs import PackFile, PackPlan, plan_pack
+from shelfmark.download.postprocess.policy import (
+    get_supported_audiobook_formats,
+    get_supported_formats,
+)
+from shelfmark.release_sources import get_handler
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from flask import Flask, Response
+
+logger = setup_logger(__name__)
+
+_INSPECT_ERRORS = (OSError, RuntimeError, ValueError, TypeError, KeyError, AttributeError)
+NOT_INSPECTABLE_REASON = "This source cannot list the release's files before downloading"
+
+
+def _serialize_plan(plan: PackPlan) -> dict[str, Any]:
+    return {
+        "is_pack": plan.is_pack,
+        "ignored": plan.ignored,
+        "books": [
+            {
+                "title": book.title,
+                "series_position": book.series_position,
+                "year": book.year,
+                "files": book.files,
+            }
+            for book in plan.books
+        ],
+    }
+
+
+def inspect_release(data: dict[str, Any]) -> dict[str, Any]:
+    """Build the inspect response for a release payload (same shape as a download)."""
+    source = str(data["source"])
+    handler = get_handler(source)
+    try:
+        files: list[PackFile] | None = handler.list_files(data)
+    except _INSPECT_ERRORS as exc:
+        logger.warning(
+            "Could not list files for %s release %s: %s", source, data.get("source_id"), exc
+        )
+        return {"inspected": False, "reason": str(exc), "files": [], "plan": None}
+
+    if files is None:
+        return {"inspected": False, "reason": NOT_INSPECTABLE_REASON, "files": [], "plan": None}
+
+    content_type = data.get("content_type")
+    supported = (
+        get_supported_audiobook_formats()
+        if is_audiobook(content_type if isinstance(content_type, str) else None)
+        else get_supported_formats()
+    )
+    series_name = data.get("series_name")
+    author_name = data.get("author")
+    plan = plan_pack(
+        files,
+        supported_extensions=set(supported),
+        series_name=series_name if isinstance(series_name, str) else None,
+        author_name=author_name if isinstance(author_name, str) else None,
+    )
+    return {
+        "inspected": True,
+        "reason": None,
+        "files": [{"path": f.path, "size": f.size} for f in files],
+        "plan": _serialize_plan(plan),
+    }
+
+
+def register_release_inspect_routes(
+    app: Flask,
+    login_required: Callable[..., Any],
+) -> None:
+    """Register POST /api/releases/inspect."""
+
+    @app.route("/api/releases/inspect", methods=["POST"])
+    @login_required
+    def api_inspect_release() -> Response | tuple[Response, int]:
+        data = request.get_json(silent=True)
+        if not isinstance(data, dict):
+            return jsonify({"error": "No data provided"}), 400
+        if not data.get("source_id"):
+            return jsonify({"error": "source_id is required"}), 400
+        if not data.get("source"):
+            return jsonify({"error": "source is required"}), 400
+        try:
+            get_handler(str(data["source"]))
+        except ValueError as exc:
+            return jsonify({"error": str(exc)}), 400
+        return jsonify(inspect_release(data))
@@ -0,0 +1,134 @@
+"""A wall-clock budget for one release search, enforced through the existing cancel flag.
+
+`/api/releases` is synchronous: the browser waits on it while the search runs. Nothing
+bounded that wait, and the bypasser's own worst case is minutes long
+(`internal_bypasser.max_duration_seconds()`), so a search that ran into an unsolvable
+protection challenge outlived every reverse proxy in front of it. The user then saw
+"Server unavailable (504)" - a gateway timeout that says nothing about what went wrong
+and points the blame at their proxy config. See issue #1276.
+
+The budget is expressed as the cancel flag the download path already understands: an
+Event armed by a timer. `html_get_page`, the bypassers and the helper subprocess all poll
+it, so an expired budget stops a solve already in flight rather than only refusing the
+next one. When it trips, the search fails with a message that names the real cause.
+
+Scoped to a context variable so it applies to the request that set it and to nothing else
+- a queued download must keep its own, much longer, budget.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from contextlib import contextmanager
+from contextvars import ContextVar
+from typing import TYPE_CHECKING
+
+from shelfmark.core.logger import setup_logger
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+logger = setup_logger(__name__)
+
+# What one search may spend. A first search on a cold start legitimately pays for a
+# browser solve - jfmlima measured 60-120s for a successful one on Anna's Archive - so
+# this cannot be as tight as a proxy's default read timeout without breaking working
+# setups. It is instead well below the ~840s the bypass path could previously reach,
+# which is what turned a failing challenge into a gateway timeout.
+DEFAULT_SEARCH_BUDGET_SECONDS = 300.0
+
+_MIN_SEARCH_BUDGET_SECONDS = 30.0
+_MAX_SEARCH_BUDGET_SECONDS = 1800.0
+
+# Raised to the caller when the budget runs out, so the API can say so plainly.
+SEARCH_DEADLINE_MESSAGE = (
+    "The release search ran out of time (%.0fs). Anna's Archive is behind a protection "
+    "challenge the bypasser could not solve in that window. Raise the release search "
+    "timeout if your setup is simply slow."
+)
+
+
+class SearchDeadline:
+    """A budget with an Event that trips when it expires."""
+
+    def __init__(self, budget_seconds: float) -> None:
+        self.budget_seconds = budget_seconds
+        self.expires_at = time.monotonic() + budget_seconds
+        # A plain threading.Event on purpose: this is handed on as a cancel flag, and
+        # that is the type the download path, the CDP worker thread and the bypass helper
+        # already poll.
+        self.event = threading.Event()
+        self._timer = threading.Timer(budget_seconds, self.event.set)
+        self._timer.daemon = True
+
+    def start(self) -> None:
+        self._timer.start()
+
+    def cancel(self) -> None:
+        self._timer.cancel()
+
+    @property
+    def remaining(self) -> float:
+        return max(0.0, self.expires_at - time.monotonic())
+
+    @property
+    def expired(self) -> bool:
+        return self.event.is_set() or self.remaining <= 0
+
+
+_current: ContextVar[SearchDeadline | None] = ContextVar("search_deadline", default=None)
+
+
+def budget_seconds() -> float:
+    """The configured budget for one release search."""
+    from shelfmark.core.config import config as app_config
+
+    raw = app_config.get("RELEASE_SEARCH_TIMEOUT", DEFAULT_SEARCH_BUDGET_SECONDS)
+    if isinstance(raw, bool) or not isinstance(raw, int | float | str):
+        return DEFAULT_SEARCH_BUDGET_SECONDS
+    try:
+        value = float(raw)
+    except TypeError, ValueError:
+        return DEFAULT_SEARCH_BUDGET_SECONDS
+    if value <= 0:
+        return DEFAULT_SEARCH_BUDGET_SECONDS
+    return min(max(value, _MIN_SEARCH_BUDGET_SECONDS), _MAX_SEARCH_BUDGET_SECONDS)
+
+
+@contextmanager
+def search_deadline(budget: float | None = None) -> Iterator[SearchDeadline]:
+    """Apply a budget to everything the calling context does."""
+    deadline = SearchDeadline(budget if budget is not None else budget_seconds())
+    token = _current.set(deadline)
+    deadline.start()
+    logger.debug("Release search budget: %.0fs", deadline.budget_seconds)
+    try:
+        yield deadline
+    finally:
+        deadline.cancel()
+        _current.reset(token)
+
+
+def current() -> SearchDeadline | None:
+    """The budget in force, or None outside a search."""
+    return _current.get()
+
+
+def expired() -> bool:
+    """Whether the budget in force has run out. False when there is no budget."""
+    deadline = _current.get()
+    return deadline is not None and deadline.expired
+
+
+def cancel_event() -> threading.Event | None:
+    """The Event that trips when the budget runs out, for use as a cancel flag."""
+    deadline = _current.get()
+    return deadline.event if deadline is not None else None
+
+
+def deadline_message() -> str:
+    """The failure to report when the budget has run out."""
+    deadline = _current.get()
+    budget = deadline.budget_seconds if deadline else DEFAULT_SEARCH_BUDGET_SECONDS
+    return SEARCH_DEADLINE_MESSAGE % budget
@@ -7,6 +7,7 @@ from dataclasses import dataclass
 from typing import TYPE_CHECKING

 from shelfmark.core.config import config
+from shelfmark.core.logger import setup_logger
 from shelfmark.metadata_providers import (
    BookMetadata,
    build_localized_search_titles,
@@ -16,6 +17,8 @@ from shelfmark.metadata_providers import (
 if TYPE_CHECKING:
    from shelfmark.core.models import SearchFilters

+logger = setup_logger(__name__)
+
 MANUAL_QUERY_MAX_LEN = 256


@@ -52,44 +55,110 @@ class ReleaseSearchPlan:
        return self.title_variants[0].query if self.title_variants else ""


-def _normalize_languages(languages: list[str] | None) -> list[str] | None:
+def _to_language_codes(values: Iterable[object], *, source: str) -> list[str] | None:
+    """Resolve any spelling of a language to the ISO code the sources expect.
+
+    Anna's Archive matches `lang=` against ISO codes: `lang=english` is not a loose
+    spelling of `lang=en`, it is a facet value AA does not have, and it filters every
+    search down to nothing. Only the *per-user* override was normalised
+    (config.users_settings.validate), so a global BOOK_LANGUAGE=english - the spelling
+    the old docs used - reached the query verbatim and silently emptied every search
+    with no error anywhere. See issue #1276.
+
+    An entry that resolves to nothing is dropped with a warning rather than passed
+    through: searching unfiltered and saying so beats reporting "no results" for a book
+    the source is full of.
+    """
+    from shelfmark.core.languages import normalize_language
+
+    codes: list[str] = []
+    unresolved: list[str] = []
+    for value in values:
+        text = str(value).strip() if value is not None else ""
+        if not text:
+            continue
+        if text.lower() == "all":
+            # An explicit "search every language", not a language.
+            return None
+        code = normalize_language(text)
+        if code is None:
+            unresolved.append(text)
+            continue
+        if code not in codes:
+            codes.append(code)
+
+    if unresolved:
+        logger.warning(
+            "Ignoring unrecognised language(s) in %s: %s. Use an ISO code such as 'en', "
+            "a three-letter code, or an English name like 'English'.",
+            source,
+            ", ".join(unresolved),
+        )
+
+    return codes or None
+
+
+def _normalize_languages(languages: list[str] | None, user_id: int | None) -> list[str] | None:
    if not languages:
-        default = getattr(config, "BOOK_LANGUAGE", None)
+        default = config.get("BOOK_LANGUAGE", None, user_id=user_id)
        if isinstance(default, str):
            default_values: list[object] = [default]
        elif isinstance(default, Iterable) and not isinstance(default, (bytes, bytearray, dict)):
            default_values = list(default)
        else:
            return None
-        return [str(lang).strip() for lang in default_values if str(lang).strip()]
+        return _to_language_codes(default_values, source="BOOK_LANGUAGE")

-    normalized: list[str] = []
-    for lang in languages:
-        if not lang:
-            continue
-        s = str(lang).strip()
-        if not s:
-            continue
-        normalized.append(s)
-
-    if any(lang.lower() == "all" for lang in normalized):
-        return None
-
-    return normalized or None
+    return _to_language_codes(languages, source="the search request")


-def _pick_search_author(book: BookMetadata) -> str:
+def first_author(value: str) -> str:
+    """The first name in a possibly comma-joined author string.
+
+    Both ends of the app hand us every contributor in one string. The frontend joins
+    `authors` with ", " for display (`bookTransformers.ts`) and that display string comes
+    straight back as the `author` request parameter, while several providers set
+    `search_author` from the same joined text. Searching a release source for
+    "Blindness Jose Saramago, Giovanni Pontiero, ..." - the author plus two translators -
+    matches nothing, and the user is told the book has no releases at all.
+
+    A "Last, First" author collapses to the surname, which is still a usable search term
+    and is what the authors[] fallback has always done with the same input. See #1252.
+    """
+    first, _, _ = value.partition(",")
+    return first.strip()
+
+
+def pick_search_author(book: BookMetadata) -> str:
+    """The one author a release query should carry, from whichever field holds one.
+
+    Every release source that builds its own query wants exactly this, so it lives here
+    rather than being re-derived per source - the two branches below drifted apart once
+    already (#1252) and the IRC source carried a third copy of the same preference.
+
+    #1290 fixed the same report by merging the two branches and trimming whichever one
+    won; this keeps that outcome ("Blindness Jose Saramago" from either field, measured
+    there at 0 releases before and 49 after) and adds the empty-narrowing fallback, so a
+    credit list that merely starts with a blank entry does not fall out to title-only.
+    """
+    # Narrowing can come back empty - the joined string starts with a comma because the
+    # first contributor was blank, and `authors.join(', ')` does not drop the empty entry.
+    # Falling through to authors[] then still finds a usable name; returning "" would
+    # search by title alone and lose the author we were holding all along.
    if book.search_author:
-        return book.search_author
+        narrowed = first_author(book.search_author)
+        if narrowed:
+            return narrowed

-    if not book.authors:
-        return ""
+    # A bare string here would otherwise be iterated one character at a time; the IRC
+    # source guarded against exactly that before it shared this helper.
+    authors = book.authors if isinstance(book.authors, list) else [book.authors or ""]
+    for author in authors:
+        narrowed = first_author(author or "")
+        if narrowed:
+            return narrowed

-    first = book.authors[0]
-    if "," in first:
-        first = first.split(",")[0].strip()
-
-    return first
+    return ""


 def _pick_search_title(book: BookMetadata) -> str:
@@ -102,15 +171,21 @@ def build_release_search_plan(
    manual_query: str | None = None,
    indexers: list[str] | None = None,
    source_filters: SearchFilters | None = None,
+    user_id: int | None = None,
 ) -> ReleaseSearchPlan:
-    """Build normalized search variants shared across release sources."""
-    resolved_languages = _normalize_languages(languages)
+    """Build normalized search variants shared across release sources.
+
+    ``user_id`` picks up that user's default languages when the caller does not
+    filter explicitly, so a search started without a language filter uses the
+    reader's own default rather than the instance-wide one.
+    """
+    resolved_languages = _normalize_languages(languages, user_id)

    resolved_manual_query = None
    if manual_query:
        resolved_manual_query = manual_query.strip()[:MANUAL_QUERY_MAX_LEN] or None

-    author = _pick_search_author(book)
+    author = pick_search_author(book)
    base_title = _pick_search_title(book)

    if resolved_manual_query:
@@ -122,7 +122,12 @@ def is_audiobook(content_type: str | None) -> bool:
 # had drifted apart: the settings UI only offered m4b/mp3/m4a, which meant a FLAC
 # audiobook could never be enabled, was silently dropped from every search result, and
 # was rejected after download as "format not supported".
-AUDIOBOOK_FORMATS = ("m4b", "mp3", "m4a", "flac", "ogg", "wma", "aac", "wav", "opus")
+#
+# "mp4" is here because some trackers (MyAnonamouse in particular) ship AAC audiobooks
+# as per-chapter .mp4 files - the same ISO-BMFF container as .m4a/.m4b, just with the
+# generic extension. Without it those releases downloaded fine and then failed
+# post-processing with "No book files found in download".
+AUDIOBOOK_FORMATS = ("m4b", "mp3", "m4a", "mp4", "flac", "ogg", "wma", "aac", "wav", "opus")

 # Multi-file audiobooks are almost always distributed as an archive. These are containers
 # rather than formats: they are what a *release* looks like, and the formats above are
@@ -26,6 +26,11 @@ from shelfmark.download.clients import (
    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

@@ -71,6 +76,7 @@ _BOOK_EXTENSIONS = (
    ".m4b",
    ".mobi",
    ".mp3",
+    ".mp4",
    ".ogg",
    ".opus",
    ".pdf",
@@ -202,41 +208,19 @@ class AllDebridClient(DownloadClient):
        expected_hash: str | None = None,
        **kwargs: object,
    ) -> str:
-        """Upload a magnet link to AllDebrid and return the magnet ID."""
+        """Send a torrent to AllDebrid and return the magnet ID.
+
+        Accepts a magnet link, a .torrent URL, or an indexer proxy URL; anything
+        that is not already a magnet is resolved first, since an HTTP URL posted
+        as a magnet is rejected rather than downloaded (#1250).
+        """
        if not self._api_key:
            msg = "AllDebrid API key is not configured"
            raise RuntimeError(msg)

-        magnet_link = url
-        if not magnet_link.startswith("magnet:") and expected_hash:
-            magnet_link = f"magnet:?xt=urn:btih:{expected_hash}"
-
-        api_url = f"{_API_BASE}/magnet/upload"
        try:
-            resp = requests.post(
-                api_url,
-                headers=self._auth_headers(),
-                data={"magnets[]": magnet_link},
-                timeout=_API_TIMEOUT,
-                verify=get_ssl_verify(api_url),
-            )
-            resp.raise_for_status()
-            data = resp.json()
-            if data.get("status") != "success":
-                code = data.get("error", {}).get("code", "UNKNOWN")
-                msg = f"AllDebrid upload failed: {code}"
-                _raise_runtime_error(msg)
-
-            magnets = data.get("data", {}).get("magnets", [])
-            if not magnets:
-                msg = "No magnet returned from AllDebrid"
-                _raise_runtime_error(msg)
-
-            info = magnets[0]
-            if info.get("error"):
-                code = info["error"].get("code", "UNKNOWN")
-                msg = f"AllDebrid magnet error: {code}"
-                _raise_runtime_error(msg)
+            upload = resolve_debrid_upload(url, expected_hash=expected_hash)
+            info = self._send_torrent(upload)

            magnet_id = str(info.get("id", ""))
            if not magnet_id:
@@ -262,12 +246,65 @@ class AllDebridClient(DownloadClient):
            )

        except Exception:
-            logger.exception("Failed to upload magnet to AllDebrid")
+            logger.exception("Failed to add torrent to AllDebrid")
            raise

        else:
            return magnet_id

+    def _send_torrent(self, upload: DebridUpload) -> dict[str, Any]:
+        """Hand the torrent to AllDebrid, as a magnet or as a file upload.
+
+        Both endpoints answer with the same envelope and the same per-entry
+        error shape, differing only in which key holds the entries.
+        """
+        if isinstance(upload, DebridMagnet):
+            api_url = f"{_API_BASE}/magnet/upload"
+            entries_key = "magnets"
+            resp = requests.post(
+                api_url,
+                headers=self._auth_headers(),
+                data={"magnets[]": upload.magnet_url},
+                timeout=_API_TIMEOUT,
+                verify=get_ssl_verify(api_url),
+            )
+        else:
+            api_url = f"{_API_BASE}/magnet/upload/file"
+            entries_key = "files"
+            resp = requests.post(
+                api_url,
+                headers=self._auth_headers(),
+                files={
+                    "files[]": (
+                        "release.torrent",
+                        upload.torrent_data,
+                        "application/x-bittorrent",
+                    )
+                },
+                timeout=_API_TIMEOUT,
+                verify=get_ssl_verify(api_url),
+            )
+
+        resp.raise_for_status()
+        data = resp.json()
+        if data.get("status") != "success":
+            code = data.get("error", {}).get("code", "UNKNOWN")
+            msg = f"AllDebrid upload failed: {code}"
+            _raise_runtime_error(msg)
+
+        entries = data.get("data", {}).get(entries_key, [])
+        if not entries:
+            msg = "AllDebrid accepted the upload but returned no torrent"
+            _raise_runtime_error(msg)
+
+        info = entries[0]
+        if info.get("error"):
+            code = info["error"].get("code", "UNKNOWN")
+            msg = f"AllDebrid rejected the torrent: {code}"
+            _raise_runtime_error(msg)
+
+        return info
+
    def get_status(self, download_id: str) -> DownloadStatus:
        """Poll AllDebrid for magnet status and drive the download."""
        state = self._ensure_state(download_id)
@@ -843,6 +843,9 @@ class ExternalClientHandler(DownloadHandler, ABC):
                            expected_hash=request.expected_hash,
                            seeding_time_limit=request.seeding_time_limit,
                            ratio_limit=request.ratio_limit,
+                            # rTorrent has no category concept, so its audiobook label
+                            # can only be chosen from the content type (#1235).
+                            content_type=task.content_type,
                        )
                    except Exception as e:
                        if not refresh_attempted:
@@ -45,6 +45,10 @@ _HASH_LENGTH_ED2K = 32
 _HTTP_STATUS_FORBIDDEN = HTTPStatus.FORBIDDEN
 _HTTP_STATUS_NOT_FOUND = HTTPStatus.NOT_FOUND
 _METADATA_DOWNLOAD_STATES = {"forcedMetaDL", "metaDL"}
+# How long add_download waits for magnet metadata before falling back to the info
+# hash it already knows, rather than holding the download queue on a thin swarm.
+_METADATA_WAIT_POLLS = 20
+_METADATA_WAIT_INTERVAL_SECONDS = 0.5
 _ONE_WEEK_IN_SECONDS = 604800


@@ -221,6 +225,9 @@ class QBittorrentClient(DownloadClient):
        self._category = config_text(config.get("QBITTORRENT_CATEGORY", "books"))
        self._download_dir = config_text(config.get("QBITTORRENT_DOWNLOAD_DIR", ""))
        self._tags = _normalize_tags(config.get("QBITTORRENT_TAG", []))
+        # download_id -> qBittorrent's current primary hash, for identities that no
+        # longer match it directly. See _resolve_torrent().
+        self._primary_hashes: dict[str, str] = {}

    @property
    def _can_reauthenticate(self) -> bool:
@@ -307,13 +314,31 @@ class QBittorrentClient(DownloadClient):
        params = {"category": category} if category else {}
        return self._request_torrent_info_records(params)

+    def _remember_primary_hash(self, download_id: str, torrent: SimpleNamespace) -> None:
+        """Note the primary hash a listing scan found, so later lookups skip the scan."""
+        torrent_hash = getattr(torrent, "hash", None)
+        if isinstance(torrent_hash, str) and torrent_hash:
+            self._primary_hashes[download_id.lower()] = torrent_hash.lower()
+
    def _resolve_torrent(
        self, download_id: str, category: str | None = None
    ) -> tuple[SimpleNamespace | None, str | None]:
-        """Resolve any known torrent identity to its current qBittorrent record."""
-        torrent, error = self._get_torrent_info(download_id)
-        if error or torrent:
-            return torrent, error
+        """Resolve any known torrent identity to its current qBittorrent record.
+
+        A hybrid torrent's primary hash switches from the v1 hash to the truncated v2
+        hash once metadata resolves, so a download tracked by its v1 hash misses the
+        `hashes=` lookup and falls through to a full listing. Since `get_status()`
+        polls every couple of seconds for the life of the download, remember the
+        primary hash a scan finds and try it first.
+        """
+        cached = self._primary_hashes.get(download_id.lower())
+        for candidate in (item for item in dict.fromkeys((cached, download_id)) if item):
+            torrent, error = self._get_torrent_info(candidate)
+            if error:
+                return None, error
+            if torrent:
+                self._remember_primary_hash(download_id, torrent)
+                return torrent, None

        categories = [candidate for candidate in (category, self._category) if candidate]
        for candidate in dict.fromkeys(categories):
@@ -325,18 +350,41 @@ class QBittorrentClient(DownloadClient):
                None,
            )
            if torrent:
+                self._remember_primary_hash(download_id, torrent)
                return torrent, None

        torrents, error = self._list_torrents_by_category(None)
        if error:
            return None, error
-        return (
-            next(
-                (item for item in torrents if _torrent_matches_download_id(item, download_id)),
-                None,
-            ),
+        torrent = next(
+            (item for item in torrents if _torrent_matches_download_id(item, download_id)),
            None,
        )
+        if torrent:
+            self._remember_primary_hash(download_id, torrent)
+        else:
+            # The torrent is gone; drop the note so a re-add is not looked up by a
+            # hash that no longer exists.
+            self._primary_hashes.pop(download_id.lower(), None)
+        return torrent, None
+
+    def _current_hash(self, download_id: str) -> str:
+        """qBittorrent's current primary hash for any identity we know the torrent by.
+
+        Falls back to the given ID when the torrent cannot be found, so callers
+        still address the hash they were handed and surface the client's error.
+        """
+        try:
+            torrent, error = self._resolve_torrent(download_id)
+        except _QBITTORRENT_CLIENT_ERRORS as e:
+            logger.debug("Could not resolve current hash for %s: %s", download_id, e)
+            return download_id
+        if error or not torrent:
+            return download_id
+        torrent_hash = getattr(torrent, "hash", None)
+        if isinstance(torrent_hash, str) and torrent_hash:
+            return torrent_hash
+        return download_id

    def _list_category_hashes(self, category: str | None) -> set[str] | None:
        """Snapshot the hashes qBittorrent currently reports for a category."""
@@ -495,9 +543,13 @@ class QBittorrentClient(DownloadClient):
                    message = f"{message} (torrent file fetch failed: {torrent_info.fetch_error})"
                _raise_runtime_error(message)

-            # Wait until qBittorrent has resolved magnet metadata so the returned
-            # hash is its stable primary torrent ID, which may differ from the v1 hash.
-            for _ in range(20):
+            # Prefer qBittorrent's primary torrent ID, which for hybrid torrents
+            # switches from the v1 hash to the truncated v2 hash once metadata
+            # resolves. A magnet with few peers can take minutes to fetch metadata,
+            # and the torrent is worth keeping in the meantime: every lookup goes
+            # through `_resolve_torrent`, which still matches the v1 hash against
+            # `infohash_v1` after the primary ID has changed.
+            for _ in range(_METADATA_WAIT_POLLS):
                torrent, error = self._resolve_torrent(expected_hash, category)
                if error:
                    logger.debug("qBittorrent add_download: %s", error)
@@ -506,17 +558,18 @@ class QBittorrentClient(DownloadClient):
                    if isinstance(torrent_hash, str) and torrent_hash:
                        logger.info("Added torrent: %s", torrent_hash)
                        return torrent_hash.lower()
-                time.sleep(0.5)
+                time.sleep(_METADATA_WAIT_INTERVAL_SECONDS)

-            _raise_runtime_error(
-                "Torrent metadata resolution was not confirmed within the visibility grace period "
-                f"(response={result_text})"
+            logger.info(
+                "Added torrent %s; metadata still pending after %.0fs, tracking it by info hash",
+                expected_hash,
+                _METADATA_WAIT_POLLS * _METADATA_WAIT_INTERVAL_SECONDS,
            )
        except _QBITTORRENT_CLIENT_ERRORS:
            logger.exception("qBittorrent add failed")
            raise
        else:
-            return expected_hash
+            return expected_hash.lower()

    def get_status(self, download_id: str) -> DownloadStatus:
        """Get torrent status by hash.
@@ -529,7 +582,7 @@ class QBittorrentClient(DownloadClient):

        """
        try:
-            torrent, error = self._get_torrent_info(download_id)
+            torrent, error = self._resolve_torrent(download_id)
            if error:
                return DownloadStatus.error(error)
            if not torrent:
@@ -613,7 +666,9 @@ class QBittorrentClient(DownloadClient):

        """
        try:
-            self._client.torrents_delete(torrent_hashes=download_id, delete_files=delete_files)
+            torrent_hash = self._current_hash(download_id)
+            self._client.torrents_delete(torrent_hashes=torrent_hash, delete_files=delete_files)
+            self._primary_hashes.pop(download_id.lower(), None)
            logger.info(
                "Removed torrent from qBittorrent: %s%s",
                download_id,
@@ -635,7 +690,7 @@ class QBittorrentClient(DownloadClient):
                    logger.debug("Could not create category '%s': %s", category, e)

            self._client.torrents_set_category(
-                torrent_hashes=download_id,
+                torrent_hashes=self._current_hash(download_id),
                category=category,
            )
            logger.info("Set qBittorrent category for %s to '%s'", download_id, category)
@@ -657,7 +712,7 @@ class QBittorrentClient(DownloadClient):
        - join `save_path` with the torrent's top-level directory
        """
        try:
-            torrent, error = self._get_torrent_info(download_id)
+            torrent, error = self._resolve_torrent(download_id)
            if error:
                logger.debug("qBittorrent get_download_path: %s", error)
                return None
@@ -758,6 +813,33 @@ class QBittorrentClient(DownloadClient):
            )
            return None

+    def _await_existing_torrent(
+        self, info_hash: str, category: str | None
+    ) -> tuple[str, DownloadStatus] | None:
+        """Report a torrent already in qBittorrent, waiting out magnet metadata first."""
+        for _ in range(_METADATA_WAIT_POLLS):
+            torrent, error = self._resolve_torrent(info_hash, category)
+            if error:
+                logger.debug("qBittorrent find_existing: %s", error)
+                return None
+            if not torrent:
+                return None
+            if getattr(torrent, "state", None) not in _METADATA_DOWNLOAD_STATES:
+                torrent_hash = getattr(torrent, "hash", None)
+                if isinstance(torrent_hash, str) and torrent_hash:
+                    torrent_hash = torrent_hash.lower()
+                    return (torrent_hash, self.get_status(torrent_hash))
+            time.sleep(_METADATA_WAIT_INTERVAL_SECONDS)
+
+        # Metadata is still pending, but the torrent is here and `add_download` keeps
+        # one in this state rather than giving up. Report it by info hash so the
+        # caller joins the download in progress instead of adding a duplicate.
+        logger.info(
+            "Existing torrent %s is still fetching metadata; joining it by info hash",
+            info_hash,
+        )
+        return (info_hash.lower(), self.get_status(info_hash))
+
    def find_existing(
        self, url: str, category: str | None = None
    ) -> tuple[str, DownloadStatus] | None:
@@ -767,21 +849,9 @@ class QBittorrentClient(DownloadClient):
            if not torrent_info.info_hash:
                return None

-            for _ in range(20):
-                torrent, error = self._resolve_torrent(torrent_info.info_hash, category)
-                if error:
-                    logger.debug("qBittorrent find_existing: %s", error)
-                    return None
-                if not torrent:
-                    return None
-                if getattr(torrent, "state", None) not in _METADATA_DOWNLOAD_STATES:
-                    torrent_hash = getattr(torrent, "hash", None)
-                    if isinstance(torrent_hash, str) and torrent_hash:
-                        torrent_hash = torrent_hash.lower()
-                        return (torrent_hash, self.get_status(torrent_hash))
-                time.sleep(0.5)
+            existing = self._await_existing_torrent(torrent_info.info_hash, category)
        except _QBITTORRENT_CLIENT_ERRORS as e:
            logger.debug("Error checking for existing torrent: %s", e)
            return None
        else:
-            return None
+            return existing
@@ -24,6 +24,11 @@ from shelfmark.download.clients import (
    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

@@ -75,6 +80,7 @@ _BOOK_EXTENSIONS = (
    ".m4b",
    ".mobi",
    ".mp3",
+    ".mp4",
    ".ogg",
    ".opus",
    ".pdf",
@@ -173,26 +179,19 @@ class RealDebridClient(DownloadClient):
        expected_hash: str | None = None,
        **kwargs: object,
    ) -> str:
-        """Upload a magnet link to Real-Debrid and select all files."""
+        """Send a torrent to Real-Debrid and select all files.
+
+        Accepts a magnet link, a .torrent URL, or an indexer proxy URL; anything
+        that is not already a magnet is resolved first, because Real-Debrid
+        answers a non-magnet body on addMagnet with a bare 404 (#1250).
+        """
        if not self._api_key:
            msg = "Real-Debrid API key is not configured"
            raise RuntimeError(msg)

-        magnet_link = url
-        if not magnet_link.startswith("magnet:") and expected_hash:
-            magnet_link = f"magnet:?xt=urn:btih:{expected_hash}"
-
-        add_url = f"{_API_BASE}/torrents/addMagnet"
        try:
-            resp = requests.post(
-                add_url,
-                headers=self._auth_headers(),
-                data={"magnet": magnet_link},
-                timeout=_API_TIMEOUT,
-                verify=get_ssl_verify(add_url),
-            )
-            resp.raise_for_status()
-            data = resp.json()
+            upload = resolve_debrid_upload(url, expected_hash=expected_hash)
+            data = self._send_torrent(upload)

            torrent_id = str(data.get("id", ""))
            if not torrent_id:
@@ -229,12 +228,41 @@ class RealDebridClient(DownloadClient):
            )

        except Exception:
-            logger.exception("Failed to upload magnet to Real-Debrid")
+            logger.exception("Failed to add torrent to Real-Debrid")
            raise

        else:
            return torrent_id

+    def _send_torrent(self, upload: DebridUpload) -> dict[str, Any]:
+        """Hand the torrent to Real-Debrid, as a magnet or as a file upload."""
+        if isinstance(upload, DebridMagnet):
+            add_url = f"{_API_BASE}/torrents/addMagnet"
+            resp = requests.post(
+                add_url,
+                headers=self._auth_headers(),
+                data={"magnet": upload.magnet_url},
+                timeout=_API_TIMEOUT,
+                verify=get_ssl_verify(add_url),
+            )
+        else:
+            # addTorrent is a PUT that takes the raw file as the request body,
+            # not a form field: https://api.real-debrid.com/
+            add_url = f"{_API_BASE}/torrents/addTorrent"
+            resp = requests.put(
+                add_url,
+                headers={
+                    **self._auth_headers(),
+                    "Content-Type": "application/x-bittorrent",
+                },
+                data=upload.torrent_data,
+                timeout=_API_TIMEOUT,
+                verify=get_ssl_verify(add_url),
+            )
+
+        resp.raise_for_status()
+        return resp.json()
+
    def get_status(self, download_id: str) -> DownloadStatus:
        """Poll Real-Debrid for torrent status and drive the download."""
        state = self._ensure_state(download_id)
@@ -11,7 +11,12 @@ from urllib.parse import urlparse

 from shelfmark.core.config import config
 from shelfmark.core.logger import setup_logger
-from shelfmark.core.utils import get_hardened_xmlrpc_client
+from shelfmark.core.utils import (
+    get_hardened_xmlrpc_client,
+)
+from shelfmark.core.utils import (
+    is_audiobook as check_audiobook,
+)
 from shelfmark.download.clients import (
    DownloadClient,
    DownloadStatus,
@@ -173,7 +178,8 @@ class RTorrentClient(DownloadClient):

            commands = []

-            is_audiobook = kwargs.get("content_type") == "audiobook"
+            content_type = kwargs.get("content_type")
+            is_audiobook = check_audiobook(content_type if isinstance(content_type, str) else None)
            default_label = (
                self._audiobook_label if is_audiobook and self._audiobook_label else self._label
            )
@@ -248,6 +248,15 @@ class SABnzbdClient(DownloadClient):
            if trusted_url and _url_origin(trusted_url) == target_origin:
                return True

+        named_indexers = config.get("NEWZNAB_INDEXERS", [])
+        if isinstance(named_indexers, list):
+            for row in named_indexers:
+                if not isinstance(row, dict):
+                    continue
+                trusted_url = normalize_http_config_url(row.get("url"))
+                if trusted_url and _url_origin(trusted_url) == target_origin:
+                    return True
+
        return False

    def _get_prowlarr_headers(self, url: str) -> dict:
@@ -17,6 +17,7 @@ from shelfmark.core.config import config
 from shelfmark.core.logger import setup_logger
 from shelfmark.core.utils import normalize_http_url
 from shelfmark.download.network import get_ssl_verify
+from shelfmark.download.postprocess.packs import PackFile

 logger = setup_logger(__name__)

@@ -82,6 +83,60 @@ class TorrentInfo:
        return self


+@dataclass
+class DebridMagnet:
+    """A magnet link, ready to hand to a debrid service as-is."""
+
+    magnet_url: str
+
+
+@dataclass
+class DebridTorrentFile:
+    """Raw .torrent bytes, for a debrid service's file-upload endpoint."""
+
+    torrent_data: bytes
+
+
+# A debrid service takes one or the other, never an indexer page or a proxy URL.
+type DebridUpload = DebridMagnet | DebridTorrentFile
+
+
+def resolve_debrid_upload(url: str, *, expected_hash: str | None = None) -> DebridUpload:
+    """Resolve a release download URL into a magnet link or .torrent bytes.
+
+    Prowlarr hands out a proxy URL, with no magnetUrl and no infoHash, for any
+    indexer that only publishes torrent files - 1337x among them. Posting that
+    URL to a debrid service as if it were a magnet is what produced a bare 404
+    from the service instead of a download (#1250).
+
+    The torrent file is preferred over a synthesized `urn:btih:` magnet because
+    it carries the tracker list, which is how the service finds a swarm that is
+    not already cached. Fetches are shared with the rest of the add path through
+    the torrent fetch cache, so resolving here costs at most one request.
+
+    Raises:
+        ValueError: The URL resolved to neither form, so there is nothing to send.
+
+    """
+    if url.startswith("magnet:"):
+        return DebridMagnet(magnet_url=url)
+
+    info = extract_torrent_info(url, expected_hash=expected_hash)
+
+    if info.is_magnet and info.magnet_url:
+        # The download URL redirected to, or returned, a magnet link.
+        return DebridMagnet(magnet_url=info.magnet_url)
+    if info.torrent_data:
+        return DebridTorrentFile(torrent_data=info.torrent_data)
+    if info.info_hash:
+        # No file to upload, but the hash alone still identifies the torrent.
+        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})"
+    raise ValueError(msg)
+
+
 def extract_torrent_info(
    url: str,
    *,
@@ -379,6 +434,56 @@ def extract_info_hash_from_torrent(torrent_data: bytes) -> str | None:
        return None


+def _decode_torrent_text(value: object) -> str | None:
+    if isinstance(value, bytes):
+        return value.decode("utf-8", errors="replace")
+    if isinstance(value, str):
+        return value
+    return None
+
+
+def extract_file_list_from_torrent(torrent_data: bytes) -> list[PackFile] | None:
+    """List the files a .torrent describes, release-relative, without downloading it.
+
+    Multi-file torrents nest every path under the torrent name (which becomes the
+    client's save folder); single-file torrents are just the named file.
+    """
+    try:
+        decoded, _ = bencode_decode(torrent_data)
+    except _TORRENT_PARSE_ERRORS as e:
+        logger.debug("Failed to parse torrent file list: %s", e)
+        return None
+    if not isinstance(decoded, dict):
+        return None
+    info = decoded.get(b"info")
+    if not isinstance(info, dict):
+        return None
+
+    name = _decode_torrent_text(info.get(b"name")) or ""
+    raw_files = info.get(b"files")
+    if not isinstance(raw_files, list):
+        length = info.get(b"length")
+        if not name:
+            return None
+        return [PackFile(name, length if isinstance(length, int) else None)]
+
+    files: list[PackFile] = []
+    for entry in raw_files:
+        if not isinstance(entry, dict):
+            continue
+        raw_path = entry.get(b"path")
+        if not isinstance(raw_path, list):
+            continue
+        segments = [seg for seg in (_decode_torrent_text(part) for part in raw_path) if seg]
+        if not segments:
+            continue
+        if name:
+            segments.insert(0, name)
+        length = entry.get(b"length")
+        files.append(PackFile("/".join(segments), length if isinstance(length, int) else None))
+    return files
+
+
 def extract_hash_from_magnet(magnet_url: str) -> str | None:
    """Extract info_hash from a magnet URL."""
    if not magnet_url.startswith("magnet:"):
@@ -5,12 +5,14 @@ import time
 from http import HTTPStatus
 from io import BytesIO
 from typing import TYPE_CHECKING, NoReturn
-from urllib.parse import urljoin, urlparse
+from urllib.parse import parse_qsl, urlencode, urljoin, urlparse, urlunparse

 import requests
 from tqdm import tqdm

-from shelfmark.bypass import BypassCancelledError
+from shelfmark.bypass import BypassCancelledError, ChallengeNotSolvedError, cookie_store
+from shelfmark.bypass.challenge import challenge_marker
+from shelfmark.core import search_deadline
 from shelfmark.core.config import config as app_config
 from shelfmark.core.logger import setup_logger
 from shelfmark.core.request_helpers import coerce_bool, normalize_positive_int
@@ -27,6 +29,10 @@ logger = setup_logger(__name__)
 _RNG = random.SystemRandom()

 _MAX_REDIRECTS = 5
+# DDoS-Guard's re-check probe. Its 302 to `?check=1` is one hop of a handshake rather
+# than a page: the parameter asserts the caller already holds the cookies that hop
+# issued.
+_DDG_CHECK_PARAM = "check"
 # Z-Library answers the first hit with a 503 whose only real payload is a Set-Cookie; echoing
 # that cookie back returns the 302 to the real page. Two attempts cover the handshake without
 # letting a server that keeps re-issuing cookies hold us in the loop.
@@ -46,11 +52,13 @@ _BYPASS_GRACE_SLACK_SECONDS = 30.0
 _BYPASSER_ERRORS = (
    AttributeError,
    BypassCancelledError,
+    ChallengeNotSolvedError,
    KeyError,
    OSError,
    RuntimeError,
    TypeError,
    ValueError,
+    network.RateLimitedError,
    requests.exceptions.RequestException,
 )

@@ -145,19 +153,13 @@ def get_bypassed_page(


 def get_cf_cookies_for_domain(domain: str) -> dict[str, str]:
-    """Get CF cookies - only available with internal bypasser."""
-    if _is_using_external_bypasser():
-        logger.debug("External bypasser in use, CF cookies not available for %s", domain)
-        return {}
-    return _get_internal_bypasser().get_cf_cookies_for_domain(domain)
+    """Get the clearance cookies won by whichever bypasser solved this domain."""
+    return cookie_store.get_cf_cookies_for_domain(domain)


 def get_cf_user_agent_for_domain(domain: str) -> str | None:
-    """Get CF user agent - only available with internal bypasser."""
-    if _is_using_external_bypasser():
-        logger.debug("External bypasser in use, CF user agent not available for %s", domain)
-        return None
-    return _get_internal_bypasser().get_cf_user_agent_for_domain(domain)
+    """Get the User-Agent that solved this domain's challenge, if one is stored."""
+    return cookie_store.get_cf_user_agent_for_domain(domain)


 def _apply_cf_bypass(url: str, headers: dict) -> dict:
@@ -239,6 +241,49 @@ def _is_retryable_error(e: Exception) -> bool:
 _DEAD_MIRROR_CODES = (410, 451)


+def _response_challenge_marker(response: requests.Response) -> str | None:
+    """The challenge marker in a response body, or None if it carries no challenge.
+
+    Content type is checked first so a JSON or octet-stream error body is never
+    decoded just to be scanned; a missing header is scanned anyway, since an
+    interstitial served without one is still an interstitial.
+    """
+    content_type = response.headers.get("Content-Type", "")
+    if content_type and "html" not in content_type.lower():
+        return None
+    try:
+        return challenge_marker(response.text)
+    except UnicodeDecodeError, ValueError:
+        return None
+
+
+def _solvable_url(url: str) -> str:
+    """The URL a solver should open, given one we may be mid-handshake on.
+
+    The manual AA redirect follower in `html_get_page` walks DDoS-Guard's handshake by
+    reassigning `current_url`, so by the time a 403, a 503 challenge or a redirect loop
+    hands that URL to a bypasser it is often the `?check=1` probe rather than the page
+    we actually wanted. A solver opens it in a fresh browser holding none of the cookies
+    the probe exists to collect, so DDoS-Guard cannot verify it automatically and answers
+    with the manual CAPTCHA page that nothing can solve - the failure in #1292, where
+    FlareSolverr reported "Challenge solved!" over a 4.7 KB DDOS-GUARD interstitial.
+
+    Handing over the pre-probe URL instead lets the solver's browser run the whole
+    handshake itself, which is what a real browser does and what the solver is for.
+
+    Scoped to the hosts whose redirects we follow manually: everywhere else `check` is
+    an ordinary query parameter and none of our business.
+    """
+    if not network.should_rotate_dns_for_url(url):
+        return url
+    parsed = urlparse(url)
+    params = parse_qsl(parsed.query, keep_blank_values=True)
+    kept = [(key, value) for key, value in params if key != _DDG_CHECK_PARAM]
+    if len(kept) == len(params):
+        return url
+    return urlunparse(parsed._replace(query=urlencode(kept)))
+
+
 def _fatal_mirror_reason(e: Exception) -> str | None:
    """Return why ``e`` proves the mirror is unusable, or None if it may recover.

@@ -322,11 +367,34 @@ def html_get_page(

    """

+    # Normalise before the closures below capture it: they touch selector.last_failure,
+    # so it must be a concrete selector, not the Optional parameter.
+    selector = selector or network.AAMirrorSelector()
+
+    # A release search runs under a wall-clock budget (see shelfmark.core.search_deadline).
+    # Adopting it as the cancel flag is what makes the budget bite on a solve already in
+    # flight: the bypassers and the helper subprocess poll this flag but know nothing about
+    # deadlines. Only when the caller has no flag of its own - a queued download brings one
+    # and must keep it, and runs outside any search context anyway.
+    if cancel_flag is None:
+        cancel_flag = search_deadline.cancel_event()
+
    def _result(html: str, response_url: str) -> str | tuple[str, str]:
        if include_response_url:
            return html, response_url
        return html

+    def _fail(reason: str, response_url: str) -> str | tuple[str, str]:
+        """Record why the fetch is giving up, then return the empty result.
+
+        Every give-up path returns an empty page, which is all the caller used to
+        see. Stashing the concrete reason on the shared selector lets the caller
+        surface it (see release_sources.direct_download) rather than reporting the
+        same generic "network restricted or mirrors blocked" for every cause.
+        """
+        selector.last_failure = reason
+        return _result("", response_url)
+
    def _run_bypasser(bypass_url: str) -> str | tuple[str, str]:
        """Run the active bypasser for one URL and return its result.

@@ -335,6 +403,16 @@ def html_get_page(
        retry-loop branch above with `continue`, and with MAX_RETRY=1 there is no
        later attempt for that branch to run on either.
        """
+        # Every handoff reaches the solver through here, so this is the one place the
+        # mid-handshake `?check=1` URL has to be unwound. See _solvable_url.
+        bypass_url = _solvable_url(bypass_url)
+        # Never start a minutes-long browser solve on a budget that has already run out:
+        # nothing downstream would get to report the real reason before the caller's
+        # deadline (or its reverse proxy) cut the request off.
+        if search_deadline.expired():
+            logger.info("Release search budget spent; not starting a bypass for %s", bypass_url)
+            return _fail(search_deadline.deadline_message(), bypass_url)
+
        if status_callback:
            status_callback("resolving", "Bypassing protection...")
        try:
@@ -344,7 +422,36 @@ def html_get_page(
            # bypasser that fails to load is still reported as a bypasser error.
            request_activity_grace(status_callback, _bypass_grace_seconds())
            result = get_bypassed_page(bypass_url, selector, cancel_flag)
-            return _result(result or "", bypass_url)
+            if result:
+                return _result(result, bypass_url)
+            return _fail(
+                "The protection bypasser returned an empty page — the challenge was "
+                "not solved. Check that FlareSolverr/the CF bypasser is reachable.",
+                bypass_url,
+            )
+        except network.RateLimitedError as e:
+            # Not a bypasser malfunction: the host is throttling this IP and a solve
+            # cannot help. Surface the wait as a plain failure so the search ends cleanly
+            # instead of looping another minutes-long solve against a 429.
+            logger.info("Skipping bypass (rate-limited): %s", e)
+            if status_callback:
+                try:
+                    status_callback("resolving", "Rate limited, try again shortly")
+                except _STATUS_CALLBACK_ERRORS:
+                    logger.debug("Rate-limit status callback failed", exc_info=True)
+            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
+            # generic handler below, whose "the protection bypasser failed" is what sent
+            # #1292 off to fix a FlareSolverr that was working perfectly.
+            logger.info("Bypass ran but did not clear the protection: %s", e)
+            if status_callback:
+                try:
+                    status_callback("error", str(e))
+                except _STATUS_CALLBACK_ERRORS:
+                    logger.debug("Unsolved-challenge status callback failed", exc_info=True)
+            return _fail(str(e), bypass_url)
        except _BYPASSER_ERRORS as e:
            logger.warning("Bypasser error: %s: %s", type(e).__name__, e)
            # Surface the real reason. Without this the caller only sees an empty
@@ -355,7 +462,13 @@ def html_get_page(
                    status_callback("error", f"Bypass failed: {type(e).__name__}: {e}")
                except _STATUS_CALLBACK_ERRORS:
                    logger.debug("Bypass error status callback failed", exc_info=True)
-            return _result("", bypass_url)
+            if isinstance(e, BypassCancelledError):
+                # The budget trips the same cancel flag a user's cancel does, so tell them
+                # apart here - "cancelled" is a confusing thing to read when nobody did.
+                if search_deadline.expired():
+                    return _fail(search_deadline.deadline_message(), bypass_url)
+                return _fail("The protection bypass was cancelled.", bypass_url)
+            return _fail(f"The protection bypasser failed: {type(e).__name__}: {e}", bypass_url)
        finally:
            release_activity_grace(status_callback)

@@ -369,39 +482,52 @@ def html_get_page(
        """
        return allow_bypasser_fallback and _is_cf_bypass_enabled() and not use_bypasser_now

+    def _purge_clearance(target_url: str) -> None:
+        """Drop the host's stored clearance cookies.
+
+        Called whenever the protection answered a request that *carried* cookies:
+        being challenged while presenting them proves they no longer work, so keeping
+        them only guarantees the same rejection on every later request. Applies to
+        either bypasser, since both fill the same store.
+        """
+        hostname = urlparse(target_url).hostname or ""
+        # An empty domain means "clear every host" to the store, so skip the purge
+        # rather than wipe clearance for sites that are working fine.
+        if hostname:
+            cookie_store.clear_cf_cookies(hostname)
+
    def _redirect_loop_handoff(bypass_url: str) -> str | tuple[str, str]:
        """Drop the host's stale clearance cookies, then bypass `bypass_url`.

        A `?check=1` loop is how DDoS-Guard answers a clearance cookie that has gone
        stale, so the dead cookie has to go before the solve — otherwise it is merged
-        back over the fresh one on the next request and the loop simply resumes. Purging
-        is internal-bypasser only; with an external one get_cf_cookies_for_domain()
-        already returns {}.
+        back over the fresh one on the next request and the loop simply resumes.
        """
-        hostname = urlparse(bypass_url).hostname or ""
-        # An empty domain means "clear every host" to the bypasser, so skip the purge
-        # rather than wipe clearance for sites that are working fine.
-        if hostname and not _is_using_external_bypasser():
-            _get_internal_bypasser().clear_cf_cookies(hostname)
+        _purge_clearance(bypass_url)
        return _run_bypasser(bypass_url)

    configured_retry = normalize_positive_int(app_config.MAX_RETRY)
    retry_limit = (
        retry if retry is not None else (configured_retry if configured_retry is not None else 1)
    )
-    selector = selector or network.AAMirrorSelector()
    original_url = url
    current_url = selector.rewrite(original_url)
    use_bypasser_now = use_bypasser
    # Survives across attempts so a cookie won once is still presented on later retries.
    handshake_cookies: dict[str, str] = {}
    handshake_retries = 0
+    # Last transport error seen, so the exhausted-retries path can name the real
+    # cause (timeout, connection refused, DNS, ...) instead of a generic message.
+    last_error: Exception | None = None

    for attempt in range(1, retry_limit + 1):
        # Check for cancellation before each attempt
        if cancel_flag and cancel_flag.is_set():
+            if search_deadline.expired():
+                logger.info("Release search budget spent before attempt %s", attempt)
+                return _fail(search_deadline.deadline_message(), current_url)
            logger.info("html_get_page cancelled before attempt %s", attempt)
-            return _result("", current_url)
+            return _fail("The request was cancelled.", current_url)

        cookies: dict[str, str] = {}
        try:
@@ -428,8 +554,15 @@ def html_get_page(
                    current_url,
                    proxies=get_proxies(current_url),
                    timeout=REQUEST_TIMEOUT,
-                    # Bypasser-derived cookies win: they came from a real solved challenge.
-                    cookies={**handshake_cookies, **cookies},
+                    # Handshake cookies win. They were issued by *this* exchange, so by
+                    # definition they are fresher than anything the store holds, and the
+                    # server is waiting to see them echoed back on the very next hop.
+                    # Letting the store overwrite them meant a stored cookie of the same
+                    # name (DDoS-Guard reuses __ddg1_/__ddg2_ for both) was replayed on
+                    # every hop and the freshly issued value never left this process - the
+                    # ?check=1 probe could then never terminate, so every request ended in
+                    # the redirect-loop handoff and paid for a full browser solve.
+                    cookies={**cookies, **handshake_cookies},
                    headers=headers,
                    allow_redirects=allow_redirects,
                    verify=get_ssl_verify(current_url),
@@ -453,6 +586,35 @@ def html_get_page(
                        )
                        continue

+                # A 503 still serving a challenge is protection, not a busy origin. The
+                # handshake above has nothing left to echo back, and 503 is in
+                # RETRYABLE_CODES, so without this the request spends every attempt on
+                # the same wall: the bypasser is only ever reached from the 403 branch
+                # and the AA redirect rescues. Gate on the body, not the status, so a
+                # genuine overloaded-origin 503 keeps its retry path.
+                if response.status_code == _HTTP_STATUS_SERVICE_UNAVAILABLE:
+                    marker = _response_challenge_marker(response)
+                    if marker and _bypass_handoff_allowed():
+                        if cookies:
+                            # Challenged while presenting clearance means those cookies
+                            # are dead; same reasoning as the 403 branch below.
+                            logger.debug(
+                                "503 challenge with cookies presented; purging: %s", current_url
+                            )
+                            _purge_clearance(current_url)
+                        logger.info(
+                            "503 challenge detected (%s); switching to bypasser: %s",
+                            marker,
+                            current_url,
+                        )
+                        return _run_bypasser(current_url)
+                    if marker:
+                        logger.debug(
+                            "503 challenge (%s) but no bypasser handoff available: %s",
+                            marker,
+                            current_url,
+                        )
+
                if is_aa_url and response.is_redirect:
                    location = response.headers.get("Location", "")
                    if not location:
@@ -474,7 +636,12 @@ def html_get_page(
                                redirect_host,
                                current_url,
                            )
-                            return _result("", current_url)
+                            return _fail(
+                                f"The configured mirror {current_host} redirected to "
+                                f"{redirect_host}; it may be down or seized. Point MIRROR at "
+                                "a working host or switch to auto mode.",
+                                current_url,
+                            )

                        new_url = _try_rotation(original_url, current_url, selector)
                        if new_url:
@@ -493,7 +660,11 @@ def html_get_page(
                            redirect_host,
                            current_url,
                        )
-                        return _result("", current_url)
+                        return _fail(
+                            "Every Anna's Archive mirror redirected away to a dead host — "
+                            "all configured mirrors are unreachable.",
+                            current_url,
+                        )

                    # Same-host redirect (relative or absolute) - follow manually.
                    # DDoS-Guard gates AA /search behind a cookie probe: the 302 to
@@ -524,7 +695,12 @@ def html_get_page(
                        logger.warning(
                            "Redirect loop and no bypasser available, giving up: %s", current_url
                        )
-                        return _result("", current_url)
+                        return _fail(
+                            "Anna's Archive is behind a protection challenge (endless "
+                            "redirect loop) and no bypasser is enabled to solve it. Enable "
+                            "FlareSolverr/the CF bypasser.",
+                            current_url,
+                        )
                    current_url = redirect_url
                    continue

@@ -534,6 +710,7 @@ def html_get_page(
                return _result(response.text, response.url)

        except Exception as e:
+            last_error = e
            status = _get_status_code(e)

            # The same DDoS-Guard rescue, for the loops the manual AA follower above hands
@@ -560,20 +737,35 @@ def html_get_page(
                        current_url = new_url
                        continue
                    logger.warning("403 error, mirrors exhausted: %s", current_url)
-                    return _result("", current_url)
+                    return _fail(
+                        "Anna's Archive returned 403 (blocked) and all mirrors are exhausted.",
+                        current_url,
+                    )

                if _is_cf_bypass_enabled() and not use_bypasser_now:
                    # Before switching to bypasser, check if cookies have become available
                    # (another concurrent download may have completed bypass and extracted cookies)
                    parsed = urlparse(current_url)
                    fresh_cookies = get_cf_cookies_for_domain(parsed.hostname or "")
-                    if fresh_cookies and not cookies:
-                        # Cookies are now available - retry with cookies before using bypasser
+                    if fresh_cookies and not cookies and attempt < retry_limit:
+                        # Cookies are now available - retry with cookies before using bypasser.
+                        # Guarded on there being a next attempt: `continue` on the last one
+                        # ends the retry loop and abandons the request without ever offering
+                        # the URL to the bypasser, and MAX_RETRY=1 is the supported setting.
+                        # Same reasoning as the bypasser invocation below.
                        logger.debug(
                            "403 but cookies now available - retrying with cookies: %s",
                            current_url,
                        )
                        continue
+                    if cookies:
+                        # Challenged *while presenting* clearance: those cookies are
+                        # dead. Without this they survive the solve and get merged back
+                        # over the fresh ones, so every later request re-presents a
+                        # known-rejected cookie and is challenged again - the stale
+                        # retry that never ends.
+                        logger.debug("403 with cookies presented; purging: %s", current_url)
+                        _purge_clearance(current_url)
                    logger.info("403 detected; switching to bypasser: %s", current_url)
                    # Invoke it here rather than setting use_bypasser_now and continuing.
                    # The branch that acts on that flag runs at the top of the *next* retry
@@ -582,12 +774,24 @@ def html_get_page(
                    # Same reasoning as the redirect-loop handoffs.
                    return _run_bypasser(current_url)
                logger.warning("403 error, giving up: %s", current_url)
-                return _result("", current_url)
+                return _fail(
+                    "Anna's Archive returned 403 (blocked) and no bypasser is enabled "
+                    "to solve the protection challenge.",
+                    current_url,
+                )

            # 404 = Not found
            if status == _HTTP_STATUS_NOT_FOUND:
                logger.warning("404 error: %s", current_url)
-                return _result("", current_url)
+                return _fail(
+                    f"Anna's Archive returned 404 Not Found for {current_url}.", current_url
+                )
+
+            # 429 = origin throttling this IP. Arm the per-host backoff so selection and
+            # the bypasser stop hammering it, then fall through to normal rotation onto a
+            # mirror that is not (yet) rate-limited.
+            if status == _HTTP_STATUS_RATE_LIMITED:
+                network.note_rate_limited(current_url)

            # Try mirror/DNS rotation on retryable errors. A failure that proves the
            # mirror is unusable also drops it from this process's rotation, so the
@@ -616,7 +820,16 @@ def html_get_page(
            else:
                logger.exception("Giving up after %s attempts: %s", retry_limit, current_url)

-    return _result("", current_url)
+    if last_error is not None:
+        return _fail(
+            f"Could not reach Anna's Archive after {retry_limit} attempt(s): "
+            f"{type(last_error).__name__}: {last_error}",
+            current_url,
+        )
+    return _fail(
+        "Could not reach Anna's Archive — all mirrors were exhausted without a usable response.",
+        current_url,
+    )


 def download_url(
@@ -733,6 +946,7 @@ def download_url(
            # Rate limited - skip to next source immediately
            # (waiting doesn't help with concurrent downloads hitting the same server)
            if status == _HTTP_STATUS_RATE_LIMITED:
+                network.note_rate_limited(current_url)
                logger.info("Rate limited (429) - trying next source")
                if status_callback:
                    status_callback("resolving", "Server busy, trying next")
@@ -3,12 +3,13 @@
 import fnmatch
 import ipaddress
 import socket
+import time
 import urllib.parse
 import urllib.request
 from datetime import UTC, datetime, timedelta
 from http import HTTPStatus
 from socket import AddressFamily, SocketKind
-from typing import TYPE_CHECKING, Any, cast
+from typing import TYPE_CHECKING, Any, NamedTuple, cast

 import dns.resolver
 import httpx
@@ -287,6 +288,108 @@ _dead_aa_urls: set[str] = set()
 _dead_aa_urls_lock = _RLock()


+# Per-host rate-limit backoff. A 429 is the origin throttling *this IP*, not a challenge:
+# a DDoS-Guard/Cloudflare solve still renders, so the bypass "succeeds" yet the cleared
+# request is rejected again and the throttle is only renewed. The single answer is to
+# wait, so a 429 sidelines the host for a growing window - mirror selection and the
+# bypasser both skip a cooling-down host until its deadline passes. The wait escalates
+# 2 -> 5 -> 10 -> 15 -> 30 minutes each time the host throttles us again *after* we
+# already waited a full window out; a host left clear for longer than the top step
+# starts the ladder over. Keyed by host so every mirror and source shares one view;
+# in-memory only, so a restart starts clean.
+_RATE_LIMIT_COOLDOWN_LADDER_SECONDS: tuple[float, ...] = (120.0, 300.0, 600.0, 900.0, 1800.0)
+# A host that has been clear this long is treated as a fresh episode: the next 429
+# restarts the ladder at 2 minutes rather than resuming the escalation.
+_RATE_LIMIT_RESET_AFTER_SECONDS = 1800.0
+
+
+class _Cooldown(NamedTuple):
+    """One host's active rate-limit window and how far up the ladder it has climbed."""
+
+    deadline: float  # time.monotonic() value at which the wait expires
+    level: int  # index into _RATE_LIMIT_COOLDOWN_LADDER_SECONDS
+
+
+_host_cooldowns: dict[str, _Cooldown] = {}
+_host_cooldowns_lock = _RLock()
+
+
+class RateLimitedError(Exception):
+    """Raised to abandon a request whose host is in a 429 cooldown.
+
+    Not a transport failure - nothing is wrong with the network, the origin is
+    throttling this IP and only time clears it. Callers surface it as a plain failure
+    rather than retrying or handing the URL to the bypasser.
+    """
+
+
+def _cooldown_key(url: str) -> str:
+    """Host a cooldown is keyed by; '' when the URL carries none."""
+    return (urllib.parse.urlparse(url).hostname or "").lower()
+
+
+def note_rate_limited(url: str) -> float:
+    """Escalate a host's 429 backoff and (re)arm its cooldown; return the wait applied.
+
+    The step advances only when a fresh 429 arrives *after* the previous window already
+    elapsed - i.e. we waited it out and the host throttled us again. A 429 that lands
+    while the host is still cooling is the same episode: it neither escalates the level
+    nor shortens the wait. See the ladder note above.
+    """
+    host = _cooldown_key(url)
+    if not host:
+        return 0.0
+    now = time.monotonic()
+    ladder = _RATE_LIMIT_COOLDOWN_LADDER_SECONDS
+    with _host_cooldowns_lock:
+        prev = _host_cooldowns.get(host)
+        if prev is not None and now < prev.deadline:
+            # Still inside the current window - same throttling episode, leave it be.
+            return prev.deadline - now
+        if prev is None or now - prev.deadline > _RATE_LIMIT_RESET_AFTER_SECONDS:
+            level = 0
+        else:
+            level = min(prev.level + 1, len(ladder) - 1)
+        wait = ladder[level]
+        _host_cooldowns[host] = _Cooldown(deadline=now + wait, level=level)
+    logger.info(
+        "Rate limited (429): backing off %s for %.0fs (step %d/%d)",
+        host,
+        wait,
+        level + 1,
+        len(ladder),
+    )
+    return wait
+
+
+def host_cooldown_remaining(url: str) -> float:
+    """Seconds left on a host's 429 cooldown; 0.0 when clear or expired.
+
+    Leaves an expired record in place: the ladder level it carries is what a later 429
+    escalates from (or resets, once the clear gap is long enough).
+    """
+    host = _cooldown_key(url)
+    if not host:
+        return 0.0
+    now = time.monotonic()
+    with _host_cooldowns_lock:
+        rec = _host_cooldowns.get(host)
+        if rec is None or rec.deadline <= now:
+            return 0.0
+        return rec.deadline - now
+
+
+def is_host_cooling_down(url: str) -> bool:
+    """True while ``url``'s host is inside its 429 cooldown window."""
+    return host_cooldown_remaining(url) > 0.0
+
+
+def clear_host_cooldowns() -> None:
+    """Forget all rate-limit cooldowns (manual reset / tests)."""
+    with _host_cooldowns_lock:
+        _host_cooldowns.clear()
+
+
 def _ensure_initialized() -> None:
    """Lazy guard so runtime setup happens once and late calls still work."""
    global _initialized
@@ -683,8 +786,6 @@ def create_custom_getaddrinfo(
            source: str,
            provider_label: str,
            res: Sequence[tuple[AddressFamily, SocketKind, int, str, tuple[Any, ...]]],
-            *,
-            is_bypass: bool = False,
        ) -> None:
            """Emit a unified resolver log with the IPs returned.

@@ -692,7 +793,6 @@ def create_custom_getaddrinfo(
                source: Description of resolver source
                provider_label: Label for the DNS provider
                res: Resolution results
-                is_bypass: If True, log at DEBUG level (for local/IP addresses)

            """
            # Skip logging entirely for localhost to reduce noise
@@ -708,11 +808,7 @@ def create_custom_getaddrinfo(
                ip = sockaddr[0]
                if isinstance(ip, str):
                    ips.append(ip)
-            msg = f"Resolved {host_str} via {source} [{provider_label}]: {ips}"
-            if is_bypass:
-                logger.debug(msg)
-            else:
-                logger.info(msg)
+            logger.debug("Resolved %s via %s [%s]: %s", host_str, source, provider_label, ips)

        # Skip custom resolution for IP addresses, local addresses, or if skip check passes
        if (
@@ -722,7 +818,7 @@ def create_custom_getaddrinfo(
        ):
            # Quietly bypass custom resolution for IP/local targets
            res = original_getaddrinfo(host, port, family, socket_type, proto, flags)
-            _log_results("system resolver (bypass)", "system", res, is_bypass=True)
+            _log_results("system resolver (bypass)", "system", res)
            return res

        results: list[tuple[AddressFamily, SocketKind, int, str, tuple[Any, ...]]] = []
@@ -1425,8 +1521,13 @@ def get_available_aa_urls() -> list[str]:
        if not alive and _aa_urls:
            logger.warning("All AA mirrors quarantined; retrying the full list")
            _dead_aa_urls.clear()
-            return _aa_urls.copy()
-    return alive
+            alive = _aa_urls.copy()
+    # Prefer mirrors that are not serving a 429 cooldown so rotation stops hammering a
+    # throttled host. When every live mirror is cooling, keep the full live list rather
+    # than returning nothing: selection must never be left with nowhere to point, and
+    # the bypasser's fail-fast reports the "all rate-limited" case with a clear error.
+    breathing = [url for url in alive if not is_host_cooling_down(url)]
+    return breathing or alive


 def _aa_base_for_url(url: str) -> str:
@@ -1493,6 +1594,11 @@ class AAMirrorSelector:

    def __init__(self) -> None:
        """Initialize mirror state from the current AA configuration."""
+        # Set by html_get_page at each give-up path so a caller that only sees the
+        # returned empty page can still report *why* the fetch produced nothing
+        # (403, 404, redirect loop, bypasser error, mirrors exhausted, ...) instead
+        # of a blanket "network restricted" guess. None means "no failure recorded".
+        self.last_failure: str | None = None
        self._ensure_fresh_state(reset_attempts=True)

    def _ensure_fresh_state(self, *, reset_attempts: bool = False) -> None:
@@ -265,6 +265,8 @@ def queue_release(
        series_position = release_data.get("series_position") or extra.get("series_position")
        subtitle = release_data.get("subtitle") or extra.get("subtitle")
        language = release_data.get("language") or extra.get("language")
+        multi_book = bool(release_data.get("multi_book") or extra.get("multi_book"))
+        book_plan = _normalize_book_plan(release_data.get("book_plan") or extra.get("book_plan"))

        books_output_mode = (
            str(config.get("BOOKS_OUTPUT_MODE", "folder", user_id=user_id) or "folder")
@@ -300,6 +302,8 @@ def queue_release(
            series_position=series_position,
            subtitle=subtitle,
            language=language,
+            multi_book=multi_book or book_plan is not None,
+            book_plan=book_plan,
            search_mode=search_mode,
            output_mode=output_mode,
            output_args=output_args,
@@ -408,6 +412,33 @@ def can_retry_download_task(
    return _has_staged_retry_source(task)


+def _normalize_book_plan(value: object) -> list[dict[str, Any]] | None:
+    """Keep only well-formed pack books: a title plus a non-empty list of file paths."""
+    if not isinstance(value, list):
+        return None
+    books: list[dict[str, Any]] = []
+    for entry in value:
+        if not isinstance(entry, dict):
+            continue
+        title = normalize_optional_text(entry.get("title"))
+        raw_files = entry.get("files")
+        if title is None or not isinstance(raw_files, list):
+            continue
+        files = [f for f in raw_files if isinstance(f, str) and f.strip()]
+        if not files:
+            continue
+        year = entry.get("year")
+        books.append(
+            {
+                "title": title,
+                "series_position": _optional_number(entry.get("series_position")),
+                "year": year if isinstance(year, int) and not isinstance(year, bool) else None,
+                "files": files,
+            }
+        )
+    return books or None
+
+
 def serialize_task_for_retry(task: DownloadTask) -> dict[str, Any]:
    """Serialize the task state needed for restart-safe retries."""
    raw_search_mode = getattr(task, "search_mode", None)
@@ -437,6 +468,8 @@ def serialize_task_for_retry(task: DownloadTask) -> dict[str, Any]:
        "subtitle": getattr(task, "subtitle", None),
        "language": getattr(task, "language", None),
        "search_mode": search_mode,
+        "multi_book": bool(getattr(task, "multi_book", False)),
+        "book_plan": _normalize_book_plan(getattr(task, "book_plan", None)),
        "output_mode": getattr(task, "output_mode", None),
        "output_args": dict(raw_output_args) if isinstance(raw_output_args, dict) else {},
        "user_id": getattr(task, "user_id", None),
@@ -495,6 +528,8 @@ def _restore_task_from_retry_payload(payload: object) -> DownloadTask | None:
        subtitle=normalize_optional_text(payload.get("subtitle")),
        language=normalize_optional_text(payload.get("language")),
        search_mode=search_mode,
+        multi_book=bool(payload.get("multi_book", False)),
+        book_plan=_normalize_book_plan(payload.get("book_plan")),
        output_mode=normalize_optional_text(payload.get("output_mode")),
        output_args=dict(output_args) if isinstance(output_args, dict) else {},
        user_id=normalize_positive_int(payload.get("user_id")),
@@ -105,6 +105,7 @@ def process_folder_output(
        maybe_run_custom_script,
        prepare_output_files,
        record_step,
+        resolve_book_groups,
        transfer_book_files,
    )

@@ -205,6 +206,7 @@ def process_folder_output(
        is_torrent=is_torrent,
        preserve_source=preserve_source,
        organization_mode=plan.organization_mode,
+        source_root=source_path,
    )

    if error:
@@ -259,7 +261,15 @@ def process_folder_output(
        prepared.cleanup_paths,
    )

-    message = "Complete" if len(final_paths) == 1 else f"Complete ({len(final_paths)} files)"
+    pack_groups = resolve_book_groups(
+        task, prepared.files, organization_mode=plan.organization_mode
+    )
+    if pack_groups is not None:
+        message = f"Complete ({len(pack_groups)} books, {len(final_paths)} files)"
+    elif len(final_paths) == 1:
+        message = "Complete"
+    else:
+        message = f"Complete ({len(final_paths)} files)"
    status_callback("complete", message)

    return str(final_paths[0])
@@ -0,0 +1,423 @@
+"""Multi-book ("pack") release planning.
+
+A pack is one release that contains several books: a whole-series torrent with one
+subfolder per book, or a flat folder of `Series 1.0 - Title.m4b` files. The same
+planning rules serve pre-download inspection (the file list comes from the release
+source) and post-processing (the file list comes from disk), so what the user
+approved in the modal is what gets filed.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass
+from pathlib import Path, PurePosixPath
+
+from shelfmark.core.utils import AUDIOBOOK_FORMATS
+
+# m4b/m4a hold a whole audiobook in one file; every other audio format (mp3, flac, ...) is
+# chaptered - many files make up one book. Ebook formats are always one file per book, so
+# only chaptered *audio* matters here. A flat folder is split one-book-per-file only when
+# none of its files are chaptered audio: a bare list of `01 - Chapter.mp3` tracks is a
+# single chaptered audiobook, not a pack of books.
+_SINGLE_FILE_AUDIO_CONTAINERS = frozenset({"m4b", "m4a"})
+_CHAPTERED_AUDIO_EXTENSIONS = frozenset(AUDIOBOOK_FORMATS) - _SINGLE_FILE_AUDIO_CONTAINERS
+
+_YEAR_SUFFIX_RE = re.compile(r"\s*\(\s*(?P<year>\d{4})\s*\)\s*$")
+_SERIES_MARKER_RE = re.compile(
+    r"""
+    ^\s*
+    (?:
+        \[\s*\#?(?P<bracket>\d+(?:\.\d+)?)\s*\]     # [03] / [#3]
+      | \#(?P<hash>\d+(?:\.\d+)?)                    # #3
+      | book\.?\s*(?P<book>\d+(?:\.\d+)?)            # Book 3 / Book. 03
+      | (?P<plain>\d+(?:\.\d+)?)(?=[\s\-:.])         # 03 - / 1.0 - / 3.
+    )
+    \s*(?:[-:.]\s*)?
+    """,
+    re.IGNORECASE | re.VERBOSE,
+)
+_SEPARATOR_CHARS = " \t-_:."
+# "Gods of Risk 2.5 - Gods of Risk": the title repeated on both sides of the position.
+_REPEATED_TITLE_RE = re.compile(
+    r"^(?P<left>.+?)\s+(?P<position>\d+(?:\.\d+)?)\s*[-:\u2013]\s*(?P<right>.+)$"
+)
+_SERIES_LABEL_WORDS = r"(?:novella|novellas|short\s+story|short|story|novel)"
+# "Uncrowned Cradle, Book 7" / "Reaper Cradle, Volume 10" / "Wintersteel (Cradle, Book 8)":
+# an explicit word marks the position at the END of the name. A bare trailing number
+# is deliberately not matched — "Title - 02" is a chapter, not a series position.
+_TRAILING_MARKER_RE = re.compile(
+    r"""
+    [\s,\-:\u2013(]*
+    (?:book|volume|vol\.?)\s*\#?(?P<position>\d+(?:\.\d+)?)
+    \s*\)?\s*$
+    """,
+    re.IGNORECASE | re.VERBOSE,
+)
+# AudiobookBay renders a file inside a folder as "<folder> <file>" with no separator,
+# so a pack row reads "Author - Title Series, Book 1 Title Series, Book 1".
+_GLUED_FOLDER_RE = re.compile(
+    r"^(?P<prefix>.+?\s[-\u2013]\s)?(?P<core>.+?)\s+(?P=core)$", re.IGNORECASE
+)
+
+
+@dataclass(frozen=True)
+class PackFile:
+    """One file inside a release, path relative to the release root."""
+
+    path: str
+    size: int | None = None
+
+
+@dataclass(frozen=True)
+class PackBook:
+    """One book split out of a pack, files as release-relative paths."""
+
+    title: str
+    series_position: float | None
+    year: int | None
+    files: list[str]
+
+
+@dataclass(frozen=True)
+class PackPlan:
+    books: list[PackBook]
+    ignored: list[str]
+
+    @property
+    def is_pack(self) -> bool:
+        return len(self.books) > 1
+
+
+@dataclass(frozen=True)
+class BookGroup:
+    """One book's on-disk files, ready for transfer."""
+
+    title: str
+    series_position: float | None
+    year: int | None
+    files: list[Path]
+
+
+def _strip_series_name(name: str, series_name: str | None) -> str:
+    if not series_name:
+        return name
+    prefix = series_name.strip()
+    if not prefix or not name.lower().startswith(prefix.lower()):
+        return name
+    remainder = name[len(prefix) :]
+    if remainder and remainder[0].isalnum():
+        return name
+    return remainder.lstrip(_SEPARATOR_CHARS)
+
+
+def _strip_series_label(work: str, series_name: str | None) -> str:
+    """Drop a leading "An <Series> Novella - " style label that some packs prepend."""
+    if not series_name:
+        return work
+    # "The Expanse" is labelled "An Expanse Novella", so match without the article.
+    core = re.sub(r"^(?:the|an?)\s+", "", series_name.strip(), flags=re.IGNORECASE)
+    if not core:
+        return work
+    pattern = re.compile(
+        rf"^(?:an?\s+|the\s+)?{re.escape(core)}\s+{_SERIES_LABEL_WORDS}\s*[-:\u2013]\s*",
+        re.IGNORECASE,
+    )
+    return pattern.sub("", work, count=1)
+
+
+def _collapse_glued_folder(name: str) -> str:
+    match = _GLUED_FOLDER_RE.match(name)
+    if not match:
+        return name
+    prefix = match.group("prefix") or ""
+    core = match.group("core")
+    # "Author - X X" → "Author - X" (the folder carried the author, the file did not).
+    return (prefix + core).strip()
+
+
+def _strip_author_name(name: str, author_name: str | None) -> str:
+    """Drop a leading "Author - " (packs are often filed as `Author - Title`)."""
+    if not author_name:
+        return name
+    prefix = author_name.strip()
+    if not prefix or not name.lower().startswith(prefix.lower()):
+        return name
+    remainder = name[len(prefix) :]
+    stripped = remainder.lstrip(_SEPARATOR_CHARS + "\u2013")
+    if stripped == remainder:  # no separator after the author: part of the title
+        return name
+    return stripped
+
+
+def _strip_trailing_series_name(work: str, series_name: str | None) -> str:
+    """Drop a trailing series name left behind by a trailing position marker."""
+    if not series_name:
+        return work
+    suffix = series_name.strip()
+    if not suffix or not work.lower().endswith(suffix.lower()):
+        return work
+    remainder = work[: -len(suffix)]
+    stripped = remainder.rstrip(_SEPARATOR_CHARS + ",(\u2013")
+    if not stripped or stripped == remainder:
+        return work
+    return stripped
+
+
+def parse_pack_book_name(
+    name: str, *, series_name: str | None, author_name: str | None = None
+) -> tuple[str, float | None, int | None]:
+    """Split a book folder/file-stem name into (title, series position, year).
+
+    Strips a leading series name, a leading position marker (`Book 3 - `, `03 - `,
+    `1.0 - `, `3. `, `[03] `, `#3 `) and a trailing `(YYYY)`. Also understands a
+    trailing marker (`Title Series, Book 3`, `Title (Series, Volume 3)`), a leading
+    `Author - `, and AudiobookBay's glued `<folder> <file>` names. Returns the name
+    unchanged with no position/year when nothing would be left of the title.
+    """
+    work = _collapse_glued_folder(name.strip())
+    work = _strip_author_name(work, author_name)
+    work = _strip_series_name(work, series_name)
+
+    year: int | None = None
+    year_match = _YEAR_SUFFIX_RE.search(work)
+    if year_match:
+        year = int(year_match.group("year"))
+        work = work[: year_match.start()]
+
+    position: float | None = None
+    repeated = _REPEATED_TITLE_RE.match(work.strip())
+    if (
+        repeated
+        and repeated.group("left").strip().lower() == repeated.group("right").strip().lower()
+    ):
+        return repeated.group("right").strip(), float(repeated.group("position")), year
+
+    marker = _SERIES_MARKER_RE.match(work)
+    if marker:
+        raw = (
+            marker.group("bracket")
+            or marker.group("hash")
+            or marker.group("book")
+            or marker.group("plain")
+        )
+        position = float(raw)
+        work = work[marker.end() :]
+    else:
+        trailing = _TRAILING_MARKER_RE.search(work)
+        if trailing and trailing.start() > 0:
+            position = float(trailing.group("position"))
+            work = _strip_trailing_series_name(work[: trailing.start()], series_name)
+
+    work = _strip_series_label(work, series_name)
+    title = work.strip().strip(_SEPARATOR_CHARS).strip()
+    if not title:
+        return name, None, None
+    return title, position, year
+
+
+def _book_from_name(
+    name: str, files: list[str], series_name: str | None, author_name: str | None = None
+) -> PackBook:
+    title, position, year = parse_pack_book_name(
+        name, series_name=series_name, author_name=author_name
+    )
+    return PackBook(title=title, series_position=position, year=year, files=files)
+
+
+def _common_root_parts(paths: list[PurePosixPath]) -> tuple[str, ...]:
+    parents = [p.parent.parts for p in paths]
+    common: list[str] = []
+    for parts in zip(*parents, strict=False):
+        if len(set(parts)) != 1:
+            break
+        common.append(parts[0])
+    return tuple(common)
+
+
+def plan_pack(
+    files: list[PackFile],
+    *,
+    supported_extensions: set[str],
+    series_name: str | None,
+    author_name: str | None = None,
+    root_depth: int | None = None,
+) -> PackPlan:
+    """Group a release's file list into books.
+
+    Files in a subfolder (relative to the common root) group by that subfolder. Files
+    directly in the root split one-book-per-file only when at least two of them carry
+    a series position in their names; otherwise they are one book (a chaptered
+    audiobook, e.g. `01.mp3`, `02.mp3`). `root_depth` fixes how many leading path
+    components form the root instead of deriving it from the files' common parent.
+    """
+    supported = {ext.lower().lstrip(".") for ext in supported_extensions}
+    book_files: list[PurePosixPath] = []
+    ignored: list[str] = []
+    for pack_file in files:
+        rel = PurePosixPath(pack_file.path.replace("\\", "/").lstrip("./"))
+        if rel.suffix.lower().lstrip(".") in supported:
+            book_files.append(rel)
+        else:
+            ignored.append(pack_file.path)
+
+    if not book_files:
+        return PackPlan(books=[], ignored=ignored)
+
+    root_parts = (
+        _common_root_parts(book_files) if root_depth is None else book_files[0].parts[:root_depth]
+    )
+    depth = len(root_parts)
+
+    root_files: list[PurePosixPath] = []
+    folders: dict[str, list[str]] = {}
+    for rel in book_files:
+        remainder = rel.parts[depth:]
+        if len(remainder) > 1:
+            folders.setdefault(remainder[0], []).append(str(rel))
+        else:
+            root_files.append(rel)
+
+    books: list[PackBook] = []
+    if root_files:
+        parsed = [
+            parse_pack_book_name(f.stem, series_name=series_name, author_name=author_name)
+            for f in root_files
+        ]
+        positions = {p[1] for p in parsed if p[1] is not None}
+        titles = {p[0].strip().lower() for p in parsed if p[0]}
+        one_book_per_file = all(
+            rel.suffix.lower().lstrip(".") not in _CHAPTERED_AUDIO_EXTENSIONS for rel in root_files
+        )
+        # Split a flat folder into a book per file only with real evidence of distinct
+        # books: two or more series positions, more than one title, and no chaptered audio
+        # (a bare list of `01 - Chapter.mp3` tracks is one book, not a pack).
+        if len(positions) >= 2 and len(titles) >= 2 and one_book_per_file:
+            books.extend(
+                PackBook(title=title, series_position=position, year=year, files=[str(f)])
+                for f, (title, position, year) in zip(root_files, parsed, strict=True)
+            )
+        elif len(root_files) == 1:
+            books.append(
+                _book_from_name(root_files[0].stem, [str(root_files[0])], series_name, author_name)
+            )
+        else:
+            group_name = root_parts[-1] if root_parts else ""
+            books.append(
+                _book_from_name(group_name, [str(f) for f in root_files], series_name, author_name)
+            )
+
+    books.extend(
+        _book_from_name(folder, paths, series_name, author_name)
+        for folder, paths in folders.items()
+    )
+    return PackPlan(books=books, ignored=ignored)
+
+
+def _relative_paths(
+    book_files: list[Path], root: Path | None = None
+) -> tuple[Path, dict[Path, str]]:
+    if root is None:
+        root = Path(os.path.commonpath([str(f.parent) for f in book_files]))
+    return root, {f: f.relative_to(root).as_posix() for f in book_files}
+
+
+def group_files_into_books(
+    book_files: list[Path],
+    *,
+    series_name: str | None,
+    author_name: str | None = None,
+    root: Path | None = None,
+) -> list[BookGroup]:
+    """Heuristically split on-disk files into books (see `plan_pack`).
+
+    `root` pins the release root when grouping a subset of a larger file set.
+    """
+    if not book_files:
+        return []
+    _root, rel_by_path = _relative_paths(book_files, root)
+    path_by_rel = {rel: path for path, rel in rel_by_path.items()}
+    extensions = {f.suffix.lower().lstrip(".") for f in book_files}
+    plan = plan_pack(
+        [PackFile(rel) for rel in rel_by_path.values()],
+        supported_extensions=extensions,
+        series_name=series_name,
+        author_name=author_name,
+        root_depth=None if root is None else 0,
+    )
+    return [
+        BookGroup(
+            title=book.title,
+            series_position=book.series_position,
+            year=book.year,
+            files=[path_by_rel[rel] for rel in book.files],
+        )
+        for book in plan.books
+    ]
+
+
+def match_plan_to_files(
+    plan: list[PackBook],
+    book_files: list[Path],
+    *,
+    series_name: str | None = None,
+    author_name: str | None = None,
+) -> list[BookGroup]:
+    """Apply an approved plan to on-disk files.
+
+    Files match by release-relative path first, then by basename (archive extraction
+    and client save paths can shift the root), then by the on-disk basename being a
+    suffix of the planned name (sources that glue folder and file names together).
+    Book files the plan does not mention fall back to heuristic grouping so nothing
+    is silently dropped.
+    """
+    if not book_files:
+        return []
+    root, rel_by_path = _relative_paths(book_files)
+    by_rel = {rel: path for path, rel in rel_by_path.items()}
+    by_name: dict[str, list[Path]] = {}
+    for path in book_files:
+        by_name.setdefault(path.name, []).append(path)
+
+    claimed: set[Path] = set()
+    groups: list[BookGroup] = []
+    for book in plan:
+        matched: list[Path] = []
+        for wanted in book.files:
+            wanted_rel = wanted.replace("\\", "/").lstrip("./")
+            candidate = by_rel.get(wanted_rel)
+            if candidate is None:
+                candidates = [
+                    p for p in by_name.get(PurePosixPath(wanted_rel).name, []) if p not in claimed
+                ]
+                candidate = candidates[0] if candidates else None
+            if candidate is None:
+                wanted_name = PurePosixPath(wanted_rel).name.lower()
+                candidates = [
+                    p
+                    for p in book_files
+                    if p not in claimed and wanted_name.endswith(p.name.lower())
+                ]
+                candidate = candidates[0] if len(candidates) == 1 else None
+            if candidate is not None and candidate not in claimed:
+                claimed.add(candidate)
+                matched.append(candidate)
+        if matched:
+            groups.append(
+                BookGroup(
+                    title=book.title,
+                    series_position=book.series_position,
+                    year=book.year,
+                    files=matched,
+                )
+            )
+
+    unmatched = [p for p in book_files if p not in claimed]
+    if unmatched:
+        groups.extend(
+            group_files_into_books(
+                unmatched, series_name=series_name, author_name=author_name, root=root
+            )
+        )
+    return groups
@@ -40,6 +40,7 @@ from .transfer import (
    build_metadata_dict,
    is_torrent_source,
    process_directory,
+    resolve_book_groups,
    resolve_hardlink_source,
    should_hardlink,
    transfer_book_files,
@@ -80,6 +81,7 @@ __all__ = [
    "process_directory",
    "record_step",
    "resolve_custom_script_target",
+    "resolve_book_groups",
    "resolve_hardlink_source",
    "run_custom_script",
    "safe_cleanup_path",
@@ -52,7 +52,7 @@ def get_file_organization(*, is_audiobook: bool) -> str:
    """Get the file organization mode for the content type."""
    key = "FILE_ORGANIZATION_AUDIOBOOK" if is_audiobook else "FILE_ORGANIZATION"
    mode = _config_text(core_config.config.get(key, "rename")).strip().lower()
-    return mode if mode in ("none", "rename", "organize") else "rename"
+    return mode if mode in ("none", "rename", "rename_and_group", "organize") else "rename"


 def get_template(*, is_audiobook: bool, organization_mode: str) -> str:
@@ -2,6 +2,7 @@

 from __future__ import annotations

+import dataclasses
 import os
 from pathlib import Path
 from typing import TYPE_CHECKING
@@ -17,6 +18,7 @@ from shelfmark.core.naming import (
    sanitize_filename,
 )
 from shelfmark.core.utils import is_audiobook as check_audiobook
+from shelfmark.download.archive import is_archive
 from shelfmark.download.fs import (
    atomic_copy,
    atomic_hardlink,
@@ -25,6 +27,7 @@ from shelfmark.download.fs import (
 )
 from shelfmark.download.postprocess.policy import get_file_organization, get_template

+from .packs import BookGroup, PackBook, group_files_into_books, match_plan_to_files
 from .scan import collect_directory_files, scan_directory_tree
 from .types import TransferPlan
 from .workspace import safe_cleanup_path
@@ -160,6 +163,24 @@ def _transfer_single_file(
    return atomic_move(source_path, dest_path, max_attempts=max_attempts), "move"


+def _group_folder_name(source_root: Path | None) -> str:
+    """Name the folder a grouped multi-file audiobook is transferred into.
+
+    A directory names the group directly. A file cannot hold several book files
+    on its own, so a non-directory source that produced more than one means
+    `collect_staged_files` extracted an archive: the stem is the release name and
+    the suffix is packaging, which is why `Book.zip` groups into `Book/` rather
+    than `Book.zip/` or, worse, not at all.
+    """
+    if source_root is None:
+        return ""
+    if run_blocking_io(source_root.is_dir):
+        return sanitize_filename(source_root.name)
+    if is_archive(source_root):
+        return sanitize_filename(source_root.stem)
+    return ""
+
+
 def transfer_book_files(
    book_files: list[Path],
    destination: Path,
@@ -169,6 +190,7 @@ def transfer_book_files(
    is_torrent: bool,
    preserve_source: bool = False,
    organization_mode: str | None = None,
+    source_root: Path | None = None,
 ) -> tuple[list[Path], str | None, dict[str, int]]:
    """Transfer discovered book files into their final destination layout."""
    if not book_files:
@@ -176,6 +198,19 @@ def transfer_book_files(

    is_audiobook = check_audiobook(task.content_type)
    organization_mode = organization_mode or get_file_organization(is_audiobook=is_audiobook)
+
+    groups = resolve_book_groups(task, book_files, organization_mode=organization_mode)
+    if groups is not None:
+        return _transfer_book_groups(
+            groups,
+            destination,
+            task,
+            use_hardlink=use_hardlink,
+            is_torrent=is_torrent,
+            preserve_source=preserve_source,
+            organization_mode=organization_mode,
+        )
+
    max_attempts = _max_attempts_for_batch(len(book_files))

    final_paths: list[Path] = []
@@ -238,6 +273,13 @@ def transfer_book_files(

        return final_paths, None, op_counts

+    transfer_destination = destination
+    if is_audiobook and len(book_files) > 1 and organization_mode == "rename_and_group":
+        source_folder = _group_folder_name(source_root)
+        if source_folder:
+            transfer_destination = destination / source_folder
+            run_blocking_io(transfer_destination.mkdir, parents=True, exist_ok=True)
+
    for book_file in book_files:
        if len(book_files) == 1 and organization_mode != "none":
            if not task.format:
@@ -256,7 +298,7 @@ def transfer_book_files(
        else:
            filename = book_file.name

-        dest_path = destination / filename
+        dest_path = transfer_destination / filename
        final_path, op = _transfer_single_file(
            book_file,
            dest_path,
@@ -272,6 +314,101 @@ def transfer_book_files(
    return final_paths, None, op_counts


+def resolve_book_groups(
+    task: DownloadTask,
+    book_files: list[Path],
+    *,
+    organization_mode: str,
+) -> list[BookGroup] | None:
+    """Split a multi-book pack into per-book groups, or None to file as one book.
+
+    An approved `book_plan` wins; a bare `multi_book` flag falls back to heuristic
+    grouping. Organization `none` keeps files as-is, and a split that yields a single
+    group is not a pack at all.
+    """
+    if organization_mode == "none" or not (task.book_plan or task.multi_book):
+        return None
+    if task.book_plan:
+        plan = [
+            PackBook(
+                title=str(entry.get("title") or ""),
+                series_position=entry.get("series_position"),
+                year=entry.get("year"),
+                files=list(entry.get("files") or []),
+            )
+            for entry in task.book_plan
+            if isinstance(entry, dict)
+        ]
+        groups = match_plan_to_files(
+            plan, book_files, series_name=task.series_name, author_name=task.author
+        )
+    else:
+        groups = group_files_into_books(
+            book_files, series_name=task.series_name, author_name=task.author
+        )
+    return groups if len(groups) > 1 else None
+
+
+def _transfer_book_groups(
+    groups: list[BookGroup],
+    destination: Path,
+    task: DownloadTask,
+    *,
+    use_hardlink: bool,
+    is_torrent: bool,
+    preserve_source: bool,
+    organization_mode: str,
+) -> tuple[list[Path], str | None, dict[str, int]]:
+    """Transfer each book of a pack through the normal single-book path.
+
+    Each book gets an isolated task copy (the single-file path mutates `task.format`)
+    carrying its own title, position and year; the searched book's position must not
+    leak onto its siblings, while author and series name apply to all of them.
+    """
+    all_paths: list[Path] = []
+    totals: dict[str, int] = {"hardlink": 0, "copy": 0, "move": 0}
+    errors: list[str] = []
+
+    for group in groups:
+        book_task = dataclasses.replace(
+            task,
+            title=group.title or task.title,
+            year=str(group.year) if group.year is not None else None,
+            subtitle=None,
+            series_position=group.series_position,
+            multi_book=False,
+            book_plan=None,
+        )
+        paths, error, op_counts = transfer_book_files(
+            group.files,
+            destination,
+            book_task,
+            use_hardlink=use_hardlink,
+            is_torrent=is_torrent,
+            preserve_source=preserve_source,
+            organization_mode=organization_mode,
+            source_root=group.files[0].parent,
+        )
+        for op, count in op_counts.items():
+            totals[op] = totals.get(op, 0) + count
+        if error:
+            errors.append(f"{group.title}: {error}")
+            logger.warning("Task %s: pack book %r failed: %s", task.task_id, group.title, error)
+            continue
+        all_paths.extend(paths)
+
+    if not all_paths:
+        return [], "; ".join(errors) or "No book files found", totals
+    if errors:
+        logger.warning(
+            "Task %s: pack filed with %d failed book(s): %s",
+            task.task_id,
+            len(errors),
+            "; ".join(errors),
+        )
+    return all_paths, None, totals
+
+
 def process_directory(
    directory: Path,
    ingest_dir: Path,
@@ -15,6 +15,7 @@ source that is down at boot must not affect startup or health.

 from __future__ import annotations

+import os
 import threading

 from shelfmark.core.config import config
@@ -31,6 +32,19 @@ _DEFAULT_QUERY = "The Great Gatsby"
 _warmup_thread: threading.Thread | None = None
 _warmup_lock = threading.Lock()

+# Set as soon as a real release search starts. The warm-up exists to pay the cold path
+# *before* the user does; once they have beaten it to the box there is nothing left to
+# pre-solve, and running anyway is actively harmful - the bypasser serializes on one
+# browser, so the warm-up's solve goes in front of the search the user is watching. In
+# the bundle on issue #1276 that cost a full minute of a 2m27s wait, on a container 16
+# seconds old, for a throwaway "The Great Gatsby" query nobody asked for.
+_user_search_seen = threading.Event()
+
+
+def note_user_search() -> None:
+    """Record that a real search has run, so a pending warm-up stands down."""
+    _user_search_seen.set()
+

 def _as_bool(value: object, *, default: bool) -> bool:
    """Coerce a config value that may arrive as a string, bool or None."""
@@ -43,13 +57,27 @@ def _as_bool(value: object, *, default: bool) -> bool:
    return bool(value)


+def _setting(key: str, default: object) -> object:
+    """Read a warm-up setting, preferring the deployment environment.
+
+    These keys are not in the settings registry, and ``config.get`` only consults the
+    environment for keys it knows about - so reading config alone silently ignored
+    SEARCH_WARMUP_ENABLED and always returned the default. Check os.environ first so
+    the documented switches actually work.
+    """
+    raw = os.environ.get(key)
+    if raw is not None and raw.strip():
+        return raw
+    return config.get(key, default)
+
+
 def is_enabled() -> bool:
    """Whether the boot-time warm-up search should run."""
-    if not _as_bool(config.get("SEARCH_WARMUP_ENABLED", True), default=True):
+    if not _as_bool(_setting("SEARCH_WARMUP_ENABLED", True), default=True):
        return False
    # Nothing to warm if the source is off, and no challenge to pre-solve without
    # the bypasser - a plain search is fast enough not to need this.
-    if not _as_bool(config.get("DIRECT_DOWNLOAD_ENABLED", True), default=True):
+    if not _as_bool(_setting("DIRECT_DOWNLOAD_ENABLED", True), default=True):
        logger.debug("Search warm-up skipped: direct download disabled")
        return False
    return True
@@ -57,7 +85,7 @@ def is_enabled() -> bool:

 def warmup_query() -> str:
    """The query used to warm the source."""
-    raw = config.get("SEARCH_WARMUP_QUERY", _DEFAULT_QUERY)
+    raw = _setting("SEARCH_WARMUP_QUERY", _DEFAULT_QUERY)
    query = str(raw).strip() if raw else ""
    return query or _DEFAULT_QUERY

@@ -70,6 +98,12 @@ def run_warmup() -> bool:
    """
    from shelfmark.core.mirrors import has_aa_mirror_configuration

+    # Checked here rather than only at schedule time: the delay is what this races with,
+    # so the user's first search usually lands *during* the wait, not before it.
+    if _user_search_seen.is_set():
+        logger.info("Search warm-up skipped: a real search got there first")
+        return False
+
    if not has_aa_mirror_configuration():
        logger.debug("Search warm-up skipped: no Anna's Archive mirrors configured")
        return False
@@ -42,6 +42,7 @@ from shelfmark.config.settings import (
    _SUPPORTED_BOOK_LANGUAGE,
    migrate_audiobook_format_settings,
 )
+from shelfmark.core import search_deadline
 from shelfmark.core.activity_view_state_service import ActivityViewStateService
 from shelfmark.core.auth_modes import (
    get_auth_check_admin_status,
@@ -62,6 +63,7 @@ from shelfmark.core.notifications import (
    notify_user,
 )
 from shelfmark.core.prefix_middleware import PrefixMiddleware
+from shelfmark.core.release_inspect_routes import register_release_inspect_routes
 from shelfmark.core.request_helpers import (
    coerce_bool,
    emit_ws_event,
@@ -1024,6 +1026,9 @@ def _serialize_release(release: Release) -> dict:
    return result


+register_release_inspect_routes(app, login_required)
+
+
@app.route("/api/releases/download", methods=["POST"])
@login_required
 def api_download_release() -> Response | tuple[Response, int]:
@@ -1150,7 +1155,7 @@ def api_config() -> Response | tuple[Response, int]:
            "build_version": BUILD_VERSION,
            "release_version": RELEASE_VERSION,
            "book_languages": _SUPPORTED_BOOK_LANGUAGE,
-            "default_language": app_config.BOOK_LANGUAGE,
+            "default_language": app_config.get("BOOK_LANGUAGE", ["en"], user_id=db_user_id),
            "supported_formats": app_config.SUPPORTED_FORMATS,
            "supported_audiobook_formats": app_config.SUPPORTED_AUDIOBOOK_FORMATS,
            "search_mode": search_mode,
@@ -1175,6 +1180,12 @@ def api_config() -> Response | tuple[Response, int]:
                [],
                user_id=db_user_id,
            ),
+            # The client must not give up before this budget does. `/api/releases`
+            # answers a spent budget with a message naming the real cause (a protection
+            # challenge nobody could solve); a browser that aborted first replaces it
+            # with a generic network/proxy error and RELEASE_SEARCH_TIMEOUT becomes a
+            # setting the user can raise with no visible effect. See issue #1285.
+            "release_search_timeout": search_deadline.budget_seconds(),
            "settings_enabled": _is_config_dir_writable(),
            "onboarding_complete": _get_onboarding_complete(),
            # Default sort orders
@@ -2840,6 +2851,7 @@ def api_releases() -> Response | tuple[Response, int]:
                    manual_query=query_text if source_query_filters is not None else manual_query,
                    indexers=indexers,
                    source_filters=source_query_filters,
+                    user_id=db_user_id,
                )

                if plan.source_filters is not None:
@@ -2892,6 +2904,8 @@ def api_releases() -> Response | tuple[Response, int]:
            if languages_param
            else None
        )
+        # Without an explicit filter the plan falls back to this user's default languages.
+        db_user_id = get_session_db_user_id(session)
        # Content type for audiobook vs ebook search
        content_type = request.args.get("content_type", "ebook").strip()

@@ -2939,6 +2953,10 @@ def api_releases() -> Response | tuple[Response, int]:
        elif provider == "manual":
            resolved_title = title_param or manual_query or "Manual Search"
            resolved_author = author_param or ""
+            # The release modal sends `authors.join(', ')` as `author`, so the commas here
+            # are joins between contributors, not part of one name. This split is the only
+            # place that knows that, so `search_author` comes from it rather than from the
+            # joined text - see issue #1252.
            authors = [a.strip() for a in resolved_author.split(",") if a.strip()]

            book = BookMetadata(
@@ -2947,7 +2965,7 @@ def api_releases() -> Response | tuple[Response, int]:
                provider_display_name="Manual Search",
                title=resolved_title,
                search_title=resolved_title,
-                search_author=resolved_author or None,
+                search_author=authors[0] if authors else None,
                authors=authors,
            )
        else:
@@ -2980,18 +2998,36 @@ def api_releases() -> Response | tuple[Response, int]:
            # Search only enabled sources
            sources_to_search = [src["name"] for src in list_available_sources() if src["enabled"]]

-        # Search each source for releases
+        # Search each source for releases.
+        #
+        # Under a wall-clock budget: this endpoint is synchronous, and the bypass path it
+        # can reach used to be allowed minutes per URL with nothing bounding the request
+        # as a whole. A search that ran into an unsolvable protection challenge therefore
+        # outlived every reverse proxy in front of it and surfaced to the user as
+        # "Server unavailable (504)" - a gateway timeout that blames their proxy for a
+        # challenge failure. The budget is shared across sources, so a stuck first source
+        # cannot spend the whole request on its own. See issue #1276.
        all_releases = []
        errors = []
        source_instances = {}  # Keep source instances for column config

-        for source_name in sources_to_search:
-            source, releases, error = _search_source_releases(source_name, book)
-            if source is not None:
-                source_instances[source_name] = source
-                all_releases.extend(releases)
-            if error is not None:
-                errors.append(error)
+        # A real search is under way, so a warm-up still sitting on its start-up delay
+        # should stand down rather than queue its throwaway solve in front of this one.
+        warmup.note_user_search()
+
+        with search_deadline.search_deadline():
+            for source_name in sources_to_search:
+                if search_deadline.expired():
+                    logger.warning("Release search budget spent; %s not searched", source_name)
+                    errors.append(f"{source_name}: {search_deadline.deadline_message()}")
+                    continue
+
+                source, releases, error = _search_source_releases(source_name, book)
+                if source is not None:
+                    source_instances[source_name] = source
+                    all_releases.extend(releases)
+                if error is not None:
+                    errors.append(error)

        # Convert Release objects to dicts
        releases_data = [_serialize_release(release) for release in all_releases]
@@ -48,6 +48,10 @@ HARDCOVER_PAGE_SIZE = 25  # Hardcover API returns max 25 results per page
 HARDCOVER_MIN_AUTHOR_PARTS = 2
 HARDCOVER_MIN_TYPEAHEAD_QUERY_LENGTH = 2
 HARDCOVER_MAX_SERIES_OPTIONS = 7
+# Hardcover hands out short opaque tokens now ("hc_pat_...") instead of the ~500 char
+# JWTs it used to, so the length floor only applies to keys without that prefix.
+HARDCOVER_API_KEY_PREFIX = "hc_pat_"
+HARDCOVER_BEARER_PREFIX_PATTERN = re.compile(r"^bearer\s+", re.IGNORECASE)
 HARDCOVER_API_KEY_MIN_LENGTH = 100
 HARDCOVER_LIST_URL_PATTERN = re.compile(
    r"^/(?:@([\w.-]+)/)?lists?/([\w-]+)/?$",
@@ -318,6 +322,7 @@ query SearchFieldOptions(
        fields: $fields,
        weights: $weights
    ) {
+        error
        results
    }
 }
@@ -536,13 +541,19 @@ SORT_MAPPING: dict[SortOrder, str] = {
    SortOrder.OLDEST: "release_year:asc",
 }

-# Mapping from abstract search type to Hardcover fields parameter
-SEARCH_TYPE_FIELDS: dict[SearchType, str] = {
-    SearchType.GENERAL: "title,isbns,series_names,author_names,alternative_titles",
-    SearchType.TITLE: "title,alternative_titles",
-    SearchType.AUTHOR: "author_names",
-    # ISBN is handled separately via search_by_isbn()
-}
+# `fields` becomes Typesense's `query_by`, but Hardcover keeps `num_typos` and
+# `query_by_weights` as fixed-length presets per query_type. Passing a different
+# number of fields than the preset expects makes Typesense reject the whole search,
+# complaining that the number of num_typos values does not match the number of
+# query_by fields. So a Book search may only ever narrow to *these five* names --
+# a shorter list is rejected outright rather than searched, and any weights sent
+# alongside must match one-for-one.
+# Weights only bias ranking: a field weighted 0 still matches, so `fields` can no
+# longer restrict which fields a Book query looks at.
+BOOK_SEARCH_FIELDS = "title,alternative_titles,author_names,series_names,isbns"
+BOOK_SEARCH_FIELD_COUNT = 5
+BOOK_TITLE_WEIGHTS = "5,1,0,0,0"
+BOOK_TITLE_AUTHOR_WEIGHTS = "5,1,3,0,0"

 SERIES_SEARCH_FIELDS = "name,books,author_name"
 SERIES_SEARCH_WEIGHTS = "2,1,1"
@@ -550,22 +561,28 @@ SERIES_SEARCH_SORT = "_text_match:desc,readers_count:desc"
 AUTHOR_SUGGESTION_FIELDS = "name,name_personal,alternate_names"
 AUTHOR_SUGGESTION_WEIGHTS = "4,3,2"
 AUTHOR_SUGGESTION_SORT = "_text_match:desc,books_count:desc"
-TITLE_SUGGESTION_FIELDS = "title,alternative_titles"
-TITLE_SUGGESTION_WEIGHTS = "5,2"
+TITLE_SUGGESTION_FIELDS = BOOK_SEARCH_FIELDS
+TITLE_SUGGESTION_WEIGHTS = "5,2,0,0,0"
 TITLE_SUGGESTION_SORT = "_text_match:desc,users_count:desc"

 # Hardcover forwards `sort` to Typesense's `sort_by` and rejects the whole search
 # if it does not like the value -- an unknown field, a bare field name with no
 # direction, more than three keys. A rejected search comes back as HTTP 200 with
 # no GraphQL errors and a null `results` body, which is otherwise indistinguishable
-# from "nothing matched". An empty sort is always accepted, so fall back to it and
-# keep the fallback sticky for a while rather than paying for a doomed request on
-# every search.
-SORT_FALLBACK = ""
+# from "nothing matched"; the reason only shows up in the sibling `error` field,
+# so every search asks for it. Dropping `sort` from the request is the one shape
+# Hardcover always accepts -- an empty string is a value like any other and has
+# been rejected too -- so retry that way and keep the fallback sticky for a while
+# rather than paying for a doomed request on every search.
 SORT_FALLBACK_TTL = 900.0
 _sort_fallback_until = 0.0


+def _without_sort(variables: dict[str, Any]) -> dict[str, Any]:
+    """Drop `sort` entirely so Hardcover applies its own default ordering."""
+    return {key: value for key, value in variables.items() if key != "sort"}
+
+
 def _search_payload_rejected(result: dict[str, Any] | None) -> bool:
    """Report whether Hardcover answered a search with a null results body.

@@ -580,6 +597,17 @@ def _search_payload_rejected(result: dict[str, Any] | None) -> bool:
    return root["results"] is None


+def _search_rejection_reason(result: dict[str, Any] | None) -> str:
+    """Return Hardcover's explanation for a rejected search, if it sent one."""
+    if not isinstance(result, dict):
+        return ""
+    root = result.get("search", result)
+    if not isinstance(root, dict):
+        return ""
+    error = root.get("error")
+    return error.strip() if isinstance(error, str) else ""
+
+
 def _combine_headline_description(headline: str | None, description: str | None) -> str | None:
    """Combine headline (tagline) and description into a single description."""
    if headline and description:
@@ -646,7 +674,7 @@ def _normalize_series_position(value: Any) -> float | None:
 def _normalize_hardcover_api_key(value: object) -> str:
    """Normalize Hardcover API keys, stripping copied auth-header prefixes."""
    normalized_value = normalize_optional_text(value) or ""
-    return normalized_value.removeprefix("Bearer ").strip()
+    return HARDCOVER_BEARER_PREFIX_PATTERN.sub("", normalized_value.strip()).strip()


 def _normalize_search_text(value: str) -> str:
@@ -1012,13 +1040,15 @@ class HardcoverProvider(MetadataProvider):
        """Build search query, fields, and weights based on provided values.

        Returns (query, fields, weights) tuple. Fields/weights are None for general search.
+        A narrowed search still sends all of BOOK_SEARCH_FIELDS -- Hardcover rejects a
+        shorter list outright -- and leans on the weights to rank the wanted field first.
        """
        if author and not title and not series:
            return author, None, None
        if title and not author and not series:
-            return title, "title,alternative_titles", "5,1"
+            return title, BOOK_SEARCH_FIELDS, BOOK_TITLE_WEIGHTS
        if author and title and not series:
-            return f"{title} {author}", "title,alternative_titles,author_names", "5,1,3"
+            return f"{title} {author}", BOOK_SEARCH_FIELDS, BOOK_TITLE_AUTHOR_WEIGHTS
        return default_query, None, None

    def _detect_list_url(self, query: str) -> tuple[str | None, str] | None:
@@ -2384,6 +2414,7 @@ class HardcoverProvider(MetadataProvider):
            graphql_query = """
            query SearchBooks($query: String!, $limit: Int!, $page: Int!, $sort: String, $fields: String, $weights: String) {
                search(query: $query, query_type: "Book", per_page: $limit, page: $page, sort: $sort, fields: $fields, weights: $weights) {
+                    error
                    results
                }
            }
@@ -2392,6 +2423,7 @@ class HardcoverProvider(MetadataProvider):
            graphql_query = """
            query SearchBooks($query: String!, $limit: Int!, $page: Int!, $sort: String) {
                search(query: $query, query_type: "Book", per_page: $limit, page: $page, sort: $sort) {
+                    error
                    results
                }
            }
@@ -2690,33 +2722,42 @@ class HardcoverProvider(MetadataProvider):

        sort = variables.get("sort")
        if sort and time.monotonic() < _sort_fallback_until:
-            variables = {**variables, "sort": SORT_FALLBACK}
+            variables = _without_sort(variables)
            sort = None

        result = self._execute_query(query, variables)
        if not _search_payload_rejected(result):
            return result

+        reason = _search_rejection_reason(result)
        if not sort:
            logger.error(
-                "Hardcover rejected this search (query_type=%s, fields=%s) and returned "
-                "no result body",
+                "Hardcover rejected this search (query_type=%s, fields=%s): %s",
                variables.get("queryType", "Book"),
                variables.get("fields"),
+                reason or "no error message",
+            )
+            return None
+
+        retry = self._execute_query(query, _without_sort(variables))
+        if _search_payload_rejected(retry):
+            # The sort was not the culprit, so leave sorting alone for other searches.
+            logger.error(
+                "Hardcover rejected this search (query_type=%s, fields=%s) with and without "
+                "a sort order: %s",
+                variables.get("queryType", "Book"),
+                variables.get("fields"),
+                _search_rejection_reason(retry) or reason or "no error message",
            )
            return None

        logger.warning(
-            "Hardcover rejected sort '%s'; retrying searches without a sort order for %ss",
+            "Hardcover rejected sort '%s' (%s); dropping the sort order from searches for %ss",
            sort,
+            reason or "no error message",
            int(SORT_FALLBACK_TTL),
        )
        _sort_fallback_until = time.monotonic() + SORT_FALLBACK_TTL
-
-        retry = self._execute_query(query, {**variables, "sort": SORT_FALLBACK})
-        if _search_payload_rejected(retry):
-            logger.error("Hardcover rejected this search even without a sort order")
-            return None
        return retry

    def _parse_search_result(self, item: dict) -> BookMetadata | None:
@@ -2982,12 +3023,13 @@ def _test_hardcover_connection(current_values: dict[str, Any] | None = None) ->
        _save_connected_user(None, None)
        return {"success": False, "message": "API key is required"}

-    if key_len < HARDCOVER_API_KEY_MIN_LENGTH:
+    is_prefixed_key = api_key.startswith(HARDCOVER_API_KEY_PREFIX)
+    if not is_prefixed_key and key_len < HARDCOVER_API_KEY_MIN_LENGTH:
        return {
            "success": False,
            "message": (
-                f"API key seems too short ({key_len} chars). "
-                f"Expected {HARDCOVER_API_KEY_MIN_LENGTH}+ chars."
+                f"API key seems too short ({key_len} chars). Expected a key starting "
+                f"with {HARDCOVER_API_KEY_PREFIX} or {HARDCOVER_API_KEY_MIN_LENGTH}+ chars."
            ),
        }

@@ -3094,7 +3136,7 @@ def hardcover_settings() -> list[SettingsField]:
        PasswordField(
            key="HARDCOVER_API_KEY",
            label="API Key",
-            description="Get your API key from hardcover.app/account/api",
+            description="Get your API key from hardcover.app/account/api (starts with hc_pat_)",
            required=True,
        ),
        ActionButton(
@@ -13,6 +13,7 @@ if TYPE_CHECKING:

    from shelfmark.core.models import DownloadTask
    from shelfmark.core.search_plan import ReleaseSearchPlan
+    from shelfmark.download.postprocess.packs import PackFile

 from shelfmark.metadata_providers import BookMetadata

@@ -400,6 +401,14 @@ class DownloadHandler(ABC):
        """Return private queue-time fields needed for restart-safe retry."""
        return {}

+    def list_files(self, release_data: dict[str, Any]) -> list[PackFile] | None:
+        """Return the release's file list without downloading it.
+
+        Lets the UI review a multi-book pack before queueing. Return None when the
+        source cannot know the files ahead of time (magnet links, usenet, ...).
+        """
+        return None
+
    @abstractmethod
    def cancel(self, task_id: str) -> bool:
        """Cancel an in-progress download."""
@@ -510,6 +519,10 @@ def browse_record_to_book_metadata(
    """Convert a source-native browse record into generic book metadata."""
    resolved_title = title_override or str(record.title or "").strip() or "Unknown title"
    resolved_author = author_override or str(record.author or "").strip()
+    # `author_override` is the frontend's display string, `authors.join(', ')` - every
+    # contributor, translators included. The split below is the only place that knows the
+    # commas were joins rather than part of a name, so `search_author` is taken from it
+    # rather than from the joined text. See issue #1252.
    authors = [part.strip() for part in resolved_author.split(",") if part.strip()]
    publish_year = None

@@ -526,7 +539,7 @@ def browse_record_to_book_metadata(
        provider_display_name=get_source_display_name(record.source),
        title=resolved_title,
        search_title=resolved_title,
-        search_author=resolved_author or None,
+        search_author=authors[0] if authors else None,
        authors=authors,
        cover_url=record.preview,
        description=record.description,
@@ -1,6 +1,6 @@
 """AudiobookBay download handler - resolves magnet links and uses shared client lifecycle."""

-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
 from urllib.parse import urlparse

 from shelfmark.core.config import config
@@ -22,6 +22,7 @@ if TYPE_CHECKING:
    from collections.abc import Callable

    from shelfmark.core.models import DownloadTask
+    from shelfmark.download.postprocess.packs import PackFile

 logger = setup_logger(__name__)
 DEFAULT_ABB_HOSTNAME = "audiobookbay.lu"
@@ -68,6 +69,19 @@ class AudiobookBayHandler(ExternalClientHandler):
            return task_id
        return None

+    def list_files(self, release_data: dict[str, Any]) -> list[PackFile] | None:
+        """Read the torrent's file list off the detail page, without downloading."""
+        raw_url = release_data.get("download_url") or release_data.get("source_url")
+        detail_url = raw_url.strip() if isinstance(raw_url, str) else ""
+        hostname = _resolve_allowed_detail_hostname()
+        if not detail_url or not _detail_url_matches_host(detail_url, hostname):
+            logger.debug("Cannot list files for AudiobookBay release without a valid detail URL")
+            return None
+        detail_html = scraper.fetch_detail_html(detail_url, hostname)
+        if not detail_html:
+            return None
+        return scraper.extract_file_list(detail_html)
+
    def _get_client(self, protocol: str) -> DownloadClient | None:
        """Compatibility shim so module-level patching still works in tests."""
        return get_client(protocol)
@@ -2,7 +2,8 @@

 import re
 import time
-from urllib.parse import quote
+from threading import Lock
+from urllib.parse import quote, quote_plus

 import requests
 from bs4 import BeautifulSoup
@@ -10,6 +11,8 @@ from bs4 import BeautifulSoup
 from shelfmark.core.config import config
 from shelfmark.core.logger import setup_logger
 from shelfmark.download import http as downloader
+from shelfmark.download.postprocess.packs import PackFile
+from shelfmark.release_sources.audiobookbay.utils import normalize_search_punctuation

 logger = setup_logger(__name__)

@@ -31,6 +34,13 @@ FIRST_PAGE_SESSION_REFRESH_ATTEMPTS = 2
 # Legacy search parameter used by older ABB flows
 LEGACY_CATEGORY_QUERY = "undefined%2Cundefined"

+# Detail pages are fetched once and shared by inspection (file list) and download
+# (magnet link) so a "review then download" round trip costs ABB a single request.
+DETAIL_PAGE_CACHE_TTL_SECONDS = 120.0
+DETAIL_PAGE_CACHE_MAX_ENTRIES = 8
+_detail_page_cache: dict[str, tuple[float, str]] = {}
+_detail_page_cache_lock = Lock()
+
 # Precompiled patterns used while parsing result cards
 LANGUAGE_PATTERN = re.compile(r"Language:\s*([A-Za-z]+)")
 POSTED_PATTERN = re.compile(r"Posted:\s*(\d+\s+[A-Za-z]+\s+\d{4})")
@@ -38,6 +48,11 @@ FORMAT_PATTERN = re.compile(r"Format:\s*([A-Za-z0-9]+)")
 BITRATE_PATTERN = re.compile(r"Bitrate:\s*([\d]+\s*[A-Za-z/]+)")
 SIZE_PATTERN = re.compile(r"File Size:\s*([\d.]+)\s*([A-Za-z]+)")
 INFO_HASH_LABEL_PATTERN = re.compile(r"Info Hash", re.IGNORECASE)
+FILE_ROW_SIZE_PATTERN = re.compile(
+    r"^(?P<name>.+?)\s+(?P<size>\d+(?:\.\d+)?)\s*(?P<unit>Bytes?|KBs?|MBs?|GBs?|TBs?)$",
+    re.IGNORECASE,
+)
+_FILE_SIZE_MULTIPLIERS = {"b": 1, "k": 1024, "m": 1024**2, "g": 1024**3, "t": 1024**4}


 def _coerce_non_negative_float(value: object, default: float) -> float:
@@ -98,8 +113,10 @@ def _encode_search_query(query: str, *, exact_phrase: bool) -> str:
        and not (search_query.startswith('"') and search_query.endswith('"'))
    ):
        search_query = f'"{search_query}"'
-    # Keep ABB-friendly encoding style (spaces as '+') while percent-encoding quotes.
-    return search_query.replace('"', "%22").replace(" ", "+")
+    # Keep ABB's space-as-'+' style, but percent-encode everything else: a bare
+    # '&' would otherwise start a new query parameter, '%' would open an invalid
+    # escape, and a literal '+' would arrive as a space.
+    return quote_plus(search_query)


 def _normalize_result_url(url: str, hostname: str) -> str:
@@ -153,6 +170,9 @@ def search_audiobookbay(

    """
    results = []
+    # ABB matches the stored, untexturized title, so a curly apostrophe reaching
+    # the search returns nothing at all rather than merely ranking worse.
+    query = normalize_search_punctuation(query)
    rate_limit_delay = _coerce_non_negative_float(config.get("ABB_RATE_LIMIT_DELAY", 1.0), 1.0)
    session = requests.Session()

@@ -342,6 +362,98 @@ def search_audiobookbay(
    return results


+def _get_cached_detail_page(details_url: str) -> str | None:
+    with _detail_page_cache_lock:
+        entry = _detail_page_cache.get(details_url)
+        if entry is None:
+            return None
+        fetched_at, html = entry
+        if time.monotonic() - fetched_at > DETAIL_PAGE_CACHE_TTL_SECONDS:
+            del _detail_page_cache[details_url]
+            return None
+    return html
+
+
+def _store_cached_detail_page(details_url: str, html: str) -> None:
+    with _detail_page_cache_lock:
+        _detail_page_cache[details_url] = (time.monotonic(), html)
+        while len(_detail_page_cache) > DETAIL_PAGE_CACHE_MAX_ENTRIES:
+            oldest = min(_detail_page_cache, key=lambda key: _detail_page_cache[key][0])
+            del _detail_page_cache[oldest]
+
+
+def clear_detail_page_cache() -> None:
+    """Drop cached detail pages (used by tests)."""
+    with _detail_page_cache_lock:
+        _detail_page_cache.clear()
+
+
+def _fetch_detail_page_once(details_url: str, hostname: str) -> str:
+    session = requests.Session()
+    _bootstrap_abb_session(hostname, session, DETAIL_PAGE_RETRY_ATTEMPTS)
+    return _coerce_markup_to_html(
+        downloader.html_get_page(
+            details_url,
+            retry=DETAIL_PAGE_RETRY_ATTEMPTS,
+            use_bypasser=False,
+            allow_bypasser_fallback=False,
+            success_delay=0,
+            session=session,
+        )
+    )
+
+
+def fetch_detail_html(details_url: str, hostname: str = "audiobookbay.lu") -> str:
+    """Fetch a detail page (one retry with a fresh session), cached briefly per URL."""
+    cached = _get_cached_detail_page(details_url)
+    if cached is not None:
+        logger.debug("Reusing recently fetched detail page: %s", details_url)
+        return cached
+    detail_html = _fetch_detail_page_once(details_url, hostname)
+    if not detail_html:
+        detail_html = _fetch_detail_page_once(details_url, hostname)
+    if detail_html:
+        _store_cached_detail_page(details_url, detail_html)
+    return detail_html
+
+
+def _parse_file_row(text: str) -> PackFile | None:
+    match = FILE_ROW_SIZE_PATTERN.match(text.strip())
+    if not match:
+        return None
+    multiplier = _FILE_SIZE_MULTIPLIERS[match.group("unit")[0].lower()]
+    return PackFile(match.group("name"), int(float(match.group("size")) * multiplier))
+
+
+def extract_file_list(detail_html: str) -> list[PackFile] | None:
+    """Read the torrent file rows off a detail page.
+
+    ABB renders the torrent's file table as single-cell rows between the
+    "This is a Multifile Torrent" marker (absent for single-file torrents) and the
+    "Combined File Size" row. Returns None when the page has no such table.
+    """
+    soup = BeautifulSoup(detail_html, "html.parser")
+    rows: list[PackFile] = []
+    for row in soup.find_all("tr"):
+        cells = row.find_all("td")
+        if not cells:
+            continue
+        label = cells[0].get_text(" ", strip=True)
+        if label.lower().startswith("combined file size"):
+            return rows or None
+        if len(cells) != 1:
+            rows = []  # a two-column metadata row means we're not in the file table yet
+            continue
+        text = cells[0].get_text(" ", strip=True)
+        if "multifile torrent" in text.lower():
+            rows = []
+            continue
+        parsed = _parse_file_row(text)
+        if parsed is not None:
+            rows.append(parsed)
+    return None
+
+
 def extract_magnet_link(details_url: str, hostname: str = "audiobookbay.lu") -> str | None:
    """Extract info hash and trackers from book detail page, then construct magnet link.

@@ -354,35 +466,7 @@ def extract_magnet_link(details_url: str, hostname: str = "audiobookbay.lu") ->

    """
    try:
-        session = requests.Session()
-        _bootstrap_abb_session(hostname, session, DETAIL_PAGE_RETRY_ATTEMPTS)
-
-        # Fetch detail page
-        detail_html = _coerce_markup_to_html(
-            downloader.html_get_page(
-                details_url,
-                retry=DETAIL_PAGE_RETRY_ATTEMPTS,
-                use_bypasser=False,
-                allow_bypasser_fallback=False,
-                success_delay=0,
-                session=session,
-            )
-        )
-
-        if not detail_html:
-            session = requests.Session()
-            _bootstrap_abb_session(hostname, session, DETAIL_PAGE_RETRY_ATTEMPTS)
-            detail_html = _coerce_markup_to_html(
-                downloader.html_get_page(
-                    details_url,
-                    retry=DETAIL_PAGE_RETRY_ATTEMPTS,
-                    use_bypasser=False,
-                    allow_bypasser_fallback=False,
-                    success_delay=0,
-                    session=session,
-                )
-            )
-
+        detail_html = fetch_detail_html(details_url, hostname)
        if not detail_html:
            logger.warning("Failed to fetch details page")
            return None
@@ -23,7 +23,11 @@ from shelfmark.release_sources import (
    register_source,
 )
 from shelfmark.release_sources.audiobookbay import scraper
-from shelfmark.release_sources.audiobookbay.utils import normalize_hostname, parse_size
+from shelfmark.release_sources.audiobookbay.utils import (
+    normalize_hostname,
+    normalize_search_punctuation,
+    parse_size,
+)

 logger = setup_logger(__name__)
 MIN_RELEVANCE_QUERY_WORD_LENGTH = 2
@@ -227,10 +231,12 @@ class AudiobookBaySource(ReleaseSource):
                        deduped_queries[index + 1].lower(),
                    )

-            # Extract query words for relevance checking
+            # Extract query words for relevance checking. Both sides of the
+            # comparison are punctuation-normalized: scraped titles carry the
+            # typographic forms WordPress renders, queries carry the ASCII ones.
            query_words = {
                word.lower()
-                for word in query_lower.split()
+                for word in normalize_search_punctuation(query_lower).split()
                if len(word) > MIN_RELEVANCE_QUERY_WORD_LENGTH
            }

@@ -239,7 +245,7 @@ class AudiobookBaySource(ReleaseSource):
                try:
                    raw_title = result["title"]
                    title, author = _split_title_and_author(raw_title)
-                    title_for_filter = raw_title.lower()
+                    title_for_filter = normalize_search_punctuation(raw_title).lower()

                    # Basic relevance check: ensure title contains at least one query word
                    # This filters out homepage "Latest" feed items that may leak through
@@ -2,6 +2,63 @@

 import re

+# WordPress texturizes punctuation on output only: a post stored as "The
+# Stranger's Wife" is rendered as "The Stranger’s Wife". ABB's search matches the
+# stored value, so a query carrying the typographic form matches nothing -- and
+# because ABB ANDs its search terms, one such term empties the entire result set.
+# Book metadata and phone keyboards both hand us the typographic forms, so map
+# them back before they reach a search or a title comparison.
+_ASCII_PUNCTUATION = str.maketrans(
+    {
+        # Single quotes
+        "‘": "'",  # left single quotation mark
+        "’": "'",  # right single quotation mark
+        "‚": "'",  # single low-9 quotation mark
+        "‛": "'",  # single high-reversed-9 quotation mark
+        "′": "'",  # prime
+        "´": "'",  # acute accent
+        "`": "'",  # grave accent
+        # Double quotes
+        "“": '"',  # left double quotation mark
+        "”": '"',  # right double quotation mark
+        "„": '"',  # double low-9 quotation mark
+        "‟": '"',  # double high-reversed-9 quotation mark
+        "″": '"',  # double prime
+        # Dashes
+        "‐": "-",  # hyphen
+        "‑": "-",  # non-breaking hyphen
+        "‒": "-",  # figure dash
+        "–": "-",  # en dash
+        "—": "-",  # em dash
+        "―": "-",  # horizontal bar
+        "−": "-",  # minus sign
+        "﹘": "-",  # small em dash
+        "﹣": "-",  # small hyphen-minus
+        "－": "-",  # fullwidth hyphen-minus
+        # Ellipsis
+        "…": "...",  # horizontal ellipsis
+    }
+)
+
+
+def normalize_search_punctuation(text: str) -> str:
+    """Replace typographic punctuation with the ASCII forms ABB stores.
+
+    Each character is mapped individually rather than collapsing runs, so an
+    ASCII "--" is left alone: only characters ABB cannot have stored are
+    rewritten.
+
+    Args:
+        text: A search query, or a scraped title being compared against one.
+
+    Returns:
+        The text with curly quotes, dashes and ellipses mapped to ASCII.
+
+    """
+    if not text:
+        return text
+    return text.translate(_ASCII_PUNCTUATION)
+

 def normalize_hostname(raw: str | None) -> str:
    """Normalize a user-supplied hostname for URL construction.
@@ -6,6 +6,8 @@ import re
 import threading
 import time
 import unicodedata
+from contextlib import contextmanager
+from contextvars import ContextVar
 from dataclasses import replace
 from http import HTTPStatus
 from pathlib import Path
@@ -16,7 +18,9 @@ import requests
 from bs4 import BeautifulSoup, Tag
 from bs4.element import NavigableString

+from shelfmark.bypass.challenge import MAX_CHALLENGE_HTML_CHARS, challenge_marker
 from shelfmark.config.env import DEBUG_SKIP_SOURCES, TMP_DIR
+from shelfmark.core import search_deadline
 from shelfmark.core.config import config
 from shelfmark.core.languages import language_alias_map
 from shelfmark.core.logger import setup_logger
@@ -42,7 +46,7 @@ from shelfmark.release_sources import (
 )

 if TYPE_CHECKING:
-    from collections.abc import Callable, Iterable
+    from collections.abc import Callable, Iterable, Iterator
    from pathlib import Path
    from threading import Event

@@ -111,6 +115,16 @@ def _html_response_text(response: str | tuple[str, str]) -> str:
    return response


+def _html_response_url(response: str | tuple[str, str]) -> str | None:
+    """The URL that actually answered, when the downloader was asked to report it.
+
+    None for the plain-string shape, so a caller can fall back to what it requested.
+    """
+    if isinstance(response, tuple):
+        return response[1] or None
+    return None
+
+
 def _attr_to_str(value: object) -> str | None:
    """Convert a BeautifulSoup attribute value to a plain string."""
    if isinstance(value, str):
@@ -555,22 +569,129 @@ _AA_PAGE_MARKERS = (
    "/fast_download",
    "/slow_download",
 )
-_CHALLENGE_MARKERS = (
-    "ddos-guard",
-    "just a moment",
-    "cloudflare",
-    "checking your browser",
-    "cf-browser-verification",
-)


 def _looks_like_aa_page(html: str) -> bool:
-    """Whether ``html`` is recognisably Anna's Archive, or a challenge in front of it."""
+    """Whether ``html`` is recognisably Anna's Archive itself."""
    lowered = html.lower()
-    return any(marker in lowered for marker in (*_AA_PAGE_MARKERS, *_CHALLENGE_MARKERS))
+    return any(marker in lowered for marker in _AA_PAGE_MARKERS)
+
+
+def _looks_like_challenge_page(html: str) -> bool:
+    """Whether ``html`` is a protection interstitial rather than the site behind it.
+
+    Delegates to the shared detector rather than substring-matching here. A bare
+    "ddos-guard"/"cloudflare" scan flags the protected site's *own* pages: DDoS-Guard
+    links its endpoints on everything it fronts, and AA ships a `DDOS-GUARD` comment in
+    the inline JS on every page it serves. That misread every real AA response that was
+    not a results table as an unsolved challenge, and sent users off to fix a bypasser
+    that had just succeeded - see #1289/#1292. `challenge_marker` caps its scan at
+    64 KB, which is what separates a few-KB interstitial from the page behind it.
+    """
+    return challenge_marker(html) is not None
+
+
+# Pages already fetched during the search in flight, keyed by URL. Scoped to one
+# DirectDownload.search() so nothing is carried between requests.
+_search_page_cache: ContextVar[dict[str, tuple[str, Tag | None]] | None] = ContextVar(
+    "aa_search_page_cache", default=None
+)
+
+
+@contextmanager
+def _search_page_reuse() -> Iterator[None]:
+    """Fetch each distinct AA search URL at most once per search.
+
+    One search asks AA for the same URL more than once. The language-filter retry in
+    `search()` re-runs every title variant, and when DIRECT_DOWNLOAD_LANGUAGE_FROM_PATH
+    is on the requested language is applied locally instead of as `&lang=`, so both
+    passes build a byte-identical URL - the retry differs only in the filtering it does
+    to the response it already had. A repeat is not a cheap round trip either: AA is
+    behind DDoS-Guard, so each one is a fresh browser solve, tens of seconds that buy
+    nothing. See issue #1285.
+    """
+    token = _search_page_cache.set({})
+    try:
+        yield
+    finally:
+        _search_page_cache.reset(token)
+
+
+def _is_reusable_answer(result: tuple[str, Tag | None]) -> bool:
+    """Whether a fetched page is an answer, rather than a giving-up worth retrying.
+
+    `_fetch_search_table_uncached` exists to rotate past mirrors that are not actually AA,
+    and when it runs out of them it *returns* instead of raising: a page with no results
+    table and no marker. Storing that would hand the language-filter retry - the pass this
+    cache exists for - a mirror set that may have recovered in between (DNS rotation, a
+    mirror coming back), turning a transient outage into "this book has no releases". A
+    real "No files found." is an answer and is worth keeping.
+    """
+    html, tbody = result
+    return tbody is not None or "No files found." in html or _looks_like_aa_page(html)
+
+
+# How much of an unreadable search page to quote in the debug log. Enough to carry the
+# <head> - title, injected challenge scripts - without pasting a 180 KB page into a log
+# file that ships inside the debug bundle.
+_PAGE_FINGERPRINT_CHARS = 700
+_TITLE_RE = re.compile(r"<title[^>]*>(.*?)</title>", re.IGNORECASE | re.DOTALL)
+
+
+def _log_untabled_search_page(url: str, html: str) -> None:
+    """Record why a search page with no results table is about to be classified.
+
+    #1289 cost a full investigation because the log said only "unsolved protection
+    challenge" while FlareSolverr said "Challenge solved!", and the debug bundle carries
+    no response bodies - there was no way to tell a real AA page from an interstitial
+    after the fact. These are the facts that would have settled it in one line: the size
+    (the 64 KB cap is what separates the two), which markers matched, and the head of
+    the document.
+
+    Diagnostics must never be the reason a search fails, so this swallows its own errors.
+    """
+    try:
+        title_match = _TITLE_RE.search(html[: _PAGE_FINGERPRINT_CHARS * 4])
+        title = " ".join(title_match.group(1).split())[:120] if title_match else "<none>"
+        lowered = html.lower()
+        aa_markers = [marker for marker in _AA_PAGE_MARKERS if marker in lowered]
+        logger.info(
+            "Search page has no results table: %s (bytes=%d, title=%r, aa_markers=%s, "
+            "challenge_marker=%r, over_challenge_size_cap=%s)",
+            url,
+            len(html),
+            title,
+            aa_markers or "none",
+            challenge_marker(html),
+            len(html) > MAX_CHALLENGE_HTML_CHARS,
+        )
+        logger.debug(
+            "Untabled search page head (%d of %d bytes): %s",
+            min(len(html), _PAGE_FINGERPRINT_CHARS),
+            len(html),
+            html[:_PAGE_FINGERPRINT_CHARS],
+        )
+    except Exception:
+        logger.debug("Could not fingerprint the untabled search page", exc_info=True)


 def _fetch_search_table(url: str, selector: network.AAMirrorSelector) -> tuple[str, Tag | None]:
+    """Fetch the AA search page, reusing one already fetched during this search."""
+    cache = _search_page_cache.get()
+    if cache is not None and url in cache:
+        logger.debug("Reusing search page already fetched for this search: %s", url)
+        return cache[url]
+
+    result = _fetch_search_table_uncached(url, selector)
+
+    if cache is not None and _is_reusable_answer(result):
+        cache[url] = result
+    return result
+
+
+def _fetch_search_table_uncached(
+    url: str, selector: network.AAMirrorSelector
+) -> tuple[str, Tag | None]:
    """Fetch the AA search page, retrying past mirrors that are not actually AA.

    A parked or seized domain answers 200 with a page that has no results table and no
@@ -580,15 +701,35 @@ def _fetch_search_table(url: str, selector: network.AAMirrorSelector) -> tuple[s
    """
    attempt_url = url
    for _ in range(len(network.get_available_aa_urls()) or 1):
-        response = downloader.html_get_page(
-            attempt_url, selector=selector, allow_bypasser_fallback=True
-        )
-        if not response:
-            # Network/mirror exhaustion path bubbles up so API can notify clients
-            msg = "Unable to reach download source. Network restricted or mirrors are blocked."
-            raise SearchUnavailableError(msg)
+        # Every mirror shares the protection, so once the search budget is gone another
+        # mirror is another full solve nobody is still waiting for.
+        if search_deadline.expired():
+            raise SearchUnavailableError(search_deadline.deadline_message())

+        # include_response_url is what makes the diagnostics below name the mirror that
+        # actually answered. html_get_page rotates mirrors and follows redirects on its
+        # own, so `attempt_url` is only where this iteration started: #1298's bundle
+        # reported the untabled page against annas-archive.gl when the body had come
+        # from .pk, which is precisely the triage cost #1289 added the line to remove.
+        response = downloader.html_get_page(
+            attempt_url,
+            selector=selector,
+            allow_bypasser_fallback=True,
+            include_response_url=True,
+        )
        html = _html_response_text(response)
+        # Checked on the body, not on `response`: with include_response_url the give-up
+        # shape is the tuple ("", url), and a tuple is truthy.
+        if not html:
+            # Network/mirror exhaustion path bubbles up so API can notify clients.
+            # html_get_page records the concrete give-up reason on the selector; fall
+            # back to the generic line only if nothing was recorded.
+            detail = getattr(selector, "last_failure", None) or (
+                "Network restricted or mirrors are blocked."
+            )
+            raise SearchUnavailableError(f"Unable to reach download source. {detail}")
+
+        answered_url = _html_response_url(response) or attempt_url
        soup = BeautifulSoup(html, "html.parser")
        table = soup.find("table")
        if isinstance(table, Tag):
@@ -596,11 +737,42 @@ def _fetch_search_table(url: str, selector: network.AAMirrorSelector) -> tuple[s
        if table is not None:
            msg = f"Expected results table tag, got {type(table).__name__}"
            raise TypeError(msg)
-        if "No files found." in html or _looks_like_aa_page(html):
-            # A real AA response - either genuinely empty, or a shape the caller
-            # should report as drift. Not the mirror's fault.
+        if "No files found." in html:
+            # A real, genuinely empty answer from a healthy mirror.
            return html, None

+        # A search page with no table is the one shape we cannot read off the response
+        # alone, and the response body is not in the debug bundle. Fingerprint it here
+        # so the next report says which branch fired and why, rather than costing
+        # another round of guesswork - see #1289.
+        _log_untabled_search_page(answered_url, html)
+
+        if _looks_like_aa_page(html):
+            # A real AA response in a shape the caller should report as drift. Checked
+            # ahead of the challenge branch: AA's own pages carry the protection's
+            # markers, so an interstitial is only the better explanation once the page
+            # has nothing of AA's about it. A genuine interstitial has no AA markers.
+            return html, None
+        if _looks_like_challenge_page(html):
+            # The bypass did not actually clear the protection - the interstitial is
+            # what came back. Rotating is pointless (every mirror shares the same
+            # protection) and reporting it as an empty result is worse: the user is
+            # told their query found nothing when the search never ran.
+            #
+            # The wording no longer blames the bypasser outright. In #1292 it was
+            # reachable and working, and the page it was handed was DDoS-Guard's manual
+            # CAPTCHA - so "check that the bypasser is working" was the one piece of
+            # advice guaranteed to waste the reporter's time. Name the marker instead
+            # and let the two causes be told apart.
+            msg = (
+                "Anna's Archive answered with a protection challenge that was not "
+                f"cleared (marker={challenge_marker(html)!r}). If the bypasser reports "
+                "solving it, the host is serving a manual CAPTCHA that no bypasser can "
+                "answer - try again shortly. Otherwise check that the bypasser is "
+                "reachable and working."
+            )
+            raise SearchUnavailableError(msg)
+
        new_base, action = selector.next_mirror_or_rotate_dns(
            fatal=True, reason="responded without an Anna's Archive page"
        )
@@ -728,8 +900,10 @@ def get_book_info(book_id: str, *, fetch_download_count: bool = True) -> BrowseR
    html = downloader.html_get_page(url, selector=selector, allow_bypasser_fallback=True)

    if not html:
-        msg = "Unable to reach download source. Network restricted or mirrors are blocked."
-        raise SearchUnavailableError(msg)
+        detail = getattr(selector, "last_failure", None) or (
+            "Network restricted or mirrors are blocked."
+        )
+        raise SearchUnavailableError(f"Unable to reach download source. {detail}")

    soup = BeautifulSoup(_html_response_text(html), "html.parser")

@@ -1884,6 +2058,22 @@ class DirectDownloadSource(ReleaseSource):
    ) -> list[Release]:
        """Search for releases using the book's metadata.

+        The whole fan-out runs under one page cache, so a URL built twice by different
+        passes is fetched once. See `_search_page_reuse`.
+        """
+        with _search_page_reuse():
+            return self._search(book, plan, expand_search=expand_search, content_type=content_type)
+
+    def _search(
+        self,
+        book: BookMetadata,
+        plan: ReleaseSearchPlan,
+        *,
+        expand_search: bool = False,
+        content_type: str = "ebook",
+    ) -> list[Release]:
+        """Search for releases using the book's metadata.
+
        Priority: ISBN search first (most precise), then title+author fallback.
        For non-English languages, uses localized titles from book.titles_by_language.

@@ -1948,6 +2138,12 @@ class DirectDownloadSource(ReleaseSource):
            query = f"{title} {author}".strip()
            if not query:
                continue
+            # `except Exception` below keeps this loop going past a failed variant, which
+            # is right for a parse error and wrong for a spent budget: without this the
+            # variants queue up behind each other and the request outlives the caller.
+            if search_deadline.expired():
+                logger.info("Release search budget spent; skipping remaining title variants")
+                break

            logger.debug("Searching direct_download: title_author='%s', langs=%s", query, langs)
            filters = SearchFilters(lang=langs if langs is not None else [])
@@ -1961,7 +2157,11 @@ class DirectDownloadSource(ReleaseSource):
            except Exception:
                logger.exception("Search error")

-        if not all_results and any(langs for _, langs in searches):
+        if (
+            not all_results
+            and any(langs for _, langs in searches)
+            and not search_deadline.expired()
+        ):
            logger.debug(
                "No title+author results with language filter, retrying without language filter"
            )
@@ -1969,6 +2169,9 @@ class DirectDownloadSource(ReleaseSource):
                query = f"{title} {author}".strip()
                if not query:
                    continue
+                if search_deadline.expired():
+                    logger.info("Release search budget spent; skipping remaining retries")
+                    break

                logger.debug("Searching direct_download: title_author='%s', langs=[]", query)
                try:
@@ -15,6 +15,7 @@ if TYPE_CHECKING:
 from shelfmark.api.websocket import ws_manager
 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,
@@ -394,11 +395,13 @@ class IRCReleaseSource(ReleaseSource):
        if book.search_title or book.title:
            parts.append(book.search_title or book.title)

-        if book.search_author:
-            parts.append(book.search_author)
-        elif book.authors:
-            # Use first author
-            author = book.authors[0] if isinstance(book.authors, list) else book.authors
+        # Only ever the first author: both metadata fields can arrive holding every
+        # 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)

        return " ".join(parts)
@@ -428,14 +431,15 @@ class IRCReleaseSource(ReleaseSource):
        "m4b": 0,
        "mp3": 1,
        "m4a": 2,
-        "flac": 3,
-        "opus": 4,
-        "ogg": 5,
-        "aac": 6,
-        "wav": 7,
-        "wma": 8,
-        "rar": 9,
-        "zip": 10,
+        "mp4": 3,
+        "flac": 4,
+        "opus": 5,
+        "ogg": 6,
+        "aac": 7,
+        "wav": 8,
+        "wma": 9,
+        "rar": 10,
+        "zip": 11,
    }

    def _convert_to_releases(
@@ -8,6 +8,7 @@ from shelfmark.core.settings_registry import (
    HeadingField,
    PasswordField,
    SettingsField,
+    TableField,
    TagListField,
    TextField,
    register_settings,
@@ -16,12 +17,36 @@ from shelfmark.core.utils import normalize_http_url


 def _test_newznab_connection(current_values: dict[str, Any] | None = None) -> dict[str, Any]:
-    """Test the Newznab connection using current form values."""
+    """Test all named Newznab connections, or the legacy connection as fallback."""
    from shelfmark.core.config import config
    from shelfmark.release_sources.newznab.api import NewznabClient
+    from shelfmark.release_sources.newznab.source import _parse_indexer_rows

    current_values = current_values or {}

+    raw_indexers = current_values.get("NEWZNAB_INDEXERS")
+    if raw_indexers is None:
+        raw_indexers = config.get("NEWZNAB_INDEXERS", [])
+    indexers = _parse_indexer_rows(raw_indexers)
+
+    if indexers:
+        details: list[str] = []
+        all_successful = True
+        for name, url, api_key in indexers:
+            try:
+                success, message = NewznabClient(url, api_key).test_connection()
+            except Exception as e:  # noqa: BLE001 — surface unexpected errors to the UI
+                success, message = False, f"Connection failed: {e!s}"
+            all_successful = all_successful and success
+            details.append(f"{name}: {message}")
+
+        summary = (
+            f"Connected to all {len(indexers)} indexers"
+            if all_successful
+            else "One or more Newznab indexers failed"
+        )
+        return {"success": all_successful, "message": summary, "details": details}
+
    raw_url = str(current_values.get("NEWZNAB_URL") or config.get("NEWZNAB_URL", "") or "")
    api_key = str(current_values.get("NEWZNAB_API_KEY") or config.get("NEWZNAB_API_KEY", "") or "")

@@ -64,25 +89,60 @@ def newznab_config_settings() -> list[SettingsField]:
            default=False,
            description="Enable searching for books via a Newznab-compatible indexer",
        ),
+        TableField(
+            key="NEWZNAB_INDEXERS",
+            label="Named Indexers",
+            description=(
+                "Add each Newznab-compatible indexer separately. The configured name is shown "
+                "beside every result from that indexer."
+            ),
+            columns=[
+                {
+                    "key": "name",
+                    "label": "Name",
+                    "type": "text",
+                    "placeholder": "NZBGeek",
+                },
+                {
+                    "key": "url",
+                    "label": "URL",
+                    "type": "text",
+                    "placeholder": "https://api.nzbgeek.info",
+                },
+                {
+                    "key": "api_key",
+                    "label": "API Key",
+                    "type": "password",
+                    "placeholder": "Optional",
+                },
+            ],
+            default=[],
+            add_label="Add Indexer",
+            empty_message=(
+                "No named indexers configured. The legacy single-indexer fields below are used "
+                "as a fallback."
+            ),
+            show_when={"field": "NEWZNAB_ENABLED", "value": True},
+        ),
        TextField(
            key="NEWZNAB_URL",
-            label="Newznab URL",
-            description="Base URL of your Newznab indexer or aggregator",
+            label="Legacy Newznab URL",
+            description="Used only when the named indexer list is empty",
            placeholder="http://nzbhydra:5076",
-            required=True,
+            required=False,
            show_when={"field": "NEWZNAB_ENABLED", "value": True},
        ),
        PasswordField(
            key="NEWZNAB_API_KEY",
-            label="API Key",
-            description="Your Newznab API key (leave blank if not required)",
+            label="Legacy API Key",
+            description="Used only with the legacy Newznab URL",
            required=False,
            show_when={"field": "NEWZNAB_ENABLED", "value": True},
        ),
        ActionButton(
            key="test_newznab",
-            label="Test Connection",
-            description="Verify your Newznab configuration",
+            label="Test Connections",
+            description="Verify every named indexer, or the legacy connection when the list is empty",
            style="primary",
            callback=_test_newznab_connection,
            show_when={"field": "NEWZNAB_ENABLED", "value": True},
@@ -4,7 +4,10 @@ from __future__ import annotations

 import re
 import time
+from dataclasses import dataclass
+from hashlib import sha256
 from typing import TYPE_CHECKING, ClassVar
+from urllib.parse import urlparse

 if TYPE_CHECKING:
    from shelfmark.core.search_plan import ReleaseSearchPlan
@@ -48,6 +51,50 @@ _DEFAULT_BOOK_CATS = [7000]
 NEWZNAB_SEARCH_TIMEOUT_SECONDS = _SEARCH_TIMEOUT


+@dataclass(frozen=True)
+class _NamedClient:
+    """A configured Newznab connection and its stable cache namespace."""
+
+    name: str
+    connection_id: str
+    client: NewznabClient
+
+
+def _parse_indexer_rows(raw: object) -> list[tuple[str, str, str]]:
+    """Normalize structured Newznab indexer settings.
+
+    Invalid/incomplete rows are ignored so one partially edited row cannot disable
+    the other configured indexers.
+    """
+    if not isinstance(raw, list):
+        return []
+
+    indexers: list[tuple[str, str, str]] = []
+    seen_connections: set[tuple[str, str]] = set()
+    for row in raw:
+        if not isinstance(row, dict):
+            continue
+        raw_url = str(row.get("url") or "").strip()
+        url = normalize_http_url(raw_url)
+        if not url:
+            if raw_url:
+                logger.warning("Newznab: ignoring indexer row with invalid URL '%s'", raw_url)
+            continue
+
+        api_key = str(row.get("api_key") or "").strip()
+        connection_key = (url, api_key)
+        if connection_key in seen_connections:
+            continue
+        seen_connections.add(connection_key)
+
+        configured_name = str(row.get("name") or "").strip()
+        hostname = urlparse(url).hostname or ""
+        name = configured_name or hostname or "Newznab"
+        indexers.append((name, url, api_key))
+
+    return indexers
+
+
 def _parse_category_ids(raw: object) -> list[int]:
    """Parse a configured category setting into Newznab category IDs.

@@ -146,8 +193,11 @@ def _newznab_result_to_release(
        else None
    )

-    # Build source_id from GUID
-    source_id = result.get("guid") or f"newznab:{hash(raw_title)}"
+    # Namespace IDs from named connections so identical GUIDs returned by two
+    # indexers cannot overwrite one another in the private release cache.
+    raw_source_id = result.get("guid") or f"newznab:{hash(raw_title)}"
+    connection_id = str(result.get("_newznab_connection_id") or "").strip()
+    source_id = f"newznab:{connection_id}:{raw_source_id}" if connection_id else raw_source_id

    # Cache the raw result for the handler
    cache_release(source_id, result)
@@ -272,6 +322,7 @@ class NewznabSource(ReleaseSource):
        )

    def _get_client(self) -> NewznabClient | None:
+        """Build the legacy single-indexer client."""
        raw_url = str(config.get("NEWZNAB_URL", "") or "")
        api_key = str(config.get("NEWZNAB_API_KEY", "") or "")

@@ -284,6 +335,28 @@ class NewznabSource(ReleaseSource):

        return NewznabClient(url, api_key or "")

+    def _get_clients(self) -> list[_NamedClient]:
+        """Build named clients, falling back to the legacy single connection."""
+        configured = _parse_indexer_rows(config.get("NEWZNAB_INDEXERS", []))
+        if configured:
+            clients: list[_NamedClient] = []
+            for name, url, api_key in configured:
+                digest = sha256(f"{name}\0{url}\0{api_key}".encode()).hexdigest()[:16]
+                clients.append(
+                    _NamedClient(
+                        name=name,
+                        connection_id=digest,
+                        client=NewznabClient(url, api_key),
+                    )
+                )
+            return clients
+
+        legacy_client = self._get_client()
+        if legacy_client is None:
+            return []
+        legacy_name = str(config.get("NEWZNAB_NAME", "") or "").strip() or "Newznab"
+        return [_NamedClient(name=legacy_name, connection_id="legacy", client=legacy_client)]
+
    def search(
        self,
        book: BookMetadata,
@@ -293,8 +366,8 @@ class NewznabSource(ReleaseSource):
        content_type: str = "ebook",
    ) -> list[Release]:
        """Search the Newznab indexer for releases matching the book."""
-        client = self._get_client()
-        if not client:
+        clients = self._get_clients()
+        if not clients:
            logger.warning("Newznab not configured - skipping search")
            return []

@@ -324,40 +397,60 @@ class NewznabSource(ReleaseSource):
        all_results: list[dict] = []

        try:
-            for idx, query in enumerate(queries, start=1):
-                _check_timeout()
-                if len(queries) > 1:
-                    logger.debug("Newznab query %d/%d: '%s'", idx, len(queries), query)
+            for connection in clients:
+                try:
+                    for idx, query in enumerate(queries, start=1):
+                        _check_timeout()
+                        if len(queries) > 1:
+                            logger.debug(
+                                "Newznab [%s] query %d/%d: '%s'",
+                                connection.name,
+                                idx,
+                                len(queries),
+                                query,
+                            )

-                raw = client.search(query=query, categories=categories)
+                        raw = connection.client.search(query=query, categories=categories)

-                # Auto-expand: retry without category filter if no results
-                if not raw and categories and auto_expand:
-                    _check_timeout()
-                    logger.info(
-                        "Newznab: no results for '%s' with category filter, auto-expanding",
-                        query,
-                    )
-                    raw = client.search(query=query, categories=None)
+                        # Auto-expand: retry without category filter if no results
+                        if not raw and categories and auto_expand:
+                            _check_timeout()
+                            logger.info(
+                                "Newznab [%s]: no results for '%s' with category filter, "
+                                "auto-expanding",
+                                connection.name,
+                                query,
+                            )
+                            raw = connection.client.search(query=query, categories=None)

-                for r in raw:
-                    key = (
-                        r.get("guid")
-                        or r.get("downloadUrl")
-                        or f"{r.get('indexer')}:{r.get('title')}"
-                    )
-                    if key in seen_keys:
-                        continue
-                    seen_keys.add(key)
-                    all_results.append(r)
+                        for raw_result in raw:
+                            r = dict(raw_result)
+                            # Aggregators can identify the underlying indexer. Plain feeds
+                            # generally cannot, so use the user-configured connection name.
+                            r["indexer"] = r.get("indexer") or connection.name
+                            r["_newznab_connection_id"] = connection.connection_id
+                            key = (
+                                connection.connection_id,
+                                r.get("guid")
+                                or r.get("downloadUrl")
+                                or f"{r.get('indexer')}:{r.get('title')}",
+                            )
+                            if key in seen_keys:
+                                continue
+                            seen_keys.add(key)
+                            all_results.append(r)
+                except TimeoutError:
+                    raise
+                except Exception:
+                    logger.exception("Newznab search failed for %s", connection.name)

        except TimeoutError as e:
            logger.warning("Newznab search timed out: %s", e)
-        except Exception:
-            logger.exception("Newznab search failed")
-            return []

        results = [_newznab_result_to_release(r, content_type, categories) for r in all_results]
+        if plan.indexers:
+            selected_indexers = set(plan.indexers)
+            results = [r for r in results if r.indexer in selected_indexers]

        if results:
            nzb_count = sum(1 for r in results if r.protocol == ReleaseProtocol.NZB)
@@ -379,5 +472,7 @@ class NewznabSource(ReleaseSource):
    def is_available(self) -> bool:
        if not config.get("NEWZNAB_ENABLED", False):
            return False
+        if _parse_indexer_rows(config.get("NEWZNAB_INDEXERS", [])):
+            return True
        url = normalize_http_url(str(config.get("NEWZNAB_URL", "") or ""))
        return bool(url)
@@ -7,6 +7,7 @@ from typing import Any, TypedDict

 import requests

+from shelfmark.core.config import config
 from shelfmark.core.logger import setup_logger
 from shelfmark.core.utils import normalize_http_url
 from shelfmark.download.network import get_ssl_verify
@@ -18,6 +19,19 @@ logger = setup_logger(__name__)
 _HTTP_STATUS_UNAUTHORIZED = HTTPStatus.UNAUTHORIZED
 _BOOK_CATEGORY_RANGE_START = 7000
 _BOOK_CATEGORY_RANGE_END = 8000
+
+# Prowlarr's own JSON endpoints (status, indexer list) read local state and answer
+# in milliseconds, so they keep a short timeout. A Torznab search is different: it
+# is Prowlarr proxying a live request to the tracker, which for a Cloudflare-fronted
+# indexer means waiting on FlareSolverr to solve a challenge. A cold challenge
+# routinely runs past a minute, so indexer searches get their own, longer budget.
+DEFAULT_INDEXER_TIMEOUT_SECONDS = 90
+MIN_INDEXER_TIMEOUT_SECONDS = 5
+MAX_INDEXER_TIMEOUT_SECONDS = 300
+
+# Connecting to Prowlarr itself is a LAN hop; only the read is allowed to be slow.
+_CONNECT_TIMEOUT_SECONDS = 10.0
+
 _PROWLARR_CLIENT_ERRORS = (
    requests.exceptions.RequestException,
    OSError,
@@ -27,6 +41,37 @@ _PROWLARR_CLIENT_ERRORS = (
 )


+class ProwlarrSearchError(RuntimeError):
+    """A Torznab search could not be completed.
+
+    Deliberately distinct from an empty result list. Reporting a failed search as
+    "this indexer has nothing" is what turns a slow FlareSolverr challenge into
+    "No releases found for this book" in the UI (#1249), and it also makes the
+    auto-expand retry fire a second request on top of the one still running.
+    """
+
+
+def resolve_indexer_timeout(timeout: object = None) -> int:
+    """Resolve the per-indexer search timeout, falling back to config.
+
+    Out-of-range and unparsable values are clamped rather than rejected: this
+    feeds an HTTP timeout, and a bad setting should not take searching down.
+    """
+    if timeout is None:
+        timeout = config.get("PROWLARR_INDEXER_TIMEOUT", DEFAULT_INDEXER_TIMEOUT_SECONDS)
+
+    resolved = coerce_int_like(timeout)
+    if resolved is None:
+        logger.warning(
+            "Invalid PROWLARR_INDEXER_TIMEOUT %r - using %ss",
+            timeout,
+            DEFAULT_INDEXER_TIMEOUT_SECONDS,
+        )
+        return DEFAULT_INDEXER_TIMEOUT_SECONDS
+
+    return max(MIN_INDEXER_TIMEOUT_SECONDS, min(MAX_INDEXER_TIMEOUT_SECONDS, resolved))
+
+
 class IndexerSeedSettings(TypedDict, total=False):
    ratio_limit: float
    seeding_time_limit_minutes: int
@@ -77,11 +122,23 @@ def _get_field_value(fields: object, name: str) -> object | None:
 class ProwlarrClient:
    """Client for interacting with the Prowlarr API."""

-    def __init__(self, url: str, api_key: str, timeout: int = 30) -> None:
-        """Initialize the API client with base URL, key, and timeout."""
+    def __init__(
+        self, url: str, api_key: str, timeout: int = 30, indexer_timeout: int | None = None
+    ) -> None:
+        """Initialize the API client with base URL, key, and timeouts.
+
+        Args:
+            url: Prowlarr base URL.
+            api_key: Prowlarr API key.
+            timeout: Timeout for Prowlarr's own JSON endpoints.
+            indexer_timeout: Timeout for Torznab searches, which Prowlarr proxies
+                out to the tracker. Defaults to PROWLARR_INDEXER_TIMEOUT.
+
+        """
        self.base_url = normalize_http_url(url)
        self.api_key = api_key
        self.timeout = timeout
+        self.indexer_timeout = resolve_indexer_timeout(indexer_timeout)
        self._session = requests.Session()
        self._session.headers.update(
            {
@@ -307,6 +364,12 @@ class ProwlarrClient:

        This returns richer fields (e.g., author/booktitle, torznab tags like
        FreeLeech) than the JSON /api/v1/search endpoint.
+
+        Raises:
+            ProwlarrSearchError: The search could not be completed. An empty list
+                strictly means the indexer answered with no matches, never that
+                the request timed out or errored.
+
        """
        if not query:
            return []
@@ -329,7 +392,7 @@ class ProwlarrClient:
            response = self._session.get(
                url=url,
                params=params,
-                timeout=self.timeout,
+                timeout=(_CONNECT_TIMEOUT_SECONDS, self.indexer_timeout),
                headers={
                    # Override the session default JSON accept header.
                    "Accept": "application/rss+xml, application/xml;q=0.9, */*;q=0.8"
@@ -347,9 +410,20 @@ class ProwlarrClient:
            for r in results:
                if r.get("indexerId") is None:
                    r["indexerId"] = int(indexer_id)
-        except Exception:
+        except requests.exceptions.Timeout as e:
+            logger.warning(
+                "Prowlarr Torznab search for indexer %s timed out after %ss. An indexer "
+                "behind FlareSolverr can need far longer than that on a cold Cloudflare "
+                "challenge - raise PROWLARR_INDEXER_TIMEOUT if this keeps happening.",
+                indexer_id,
+                self.indexer_timeout,
+            )
+            msg = f"indexer {indexer_id} did not respond within {self.indexer_timeout}s"
+            raise ProwlarrSearchError(msg) from e
+        except Exception as e:
            logger.exception("Prowlarr Torznab search failed for indexer %s", indexer_id)
-            return []
+            msg = f"indexer {indexer_id} search failed: {e}"
+            raise ProwlarrSearchError(msg) from e
        else:
            return results

@@ -28,6 +28,10 @@ from shelfmark.download.clients.base_handler import (
    DownloadRequest,
    ExternalClientHandler,
 )
+from shelfmark.download.clients.torrent_utils import (
+    extract_file_list_from_torrent,
+    extract_torrent_info,
+)
 from shelfmark.metadata_providers import BookMetadata
 from shelfmark.release_sources import register_handler
 from shelfmark.release_sources.prowlarr.api import IndexerSeedSettings, ProwlarrClient
@@ -38,12 +42,14 @@ from shelfmark.release_sources.prowlarr.utils import (
    coerce_int_like,
    get_preferred_download_url,
    get_protocol,
+    sanitize_download_url,
 )

 if TYPE_CHECKING:
    from collections.abc import Callable

    from shelfmark.core.models import DownloadTask
+    from shelfmark.download.postprocess.packs import PackFile

 logger = setup_logger(__name__)

@@ -127,6 +133,24 @@ class ProwlarrHandler(ExternalClientHandler):

        return settings.get(indexer_id)

+    def list_files(self, release_data: dict[str, Any]) -> list[PackFile] | None:
+        """List a cached torrent release's files from its .torrent, without downloading.
+
+        Magnet-only and usenet releases cannot be listed ahead of time.
+        """
+        source_id = str(release_data.get("source_id") or "")
+        prowlarr_result = get_release(source_id) if source_id else None
+        if not prowlarr_result or get_protocol(prowlarr_result) != "torrent":
+            return None
+        download_url = sanitize_download_url(str(prowlarr_result.get("downloadUrl") or "").strip())
+        if not download_url or download_url.startswith("magnet:"):
+            return None
+        expected_hash = str(prowlarr_result.get("infoHash") or "").strip() or None
+        info = extract_torrent_info(download_url, expected_hash=expected_hash)
+        if not info.torrent_data:
+            return None
+        return extract_file_list_from_torrent(info.torrent_data)
+
    def _get_client(self, protocol: str) -> DownloadClient | None:
        """Compatibility shim so module-level patching still works in tests."""
        return get_client(protocol)
@@ -297,6 +321,8 @@ class ProwlarrHandler(ExternalClientHandler):
            search_title=title,
            search_author=task.author,
        )
+        # No language default here on purpose: this re-finds one exact release by its
+        # guid, and Prowlarr does not filter on plan.languages anyway.
        plan = build_release_search_plan(
            book,
            indexers=[indexer] if indexer is not None else None,
@@ -10,12 +10,18 @@ from shelfmark.core.settings_registry import (
    CheckboxField,
    HeadingField,
    MultiSelectField,
+    NumberField,
    PasswordField,
    SettingsField,
    TextField,
    register_settings,
 )
 from shelfmark.core.utils import normalize_http_url
+from shelfmark.release_sources.prowlarr.api import (
+    DEFAULT_INDEXER_TIMEOUT_SECONDS,
+    MAX_INDEXER_TIMEOUT_SECONDS,
+    MIN_INDEXER_TIMEOUT_SECONDS,
+)

 # ==================== Dynamic Options Loaders ====================

@@ -183,6 +189,20 @@ def prowlarr_config_settings() -> list[SettingsField]:
            default=[],
            show_when={"field": "PROWLARR_ENABLED", "value": True},
        ),
+        NumberField(
+            key="PROWLARR_INDEXER_TIMEOUT",
+            label="Indexer Search Timeout (seconds)",
+            description=(
+                "How long to wait for a single indexer to answer a search. Indexers behind "
+                "FlareSolverr can need 90 seconds or more while a cold Cloudflare challenge "
+                "is solved; raise this if searches come back empty and the Prowlarr log "
+                "shows the search still running."
+            ),
+            default=DEFAULT_INDEXER_TIMEOUT_SECONDS,
+            min_value=MIN_INDEXER_TIMEOUT_SECONDS,
+            max_value=MAX_INDEXER_TIMEOUT_SECONDS,
+            show_when={"field": "PROWLARR_ENABLED", "value": True},
+        ),
        CheckboxField(
            key="PROWLARR_AUTO_EXPAND",
            label="Auto-expand search on no results",
@@ -2,6 +2,7 @@

 import re
 import time
+from dataclasses import dataclass
 from threading import Lock
 from typing import TYPE_CHECKING, ClassVar, NoReturn

@@ -30,11 +31,18 @@ from shelfmark.release_sources import (
    ReleaseProtocol,
    ReleaseSource,
    SortOption,
+    SourceUnavailableError,
    register_source,
 )
-from shelfmark.release_sources.prowlarr.api import IndexerSeedSettings, ProwlarrClient
+from shelfmark.release_sources.prowlarr.api import (
+    IndexerSeedSettings,
+    ProwlarrClient,
+    ProwlarrSearchError,
+)
 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,
@@ -50,10 +58,10 @@ _PROWLARR_SOURCE_ERRORS = (AttributeError, OSError, RuntimeError, TypeError, Val
 # Prowlarr indexer priority is 1-50 and lower is preferred; unknown sorts last.
 _UNRANKED_INDEXER_RANK = 51

-# Errors that can surface from ProwlarrClient.get_indexer_seed_settings(). The
+# Errors that can surface from a ProwlarrClient call that talks to Prowlarr. The
 # client raises requests exceptions (subclasses of OSError via IOError lineage
 # is not guaranteed), so include RequestException explicitly.
-_PROWLARR_SEED_SETTINGS_ERRORS = (*_PROWLARR_SOURCE_ERRORS, requests.exceptions.RequestException)
+_PROWLARR_REQUEST_ERRORS = (*_PROWLARR_SOURCE_ERRORS, requests.exceptions.RequestException)


 def _raise_timeout_error(message: str) -> NoReturn:
@@ -139,6 +147,36 @@ def _build_indexer_priority(indexers: list[dict]) -> dict[int, int]:
    return priority


+def _drop_unknown_indexer_ids(
+    selected_ids: list[int] | None, indexers: list[dict]
+) -> list[int] | None:
+    """Keep only selected indexer ids Prowlarr still serves.
+
+    An indexer removed or disabled in Prowlarr stays in the saved selection,
+    where settings can no longer show it - so it cannot be unselected, and every
+    search keeps querying an indexer that is gone (#1283). Dropping it here
+    keeps the saved selection intact for an indexer that comes back.
+    """
+    if selected_ids is None:
+        return None
+
+    live_ids = {
+        indexer_id
+        for indexer in indexers
+        if (indexer_id := _coerce_indexer_id(indexer.get("id"))) is not None
+    }
+    kept = [indexer_id for indexer_id in selected_ids if indexer_id in live_ids]
+
+    stale = [indexer_id for indexer_id in selected_ids if indexer_id not in live_ids]
+    if stale:
+        logger.warning(
+            "Skipping selected Prowlarr indexers that are no longer enabled in Prowlarr: %s",
+            stale,
+        )
+
+    return kept
+
+
 def _rank_for_indexer_id(indexer_id: object, priority: dict[int, int]) -> int:
    """Preference rank for an indexer id. Lower wins, unknown ranks last."""
    coerced = _coerce_indexer_id(indexer_id)
@@ -232,6 +270,35 @@ ALL_BOOK_FORMATS = AUDIOBOOK_FORMATS + EBOOK_FORMATS
 # Backend safeguard: cap total Prowlarr search time per request.
 PROWLARR_SEARCH_TIMEOUT_SECONDS = 120.0

+# The overall budget has to leave room for at least a couple of indexers to spend
+# their full per-indexer timeout, otherwise raising PROWLARR_INDEXER_TIMEOUT for a
+# Cloudflare-fronted tracker just moves the cutoff here. Capped short of the
+# gunicorn worker timeout (300s) so the worker is never the thing that gives up.
+_MAX_SEARCH_BUDGET_SECONDS = 240.0
+
+
+def _search_budget_seconds(indexer_timeout: int) -> float:
+    """Total time one Prowlarr search may spend, scaled to the per-indexer timeout."""
+    return min(
+        _MAX_SEARCH_BUDGET_SECONDS,
+        max(PROWLARR_SEARCH_TIMEOUT_SECONDS, indexer_timeout * 2.0),
+    )
+
+
+@dataclass
+class _IndexerSearchOutcome:
+    """What one pass over the target indexers produced.
+
+    Separates "every indexer answered, none had this book" from "the indexers
+    never answered", which the caller has to tell apart before it decides to
+    auto-expand or to report the search as failed.
+    """
+
+    results: list[dict]
+    attempted: int = 0
+    failed: int = 0
+    last_error: str | None = None
+

 def _extract_format(title: str) -> str | None:
    """Extract ebook/audiobook format from release title (extension, bracketed, or standalone)."""
@@ -282,19 +349,25 @@ def _extract_mam_language(raw_title: str) -> str | None:
    return None


-def _extract_mam_formats(raw_title: str) -> list[str]:
-    """Extract a list of formats from MyAnonamouse titles.
+def _split_mam_formats(raw_title: str) -> tuple[list[str], list[str]]:
+    """Split the format tokens of a MyAnonamouse title into (recognized, unrecognized).

    Prowlarr's MAM parser appends a structured bracket segment like:
      [ENG / EPUB MOBI PDF]

    We only trust this structured segment (and do not attempt generic title
    heuristics for other indexers).
+
+    Tokens after the "/" that Shelfmark does not know as a book or audiobook format
+    (e.g. ``[ENG / AVI]``) are returned separately so the UI can warn that the release
+    will download but cannot be processed, instead of showing a bare content-type icon
+    that looks like an ordinary result.
    """
    if not raw_title:
-        return []
+        return [], []

    format_set = set(ALL_BOOK_FORMATS)
+    first_unrecognized: list[str] | None = None
    for bracket in re.findall(r"\[([^\]]+)\]", raw_title):
        if "/" not in bracket:
            continue
@@ -303,15 +376,26 @@ def _extract_mam_formats(raw_title: str) -> list[str]:
        tokens = re.findall(r"[A-Za-z0-9]+", after_slash)

        formats: list[str] = []
+        unrecognized: list[str] = []
        for token in tokens:
            fmt = token.lower()
-            if fmt in format_set and fmt not in formats:
-                formats.append(fmt)
+            if fmt in format_set:
+                if fmt not in formats:
+                    formats.append(fmt)
+            elif fmt not in unrecognized:
+                unrecognized.append(fmt)

        if formats:
-            return formats
+            return formats, unrecognized
+        if unrecognized and first_unrecognized is None:
+            first_unrecognized = unrecognized

-    return []
+    return [], first_unrecognized or []
+
+
+def _extract_mam_formats(raw_title: str) -> list[str]:
+    """Extract the recognized formats from a MyAnonamouse title (see _split_mam_formats)."""
+    return _split_mam_formats(raw_title)[0]


 def _formats_display(formats: list[str]) -> str | None:
@@ -450,6 +534,7 @@ def _prowlarr_result_to_release(

    format_detected: str | None = None
    formats: list[str] = []
+    unrecognized_formats: list[str] = []
    formats_display: str | None = None
    language_detected: str | None = None
    if enable_format_detection:
@@ -457,7 +542,7 @@ def _prowlarr_result_to_release(
        if book_title:
            title = book_title

-        formats = _extract_mam_formats(str(raw_title or ""))
+        formats, unrecognized_formats = _split_mam_formats(str(raw_title or ""))
        format_detected = formats[0] if formats else None
        formats_display = _formats_display(formats)
        language_detected = _extract_mam_language(str(raw_title or ""))
@@ -519,6 +604,9 @@ def _prowlarr_result_to_release(
            "info_hash": result.get("infoHash"),
            "formats": formats or None,
            "formats_display": formats_display,
+            # Format tokens the indexer declared but Shelfmark can't process (e.g. a MAM
+            # "[ENG / AVI]"). Lets the UI warn instead of showing a bare content icon.
+            "unrecognized_formats": unrecognized_formats or None,
            # Raw torznab attributes for rich tooltips (enriched indexers)
            "torznab_attrs": result.get("torznabAttrs"),
        },
@@ -539,7 +627,7 @@ def _fetch_indexer_seed_settings(
    """Fetch per-indexer share limits, falling back to last-known-good on failure."""
    try:
        fetched = client.get_indexer_seed_settings(restrict_to=indexer_ids)
-    except _PROWLARR_SEED_SETTINGS_ERRORS:
+    except _PROWLARR_REQUEST_ERRORS:
        with _seed_settings_lock:
            fallback = dict(_last_known_seed_settings)
        logger.warning(
@@ -895,8 +983,17 @@ class ProwlarrSource(ReleaseSource):

        try:
            auto_expand_enabled = config.get("PROWLARR_AUTO_EXPAND", False)
-            deadline = time.monotonic() + PROWLARR_SEARCH_TIMEOUT_SECONDS
-            enabled_indexers = client.get_enabled_indexers_detailed()
+            search_budget = _search_budget_seconds(client.indexer_timeout)
+            deadline = time.monotonic() + search_budget
+            try:
+                enabled_indexers = client.get_enabled_indexers_detailed(raise_on_error=True)
+            except _PROWLARR_REQUEST_ERRORS as e:
+                # Prowlarr itself is unreachable. Swallowing this leaves the search
+                # with no indexers to query, which the UI renders as "No releases
+                # found for this book" - the same lie as a swallowed timeout (#1249).
+                msg = f"could not reach Prowlarr: {e}"
+                raise SourceUnavailableError(msg) from e
+            indexer_ids = _drop_unknown_indexer_ids(indexer_ids, enabled_indexers)
            indexer_priority = _build_indexer_priority(enabled_indexers)
            # Some indexers benefit from title+author queries and extra format detection.
            enriched_indexer_ids = client.get_enriched_indexer_ids(
@@ -911,65 +1008,88 @@ class ProwlarrSource(ReleaseSource):

            def _check_timeout() -> None:
                if time.monotonic() > deadline:
-                    _raise_timeout_error(
-                        f"Prowlarr search timed out after {int(PROWLARR_SEARCH_TIMEOUT_SECONDS)}s"
-                    )
+                    _raise_timeout_error(f"Prowlarr search timed out after {int(search_budget)}s")

-            def search_indexers(
-                query: str, cats: list[int] | None, *, enriched_query: str | None = None
-            ) -> list[dict]:
-                """Search indexers with given categories via Torznab/Newznab."""
-                results: list[dict] = []
+            def search_indexers(query: str, cats: list[int] | None) -> _IndexerSearchOutcome:
+                """Search indexers with given categories via Torznab/Newznab.
+
+                Every indexer gets the same title-only query. Enriched indexers used
+                to be sent "{title} {author}", but an indexer that ANDs its search
+                terms (MyAnonamouse) returns nothing whenever the metadata provider
+                spells the author differently to the tracker - "Timothy Ferriss" vs
+                "Tim Ferriss" - and the UI reports the book as missing (#1293). The
+                author still decides ordering below, where a spelling difference
+                costs a release its position rather than its existence.
+                """
+                outcome = _IndexerSearchOutcome(results=[])
                target_indexer_ids = self._get_search_indexer_ids(client, indexer_ids, cats)
                if not target_indexer_ids:
-                    return results
+                    return outcome

                for indexer_id in target_indexer_ids:
                    _check_timeout()
-                    indexer_query = (
-                        enriched_query
-                        if indexer_id in enriched_indexer_ids_set and enriched_query
-                        else query
-                    )
-                    raw = client.torznab_search(
-                        indexer_id=indexer_id,
-                        query=indexer_query,
-                        categories=cats,
-                        search_type="book",
-                    )
+                    outcome.attempted += 1
+                    try:
+                        raw = client.torznab_search(
+                            indexer_id=indexer_id,
+                            query=query,
+                            categories=cats,
+                            search_type="book",
+                        )
+                    except ProwlarrSearchError as e:
+                        # One unreachable indexer must not sink the others, but it
+                        # is not "no results" either - record it so the caller can
+                        # report a failed search instead of an empty one.
+                        outcome.failed += 1
+                        outcome.last_error = str(e)
+                        continue
                    if raw:
-                        results.extend(raw)
+                        outcome.results.extend(raw)

-                return results
+                return outcome

            seen_keys: set[tuple[int | None, str]] = set()
            all_results: list[dict] = []
+            attempted_searches = 0
+            failed_searches = 0
+            last_search_error: str | None = None

            for idx, variant in enumerate(variants, start=1):
                _check_timeout()
                query = variant.title
-                enriched_query = variant.query  # title + author

                if len(variants) > 1:
                    logger.debug("Prowlarr query %s/%s: '%s'", idx, len(variants), query)

-                raw_results = search_indexers(
-                    query=query, cats=categories, enriched_query=enriched_query
-                )
+                outcome = search_indexers(query=query, cats=categories)

-                # Auto-expand: if no results with categories and auto-expand enabled, retry without
-                if not raw_results and categories and auto_expand_enabled:
+                # Auto-expand: if no results with categories and auto-expand enabled, retry without.
+                # Only when every indexer actually answered: a failed search says nothing about
+                # whether the category filter is what hid the book, and retrying it stacks a second
+                # request on an indexer that is still busy solving a Cloudflare challenge (#1249).
+                if (
+                    not outcome.results
+                    and not outcome.failed
+                    and categories
+                    and auto_expand_enabled
+                ):
                    _check_timeout()
                    logger.info(
                        "Prowlarr: no results for query '%s' with category filter, auto-expanding search",
                        query,
                    )
-                    raw_results = search_indexers(
-                        query=query, cats=None, enriched_query=enriched_query
-                    )
+                    expanded = search_indexers(query=query, cats=None)
+                    outcome.results = expanded.results
+                    outcome.attempted += expanded.attempted
+                    outcome.failed += expanded.failed
+                    outcome.last_error = expanded.last_error or outcome.last_error
                    self.last_search_type = "expanded"

-                for r in raw_results:
+                attempted_searches += outcome.attempted
+                failed_searches += outcome.failed
+                last_search_error = outcome.last_error or last_search_error
+
+                for r in outcome.results:
                    key = _result_dedup_key(r)
                    if key is not None:
                        if key in seen_keys:
@@ -977,6 +1097,14 @@ class ProwlarrSource(ReleaseSource):
                        seen_keys.add(key)
                    all_results.append(r)

+            if failed_searches:
+                logger.warning(
+                    "Prowlarr: %s of %s indexer searches failed (%s)",
+                    failed_searches,
+                    attempted_searches,
+                    last_search_error,
+                )
+
            if config.get("PROWLARR_COLLAPSE_DUPLICATES", True):
                before_collapse = len(all_results)
                all_results = _collapse_duplicate_indexer_results(all_results, indexer_priority)
@@ -988,6 +1116,10 @@ class ProwlarrSource(ReleaseSource):

            results: list[Release] = []
            enriched_source_ids: set[str] = set()
+            affinity_by_source_id: dict[str, int] = {}
+            # 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

            for raw_result in all_results:
                result_with_seed_settings = _apply_indexer_seed_settings(
@@ -1007,13 +1139,20 @@ class ProwlarrSource(ReleaseSource):
                if idx_id_int is not None and idx_id_int in indexer_priority:
                    release.extra["indexer_priority"] = indexer_priority[idx_id_int]
                results.append(release)
+                affinity_by_source_id[release.source_id] = author_affinity(
+                    wanted_author, release.extra.get("author")
+                )

                if is_enriched:
                    enriched_source_ids.add(release.source_id)

+            # Indexer priority first: it is an explicit user preference. Author
+            # agreement then orders what one indexer returned, so the editions that
+            # match the requested author lead and the rest stay reachable below.
            results.sort(
                key=lambda r: (
                    _release_indexer_rank(r, indexer_priority),
+                    affinity_by_source_id.get(r.source_id, AUTHOR_UNKNOWN),
                    0 if r.source_id in enriched_source_ids else 1,
                )
            )
@@ -1033,6 +1172,10 @@ class ProwlarrSource(ReleaseSource):
            else:
                logger.debug("Prowlarr: no results found")

+        except SourceUnavailableError:
+            # Already carries its own message for the caller to surface; the blanket
+            # handler below would turn it back into a silent empty result.
+            raise
        except TimeoutError as e:
            logger.warning("Prowlarr search timed out: %s", e)
            raise
@@ -1040,6 +1183,15 @@ class ProwlarrSource(ReleaseSource):
            logger.exception("Prowlarr search failed")
            return []
        else:
+            # An empty list is the UI's "No releases found for this book", so it has
+            # to mean the indexers answered and had nothing. When they failed instead,
+            # say so rather than blaming the book (#1249).
+            if not results and failed_searches:
+                msg = (
+                    f"{failed_searches} of {attempted_searches} indexer searches failed "
+                    f"({last_search_error})"
+                )
+                raise SourceUnavailableError(msg)
            return results

    def is_available(self) -> bool:
@@ -14,6 +14,20 @@ 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:
@@ -32,6 +46,49 @@ 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.

@@ -35,6 +35,15 @@
    "typescript/no-misused-promises": "error",
    "typescript/no-non-null-assertion": "error",
    "typescript/only-throw-error": "error",
+    // React Compiler advisories, enforced everywhere with no per-file exemptions.
+    // The violations inherited from the oxlint 1.70 -> 1.80 bump are all resolved:
+    // three by widening a dependency to the object the compiler infers, and seven
+    // by an `oxlint-disable-next-line` that says, at the callsite, why the flagged
+    // dependency is load-bearing - five are re-run triggers that are never read,
+    // and two are values the callback genuinely uses.
+    "react/preserve-manual-memoization": "error",
+    "react/exhaustive-effect-dependencies": "error",
+    "react/memo-dependencies": "error",
    "react/no-danger": "error",
    "react/no-clone-element": "error",
    "react/no-react-children": "error",
@@ -24,17 +24,17 @@
    "socket.io-client": "^4.7.5"
  },
  "devDependencies": {
-    "@types/node": "^26.2.0",
+    "@types/node": "^26.3.0",
    "@types/react": "^19.2.18",
-    "@types/react-dom": "^19.2.4",
-    "@vitejs/plugin-react": "^6.0.5",
-    "knip": "^6.32.1",
-    "oxfmt": "^0.63.0",
-    "oxlint": "^1.78.0",
+    "@types/react-dom": "^19.2.5",
+    "@vitejs/plugin-react": "^6.1.0",
+    "knip": "^6.32.2",
+    "oxfmt": "^0.65.0",
+    "oxlint": "^1.80.0",
    "oxlint-tsgolint": "^7.0.2001",
    "tailwindcss": "^4.2.2",
    "typescript": "^7.0.2",
-    "vite": "^8.2.1",
-    "vitest": "^4.1.10"
+    "vite": "^8.2.2",
+    "vitest": "^4.1.11"
  }
 }
@@ -32,6 +32,7 @@ import {
 import { useActivity } from './hooks/useActivity';
 import { useAuth } from './hooks/useAuth';
 import { useDownloadTracking } from './hooks/useDownloadTracking';
+import { useLatestCallback } from './hooks/useLatestCallback';
 import { useMediaQuery } from './hooks/useMediaQuery';
 import { useMountEffect } from './hooks/useMountEffect';
 import { useRealtimeStatus } from './hooks/useRealtimeStatus';
@@ -58,7 +59,6 @@ import {
  isApiResponseError,
  updateSelfUser,
  setBookTargetState,
-  type DownloadReleasePayload,
 } from './services/api';
 import type {
  Book,
@@ -74,6 +74,7 @@ import type {
  ActingAsUserSelection,
  MetadataProviderSummary,
  MetadataSearchConfig,
+  MetadataSearchField,
  QueuedDownloadResult,
  QueryTargetOption,
  SearchMode,
@@ -87,11 +88,13 @@ import { bookSupportsTargets } from './utils/bookTargetLoader';
 import { buildSearchQuery } from './utils/buildSearchQuery';
 import { wasDownloadQueuedAfterResponseError } from './utils/downloadRecovery';
 import { getDynamicOptionGroup } from './utils/dynamicFieldOptions';
+import { resolveDefaultLanguageCodes } from './utils/languageFilters';
 import { getConfiguredMetadataProviderForContentType } from './utils/metadataProviders';
 import { getEffectiveMetadataSort } from './utils/metadataSort';
 import { isRecord } from './utils/objectHelpers';
 import { policyTrace } from './utils/policyTrace';
 import { buildQueryTargets, getDefaultQueryTargetKey } from './utils/queryTargets';
+import { buildReleaseDownloadPayload, type ReleaseDownloadOptions } from './utils/releasePayload';
 import { applyRequestNoteToPayload } from './utils/requestConfirmation';
 import { bookFromRequestData } from './utils/requestFulfil';
 import {
@@ -218,6 +221,7 @@ type PendingOnBehalfDownload =
      release: Release;
      releaseContentType: ContentType;
      actingAsUser: ActingAsUserSelection;
+      options?: ReleaseDownloadOptions;
    }
  | {
      type: 'combined';
@@ -490,8 +494,6 @@ function App() {
  });

  // When a book is removed from the Hardcover list currently being browsed, remove it from results
-  const searchFieldValuesRef = useRef(searchFieldValues);
-  searchFieldValuesRef.current = searchFieldValues;
  useBookTargetDeselectSync({
    activeListValue: searchFieldValues.hardcover_list,
    setBooks,
@@ -603,24 +605,6 @@ function App() {
    };
  }, [effectiveActingAsUser, pendingOnBehalfDownload]);

-  // Wire up logout callback to clear search state
-  const handleLogoutWithCleanup = useCallback(async () => {
-    await handleLogout();
-    resetSearchResultsState();
-    setActiveQueryTarget('general');
-    setPendingRequestPayload(null);
-    setPendingRequestExtraPayloads([]);
-    setActingAsUser(null);
-    setAdminUsers([]);
-    setAdminUsersError(null);
-    setHasLoadedAdminUsers(false);
-    setPendingOnBehalfDownload(null);
-    setFulfillingRequest(null);
-    resetActivity();
-    setSettingsOpen(false);
-    setSelfSettingsOpen(false);
-  }, [handleLogout, resetActivity, resetSearchResultsState]);
-
  // Combined mode state (ebook + audiobook in one transaction)
  const [combinedState, setCombinedState] = useState<CombinedSelectionState | null>(null);

@@ -653,20 +637,6 @@ function App() {
    setDownloadsSidebarOpen(true);
    prefetchActivityHistory();
  }, [downloadsSidebarOpen, prefetchActivityHistory]);
-  const handleSettingsClick = useCallback(() => {
-    if (config?.settings_enabled) {
-      if (authIsAdmin) {
-        void primeUsersCache();
-        void primeSettingsCache();
-        setSettingsOpen(true);
-      } else {
-        setSelfSettingsOpen(true);
-      }
-      return;
-    }
-    setConfigBannerOpen(true);
-  }, [authIsAdmin, config?.settings_enabled]);
-
  const headerRef = useCallback((el: HTMLDivElement | null) => {
    if (headerObserverRef.current) {
      headerObserverRef.current.disconnect();
@@ -683,6 +653,39 @@ function App() {
  const [settingsOpen, setSettingsOpen] = useState(false);
  const [selfSettingsOpen, setSelfSettingsOpen] = useState(false);
  const [configBannerOpen, setConfigBannerOpen] = useState(false);
+
+  // Wire up logout callback to clear search state
+  const handleLogoutWithCleanup = useCallback(async () => {
+    await handleLogout();
+    resetSearchResultsState();
+    setActiveQueryTarget('general');
+    setPendingRequestPayload(null);
+    setPendingRequestExtraPayloads([]);
+    setActingAsUser(null);
+    setAdminUsers([]);
+    setAdminUsersError(null);
+    setHasLoadedAdminUsers(false);
+    setPendingOnBehalfDownload(null);
+    setFulfillingRequest(null);
+    resetActivity();
+    setSettingsOpen(false);
+    setSelfSettingsOpen(false);
+  }, [handleLogout, resetActivity, resetSearchResultsState]);
+
+  const handleSettingsClick = useCallback(() => {
+    if (config?.settings_enabled) {
+      if (authIsAdmin) {
+        void primeUsersCache();
+        void primeSettingsCache();
+        setSettingsOpen(true);
+      } else {
+        setSelfSettingsOpen(true);
+      }
+      return;
+    }
+    setConfigBannerOpen(true);
+  }, [authIsAdmin, config?.settings_enabled]);
+
  const [onboardingOpen, setOnboardingOpen] = useState(false);
  useShowOnboardingDebug({
    setOnboardingOpen,
@@ -1071,85 +1074,45 @@ function App() {
    [],
  );

-  const buildReleaseDownloadPayload = useCallback(
-    (book: Book, release: Release, releaseContentType: ContentType): DownloadReleasePayload => {
-      const isManual = book.provider === 'manual';
-      const releasePreview =
-        typeof release.extra?.preview === 'string' ? release.extra.preview : undefined;
-      const releaseAuthor =
-        typeof release.extra?.author === 'string' ? release.extra.author : undefined;
-
-      return {
-        source: release.source,
-        source_id: release.source_id,
-        title: isManual ? release.title : book.title,
-        author: isManual ? releaseAuthor || '' : book.author,
-        year: book.year,
-        format: release.format,
-        size: release.size,
-        size_bytes: release.size_bytes,
-        download_url: release.download_url,
-        protocol: release.protocol,
-        indexer: release.indexer,
-        seeders: release.seeders,
-        extra: release.extra,
-        preview: isManual ? releasePreview || undefined : book.preview,
-        content_type: releaseContentType,
-        series_name: book.series_name,
-        series_position: book.series_position,
-        subtitle: book.subtitle,
-        // From the release, never the book: book.language is the provider's
-        // canonical edition, which would mislabel a translated release.
-        language: release.language ?? undefined,
-      };
-    },
-    [],
-  );
-
  // When downloading a book while browsing a Hardcover list the user owns,
  // automatically remove it from that list (fire-and-forget).
-  const searchFieldLabelsRef = useRef(searchFieldLabels);
-  searchFieldLabelsRef.current = searchFieldLabels;
-  const metadataConfigRef = useRef(activeMetadataConfig);
-  metadataConfigRef.current = activeMetadataConfig;
+  // Stable identity for the download handlers below, while still reading the current
+  // search field values, labels and metadata config. Not an Effect Event: the callers
+  // are download handlers, not Effects. See useLatestCallback.
+  const removeBookFromActiveList = useLatestCallback((book: Book) => {
+    if (config?.hardcover_auto_remove_on_download === false) return;
+    if (!bookSupportsTargets(book)) return;
+    const activeList = searchFieldValues.hardcover_list;
+    if (!activeList) return;
+    const target = String(activeList);
+    const provider = book.provider;
+    const bookId = book.provider_id;
+    if (!provider || !bookId) return;

-  const removeBookFromActiveList = useCallback(
-    (book: Book) => {
-      if (config?.hardcover_auto_remove_on_download === false) return;
-      if (!bookSupportsTargets(book)) return;
-      const activeList = searchFieldValuesRef.current.hardcover_list;
-      if (!activeList) return;
-      const target = String(activeList);
-      const provider = book.provider;
-      const bookId = book.provider_id;
-      if (!provider || !bookId) return;
+    // Only auto-remove from lists the user owns (Reading Status / My Lists)
+    const listField = activeMetadataConfig?.search_fields.find(
+      (f) => f.key === 'hardcover_list' && f.type === 'DynamicSelectSearchField',
+    );
+    if (listField && listField.type === 'DynamicSelectSearchField') {
+      const group = getDynamicOptionGroup(listField.options_endpoint, target);
+      if (group && group !== 'Reading Status' && group !== 'My Lists') return;
+    }

-      // Only auto-remove from lists the user owns (Reading Status / My Lists)
-      const listField = metadataConfigRef.current?.search_fields.find(
-        (f) => f.key === 'hardcover_list' && f.type === 'DynamicSelectSearchField',
-      );
-      if (listField && listField.type === 'DynamicSelectSearchField') {
-        const group = getDynamicOptionGroup(listField.options_endpoint, target);
-        if (group && group !== 'Reading Status' && group !== 'My Lists') return;
-      }
-
-      void setBookTargetState(provider, bookId, target, false)
-        .then((result) => {
-          if (result.changed) {
-            emitBookTargetChange({
-              provider,
-              bookId,
-              target,
-              selected: false,
-            });
-            const listName = searchFieldLabelsRef.current['hardcover_list'];
-            showToast(`Removed from ${listName || 'list'}`, 'info');
-          }
-        })
-        .catch(() => undefined);
-    },
-    [config?.hardcover_auto_remove_on_download, showToast],
-  );
+    void setBookTargetState(provider, bookId, target, false)
+      .then((result) => {
+        if (result.changed) {
+          emitBookTargetChange({
+            provider,
+            bookId,
+            target,
+            selected: false,
+          });
+          const listName = searchFieldLabels['hardcover_list'];
+          showToast(`Removed from ${listName || 'list'}`, 'info');
+        }
+      })
+      .catch(() => undefined);
+  });

  const executeBookDownload = useCallback(
    async (book: Book, onBehalfOfUserId?: number): Promise<void> => {
@@ -1213,12 +1176,13 @@ function App() {
      release: Release,
      releaseContentType: ContentType,
      onBehalfOfUserId?: number,
+      options?: ReleaseDownloadOptions,
    ): Promise<void> => {
      const requestStartedAtSeconds = Date.now() / 1000;
      try {
        trackRelease(book.id, release.source_id);
        await downloadRelease(
-          buildReleaseDownloadPayload(book, release, releaseContentType),
+          buildReleaseDownloadPayload(book, release, releaseContentType, options),
          onBehalfOfUserId,
        );
        await fetchStatus();
@@ -1300,7 +1264,6 @@ function App() {
      }
    },
    [
-      buildReleaseDownloadPayload,
      fetchStatus,
      openRequestConfirmation,
      refreshRequestPolicy,
@@ -1415,6 +1378,7 @@ function App() {
          effectivePendingOnBehalfDownload.release,
          effectivePendingOnBehalfDownload.releaseContentType,
          onBehalfOfUserId,
+          effectivePendingOnBehalfDownload.options,
        );
      }
      setPendingOnBehalfDownload(null);
@@ -1639,6 +1603,7 @@ function App() {
    book: Book,
    release: Release,
    releaseContentType: ContentType,
+    options?: ReleaseDownloadOptions,
  ) => {
    policyTrace('release.action:start', {
      bookId: book.id,
@@ -1654,11 +1619,12 @@ function App() {
        release,
        releaseContentType,
        actingAsUser: effectiveActingAsUser,
+        options,
      });
      return;
    }

-    await executeReleaseDownload(book, release, releaseContentType);
+    await executeReleaseDownload(book, release, releaseContentType, undefined, options);
  };

  const handleReleaseRequest = useCallback(
@@ -1927,10 +1893,7 @@ function App() {
  );
  const supportedFormats = config?.supported_formats || DEFAULT_SUPPORTED_FORMATS;
  const defaultLanguageCodes = useMemo(
-    () =>
-      config?.default_language && config.default_language.length > 0
-        ? config.default_language
-        : [bookLanguages[0]?.code || 'en'],
+    () => resolveDefaultLanguageCodes(config?.default_language, bookLanguages),
    [config?.default_language, bookLanguages],
  );

@@ -1942,14 +1905,27 @@ function App() {
    effectiveSearchMode === 'universal' &&
    (universalDefaultMode === 'download' || universalDefaultMode === 'request_release');

+  // Keep the last known search fields so queryTargets doesn't collapse to
+  // [general] while the metadata config briefly reloads on content type switch.
+  // Held in state rather than a ref written during render: a ref read back in the same
+  // pass is what `react/refs` forbids, and this is the adjust-state-during-render shape
+  // React documents for exactly this - carry the previous value until a new one arrives.
+  const [stableSearchFields, setStableSearchFields] = useState<MetadataSearchField[]>(
+    () => activeMetadataConfig?.search_fields ?? [],
+  );
+  const incomingSearchFields = activeMetadataConfig?.search_fields;
+  if (incomingSearchFields && incomingSearchFields !== stableSearchFields) {
+    setStableSearchFields(incomingSearchFields);
+  }
+
  const queryTargets = useMemo<QueryTargetOption[]>(
    () =>
      buildQueryTargets({
        searchMode: effectiveSearchMode,
-        metadataSearchFields: activeMetadataConfig?.search_fields ?? [],
+        metadataSearchFields: stableSearchFields,
        manualSearchAllowed,
      }),
-    [effectiveSearchMode, activeMetadataConfig?.search_fields, manualSearchAllowed],
+    [effectiveSearchMode, stableSearchFields, manualSearchAllowed],
  );
  const effectiveActiveQueryTarget = useMemo(() => {
    if (queryTargets.some((target) => target.key === activeQueryTarget)) {
@@ -1978,27 +1954,27 @@ function App() {
        ? (queryTargets.find((target) => target.field?.key === seriesBrowseCapability.field_key) ??
          null)
        : null,
-    [queryTargets, seriesBrowseCapability?.field_key],
+    // `seriesBrowseCapability` whole: the body reads `.field_key` off it unguarded
+    // inside the ternary, so that object is the dependency the compiler infers.
+    [queryTargets, seriesBrowseCapability],
  );

  const activeQueryValue = useMemo(() => {
    if (
      !activeQueryOption ||
      activeQueryOption.source === 'general' ||
-      activeQueryOption.source === 'manual'
+      activeQueryOption.source === 'manual' ||
+      activeQueryOption.source === 'direct-field'
    ) {
      return searchInput;
    }

-    if (activeQueryOption.source === 'direct-field') {
-      if (activeQueryOption.key === 'isbn') return advancedFilters.isbn;
-      if (activeQueryOption.key === 'author') return advancedFilters.author;
-      if (activeQueryOption.key === 'title') return advancedFilters.title;
+    if (!activeQueryOption.field) {
      return '';
    }

-    if (!activeQueryOption.field) {
-      return '';
+    if (activeQueryOption.field.type === 'TextSearchField') {
+      return searchInput;
    }

    if (activeQueryOption.field.type === 'CheckboxSearchField') {
@@ -2008,7 +1984,7 @@ function App() {
    }

    return searchFieldValues[activeQueryOption.field.key] ?? '';
-  }, [activeQueryOption, searchInput, advancedFilters, searchFieldValues]);
+  }, [activeQueryOption, searchInput, searchFieldValues]);

  const activeQueryValueLabel = useMemo(() => {
    if (!activeQueryOption?.field) {
@@ -2056,29 +2032,25 @@ function App() {
      if (
        !activeQueryOption ||
        activeQueryOption.source === 'general' ||
-        activeQueryOption.source === 'manual'
+        activeQueryOption.source === 'manual' ||
+        activeQueryOption.source === 'direct-field'
      ) {
        setSearchInput(typeof value === 'string' ? value : String(value ?? ''));
        return;
      }

-      if (activeQueryOption.source === 'direct-field') {
-        const nextValue = typeof value === 'string' ? value : String(value ?? '');
-        if (activeQueryOption.key === 'isbn') {
-          updateAdvancedFilters({ isbn: nextValue });
-        } else if (activeQueryOption.key === 'author') {
-          updateAdvancedFilters({ author: nextValue });
-        } else if (activeQueryOption.key === 'title') {
-          updateAdvancedFilters({ title: nextValue });
-        }
-        return;
-      }
-
      if (activeQueryOption.field) {
+        if (activeQueryOption.field.type === 'TextSearchField') {
+          setSearchInput(typeof value === 'string' ? value : String(value ?? ''));
+          if (label !== undefined) {
+            updateSearchFieldValue(activeQueryOption.field.key, value, label);
+          }
+          return;
+        }
        updateSearchFieldValue(activeQueryOption.field.key, value, label);
      }
    },
-    [activeQueryOption, setSearchInput, updateAdvancedFilters, updateSearchFieldValue],
+    [activeQueryOption, setSearchInput, updateSearchFieldValue],
  );

  const handleSearchModeChange = useCallback(
@@ -2276,7 +2248,9 @@ function App() {

      return book.provider === activeMetadataConfig.provider;
    },
-    [activeMetadataConfig?.provider, seriesBrowseCapability?.sort, seriesBrowseTarget?.field],
+    // `activeMetadataConfig` whole: the body reads `.provider` off it unguarded on
+    // the last line, so that object is the dependency the compiler infers.
+    [activeMetadataConfig, seriesBrowseCapability?.sort, seriesBrowseTarget?.field],
  );

  const handleManualSearch = useCallback(() => {
@@ -0,0 +1,193 @@
+import { useState } from 'react';
+
+import type { PackBook, PackPlan, Release } from '../types';
+import {
+  describePackPlan,
+  parseSeriesPositionInput,
+  toBookPlanPayload,
+  updateReviewBook,
+} from '../utils/packReview';
+import { ToggleSwitch } from './shared/ToggleSwitch';
+
+interface PackReviewPanelProps {
+  release: Release;
+  plan: PackPlan;
+  books: PackBook[];
+  onChange: (books: PackBook[]) => void;
+  onBack: () => void;
+  /** `null` means "treat the whole release as one book". */
+  onConfirm: (books: PackBook[] | null) => Promise<void>;
+  isSubmitting: boolean;
+}
+
+const inputClassName =
+  'w-full rounded-md border border-(--border-muted) bg-(--bg) px-2 py-1 text-sm text-(--text) focus:border-emerald-500 focus:outline-none';
+
+export const PackReviewPanel = ({
+  release,
+  plan,
+  books,
+  onChange,
+  onBack,
+  onConfirm,
+  isSubmitting,
+}: PackReviewPanelProps) => {
+  const [singleBook, setSingleBook] = useState(false);
+  const [expandedFiles, setExpandedFiles] = useState<number | null>(null);
+  const [showIgnored, setShowIgnored] = useState(false);
+
+  const payloadBooks = toBookPlanPayload(books);
+  const canConfirm = !isSubmitting && (singleBook || payloadBooks.length > 0);
+  const confirmLabel = singleBook
+    ? 'Download as one book'
+    : `Download ${payloadBooks.length} ${payloadBooks.length === 1 ? 'book' : 'books'}`;
+
+  return (
+    <div className="flex flex-col gap-4 px-5 py-4" data-testid="pack-review-panel">
+      <div>
+        <h3 className="text-base font-semibold text-(--text)">
+          This release contains several books
+        </h3>
+        <p className="mt-1 text-sm text-zinc-500 dark:text-zinc-400">
+          <span className="font-medium text-(--text)">{release.title}</span> ·{' '}
+          {describePackPlan(books, plan.ignored)}
+        </p>
+        <p className="mt-1 text-xs text-zinc-500 dark:text-zinc-400">
+          Each book below is filed separately with its own title. Fix any titles before downloading
+          — the author and series come from the book you searched.
+        </p>
+      </div>
+
+      <div className="flex items-center justify-between rounded-lg border border-(--border-muted) px-3 py-2">
+        <div>
+          <p className="text-sm font-medium text-(--text)">Treat as a single book</p>
+          <p className="text-xs text-zinc-500 dark:text-zinc-400">
+            Use this if the split is wrong and the files are really one audiobook.
+          </p>
+        </div>
+        <ToggleSwitch
+          checked={singleBook}
+          onChange={setSingleBook}
+          color="emerald"
+          ariaLabel="Treat as a single book"
+          disabled={isSubmitting}
+        />
+      </div>
+
+      <div
+        className={`flex flex-col divide-y divide-zinc-200/60 dark:divide-zinc-800/60 ${
+          singleBook ? 'pointer-events-none opacity-40' : ''
+        }`}
+      >
+        <div className="grid grid-cols-[minmax(0,1fr)_72px_72px_80px] gap-2 pb-1 text-xs font-medium tracking-wide text-zinc-500 uppercase dark:text-zinc-400">
+          <span>Title</span>
+          <span>Series #</span>
+          <span>Year</span>
+          <span className="text-right">Files</span>
+        </div>
+        {books.map((book, index) => (
+          <div key={book.files[0] ?? index} className="py-2">
+            <div className="grid grid-cols-[minmax(0,1fr)_72px_72px_80px] items-center gap-2">
+              <input
+                type="text"
+                value={book.title}
+                onChange={(e) =>
+                  onChange(updateReviewBook(books, index, { title: e.target.value }))
+                }
+                aria-label={`Title for book ${index + 1}`}
+                className={inputClassName}
+                disabled={isSubmitting}
+              />
+              <input
+                type="text"
+                inputMode="decimal"
+                value={book.series_position ?? ''}
+                onChange={(e) =>
+                  onChange(
+                    updateReviewBook(books, index, {
+                      series_position: parseSeriesPositionInput(e.target.value),
+                    }),
+                  )
+                }
+                aria-label={`Series position for book ${index + 1}`}
+                className={inputClassName}
+                disabled={isSubmitting}
+              />
+              <input
+                type="text"
+                inputMode="numeric"
+                value={book.year ?? ''}
+                onChange={(e) => {
+                  const parsed = parseSeriesPositionInput(e.target.value);
+                  onChange(
+                    updateReviewBook(books, index, {
+                      year: parsed === null ? null : Math.trunc(parsed),
+                    }),
+                  );
+                }}
+                aria-label={`Year for book ${index + 1}`}
+                className={inputClassName}
+                disabled={isSubmitting}
+              />
+              <button
+                type="button"
+                onClick={() => setExpandedFiles(expandedFiles === index ? null : index)}
+                className="hover-surface rounded-md px-2 py-1 text-right text-sm text-zinc-500 transition-colors dark:text-zinc-400"
+                aria-expanded={expandedFiles === index}
+              >
+                {book.files.length} {book.files.length === 1 ? 'file' : 'files'}
+              </button>
+            </div>
+            {expandedFiles === index && (
+              <ul className="mt-2 max-h-40 overflow-y-auto rounded-md bg-(--bg-soft) px-3 py-2 font-mono text-xs break-all text-zinc-600 dark:text-zinc-300">
+                {book.files.map((file) => (
+                  <li key={file}>{file}</li>
+                ))}
+              </ul>
+            )}
+          </div>
+        ))}
+      </div>
+
+      {plan.ignored.length > 0 && (
+        <div>
+          <button
+            type="button"
+            onClick={() => setShowIgnored(!showIgnored)}
+            className="text-xs text-zinc-500 underline-offset-2 hover:underline dark:text-zinc-400"
+            aria-expanded={showIgnored}
+          >
+            {plan.ignored.length} {plan.ignored.length === 1 ? 'file' : 'files'} ignored (not a book
+            format)
+          </button>
+          {showIgnored && (
+            <ul className="mt-2 max-h-32 overflow-y-auto rounded-md bg-(--bg-soft) px-3 py-2 font-mono text-xs break-all text-zinc-600 dark:text-zinc-300">
+              {plan.ignored.map((file) => (
+                <li key={file}>{file}</li>
+              ))}
+            </ul>
+          )}
+        </div>
+      )}
+
+      <div className="flex items-center justify-end gap-3 border-t border-(--border-muted) pt-4">
+        <button
+          type="button"
+          onClick={onBack}
+          disabled={isSubmitting}
+          className="hover-surface rounded-lg px-3 py-1.5 text-sm font-medium text-(--text) transition-colors disabled:opacity-50"
+        >
+          &larr; Back
+        </button>
+        <button
+          type="button"
+          onClick={() => void onConfirm(singleBook ? null : payloadBooks)}
+          disabled={!canConfirm}
+          className="rounded-lg bg-emerald-600 px-4 py-1.5 text-sm font-medium text-white transition-colors hover:bg-emerald-700 disabled:cursor-not-allowed disabled:opacity-50"
+        >
+          {isSubmitting ? 'Queuing…' : confirmLabel}
+        </button>
+      </div>
+    </div>
+  );
+};
@@ -8,6 +8,7 @@ import {
  toStringArray,
  toStringValue,
 } from '../utils/objectHelpers';
+import { getUnrecognizedReleaseFormats } from '../utils/releaseFormats';
 import { Tooltip } from './shared/Tooltip';

 interface ReleaseCellProps {
@@ -424,6 +425,38 @@ export const ReleaseCell = ({
      const primaryFormat = formats?.[0] || null;
      const additionalFormats = formats?.slice(1) || [];

+      // The indexer named a format Shelfmark can't process (e.g. MAM "[ENG / AVI]").
+      // Downloading it would only fail post-processing, so warn instead of showing the
+      // bare content-type icon that makes it look like any other result.
+      const unrecognizedFormats = primaryFormat ? [] : getUnrecognizedReleaseFormats(release);
+      if (unrecognizedFormats.length > 0) {
+        const unsupportedLabel = unrecognizedFormats.map((fmt) => fmt.toUpperCase()).join(', ');
+        const unsupportedTitle = `Unsupported format (${unsupportedLabel}) - Shelfmark cannot process this release`;
+        if (compact) {
+          return (
+            <span
+              className="font-semibold text-amber-600 dark:text-amber-400"
+              title={unsupportedTitle}
+            >
+              {unrecognizedFormats[0].toUpperCase()}
+              {unrecognizedFormats.length > 1 && ` +${unrecognizedFormats.length - 1}`}
+            </span>
+          );
+        }
+        return (
+          <div className="flex items-center justify-start" title={unsupportedTitle}>
+            <span className="inline-flex items-center gap-1">
+              <span className="w-13 rounded-lg bg-amber-500/20 py-0.5 text-center text-[10px] font-semibold tracking-wide whitespace-nowrap text-amber-700 sm:text-[11px] dark:text-amber-400">
+                {unrecognizedFormats[0].toUpperCase()}
+              </span>
+              <span className="text-[10px] font-medium whitespace-nowrap text-amber-700 sm:text-[11px] dark:text-amber-400">
+                Unsupported
+              </span>
+            </span>
+          </div>
+        );
+      }
+
      // Use blue for book, violet for audiobook when no format specified
      const noFormatStyle = isAudiobook
        ? { bg: 'bg-violet-500/20', text: 'text-violet-600 dark:text-violet-400' }
@@ -7,6 +7,7 @@ import { useReleaseSearchSession } from '../hooks/releaseModal/useReleaseSearchS
 import { useTabIndicator } from '../hooks/ui/useTabIndicator';
 import { useBodyScrollLock } from '../hooks/useBodyScrollLock';
 import { useEscapeKey } from '../hooks/useEscapeKey';
+import { inspectRelease } from '../services/api';
 import type {
  Book,
  Release,
@@ -18,6 +19,8 @@ import type {
  LeadingCellConfig,
  ContentType,
  RequestPolicyMode,
+  PackBook,
+  PackPlan,
 } from '../types';
 import { isMetadataBook } from '../types';
 import { bookSupportsTargets } from '../utils/bookTargetLoader';
@@ -29,7 +32,10 @@ import {
  buildLanguageNormalizer,
 } from '../utils/languageFilters';
 import { getNestedValue, toComparableText, toStringValue } from '../utils/objectHelpers';
+import { toBookPlanPayload } from '../utils/packReview';
 import { getReleaseFormats } from '../utils/releaseFormats';
+import { INITIAL_ENTER_ANIMATION, nextEnterAnimation } from '../utils/releaseModalEnterAnimation';
+import { buildReleaseDownloadPayload, type ReleaseDownloadOptions } from '../utils/releasePayload';
 import {
  getBookTitleCandidates,
  getBookAuthorCandidates,
@@ -50,6 +56,7 @@ import { BookTargetDropdown } from './BookTargetDropdown';
 import { Dropdown } from './Dropdown';
 import { DropdownList } from './DropdownList';
 import { LanguageMultiSelect } from './LanguageMultiSelect';
+import { PackReviewPanel } from './PackReviewPanel';
 import { ReleaseCell } from './ReleaseCell';

 // Combined mode configuration for the ReleaseModal
@@ -140,7 +147,12 @@ const DEFAULT_COLUMN_CONFIG: ReleaseColumnConfig = {
 interface ReleaseModalProps {
  book: Book | null;
  onClose: () => void;
-  onDownload: (book: Book, release: Release, contentType: ContentType) => Promise<void>;
+  onDownload: (
+    book: Book,
+    release: Release,
+    contentType: ContentType,
+    options?: ReleaseDownloadOptions,
+  ) => Promise<void>;
  onRequestRelease?: (book: Book, release: Release, contentType: ContentType) => Promise<void>;
  onRequestBook?: (book: Book, contentType: ContentType) => Promise<void>;
  getPolicyModeForSource?: (source: string, contentType: ContentType) => RequestPolicyMode;
@@ -762,6 +774,15 @@ const ReleaseModalSession = ({
      : supportedFormats;
  const [isRequestingBook, setIsRequestingBook] = useState(false);
  const [selectedRelease, setSelectedRelease] = useState<Release | null>(null);
+  // Multi-book packs: `multiBook` is the manual header toggle (heuristic split for
+  // releases we can't inspect); `packReview` holds an inspected pack awaiting approval.
+  const [multiBook, setMultiBook] = useState(false);
+  const [packReview, setPackReview] = useState<{
+    release: Release;
+    plan: PackPlan;
+    books: PackBook[];
+  } | null>(null);
+  const [packSubmitting, setPackSubmitting] = useState(false);
  const isCombinedMode = combinedMode != null;
  const combinedPhase = combinedMode?.phase ?? null;
  const combinedStepLabel = combinedMode?.stepLabel ?? '';
@@ -869,6 +890,11 @@ const ReleaseModalSession = ({
    } finally {
      setIsRequestingBook(false);
    }
+    // Kept against the advisory: the body really does read both. `handleClose` is aliased
+    // from the `onClose` prop, which is why the compiler names the source instead, and
+    // dropping `contentType` would let this close over a stale one and request the wrong
+    // format. Correctness first; the cost is an extra callback identity.
+    // oxlint-disable-next-line react/memo-dependencies
  }, [book, onRequestBook, isRequestingBook, contentType, handleClose]);

  const tabRefs = useRef<Record<string, HTMLButtonElement | null>>({});
@@ -1115,7 +1141,9 @@ const ReleaseModalSession = ({
    const narratorField = book.display_fields.find((f) => f.icon === 'microphone');

    return { starField, ratingsField, usersField, pagesField, lengthField, narratorField };
-  }, [book?.display_fields]);
+    // `book`, not `book?.display_fields`: the body reads `book.display_fields`
+    // unguarded after the early return, which is the dependency the compiler infers.
+  }, [book]);

  const getReleaseActionMode = useCallback(
    (release: Release): RequestPolicyMode => {
@@ -1196,7 +1224,36 @@ const ReleaseModalSession = ({

      const mode = getReleaseActionMode(release);
      if (mode === 'download') {
-        await onDownload(book, release, contentType);
+        // Look at the release's files before queueing so a whole-series pack can be
+        // reviewed and filed as separate books instead of one mangled item.
+        let inspected = false;
+        let plan: PackPlan | null = null;
+        let reason: string | null = null;
+        try {
+          const inspection = await inspectRelease(
+            buildReleaseDownloadPayload(book, release, contentType),
+          );
+          inspected = inspection.inspected;
+          plan = inspection.plan;
+          reason = inspection.reason;
+        } catch (error) {
+          console.error('Release inspection failed:', error);
+        }
+        if (inspected && plan?.is_pack) {
+          setPackReview({ release, plan, books: plan.books });
+          return;
+        }
+        // Not a pack (or couldn't be inspected): queue exactly as before. A release we
+        // couldn't inspect might still be an unnoticed pack, so leave a console breadcrumb
+        // rather than interrupting the user; the multi-book toggle forces the split.
+        if (!inspected && !multiBook) {
+          console.warn(
+            `Could not inspect release "${release.title}" before download${
+              reason ? `: ${reason}` : ''
+            }. If it contains several books, enable the multi-book pack toggle.`,
+          );
+        }
+        await onDownload(book, release, contentType, multiBook ? { multiBook: true } : {});
        handleClose();
        return;
      }
@@ -1215,9 +1272,34 @@ const ReleaseModalSession = ({
      onRequestRelease,
      contentType,
      handleClose,
+      multiBook,
    ],
  );

+  const handlePackConfirm = useCallback(
+    async (books: PackBook[] | null): Promise<void> => {
+      if (!book || !packReview) {
+        return;
+      }
+      setPackSubmitting(true);
+      try {
+        await onDownload(
+          book,
+          packReview.release,
+          contentType,
+          books ? { multiBook: true, bookPlan: toBookPlanPayload(books) } : {},
+        );
+        handleClose();
+      } finally {
+        setPackSubmitting(false);
+      }
+    },
+    // Same as handleRequestBook above: the body reads `onDownload`, `contentType` and
+    // `handleClose`, so they stay in the list whatever the advisory infers.
+    // oxlint-disable-next-line react/memo-dependencies
+    [book, packReview, onDownload, contentType, handleClose],
+  );
+
  const titleId = `release-modal-title-${book.id}`;
  const providerDisplay =
    book.provider_display_name ||
@@ -1720,6 +1802,37 @@ const ReleaseModalSession = ({
                  </div>

                  <div className="flex items-center gap-3 pr-1 pl-2">
+                    {/* Multi-book pack toggle (fallback for releases that can't be inspected) */}
+                    {!isCombinedMode && (
+                      <button
+                        type="button"
+                        onClick={() => setMultiBook((prev) => !prev)}
+                        className={`hover-surface relative rounded-full p-2.5 text-zinc-500 transition-colors dark:text-zinc-400 ${
+                          multiBook ? 'text-emerald-600 dark:text-emerald-400' : ''
+                        }`}
+                        aria-label="Multi-book pack"
+                        aria-pressed={multiBook}
+                        title="Multi-book pack: file each subfolder (or each file) as a separate book. Only needed when a release can't be inspected before download."
+                      >
+                        <svg
+                          className="h-4 w-4"
+                          fill="none"
+                          stroke="currentColor"
+                          viewBox="0 0 24 24"
+                          strokeWidth={1.5}
+                        >
+                          <path
+                            strokeLinecap="round"
+                            strokeLinejoin="round"
+                            d="M6.429 9.75 2.25 12l4.179 2.25m0-4.5 5.571 3 5.571-3m-11.142 0L2.25 7.5 12 2.25l9.75 5.25-4.179 2.25m0 0L21.75 12l-4.179 2.25m0 0 4.179 2.25L12 21.75 2.25 16.5l4.179-2.25m11.142 0-5.571 3-5.571-3"
+                          />
+                        </svg>
+                        {multiBook && (
+                          <span className="absolute top-1 right-1 h-2 w-2 rounded-full bg-emerald-500" />
+                        )}
+                      </button>
+                    )}
+
                    {/* Manual query button */}
                    <button
                      type="button"
@@ -2120,6 +2233,19 @@ const ReleaseModalSession = ({
            {/* Release list content */}
            <div className="min-h-[200px]">
              {(() => {
+                if (packReview) {
+                  return (
+                    <PackReviewPanel
+                      release={packReview.release}
+                      plan={packReview.plan}
+                      books={packReview.books}
+                      onChange={(books) => setPackReview({ ...packReview, books })}
+                      onBack={() => setPackReview(null)}
+                      onConfirm={handlePackConfirm}
+                      isSubmitting={packSubmitting}
+                    />
+                  );
+                }
                if (sourcesLoading) {
                  return <ReleaseSkeleton />;
                }
@@ -2335,7 +2461,7 @@ const ReleaseModalSession = ({

 export const ReleaseModal = ({ book, onClose, ...rest }: ReleaseModalProps) => {
  const [isClosing, setIsClosing] = useState(false);
-  const previousSessionKeyRef = useRef<string | null>(null);
+  const [enterAnimation, setEnterAnimation] = useState(INITIAL_ENTER_ANIMATION);

  const handleClose = useCallback(() => {
    setIsClosing(true);
@@ -2359,12 +2485,13 @@ export const ReleaseModal = ({ book, onClose, ...rest }: ReleaseModalProps) => {
      ].join('|')
    : null;

-  const animateEnter =
-    !rest.combinedMode ||
-    previousSessionKeyRef.current === null ||
-    previousSessionKeyRef.current === sessionKey;
-
-  previousSessionKeyRef.current = sessionKey;
+  // Decided once per session key and held for that session's lifetime, so a
+  // re-render mid-session cannot restart the enter animation.
+  const nextAnimation = nextEnterAnimation(enterAnimation, sessionKey, rest.combinedMode != null);
+  if (nextAnimation !== enterAnimation) {
+    setEnterAnimation(nextAnimation);
+  }
+  const animateEnter = nextAnimation.animate;

  if (!book && !isClosing) return null;
  if (!book || !sessionKey) return null;
@@ -3,8 +3,8 @@ import { forwardRef, useImperativeHandle, useMemo, useRef, useState } from 'reac

 import { useSearchMode } from '../contexts/SearchModeContext';
 import { useSearchBarAutocomplete } from '../hooks/searchBar/useSearchBarAutocomplete';
-import { useSearchBarHoverTimeout } from '../hooks/searchBar/useSearchBarHoverTimeout';
 import { useDismiss } from '../hooks/useDismiss';
+import { useLatestCallback } from '../hooks/useLatestCallback';
 import type { DynamicFieldOption } from '../services/api';
 import type { ContentType, MetadataSearchField, QueryTargetOption, SortOption } from '../types';
 import { SearchBarAutocompleteSession } from './SearchBarAutocompleteSession';
@@ -51,6 +51,8 @@ const EMPTY_SORT_OPTIONS: SortOption[] = [];
 const EMPTY_AUTOCOMPLETE_OPTIONS: DynamicFieldOption[] = [];
 const EMPTY_QUERY_TARGETS: QueryTargetOption[] = [];

+const SEARCH_CONTROLS_PANEL_ID = 'search-bar-controls-panel';
+
 const BookIcon = () => (
  <svg
    className="h-5 w-5 shrink-0"
@@ -195,8 +197,9 @@ export const SearchBar = forwardRef<SearchBarHandle, SearchBarProps>(
    const { searchMode } = useSearchMode();
    const inputRef = useRef<HTMLInputElement>(null);
    const buttonRef = useRef<HTMLButtonElement>(null);
-    const onSubmitRef = useRef(onSubmit);
-    onSubmitRef.current = onSubmit;
+    // Deferred submits below run from a timeout, not an Effect, so this is a latest-value
+    // callback rather than an Effect Event. See useLatestCallback.
+    const submitLatest = useLatestCallback(() => onSubmit());
    const selectorRef = useRef<HTMLDivElement>(null);
    const hasSearchQuery = hasActiveValue(value);
    const [isSelectorOpen, setIsSelectorOpen] = useState(false);
@@ -205,7 +208,7 @@ export const SearchBar = forwardRef<SearchBarHandle, SearchBarProps>(
    const selectTriggerRef = useRef<HTMLButtonElement>(null);
    const selectPanelRef = useRef<HTMLDivElement>(null);
    const autocompletePanelRef = useRef<HTMLDivElement>(null);
-    const { hoverTimeoutRef: selectorHoverTimeout, clearHoverTimeout } = useSearchBarHoverTimeout();
+    const controlsPanelRef = useRef<HTMLDivElement>(null);

    const hasMultipleContentTypes = !allowedContentTypes || allowedContentTypes.length !== 1;
    const showContentTypeSelector =
@@ -221,9 +224,20 @@ export const SearchBar = forwardRef<SearchBarHandle, SearchBarProps>(
      () => queryTargets.find((target) => target.key === activeQueryTarget) ?? queryTargets[0],
      [queryTargets, activeQueryTarget],
    );
-    const showActiveTargetLabel = queryTargets.length > 0 && activeTarget.source !== 'general';
+    const showActiveTargetLabel = queryTargets.length > 0 && activeTarget?.source !== 'general';

-    useDismiss(isSelectorOpen, [selectorRef], () => setIsSelectorOpen(false));
+    // Manual search browses release sources directly, one media type at a time — the
+    // combined ("both") flow doesn't apply. Present a plain, switchable Books/Audiobooks
+    // choice for it, even when combined search is forced on for metadata targets.
+    const isManualTarget = activeTarget?.source === 'manual';
+    const combinedSelectionActive = combinedMode && !isManualTarget;
+    const combinedSelectorLocked = combinedModeLocked && !isManualTarget;
+    const combinedToggleAvailable = !!onCombinedModeChange && !isManualTarget;
+    const combinedLineColor = combinedSelectionActive
+      ? 'bg-emerald-500'
+      : 'bg-(--border-muted) group-hover:bg-zinc-400 dark:group-hover:bg-zinc-500';
+
+    useDismiss(isSelectorOpen, [selectorRef, controlsPanelRef], () => setIsSelectorOpen(false));
    useDismiss(isSelectOpen, [selectPanelRef, selectTriggerRef], () => setIsSelectOpen(false));
    useDismiss(isAutocompleteOpen, [autocompletePanelRef, inputRef], () =>
      setIsAutocompleteOpen(false),
@@ -325,18 +339,15 @@ export const SearchBar = forwardRef<SearchBarHandle, SearchBarProps>(
    const handleContentTypeSelect = (type: ContentType) => {
      onContentTypeChange?.(type);
      onCombinedModeChange?.(false);
-      setIsSelectorOpen(false);
    };

    const handleCombinedModeSelect = () => {
      if (combinedMode) {
-        // Toggle off — revert to ebook-only
        onCombinedModeChange?.(false);
      } else {
        onContentTypeChange?.('ebook');
        onCombinedModeChange?.(true);
      }
-      setIsSelectorOpen(false);
    };

    const handleQueryTargetSelect = (targetKey: string) => {
@@ -349,14 +360,13 @@ export const SearchBar = forwardRef<SearchBarHandle, SearchBarProps>(
      setIsSelectOpen(shouldOpenSelect);
      setIsAutocompleteOpen(false);
      resetAutocomplete();
-      setIsSelectorOpen(false);
    };

    const effectivePlaceholder = getDefaultPlaceholder(
      contentType,
      activeTarget,
      placeholder,
-      combinedMode,
+      combinedSelectionActive,
    );
    const effectiveInputAriaLabel = activeTarget
      ? `${inputAriaLabel}: ${activeTarget.label}`
@@ -404,7 +414,6 @@ export const SearchBar = forwardRef<SearchBarHandle, SearchBarProps>(
                setAutocompleteDraftValue(nextValue);
                setIsAutocompleteOpen(nextValue.trim().length >= autocompleteMinQueryLength);
                setIsSelectOpen(false);
-                setIsSelectorOpen(false);
                onChange(nextValue);
                return;
              }
@@ -416,7 +425,6 @@ export const SearchBar = forwardRef<SearchBarHandle, SearchBarProps>(
                textInputValue.trim().length >= autocompleteMinQueryLength
              ) {
                setIsAutocompleteOpen(true);
-                setIsSelectorOpen(false);
              }
            }}
            onKeyDown={handleKeyDown}
@@ -482,7 +490,6 @@ export const SearchBar = forwardRef<SearchBarHandle, SearchBarProps>(
              onClick={() => {
                if (!disabled && !isDynamicLoading) {
                  setIsSelectOpen((prev) => !prev);
-                  setIsSelectorOpen(false);
                  setIsAutocompleteOpen(false);
                }
              }}
@@ -537,7 +544,7 @@ export const SearchBar = forwardRef<SearchBarHandle, SearchBarProps>(

    let selectorContentTypeLabel = 'audiobooks';
    let selectorIcon = <AudiobookIcon />;
-    if (combinedMode) {
+    if (combinedSelectionActive) {
      selectorContentTypeLabel = 'books and audiobooks';
      selectorIcon = <BothIcon />;
    } else if (contentType === 'ebook') {
@@ -593,25 +600,7 @@ export const SearchBar = forwardRef<SearchBarHandle, SearchBarProps>(
          }}
        >
          {showQueryTargetSelector && (
-            <div
-              className="relative flex shrink-0 self-stretch"
-              ref={selectorRef}
-              onPointerEnter={(e) => {
-                if (e.pointerType !== 'mouse') return;
-                clearHoverTimeout();
-                setIsSelectorOpen(true);
-                setIsSelectOpen(false);
-                setIsAutocompleteOpen(false);
-              }}
-              onPointerLeave={(e) => {
-                if (e.pointerType !== 'mouse') return;
-                clearHoverTimeout();
-                selectorHoverTimeout.current = setTimeout(() => {
-                  setIsSelectorOpen(false);
-                  selectorHoverTimeout.current = null;
-                }, 150);
-              }}
-            >
+            <div className="relative flex shrink-0 self-stretch" ref={selectorRef}>
              <button
                type="button"
                onClick={() => {
@@ -619,11 +608,11 @@ export const SearchBar = forwardRef<SearchBarHandle, SearchBarProps>(
                  setIsSelectOpen(false);
                  setIsAutocompleteOpen(false);
                }}
-                className="hover-action flex items-center gap-1.5 rounded-l-full pr-2 pl-5 transition-colors"
+                className="hover-action flex cursor-pointer items-center gap-1.5 rounded-l-full pr-2 pl-5 transition-colors"
                style={{ color: 'var(--text)' }}
                aria-label={`Searching ${selectorContentTypeLabel} by ${activeTarget?.label ?? 'general'}. Click to change.`}
                aria-expanded={isSelectorOpen}
-                aria-haspopup="dialog"
+                aria-controls={SEARCH_CONTROLS_PANEL_ID}
              >
                {selectorIcon}
                {showActiveTargetLabel && (
@@ -646,266 +635,10 @@ export const SearchBar = forwardRef<SearchBarHandle, SearchBarProps>(
                  />
                </svg>
              </button>
-
              <div
                className="absolute top-1/2 right-0 h-6 w-px -translate-y-1/2"
                style={{ background: 'var(--border-muted)' }}
              />
-
-              {isSelectorOpen && (
-                <div
-                  className="animate-fade-in-down absolute top-full left-0 z-50 mt-2 w-[min(20rem,calc(100vw-2rem))] overflow-hidden rounded-2xl border shadow-2xl"
-                  style={{
-                    background: 'var(--bg)',
-                    borderColor: 'var(--border-muted)',
-                  }}
-                  role="dialog"
-                  aria-label="Search context"
-                >
-                  <div className="max-h-[min(24rem,calc(100vh-8rem))] overflow-y-auto p-3">
-                    {showContentTypeSelector && (
-                      <div
-                        className={`border-b ${onCombinedModeChange ? 'pb-0' : 'pb-3'}`}
-                        style={{ borderColor: 'var(--border-muted)' }}
-                      >
-                        <div className="flex items-center justify-between px-1 pb-2">
-                          <span className="text-xs font-medium tracking-wide uppercase opacity-60">
-                            Content
-                          </span>
-                          {onAdvancedToggle && (
-                            <button
-                              type="button"
-                              onClick={() => {
-                                setIsSelectorOpen(false);
-                                onAdvancedToggle();
-                              }}
-                              className={`-mt-1.5 -mr-1 -mb-0.5 flex items-center gap-1.5 rounded-xl px-4 py-2.5 text-xs font-medium transition-colors ${
-                                isAdvancedActive ? 'bg-emerald-600 text-white' : 'hover-surface'
-                              }`}
-                              style={
-                                isAdvancedActive
-                                  ? { borderColor: 'rgb(16 185 129 / 0.7)' }
-                                  : { color: 'var(--text-muted)' }
-                              }
-                            >
-                              <svg
-                                className="h-3.5 w-3.5"
-                                xmlns="http://www.w3.org/2000/svg"
-                                fill="none"
-                                viewBox="0 0 24 24"
-                                strokeWidth="1.5"
-                                stroke="currentColor"
-                                aria-hidden="true"
-                              >
-                                <path
-                                  strokeLinecap="round"
-                                  strokeLinejoin="round"
-                                  d="M10.5 6h9.75M10.5 6a1.5 1.5 0 1 1-3 0m3 0a1.5 1.5 0 1 0-3 0M3.75 6H7.5m3 12h9.75m-9.75 0a1.5 1.5 0 0 1-3 0m3 0a1.5 1.5 0 0 0-3 0m-3.75 0H7.5m9-6h3.75m-3.75 0a1.5 1.5 0 0 1-3 0m3 0a1.5 1.5 0 0 0-3 0m-9.75 0h9.75"
-                                />
-                              </svg>
-                              Options
-                            </button>
-                          )}
-                        </div>
-                        <div className="grid grid-cols-2 gap-2">
-                          <button
-                            type="button"
-                            onClick={() => handleContentTypeSelect('ebook')}
-                            className={`flex items-center gap-2 rounded-xl border px-3 py-2 text-sm font-medium transition-colors ${
-                              contentType === 'ebook' || combinedMode
-                                ? 'bg-emerald-600 text-white'
-                                : 'hover-surface'
-                            }`}
-                            style={
-                              contentType === 'ebook' || combinedMode
-                                ? { borderColor: 'rgb(16 185 129 / 0.7)' }
-                                : { color: 'var(--text)', borderColor: 'var(--border-muted)' }
-                            }
-                          >
-                            {contentType === 'ebook' || combinedMode ? <CheckIcon /> : <BookIcon />}
-                            <span>Books</span>
-                          </button>
-                          <button
-                            type="button"
-                            onClick={() => handleContentTypeSelect('audiobook')}
-                            className={`flex items-center gap-2 rounded-xl border px-3 py-2 text-sm font-medium transition-colors ${
-                              contentType === 'audiobook' || combinedMode
-                                ? 'bg-emerald-600 text-white'
-                                : 'hover-surface'
-                            }`}
-                            style={
-                              contentType === 'audiobook' || combinedMode
-                                ? { borderColor: 'rgb(16 185 129 / 0.7)' }
-                                : { color: 'var(--text)', borderColor: 'var(--border-muted)' }
-                            }
-                          >
-                            {contentType === 'audiobook' || combinedMode ? (
-                              <CheckIcon />
-                            ) : (
-                              <AudiobookIcon />
-                            )}
-                            <span>Audiobooks</span>
-                          </button>
-                        </div>
-                        {onCombinedModeChange &&
-                          (() => {
-                            const lineColor = combinedMode
-                              ? 'bg-emerald-500'
-                              : 'bg-(--border-muted) group-hover:bg-zinc-400 dark:group-hover:bg-zinc-500';
-                            return (
-                              <Tooltip
-                                content="Combined search"
-                                position="bottom"
-                                triggerClassName="w-full"
-                              >
-                                <button
-                                  type="button"
-                                  onClick={handleCombinedModeSelect}
-                                  className="group w-full"
-                                  aria-label="Combined search"
-                                >
-                                  {/* Bracket connector: vertical drops + horizontal bar with icon */}
-                                  <div className="relative flex h-7 items-end">
-                                    {/* Left vertical */}
-                                    <div
-                                      className={`absolute top-1.5 bottom-[11px] left-[25%] w-px transition-colors ${lineColor}`}
-                                    />
-                                    {/* Right vertical */}
-                                    <div
-                                      className={`absolute top-1.5 right-[25%] bottom-[11px] w-px transition-colors ${lineColor}`}
-                                    />
-                                    {/* Horizontal bar – left segment */}
-                                    <div
-                                      className={`absolute bottom-[11px] left-[25%] h-px transition-colors ${lineColor}`}
-                                      style={{ width: 'calc(25% - 16px)' }}
-                                    />
-                                    {/* Horizontal bar – right segment */}
-                                    <div
-                                      className={`absolute right-[25%] bottom-[11px] h-px transition-colors ${lineColor}`}
-                                      style={{ width: 'calc(25% - 16px)' }}
-                                    />
-                                    {/* Chain icon centered at bottom */}
-                                    <div
-                                      className={`relative z-10 mx-auto rounded-full p-1 transition-colors ${
-                                        combinedMode
-                                          ? 'bg-emerald-600 text-white'
-                                          : 'bg-(--bg) text-zinc-400 group-hover:bg-zinc-200 group-hover:text-zinc-600 dark:text-zinc-500 dark:group-hover:bg-zinc-700 dark:group-hover:text-zinc-300'
-                                      }`}
-                                    >
-                                      <svg
-                                        className="h-3.5 w-3.5"
-                                        fill="none"
-                                        viewBox="0 0 24 24"
-                                        strokeWidth="2"
-                                        stroke="currentColor"
-                                        aria-hidden="true"
-                                      >
-                                        {combinedModeLocked ? (
-                                          <path
-                                            strokeLinecap="round"
-                                            strokeLinejoin="round"
-                                            d="M16.5 10.5V6.75a4.5 4.5 0 1 0-9 0v3.75m-.75 11.25h10.5a2.25 2.25 0 0 0 2.25-2.25v-6.75a2.25 2.25 0 0 0-2.25-2.25H6.75a2.25 2.25 0 0 0-2.25 2.25v6.75a2.25 2.25 0 0 0 2.25 2.25Z"
-                                          />
-                                        ) : (
-                                          <path
-                                            strokeLinecap="round"
-                                            strokeLinejoin="round"
-                                            d="M13.19 8.688a4.5 4.5 0 0 1 1.242 7.244l-4.5 4.5a4.5 4.5 0 0 1-6.364-6.364l1.757-1.757m13.35-.622 1.757-1.757a4.5 4.5 0 0 0-6.364-6.364l-4.5 4.5a4.5 4.5 0 0 0 1.242 7.244"
-                                          />
-                                        )}
-                                      </svg>
-                                    </div>
-                                  </div>
-                                </button>
-                              </Tooltip>
-                            );
-                          })()}
-                      </div>
-                    )}
-
-                    <div className={showContentTypeSelector ? 'pt-2' : ''}>
-                      <div className="flex items-center justify-between px-1 pb-1.5">
-                        <span className="text-xs font-medium tracking-wide uppercase opacity-60">
-                          Search By
-                        </span>
-                        {!showContentTypeSelector && onAdvancedToggle && (
-                          <button
-                            type="button"
-                            onClick={() => {
-                              setIsSelectorOpen(false);
-                              onAdvancedToggle();
-                            }}
-                            className={`-mt-1.5 -mr-1 -mb-0.5 flex items-center gap-1.5 rounded-xl px-4 py-2.5 text-xs font-medium transition-colors ${
-                              isAdvancedActive
-                                ? `${searchMode === 'direct' ? 'bg-sky-700' : 'bg-emerald-600'} text-white`
-                                : 'hover-surface'
-                            }`}
-                            style={
-                              isAdvancedActive
-                                ? {
-                                    borderColor:
-                                      searchMode === 'direct'
-                                        ? 'rgb(3 105 161 / 0.7)'
-                                        : 'rgb(16 185 129 / 0.7)',
-                                  }
-                                : { color: 'var(--text-muted)' }
-                            }
-                          >
-                            <svg
-                              className="h-3.5 w-3.5"
-                              xmlns="http://www.w3.org/2000/svg"
-                              fill="none"
-                              viewBox="0 0 24 24"
-                              strokeWidth="1.5"
-                              stroke="currentColor"
-                              aria-hidden="true"
-                            >
-                              <path
-                                strokeLinecap="round"
-                                strokeLinejoin="round"
-                                d="M10.5 6h9.75M10.5 6a1.5 1.5 0 1 1-3 0m3 0a1.5 1.5 0 1 0-3 0M3.75 6H7.5m3 12h9.75m-9.75 0a1.5 1.5 0 0 1-3 0m3 0a1.5 1.5 0 0 0-3 0m-3.75 0H7.5m9-6h3.75m-3.75 0a1.5 1.5 0 0 1-3 0m3 0a1.5 1.5 0 0 0-3 0m-9.75 0h9.75"
-                              />
-                            </svg>
-                            Options
-                          </button>
-                        )}
-                      </div>
-                      <div className="grid grid-cols-2 gap-2">
-                        {queryTargets.map((target) => {
-                          const isActive = target.key === activeTarget?.key;
-                          return (
-                            <button
-                              type="button"
-                              key={target.key}
-                              onClick={() => handleQueryTargetSelect(target.key)}
-                              title={target.description || target.label}
-                              aria-label={target.label}
-                              className={`flex min-w-0 items-center gap-2 rounded-xl border px-3 py-2 text-sm font-medium transition-colors ${
-                                isActive
-                                  ? `${searchMode === 'direct' ? 'bg-sky-700' : 'bg-emerald-600'} text-white`
-                                  : 'hover-surface'
-                              }`}
-                              style={
-                                isActive
-                                  ? {
-                                      borderColor:
-                                        searchMode === 'direct'
-                                          ? 'rgb(3 105 161 / 0.7)'
-                                          : 'rgb(16 185 129 / 0.7)',
-                                    }
-                                  : { color: 'var(--text)', borderColor: 'var(--border-muted)' }
-                              }
-                            >
-                              {isActive && <CheckIcon />}
-                              <span className="block truncate">{target.label}</span>
-                            </button>
-                          );
-                        })}
-                      </div>
-                    </div>
-                  </div>
-                </div>
-              )}
            </div>
          )}

@@ -999,7 +732,7 @@ export const SearchBar = forwardRef<SearchBarHandle, SearchBarProps>(
                        onClick={() => {
                          onChange(option.value, option.label);
                          setIsSelectOpen(false);
-                          setTimeout(() => onSubmitRef.current(), 0);
+                          setTimeout(() => submitLatest(), 0);
                        }}
                        className={`flex w-full items-center gap-3 px-5 py-2.5 text-left text-sm transition-colors ${
                          isSelected ? '' : 'hover-surface'
@@ -1069,7 +802,7 @@ export const SearchBar = forwardRef<SearchBarHandle, SearchBarProps>(
                          setAutocompleteSelection(option.value, option.label);
                          onChange(option.value, option.label);
                          setIsAutocompleteOpen(false);
-                          setTimeout(() => onSubmitRef.current(), 0);
+                          setTimeout(() => submitLatest(), 0);
                        }}
                        className="hover-surface w-full px-5 py-3 text-left text-sm transition-colors"
                        style={{ color: 'var(--text)' }}
@@ -1087,6 +820,246 @@ export const SearchBar = forwardRef<SearchBarHandle, SearchBarProps>(
            </div>
          )}
        </div>
+
+        {showQueryTargetSelector && isSelectorOpen && (
+          <div
+            id={SEARCH_CONTROLS_PANEL_ID}
+            className="animate-fade-in-down flex flex-wrap items-start gap-x-8 gap-y-2 px-1 pt-2"
+            ref={controlsPanelRef}
+          >
+            {showContentTypeSelector && (
+              <div className="shrink-0">
+                <div className="flex items-center justify-between pb-1.5">
+                  <span className="text-xs font-medium tracking-wide uppercase opacity-60">
+                    Content
+                  </span>
+                  {onAdvancedToggle && (
+                    <button
+                      type="button"
+                      onClick={onAdvancedToggle}
+                      className={`-mt-1.5 -mr-1 -mb-0.5 flex cursor-pointer items-center gap-1.5 rounded-xl px-4 py-2.5 text-xs font-medium transition-colors ${
+                        isAdvancedActive ? 'bg-emerald-600 text-white' : 'hover-surface'
+                      }`}
+                      style={
+                        isAdvancedActive
+                          ? { borderColor: 'rgb(16 185 129 / 0.7)' }
+                          : { color: 'var(--text-muted)' }
+                      }
+                    >
+                      <svg
+                        className="h-3.5 w-3.5"
+                        xmlns="http://www.w3.org/2000/svg"
+                        fill="none"
+                        viewBox="0 0 24 24"
+                        strokeWidth="1.5"
+                        stroke="currentColor"
+                        aria-hidden="true"
+                      >
+                        <path
+                          strokeLinecap="round"
+                          strokeLinejoin="round"
+                          d="M10.5 6h9.75M10.5 6a1.5 1.5 0 1 1-3 0m3 0a1.5 1.5 0 1 0-3 0M3.75 6H7.5m3 12h9.75m-9.75 0a1.5 1.5 0 0 1-3 0m3 0a1.5 1.5 0 0 0-3 0m-3.75 0H7.5m9-6h3.75m-3.75 0a1.5 1.5 0 0 1-3 0m3 0a1.5 1.5 0 0 0-3 0m-9.75 0h9.75"
+                        />
+                      </svg>
+                      Options
+                    </button>
+                  )}
+                </div>
+                <div className="grid w-fit grid-cols-2 gap-2">
+                  <button
+                    type="button"
+                    onClick={() => handleContentTypeSelect('ebook')}
+                    className={`flex cursor-pointer items-center gap-2 rounded-xl border px-3 py-2 text-sm font-medium transition-colors ${
+                      contentType === 'ebook' || combinedSelectionActive
+                        ? 'bg-emerald-600 text-white'
+                        : 'hover-surface'
+                    }`}
+                    style={
+                      contentType === 'ebook' || combinedSelectionActive
+                        ? { borderColor: 'rgb(16 185 129 / 0.7)' }
+                        : { color: 'var(--text)', borderColor: 'var(--border-muted)' }
+                    }
+                  >
+                    <span className="flex w-4 justify-center">
+                      {contentType === 'ebook' || combinedSelectionActive ? (
+                        <CheckIcon />
+                      ) : (
+                        <BookIcon />
+                      )}
+                    </span>
+                    <span>Books</span>
+                  </button>
+                  <button
+                    type="button"
+                    onClick={() => handleContentTypeSelect('audiobook')}
+                    className={`flex cursor-pointer items-center gap-2 rounded-xl border px-3 py-2 text-sm font-medium transition-colors ${
+                      contentType === 'audiobook' || combinedSelectionActive
+                        ? 'bg-emerald-600 text-white'
+                        : 'hover-surface'
+                    }`}
+                    style={
+                      contentType === 'audiobook' || combinedSelectionActive
+                        ? { borderColor: 'rgb(16 185 129 / 0.7)' }
+                        : { color: 'var(--text)', borderColor: 'var(--border-muted)' }
+                    }
+                  >
+                    <span className="flex w-4 justify-center">
+                      {contentType === 'audiobook' || combinedSelectionActive ? (
+                        <CheckIcon />
+                      ) : (
+                        <AudiobookIcon />
+                      )}
+                    </span>
+                    <span>Audiobooks</span>
+                  </button>
+                  {combinedToggleAvailable && (
+                    <div className="col-span-2">
+                      <Tooltip
+                        content="Combined search"
+                        position="bottom"
+                        triggerClassName="w-full"
+                      >
+                        <button
+                          type="button"
+                          onClick={handleCombinedModeSelect}
+                          className="group w-full cursor-pointer"
+                          aria-label="Combined search"
+                        >
+                          <div className="relative flex h-7 items-end">
+                            <div
+                              className={`absolute top-1.5 bottom-[11px] left-[25%] w-px transition-colors ${combinedLineColor}`}
+                            />
+                            <div
+                              className={`absolute top-1.5 right-[25%] bottom-[11px] w-px transition-colors ${combinedLineColor}`}
+                            />
+                            <div
+                              className={`absolute bottom-[11px] left-[25%] h-px transition-colors ${combinedLineColor}`}
+                              style={{ width: 'calc(25% - 16px)' }}
+                            />
+                            <div
+                              className={`absolute right-[25%] bottom-[11px] h-px transition-colors ${combinedLineColor}`}
+                              style={{ width: 'calc(25% - 16px)' }}
+                            />
+                            <div
+                              className={`relative z-10 mx-auto rounded-full p-1 transition-colors ${
+                                combinedSelectionActive
+                                  ? 'bg-emerald-600 text-white'
+                                  : 'bg-(--bg) text-zinc-400 group-hover:bg-zinc-200 group-hover:text-zinc-600 dark:text-zinc-500 dark:group-hover:bg-zinc-700 dark:group-hover:text-zinc-300'
+                              }`}
+                            >
+                              <svg
+                                className="h-3.5 w-3.5"
+                                fill="none"
+                                viewBox="0 0 24 24"
+                                strokeWidth="2"
+                                stroke="currentColor"
+                                aria-hidden="true"
+                              >
+                                {combinedSelectorLocked ? (
+                                  <path
+                                    strokeLinecap="round"
+                                    strokeLinejoin="round"
+                                    d="M16.5 10.5V6.75a4.5 4.5 0 1 0-9 0v3.75m-.75 11.25h10.5a2.25 2.25 0 0 0 2.25-2.25v-6.75a2.25 2.25 0 0 0-2.25-2.25H6.75a2.25 2.25 0 0 0-2.25 2.25v6.75a2.25 2.25 0 0 0 2.25 2.25Z"
+                                  />
+                                ) : (
+                                  <path
+                                    strokeLinecap="round"
+                                    strokeLinejoin="round"
+                                    d="M13.19 8.688a4.5 4.5 0 0 1 1.242 7.244l-4.5 4.5a4.5 4.5 0 0 1-6.364-6.364l1.757-1.757m13.35-.622 1.757-1.757a4.5 4.5 0 0 0-6.364-6.364l-4.5 4.5a4.5 4.5 0 0 0 1.242 7.244"
+                                  />
+                                )}
+                              </svg>
+                            </div>
+                          </div>
+                        </button>
+                      </Tooltip>
+                    </div>
+                  )}
+                </div>
+              </div>
+            )}
+
+            {queryTargets.length > 1 && (
+              <div className="shrink-0">
+                <div className="flex items-center justify-between pb-1.5">
+                  <span className="text-xs font-medium tracking-wide uppercase opacity-60">
+                    Search By
+                  </span>
+                  {!showContentTypeSelector && onAdvancedToggle && (
+                    <button
+                      type="button"
+                      onClick={onAdvancedToggle}
+                      className={`-mt-1.5 -mr-1 -mb-0.5 flex cursor-pointer items-center gap-1.5 rounded-xl px-4 py-2.5 text-xs font-medium transition-colors ${
+                        isAdvancedActive
+                          ? `${searchMode === 'direct' ? 'bg-sky-700' : 'bg-emerald-600'} text-white`
+                          : 'hover-surface'
+                      }`}
+                      style={
+                        isAdvancedActive
+                          ? {
+                              borderColor:
+                                searchMode === 'direct'
+                                  ? 'rgb(3 105 161 / 0.7)'
+                                  : 'rgb(16 185 129 / 0.7)',
+                            }
+                          : { color: 'var(--text-muted)' }
+                      }
+                    >
+                      <svg
+                        className="h-3.5 w-3.5"
+                        xmlns="http://www.w3.org/2000/svg"
+                        fill="none"
+                        viewBox="0 0 24 24"
+                        strokeWidth="1.5"
+                        stroke="currentColor"
+                        aria-hidden="true"
+                      >
+                        <path
+                          strokeLinecap="round"
+                          strokeLinejoin="round"
+                          d="M10.5 6h9.75M10.5 6a1.5 1.5 0 1 1-3 0m3 0a1.5 1.5 0 1 0-3 0M3.75 6H7.5m3 12h9.75m-9.75 0a1.5 1.5 0 0 1-3 0m3 0a1.5 1.5 0 0 0-3 0m-3.75 0H7.5m9-6h3.75m-3.75 0a1.5 1.5 0 0 1-3 0m3 0a1.5 1.5 0 0 0-3 0m-9.75 0h9.75"
+                        />
+                      </svg>
+                      Options
+                    </button>
+                  )}
+                </div>
+                <div className="flex flex-wrap gap-2">
+                  {queryTargets.map((target) => {
+                    const isActive = target.key === activeTarget?.key;
+                    return (
+                      <button
+                        type="button"
+                        key={target.key}
+                        onClick={() => handleQueryTargetSelect(target.key)}
+                        title={target.description || target.label}
+                        aria-label={target.label}
+                        className={`flex min-w-0 cursor-pointer items-center gap-2 rounded-xl border px-3 py-2 text-sm font-medium transition-colors ${
+                          isActive
+                            ? `${searchMode === 'direct' ? 'bg-sky-700' : 'bg-emerald-600'} text-white`
+                            : 'hover-surface'
+                        }`}
+                        style={
+                          isActive
+                            ? {
+                                borderColor:
+                                  searchMode === 'direct'
+                                    ? 'rgb(3 105 161 / 0.7)'
+                                    : 'rgb(16 185 129 / 0.7)',
+                              }
+                            : { color: 'var(--text)', borderColor: 'var(--border-muted)' }
+                        }
+                      >
+                        {isActive && <CheckIcon />}
+                        <span className="block truncate">{target.label}</span>
+                      </button>
+                    );
+                  })}
+                </div>
+              </div>
+            )}
+          </div>
+        )}
      </>
    );
  },
@@ -3,6 +3,7 @@ import type { Dispatch, SetStateAction } from 'react';
 import { useMountEffect } from '@/hooks/useMountEffect';
 import type { AppConfig, AdvancedFilterState, ContentType, 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';

@@ -73,10 +74,10 @@ export const UrlSearchBootstrapMount = ({
    }

    const bookLanguages = config.book_languages || [];
-    const defaultLanguageCodes =
-      config.default_language && config.default_language.length > 0
-        ? config.default_language
-        : [bookLanguages[0]?.code || 'en'];
+    const defaultLanguageCodes = resolveDefaultLanguageCodes(
+      config.default_language,
+      bookLanguages,
+    );

    if (parsedParams.searchInput) {
      setSearchInput(parsedParams.searchInput);
@@ -562,6 +562,10 @@ export const ActivityCard = ({
    }

    return () => observer.disconnect();
+    // None of these are read here - they are all re-measure triggers. The title's overflow
+    // depends on its text and on the width it is laid out in, and opening either panel
+    // reflows the card. Drop them and the tooltip-on-truncation goes stale.
+    // oxlint-disable-next-line react/exhaustive-effect-dependencies
  }, [item.title, item.author, isRequestDetailsOpen, isRequestRejectOpen]);

  const reviewRecord = item.requestRecord;
@@ -347,6 +347,10 @@ function SettingsContentPanel({
    if (scrollRef.current) {
      scrollRef.current.scrollTop = 0;
    }
+    // `tab.name` is never read here - it is the trigger, and the whole point: the scroll
+    // position resets *because* the tab changed. Removing it strands the new tab at the
+    // previous one's offset.
+    // oxlint-disable-next-line react/exhaustive-effect-dependencies
  }, [embedded, tab.name]);

  const updateCustomFieldUiState = useCallback((fieldKey: string, key: string, value: unknown) => {
@@ -407,6 +411,9 @@ function SettingsContentPanel({
    if (scrollRef.current) {
      scrollRef.current.scrollTop = 0;
    }
+    // `activeTakeOverFieldKey` is never read here - it is the trigger. Entering or leaving
+    // a subpage takeover is exactly when the scroll must reset.
+    // oxlint-disable-next-line react/exhaustive-effect-dependencies
  }, [embedded, activeTakeOverFieldKey]);

  const visibleFields = useMemo(() => {
@@ -1,5 +1,6 @@
 import { useCallback, useLayoutEffect, useRef } from 'react';

+import { useLatestCallback } from '../../../hooks/useLatestCallback';
 import { useMountEffect } from '../../../hooks/useMountEffect';
 import type { AdminUser } from '../../../services/api';
 import { testAdminUserNotificationPreferences } from '../../../services/api';
@@ -169,12 +170,12 @@ export const UsersManagementField = ({
    }
  }, [backToList, onRefreshOverrideSummary, onSettingsSaved, onUiStateChange, saveEditedUser]);

-  const handleSaveUserOverridesRef = useRef(handleSaveUserOverrides);
-  handleSaveUserOverridesRef.current = handleSaveUserOverrides;
-
-  const triggerSaveUserOverrides = useCallback(async () => {
-    await handleSaveUserOverridesRef.current();
-  }, []);
+  // Stored in parent UI state, so it must keep a stable identity while still invoking the
+  // latest handler. Not an Effect Event: those must not be handed to another component.
+  // See useLatestCallback.
+  const triggerSaveUserOverrides = useLatestCallback(async () => {
+    await handleSaveUserOverrides();
+  });

  const handleOpenOverrides = () => {
    if (editingUser) {
@@ -44,162 +44,172 @@ const getOptionsIdentity = (options: MultiSelectFieldConfig['options']): string
 const getSelectionIdentity = (values: string[]): string =>
  values.toSorted((left, right) => left.localeCompare(right)).join('\u0001');

-export const MultiSelectField = ({
+interface MultiSelectVariantProps {
+  field: MultiSelectFieldConfig;
+  selected: string[];
+  onChange: (value: string[]) => void;
+  isDisabled: boolean;
+}
+
+// Dropdown variant - use DropdownList with checkboxes
+const MultiSelectDropdownField = ({
  field,
-  value: fieldValue,
+  selected,
  onChange,
-  disabled,
-}: MultiSelectFieldProps) => {
-  const selected = fieldValue ?? EMPTY_SELECTION;
-  // disabled prop is already computed by SettingsContent.getDisabledState()
-  const isDisabled = disabled ?? false;
+  isDisabled,
+}: MultiSelectVariantProps) => {
+  const optionValues = field.options.map((opt) => opt.value);
+  const optionSet = new Set(optionValues);
+  const hasAllOption = optionSet.has(ALL_OPTION_VALUE);
+  const orderedOptions = hasAllOption
+    ? [
+        ...field.options.filter((opt) => opt.value === ALL_OPTION_VALUE),
+        ...field.options.filter((opt) => opt.value !== ALL_OPTION_VALUE),
+      ]
+    : field.options;
+  const nonAllValues = orderedOptions
+    .map((opt) => opt.value)
+    .filter((optValue) => optValue !== ALL_OPTION_VALUE);

-  // Dropdown variant - use DropdownList with checkboxes
-  if (field.variant === 'dropdown') {
-    const optionValues = field.options.map((opt) => opt.value);
-    const optionSet = new Set(optionValues);
-    const hasAllOption = optionSet.has(ALL_OPTION_VALUE);
-    const orderedOptions = hasAllOption
-      ? [
-          ...field.options.filter((opt) => opt.value === ALL_OPTION_VALUE),
-          ...field.options.filter((opt) => opt.value !== ALL_OPTION_VALUE),
-        ]
-      : field.options;
-    const nonAllValues = orderedOptions
-      .map((opt) => opt.value)
-      .filter((optValue) => optValue !== ALL_OPTION_VALUE);
+  const normalizeValues = (values: string[]): string[] => {
+    const deduped = new Set(
+      values
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length > 0 && optionSet.has(entry)),
+    );
+    return orderedOptions.map((opt) => opt.value).filter((optValue) => deduped.has(optValue));
+  };

-    const normalizeValues = (values: string[]): string[] => {
-      const deduped = new Set(
-        values
-          .map((entry) => entry.trim())
-          .filter((entry) => entry.length > 0 && optionSet.has(entry)),
-      );
-      return orderedOptions.map((opt) => opt.value).filter((optValue) => deduped.has(optValue));
-    };
+  const selectedExplicit = normalizeValues(selected);
+  const allSelected =
+    hasAllOption &&
+    (selectedExplicit.includes(ALL_OPTION_VALUE) ||
+      (nonAllValues.length > 0 &&
+        nonAllValues.every((optValue) => selectedExplicit.includes(optValue))));

-    const selectedExplicit = normalizeValues(selected);
-    const allSelected =
-      hasAllOption &&
-      (selectedExplicit.includes(ALL_OPTION_VALUE) ||
-        (nonAllValues.length > 0 &&
-          nonAllValues.every((optValue) => selectedExplicit.includes(optValue))));
+  // Build parent -> children map for cascading selection
+  const parentChildMap = new Map<string, string[]>();
+  orderedOptions.forEach((opt) => {
+    if (opt.childOf) {
+      const children = parentChildMap.get(opt.childOf) || [];
+      children.push(opt.value);
+      parentChildMap.set(opt.childOf, children);
+    }
+  });

-    // Build parent -> children map for cascading selection
-    const parentChildMap = new Map<string, string[]>();
-    orderedOptions.forEach((opt) => {
-      if (opt.childOf) {
-        const children = parentChildMap.get(opt.childOf) || [];
-        children.push(opt.value);
-        parentChildMap.set(opt.childOf, children);
+  // Check which children are implicitly selected via parent
+  const selectedForCascade = allSelected
+    ? selectedExplicit.filter((optValue) => optValue !== ALL_OPTION_VALUE)
+    : selectedExplicit;
+  const implicitlySelected = new Set<string>();
+  selectedForCascade.forEach((val) => {
+    const children = parentChildMap.get(val);
+    if (children) {
+      children.forEach((child) => implicitlySelected.add(child));
+    }
+  });
+
+  // Build options with disabled state for implicitly selected children
+  const dropdownOptions = orderedOptions.map((opt) => ({
+    value: opt.value,
+    label: opt.label,
+    disabled: !allSelected && implicitlySelected.has(opt.value),
+  }));
+
+  // For display purposes:
+  // - if "all" is active, check every option
+  // - otherwise show explicit + implicit parent/child selections
+  const displayValue = allSelected
+    ? [ALL_OPTION_VALUE, ...nonAllValues]
+    : normalizeValues([...selectedExplicit, ...Array.from(implicitlySelected)]);
+
+  const handleDropdownChange = (newValue: string | string[]) => {
+    const nextValues = normalizeValues(Array.isArray(newValue) ? newValue : [newValue]);
+
+    if (hasAllOption) {
+      const includesAll = nextValues.includes(ALL_OPTION_VALUE);
+
+      // When currently "all" is active:
+      // - unticking "all" clears everything
+      // - unticking a specific option converts to explicit subset
+      if (allSelected && !includesAll && nextValues.length === nonAllValues.length) {
+        onChange([]);
+        return;
      }
-    });
-
-    // Check which children are implicitly selected via parent
-    const selectedForCascade = allSelected
-      ? selectedExplicit.filter((optValue) => optValue !== ALL_OPTION_VALUE)
-      : selectedExplicit;
-    const implicitlySelected = new Set<string>();
-    selectedForCascade.forEach((val) => {
-      const children = parentChildMap.get(val);
-      if (children) {
-        children.forEach((child) => implicitlySelected.add(child));
-      }
-    });
-
-    // Build options with disabled state for implicitly selected children
-    const dropdownOptions = orderedOptions.map((opt) => ({
-      value: opt.value,
-      label: opt.label,
-      disabled: !allSelected && implicitlySelected.has(opt.value),
-    }));
-
-    // For display purposes:
-    // - if "all" is active, check every option
-    // - otherwise show explicit + implicit parent/child selections
-    const displayValue = allSelected
-      ? [ALL_OPTION_VALUE, ...nonAllValues]
-      : normalizeValues([...selectedExplicit, ...Array.from(implicitlySelected)]);
-
-    const handleDropdownChange = (newValue: string | string[]) => {
-      const nextValues = normalizeValues(Array.isArray(newValue) ? newValue : [newValue]);
-
-      if (hasAllOption) {
-        const includesAll = nextValues.includes(ALL_OPTION_VALUE);
-
-        // When currently "all" is active:
-        // - unticking "all" clears everything
-        // - unticking a specific option converts to explicit subset
-        if (allSelected && !includesAll && nextValues.length === nonAllValues.length) {
-          onChange([]);
-          return;
-        }
-        if (allSelected && includesAll && nextValues.length < optionValues.length) {
-          onChange(nextValues.filter((entry) => entry !== ALL_OPTION_VALUE));
-          return;
-        }
-
-        if (includesAll) {
-          onChange([ALL_OPTION_VALUE]);
-          return;
-        }
-
-        // If user selects every specific option individually, collapse to "all".
-        if (
-          nonAllValues.length > 0 &&
-          nonAllValues.every((optValue) => nextValues.includes(optValue))
-        ) {
-          onChange([ALL_OPTION_VALUE]);
-          return;
-        }
+      if (allSelected && includesAll && nextValues.length < optionValues.length) {
+        onChange(nextValues.filter((entry) => entry !== ALL_OPTION_VALUE));
+        return;
      }

-      // Filter out implicitly selected values - only store explicit selections.
-      const explicitOnly = nextValues.filter((entry) => !implicitlySelected.has(entry));
-      onChange(explicitOnly);
-    };
+      if (includesAll) {
+        onChange([ALL_OPTION_VALUE]);
+        return;
+      }

-    // Custom summary formatter - only count explicit selections
-    const summaryFormatter = () => {
-      if (allSelected) {
-        return orderedOptions.find((opt) => opt.value === ALL_OPTION_VALUE)?.label || 'All';
+      // If user selects every specific option individually, collapse to "all".
+      if (
+        nonAllValues.length > 0 &&
+        nonAllValues.every((optValue) => nextValues.includes(optValue))
+      ) {
+        onChange([ALL_OPTION_VALUE]);
+        return;
      }
-      if (selectedExplicit.length === 0) {
-        return <span className="opacity-60">{field.placeholder || 'Select categories...'}</span>;
-      }
-      const selectedLabels = selectedExplicit
-        .map((v) => orderedOptions.find((o) => o.value === v)?.label)
-        .filter(Boolean);
-      if (selectedLabels.length === 1) {
-        return selectedLabels[0];
-      }
-      const [first, second, ...rest] = selectedLabels;
-      const suffix = rest.length > 0 ? ` +${rest.length}` : '';
-      return `${first}, ${second ?? ''}${suffix}`.trim();
-    };
-
-    if (isDisabled) {
-      return (
-        <div className="w-full cursor-not-allowed rounded-lg border border-(--border-muted) bg-(--bg-soft) px-3 py-2 text-sm opacity-60">
-          {summaryFormatter()}
-        </div>
-      );
    }

+    // Filter out implicitly selected values - only store explicit selections.
+    const explicitOnly = nextValues.filter((entry) => !implicitlySelected.has(entry));
+    onChange(explicitOnly);
+  };
+
+  // Custom summary formatter - only count explicit selections
+  const summaryFormatter = () => {
+    if (allSelected) {
+      return orderedOptions.find((opt) => opt.value === ALL_OPTION_VALUE)?.label || 'All';
+    }
+    if (selectedExplicit.length === 0) {
+      return <span className="opacity-60">{field.placeholder || 'Select categories...'}</span>;
+    }
+    const selectedLabels = selectedExplicit
+      .map((v) => orderedOptions.find((o) => o.value === v)?.label)
+      .filter(Boolean);
+    if (selectedLabels.length === 1) {
+      return selectedLabels[0];
+    }
+    const [first, second, ...rest] = selectedLabels;
+    const suffix = rest.length > 0 ? ` +${rest.length}` : '';
+    return `${first}, ${second ?? ''}${suffix}`.trim();
+  };
+
+  if (isDisabled) {
    return (
-      <DropdownList
-        options={dropdownOptions}
-        value={displayValue}
-        onChange={handleDropdownChange}
-        multiple
-        showCheckboxes
-        keepOpenOnSelect
-        placeholder={field.placeholder || 'Select categories...'}
-        widthClassName="w-full"
-        summaryFormatter={summaryFormatter}
-      />
+      <div className="w-full cursor-not-allowed rounded-lg border border-(--border-muted) bg-(--bg-soft) px-3 py-2 text-sm opacity-60">
+        {summaryFormatter()}
+      </div>
    );
  }
+
+  return (
+    <DropdownList
+      options={dropdownOptions}
+      value={displayValue}
+      onChange={handleDropdownChange}
+      multiple
+      showCheckboxes
+      keepOpenOnSelect
+      placeholder={field.placeholder || 'Select categories...'}
+      widthClassName="w-full"
+      summaryFormatter={summaryFormatter}
+    />
+  );
+};
+
+// Pill variant - inline toggle buttons that collapse past a threshold
+const MultiSelectPillsField = ({
+  field,
+  selected,
+  onChange,
+  isDisabled,
+}: MultiSelectVariantProps) => {
  const [isExpanded, setIsExpanded] = useState(false);
  // Initialize based on option count to avoid flash of expanded content
  const [needsCollapse, setNeedsCollapse] = useState(
@@ -353,3 +363,35 @@ export const MultiSelectField = ({
    </div>
  );
 };
+
+export const MultiSelectField = ({
+  field,
+  value: fieldValue,
+  onChange,
+  disabled,
+}: MultiSelectFieldProps) => {
+  const selected = fieldValue ?? EMPTY_SELECTION;
+  // disabled prop is already computed by SettingsContent.getDisabledState()
+  const isDisabled = disabled ?? false;
+
+  // Each variant is its own component so neither calls hooks conditionally.
+  if (field.variant === 'dropdown') {
+    return (
+      <MultiSelectDropdownField
+        field={field}
+        selected={selected}
+        onChange={onChange}
+        isDisabled={isDisabled}
+      />
+    );
+  }
+
+  return (
+    <MultiSelectPillsField
+      field={field}
+      selected={selected}
+      onChange={onChange}
+      isDisabled={isDisabled}
+    />
+  );
+};
@@ -353,12 +353,12 @@ export const TableField = ({ field, value, onChange, disabled }: TableFieldProps
                );
              }

-              // text/path
+              // text/password/path
              return (
                <div key={col.key} className="flex min-w-0 flex-col gap-1">
                  {mobileLabel}
                  <input
-                    type="text"
+                    type={col.type === 'password' ? 'password' : 'text'}
                    value={toPrimitiveString(cellValue)}
                    onChange={(e) => updateCell(rowIndex, col.key, e.target.value)}
                    placeholder={col.placeholder}
@@ -7,7 +7,12 @@ import type {
 } from '../../../types/settings';
 import { HeadingField, MultiSelectField, SelectField, TextField } from '../fields';
 import { FieldWrapper } from '../shared';
-import { getFieldByKey, toNormalizedLowercaseTextValue, toTextValue } from './fieldHelpers';
+import {
+  getFieldByKey,
+  resolveListOverride,
+  toNormalizedLowercaseTextValue,
+  toTextValue,
+} from './fieldHelpers';
 import type { PerUserSettings } from './types';

 interface UserOverridesSectionProps {
@@ -175,16 +180,6 @@ export const UserOverridesSection = ({
    label: 'Email Recipient',
    description: 'Email address used for this user in Email output mode.',
  };
-  const browserDownloadGlobalValue = Array.isArray(globalValues.DOWNLOAD_TO_BROWSER_CONTENT_TYPES)
-    ? globalValues.DOWNLOAD_TO_BROWSER_CONTENT_TYPES.map((entry) => String(entry).trim()).filter(
-        (entry) => entry.length > 0,
-      )
-    : [];
-  const browserDownloadUserValue = Array.isArray(userSettings.DOWNLOAD_TO_BROWSER_CONTENT_TYPES)
-    ? userSettings.DOWNLOAD_TO_BROWSER_CONTENT_TYPES.map((entry) => entry.trim()).filter(
-        (entry) => entry.length > 0,
-      )
-    : [];

  const isOverridden = (key: DeliverySettingKey): boolean => {
    if (
@@ -200,10 +195,12 @@ export const UserOverridesSection = ({
    return userValue !== globalValue;
  };

-  const isBrowserDownloadOverridden =
-    Object.prototype.hasOwnProperty.call(userSettings, 'DOWNLOAD_TO_BROWSER_CONTENT_TYPES') &&
-    userSettings.DOWNLOAD_TO_BROWSER_CONTENT_TYPES !== null &&
-    JSON.stringify(browserDownloadUserValue) !== JSON.stringify(browserDownloadGlobalValue);
+  const { value: browserDownloadContentTypes, isOverridden: isBrowserDownloadOverridden } =
+    resolveListOverride(
+      userSettings.DOWNLOAD_TO_BROWSER_CONTENT_TYPES,
+      globalValues.DOWNLOAD_TO_BROWSER_CONTENT_TYPES,
+      Object.prototype.hasOwnProperty.call(userSettings, 'DOWNLOAD_TO_BROWSER_CONTENT_TYPES'),
+    );

  const resetKeys = (keys: DeliverySettingKey[]) => {
    setUserSettings((prev) => {
@@ -232,9 +229,6 @@ export const UserOverridesSection = ({
  const outputModeValue = readValue('BOOKS_OUTPUT_MODE', 'folder');
  const effectiveOutputMode = normalizeMode(outputModeValue);

-  const browserDownloadContentTypes = isBrowserDownloadOverridden
-    ? browserDownloadUserValue
-    : browserDownloadGlobalValue;
  const destinationValue = readValue('DESTINATION');
  const destinationAudiobookValue = readValue('DESTINATION_AUDIOBOOK');
  const libraryValue = readValue('BOOKLORE_LIBRARY_ID');
@@ -1,8 +1,17 @@
 import type { DeliveryPreferencesResponse } from '../../../services/api';
-import type { HeadingFieldConfig, SelectFieldConfig } from '../../../types/settings';
-import { HeadingField, SelectField } from '../fields';
+import type {
+  HeadingFieldConfig,
+  MultiSelectFieldConfig,
+  SelectFieldConfig,
+} from '../../../types/settings';
+import { HeadingField, MultiSelectField, SelectField } from '../fields';
 import { FieldWrapper } from '../shared';
-import { getFieldByKey, toNormalizedLowercaseTextValue, toTextValue } from './fieldHelpers';
+import {
+  getFieldByKey,
+  resolveListOverride,
+  toNormalizedLowercaseTextValue,
+  toTextValue,
+} from './fieldHelpers';
 import type { PerUserSettings } from './types';

 interface UserSearchPreferencesSectionProps {
@@ -14,6 +23,7 @@ interface UserSearchPreferencesSectionProps {

 type SearchSettingKey =
  | 'SEARCH_MODE'
+  | 'BOOK_LANGUAGE'
  | 'METADATA_PROVIDER'
  | 'METADATA_PROVIDER_AUDIOBOOK'
  | 'DEFAULT_RELEASE_SOURCE'
@@ -68,6 +78,15 @@ const fallbackDefaultAudiobookReleaseSourceField: SelectFieldConfig = {
  options: [{ value: '', label: 'Use book release source' }],
 };

+const fallbackBookLanguageField: MultiSelectFieldConfig = {
+  type: 'MultiSelectField',
+  key: 'BOOK_LANGUAGE',
+  label: 'Default Book Languages',
+  description: 'Default language filter for searches.',
+  value: [],
+  options: [],
+};
+
 const searchHeading: HeadingFieldConfig = {
  type: 'HeadingField',
  key: 'search_preferences_heading',
@@ -120,6 +139,13 @@ export const UserSearchPreferencesSection = ({
    'DEFAULT_RELEASE_SOURCE_AUDIOBOOK',
    fallbackDefaultAudiobookReleaseSourceField,
  );
+  const bookLanguageField = getFieldByKey(fields, 'BOOK_LANGUAGE', fallbackBookLanguageField);
+
+  const { value: bookLanguageValue, isOverridden: isBookLanguageOverridden } = resolveListOverride(
+    userSettings.BOOK_LANGUAGE,
+    globalValues.BOOK_LANGUAGE,
+    Object.prototype.hasOwnProperty.call(userSettings, 'BOOK_LANGUAGE'),
+  );

  const isOverridden = (key: SearchSettingKey): boolean => {
    if (
@@ -172,9 +198,12 @@ export const UserSearchPreferencesSection = ({
  const canOverrideDefaultAudiobookReleaseSource =
    isUserOverridable('DEFAULT_RELEASE_SOURCE_AUDIOBOOK') &&
    preferenceKeySet.has('DEFAULT_RELEASE_SOURCE_AUDIOBOOK');
+  const canOverrideBookLanguage =
+    isUserOverridable('BOOK_LANGUAGE') && preferenceKeySet.has('BOOK_LANGUAGE');

  if (
    !canOverrideSearchMode &&
+    !canOverrideBookLanguage &&
    !canOverrideMetadataProvider &&
    !canOverrideAudiobookMetadataProvider &&
    !canOverrideDefaultReleaseSource &&
@@ -208,6 +237,27 @@ export const UserSearchPreferencesSection = ({
        </FieldWrapper>
      )}

+      {canOverrideBookLanguage && (
+        <FieldWrapper
+          field={bookLanguageField}
+          resetAction={
+            isBookLanguageOverridden
+              ? {
+                  disabled: Boolean(bookLanguageField.fromEnv),
+                  onClick: () => resetKeys(['BOOK_LANGUAGE']),
+                }
+              : undefined
+          }
+        >
+          <MultiSelectField
+            field={bookLanguageField}
+            value={bookLanguageValue}
+            onChange={(value) => setUserSettings((prev) => ({ ...prev, BOOK_LANGUAGE: value }))}
+            disabled={Boolean(bookLanguageField.fromEnv)}
+          />
+        </FieldWrapper>
+      )}
+
      {effectiveSearchMode === 'universal' && canOverrideMetadataProvider && (
        <FieldWrapper
          field={metadataProviderField}
@@ -31,6 +31,33 @@ export const toNormalizedLowercaseTextValue = (value: unknown): string => {
  return toTrimmedTextValue(value).toLowerCase();
 };

+const toStringListValue = (value: unknown): string[] => {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value.map((entry) => toTrimmedTextValue(entry)).filter((entry) => entry.length > 0);
+};
+
+/**
+ * Resolve a list-valued per-user override against its global value.
+ *
+ * A key absent from userSettings, or set to null, is not an override. A stored list
+ * that matches the global one is treated as inherited, matching how
+ * buildUserSettingsPayload clears it on save.
+ */
+export const resolveListOverride = (
+  userValue: unknown,
+  globalValue: unknown,
+  hasUserKey: boolean,
+): { value: string[]; isOverridden: boolean } => {
+  const globalList = toStringListValue(globalValue);
+  const userList = toStringListValue(userValue);
+  const isOverridden =
+    hasUserKey && userValue !== null && JSON.stringify(userList) !== JSON.stringify(globalList);
+
+  return { value: isOverridden ? userList : globalList, isOverridden };
+};
+
 export const toComparableValue = (value: unknown): string => {
  if (value === null || value === undefined) {
    return '';
@@ -10,6 +10,7 @@ export interface PerUserSettings {
  EMAIL_RECIPIENT?: string;
  DOWNLOAD_TO_BROWSER_CONTENT_TYPES?: string[];
  SEARCH_MODE?: string;
+  BOOK_LANGUAGE?: string[];
  METADATA_PROVIDER?: string;
  METADATA_PROVIDER_AUDIOBOOK?: string;
  DEFAULT_RELEASE_SOURCE?: string;
@@ -139,6 +139,10 @@ export function Tooltip({
    }

    if (deltaX !== 0 || deltaY !== 0) {
+      // Genuine measure-and-adjust: the tooltip must be laid out before we know
+      // whether it overflows the viewport. The loop converges in one pass because
+      // the corrected position yields deltaX/deltaY of 0 on the next run.
+      // oxlint-disable-next-line react/set-state-in-effect
      setCoords((current) => {
        if (!current) {
          return current;
@@ -1,8 +1,8 @@
-import { useRef } from 'react';
+import { useEffectEvent } from 'react';
 import type { Dispatch, SetStateAction } from 'react';

 import type { Book } from '../../types';
-import { onBookTargetChange } from '../../utils/bookTargetEvents';
+import { onBookTargetChange, type BookTargetChangeEvent } from '../../utils/bookTargetEvents';
 import { useMountEffect } from '../useMountEffect';

 interface UseBookTargetDeselectSyncOptions {
@@ -14,15 +14,14 @@ export const useBookTargetDeselectSync = ({
  activeListValue,
  setBooks,
 }: UseBookTargetDeselectSyncOptions): void => {
-  const activeListValueRef = useRef(activeListValue);
-  activeListValueRef.current = activeListValue;
-
-  useMountEffect(() => {
-    return onBookTargetChange((event) => {
-      if (event.selected) return;
-      const currentValue = activeListValueRef.current;
-      if (!currentValue || String(currentValue) !== event.target) return;
-      setBooks((prev) => prev.filter((book) => book.provider_id !== event.bookId));
-    });
+  const handleTargetChange = useEffectEvent((event: BookTargetChangeEvent) => {
+    if (event.selected) return;
+    if (!activeListValue || String(activeListValue) !== event.target) return;
+    setBooks((prev) => prev.filter((book) => book.provider_id !== event.bookId));
  });
+
+  // Wrapped rather than handed over directly: an Effect Event must not be given to
+  // something that stores it, and `onBookTargetChange` puts its argument in a
+  // module-level listener set. Same shape as useDismiss.
+  useMountEffect(() => onBookTargetChange((event) => handleTargetChange(event)));
 };
@@ -1,11 +1,17 @@
-import { useCallback, useRef, useState } from 'react';
+import { useCallback, useState } from 'react';
 import type { Dispatch, SetStateAction } from 'react';

 import type { ContentType } from '../../types';
+import { useDependencyEffect } from '../useMountEffect';

 const CONTENT_TYPE_STORAGE_KEY = 'preferred-content-type';

-const readInitialPreference = (): { contentType: ContentType; combinedMode: boolean } => {
+interface ContentTypePreference {
+  contentType: ContentType;
+  combinedMode: boolean;
+}
+
+const readInitialPreference = (): ContentTypePreference => {
  try {
    const saved = localStorage.getItem(CONTENT_TYPE_STORAGE_KEY);
    if (saved === 'combined') {
@@ -26,53 +32,32 @@ export const useContentTypePreferences = (): {
  combinedMode: boolean;
  setCombinedMode: Dispatch<SetStateAction<boolean>>;
 } => {
-  const initialPreference = readInitialPreference();
-  const [contentType, setContentTypeState] = useState<ContentType>(
-    () => initialPreference.contentType,
-  );
-  const [combinedMode, setCombinedModeState] = useState<boolean>(
-    () => initialPreference.combinedMode,
-  );
-  const contentTypeRef = useRef(contentType);
-  const combinedModeRef = useRef(combinedMode);
-  contentTypeRef.current = contentType;
-  combinedModeRef.current = combinedMode;
+  // Both values live in one state object so each setter can derive the other
+  // from a pure updater instead of mirroring it into a ref during render.
+  const [preference, setPreference] = useState<ContentTypePreference>(readInitialPreference);
+  const { contentType, combinedMode } = preference;

-  const persistPreference = useCallback(
-    (nextContentType: ContentType, nextCombinedMode: boolean) => {
-      try {
-        localStorage.setItem(
-          CONTENT_TYPE_STORAGE_KEY,
-          nextCombinedMode ? 'combined' : nextContentType,
-        );
-      } catch {
-        // localStorage may be unavailable in private browsing
-      }
-    },
-    [],
-  );
+  const setContentType: Dispatch<SetStateAction<ContentType>> = useCallback((value) => {
+    setPreference((current) => ({
+      ...current,
+      contentType: typeof value === 'function' ? value(current.contentType) : value,
+    }));
+  }, []);

-  const setContentType: Dispatch<SetStateAction<ContentType>> = useCallback(
-    (value) => {
-      setContentTypeState((current) => {
-        const nextContentType = typeof value === 'function' ? value(current) : value;
-        persistPreference(nextContentType, combinedModeRef.current);
-        return nextContentType;
-      });
-    },
-    [persistPreference],
-  );
+  const setCombinedMode: Dispatch<SetStateAction<boolean>> = useCallback((value) => {
+    setPreference((current) => ({
+      ...current,
+      combinedMode: typeof value === 'function' ? value(current.combinedMode) : value,
+    }));
+  }, []);

-  const setCombinedMode: Dispatch<SetStateAction<boolean>> = useCallback(
-    (value) => {
-      setCombinedModeState((current) => {
-        const nextCombinedMode = typeof value === 'function' ? value(current) : value;
-        persistPreference(contentTypeRef.current, nextCombinedMode);
-        return nextCombinedMode;
-      });
-    },
-    [persistPreference],
-  );
+  useDependencyEffect(() => {
+    try {
+      localStorage.setItem(CONTENT_TYPE_STORAGE_KEY, combinedMode ? 'combined' : contentType);
+    } catch {
+      // localStorage may be unavailable in private browsing
+    }
+  }, [contentType, combinedMode]);

  return {
    contentType,
@@ -44,6 +44,10 @@ export function useDescriptionOverflow({
    return () => {
      observer.disconnect();
    };
+    // `descriptionKey` is never read here - it is the trigger. When the modal swaps to a
+    // different release the text changes under the same element, and the overflow has to
+    // be measured again; drop it and the clamp keeps the previous release's answer.
+    // oxlint-disable-next-line react/exhaustive-effect-dependencies
  }, [descriptionExpanded, descriptionKey, descriptionRef]);

  return descriptionOverflows;
@@ -164,7 +164,6 @@ export function useReleaseSearchSession(
  const lastStatusTimeRef = useRef(0);
  const pendingStatusRef = useRef<SearchStatusData | null>(null);
  const statusTimeoutRef = useRef<NodeJS.Timeout | null>(null);
-  activeTabRef.current = activeTab;

  const allTabs = useMemo(() => {
    return buildReleaseTabs(
@@ -363,7 +362,6 @@ export function useReleaseSearchSession(
    indexerFilterInitializedRef.current = new Set<string>();
    const nextInitialActiveTab = preferredDefaultReleaseSource || '';
    initialActiveTabRef.current = nextInitialActiveTab;
-    activeTabRef.current = nextInitialActiveTab;
    pendingStatusRef.current = null;
    lastStatusTimeRef.current = 0;
    if (statusTimeoutRef.current) {
@@ -381,6 +379,7 @@ export function useReleaseSearchSession(
      ? nextInitialActiveTab
      : (tabs[0]?.name ?? '');

+    activeTabRef.current = nextActiveTab;
    setActiveTabState(nextActiveTab);
    setReleasesBySource({});
    setLoadingBySource({});
@@ -458,6 +457,7 @@ export function useReleaseSearchSession(

  const setActiveTab = useCallback(
    (tabName: string) => {
+      activeTabRef.current = tabName;
      setActiveTabState(tabName);

      if (!tabName) {
@@ -1,25 +0,0 @@
-import { useCallback, useRef } from 'react';
-
-import { useMountEffect } from '@/hooks/useMountEffect';
-
-export const useSearchBarHoverTimeout = () => {
-  const hoverTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-
-  const clearHoverTimeout = useCallback(() => {
-    if (hoverTimeoutRef.current) {
-      clearTimeout(hoverTimeoutRef.current);
-      hoverTimeoutRef.current = null;
-    }
-  }, []);
-
-  useMountEffect(() => {
-    return () => {
-      clearHoverTimeout();
-    };
-  });
-
-  return {
-    hoverTimeoutRef,
-    clearHoverTimeout,
-  };
-};
@@ -5,24 +5,30 @@ interface TabIndicatorStyle {
  width: number;
 }

+// One shared instance, so the no-active-tab path below can set it repeatedly and React
+// bails out on reference equality instead of re-rendering on every resize event.
+const HIDDEN_INDICATOR: TabIndicatorStyle = { left: 0, width: 0 };
+
 export function useTabIndicator(
  tabRefs: MutableRefObject<Record<string, HTMLButtonElement | null>>,
  activeTab: string,
  tabsDependency: unknown,
 ): TabIndicatorStyle {
-  const [tabIndicatorStyle, setTabIndicatorStyle] = useState({
-    left: 0,
-    width: 0,
-  });
+  const [tabIndicatorStyle, setTabIndicatorStyle] = useState<TabIndicatorStyle>(HIDDEN_INDICATOR);

  useLayoutEffect(() => {
-    const activeButton = tabRefs.current[activeTab];
-    if (!activeButton) {
-      setTabIndicatorStyle({ left: 0, width: 0 });
-      return undefined;
-    }
-
+    // Single measurement path, so a resize that removes the active tab also
+    // resets the indicator instead of leaving it stranded.
    const updateIndicator = () => {
+      const activeButton = tabRefs.current[activeTab];
+      if (!activeButton) {
+        // The shared constant, not a fresh literal: this path now runs on every resize
+        // event, and a new object would never be Object.is-equal to the current state,
+        // so React would re-render on every frame of a window drag for an unchanged value.
+        setTabIndicatorStyle(HIDDEN_INDICATOR);
+        return;
+      }
+
      const containerRect = activeButton.parentElement?.getBoundingClientRect();
      const buttonRect = activeButton.getBoundingClientRect();
      if (!containerRect) {
@@ -41,6 +47,10 @@ export function useTabIndicator(
    return () => {
      window.removeEventListener('resize', updateIndicator);
    };
+    // `tabsDependency` is never read here - it exists only to re-run the measurement when
+    // the tab set changes (callers pass `allTabs` / `showRequestsTab`). The buttons move
+    // when tabs are added or removed, so without it the indicator sits under the old one.
+    // oxlint-disable-next-line react/exhaustive-effect-dependencies
  }, [activeTab, tabRefs, tabsDependency]);

  return tabIndicatorStyle;
@@ -1,47 +1,43 @@
-import { useEffect, useEffectEvent, useRef, type RefObject } from 'react';
+import { useEffect, useEffectEvent, type RefObject } from 'react';

 export const useDismiss = (
  isOpen: boolean,
  refs: RefObject<HTMLElement | null>[],
  onClose: () => void,
 ) => {
-  const handleClose = useEffectEvent(() => {
+  const handlePointerDown = useEffectEvent((event: MouseEvent) => {
+    const target = event.target;
+    if (!(target instanceof Node)) {
+      return;
+    }
+
+    if (refs.some((ref) => ref.current?.contains(target))) {
+      return;
+    }
+
    onClose();
  });

-  const refsRef = useRef(refs);
-  refsRef.current = refs;
+  const handleEscape = useEffectEvent((event: KeyboardEvent) => {
+    if (event.key === 'Escape') {
+      onClose();
+    }
+  });

  useEffect(() => {
    if (!isOpen) {
      return undefined;
    }

-    const handleClickOutside = (event: MouseEvent) => {
-      const target = event.target;
-      if (!(target instanceof Node)) {
-        return;
-      }
-
-      if (refsRef.current.some((ref) => ref.current?.contains(target))) {
-        return;
-      }
-
-      handleClose();
-    };
-
-    const handleEscape = (event: KeyboardEvent) => {
-      if (event.key === 'Escape') {
-        handleClose();
-      }
-    };
+    const handleClickOutside = (event: MouseEvent) => handlePointerDown(event);
+    const handleKeyDown = (event: KeyboardEvent) => handleEscape(event);

    document.addEventListener('mousedown', handleClickOutside);
-    document.addEventListener('keydown', handleEscape);
+    document.addEventListener('keydown', handleKeyDown);

    return () => {
      document.removeEventListener('mousedown', handleClickOutside);
-      document.removeEventListener('keydown', handleEscape);
+      document.removeEventListener('keydown', handleKeyDown);
    };
  }, [isOpen]);
 };
@@ -0,0 +1,31 @@
+import { useCallback, useLayoutEffect, useRef } from 'react';
+
+/**
+ * A callback with a stable identity that always runs the latest render's implementation.
+ *
+ * `useEffectEvent` is React's answer to this shape, but its contract is narrower than it
+ * looks: an Effect Event may only be called from inside an Effect, and must not be handed
+ * to another component, stored in state, or registered with something that outlives the
+ * Effect. Handlers that run from a DOM event, from an async continuation, or from a parent
+ * holding the function in its own UI state are all outside that contract - React documents
+ * the behaviour there as undefined, and the React Compiler advisories oxlint reports
+ * ("existing memoization could not be preserved") are the same fact from the other side.
+ *
+ * So this is the supported shape for those callers. The ref is published in a layout
+ * effect - after commit, before paint - rather than assigned during render, so a render
+ * React later throws away cannot leak its closure into a handler, and no event can
+ * observe the gap.
+ *
+ * Use `useEffectEvent` when the caller really is an Effect; use this everywhere else.
+ */
+export function useLatestCallback<Args extends unknown[], Result>(
+  callback: (...args: Args) => Result,
+): (...args: Args) => Result {
+  const callbackRef = useRef(callback);
+
+  useLayoutEffect(() => {
+    callbackRef.current = callback;
+  });
+
+  return useCallback((...args: Args) => callbackRef.current(...args), []);
+}
@@ -1,16 +1,14 @@
-import { useEffect, useRef, type DependencyList, type EffectCallback } from 'react';
+import { useEffect, useEffectEvent, type DependencyList, type EffectCallback } from 'react';

 export function useMountEffect(effect: EffectCallback): void {
-  const effectRef = useRef(effect);
-  effectRef.current = effect;
+  const runEffect = useEffectEvent(effect);

-  useEffect(() => effectRef.current(), []);
+  useEffect(() => runEffect(), []);
 }

 export function useDependencyEffect(effect: EffectCallback, deps: DependencyList): void {
-  const effectRef = useRef(effect);
-  effectRef.current = effect;
+  const runEffect = useEffectEvent(effect);

  // eslint-disable-next-line react-hooks/exhaustive-deps
-  useEffect(() => effectRef.current(), deps);
+  useEffect(() => runEffect(), deps);
 }
@@ -5,6 +5,7 @@ import { DEFAULT_SUPPORTED_FORMATS } from '../data/languages';
 import { searchBooks, searchMetadata, AuthenticationError } from '../services/api';
 import type { Book, AppConfig, AdvancedFilterState, ContentType, SearchMode } from '../types';
 import { LANGUAGE_OPTION_DEFAULT } from '../utils/languageFilters';
+import { describeSearchFailure } from '../utils/searchFailureMessage';

 const DEFAULT_FORMAT_SELECTION = DEFAULT_SUPPORTED_FORMATS;

@@ -263,12 +264,7 @@ export function useSearch(options: UseSearchOptions): UseSearchReturn {
          handleSearchError(error, 'Search failed');
        } else {
          console.error('Search failed:', error);
-          const message = error instanceof Error ? error.message : 'Search failed';
-          const friendly =
-            message.includes('Network restricted') || message.includes('Unable to reach')
-              ? message
-              : 'Unable to reach download source. Network may be restricted or mirrors blocked.';
-          showToast(friendly, 'error');
+          showToast(describeSearchFailure(error), 'error');
        }
      } finally {
        setIsSearching(false);
@@ -1,4 +1,4 @@
-import { useState, useCallback, useRef } from 'react';
+import { useState, useCallback } from 'react';

 import { getSettings, updateSettings, executeSettingsAction } from '../services/api';
 import type {
@@ -23,6 +23,7 @@ import {
  setThemePreference,
  THEME_FIELD,
 } from '../utils/themePreference';
+import { useLatestCallback } from './useLatestCallback';
 import { useMountEffect } from './useMountEffect';

 interface FetchSettingsOptions {
@@ -137,13 +138,9 @@ export function useSettings(): UseSettingsReturn {
    () => initialState?.originalValues ?? {},
  );
  const [isSaving, setIsSaving] = useState(false);
-  const valuesRef = useRef<SettingsValues>({});
-  const originalValuesRef = useRef<SettingsValues>({});
-
-  valuesRef.current = values;
-  originalValuesRef.current = originalValues;
-
-  const applySettingsResponse = useCallback(
+  // Stable identity, latest `values`/`originalValues`. Not an Effect Event: it is called
+  // from async fetch and save continuations, not from an Effect. See useLatestCallback.
+  const applySettingsResponse = useLatestCallback(
    (response: SettingsResponse, options: { preserveDirtyValues?: boolean } = {}) => {
      const { preserveDirtyValues = false } = options;
      cachedSettingsResponse = response;
@@ -156,11 +153,7 @@ export function useSettings(): UseSettingsReturn {
      setError(null);

      const nextValues = preserveDirtyValues
-        ? mergeFetchedSettingsWithDirtyValues(
-            hydratedState.values,
-            valuesRef.current,
-            originalValuesRef.current,
-          )
+        ? mergeFetchedSettingsWithDirtyValues(hydratedState.values, values, originalValues)
        : hydratedState.values;

      setValues(nextValues);
@@ -170,7 +163,6 @@ export function useSettings(): UseSettingsReturn {
        setSelectedTab((current) => current ?? hydratedState.selectedTab);
      }
    },
-    [],
  );

  const fetchSettings = useCallback(
@@ -12,6 +12,8 @@ import type {
  RequestSubmissionResult,
  MetadataProvidersResponse,
  MetadataSearchConfig,
+  PackBook,
+  InspectReleaseResponse,
 } from '../types';
 import type {
  ActionResult,
@@ -82,6 +84,9 @@ type ApiResponseErrorShape = Error & {
  code?: string;
  requiredMode?: string;
  payload?: Record<string, unknown>;
+  // Set only when the server explained itself, so callers can tell a real explanation
+  // apart from the `503 SERVICE UNAVAILABLE` placeholder built from the status line.
+  serverMessage?: string;
 };

 class ApiResponseError extends Error {
@@ -89,6 +94,7 @@ class ApiResponseError extends Error {
  code?: string;
  requiredMode?: string;
  payload?: Record<string, unknown>;
+  serverMessage?: string;

  constructor(
    message: string,
@@ -97,6 +103,7 @@ class ApiResponseError extends Error {
      code?: string;
      requiredMode?: string;
      payload?: Record<string, unknown>;
+      serverMessage?: string;
    },
  ) {
    super(message);
@@ -105,6 +112,7 @@ class ApiResponseError extends Error {
    this.code = params.code;
    this.requiredMode = params.requiredMode;
    this.payload = params.payload;
+    this.serverMessage = params.serverMessage;
  }
 }

@@ -112,6 +120,13 @@ export const isApiResponseError = (error: unknown): error is ApiResponseErrorSha
  return error instanceof ApiResponseError;
 };

+// The client gave up before the server answered. Distinguishable so callers can report
+// the wait rather than guessing at a cause: a search that hits this has told us nothing
+// about the network or the mirrors, and saying it did is what issue #1285 was about.
+export const isTimeoutError = (error: unknown): error is Error => {
+  return error instanceof TimeoutError;
+};
+
 const mapApiErrorToActionResult = (error: unknown): ActionResult | null => {
  if (!isApiResponseError(error) || !error.payload) {
    return null;
@@ -147,7 +162,31 @@ const DEFAULT_TIMEOUT_MS = 30000;
 // Release searches can be long-running: a source behind Cloudflare/DDoS-Guard has
 // to spin up the bypasser and solve the challenge before any results come back,
 // which routinely takes well over the default timeout.
-const SEARCH_TIMEOUT_MS = 180000;
+//
+// The server bounds them itself (RELEASE_SEARCH_TIMEOUT, reported by /api/config) and
+// answers a spent budget with a message naming the real cause. This client abort is only
+// the backstop for a server that never answers at all, so it has to fire *after* the
+// server's own deadline - a fixed 180s here beat the 300s default, so the accurate
+// message was never reachable and raising the setting did nothing. See issue #1285.
+//
+// The margin has to cover what the server still has to do *after* its budget trips, not
+// just the budget itself. The deadline is cooperative: it is handed to the bypasser as a
+// cancel flag, and internal_bypasser._CDP_UNWIND_GRACE_SECONDS allows 15s on its own for a
+// cancelled solve to close its browser - before the handler has serialized releases, built
+// the column config and put bytes on the wire. A 15s margin is entirely spent by that
+// unwind, so give it room for the unwind plus the response.
+const SEARCH_TIMEOUT_MARGIN_MS = 45000;
+const FALLBACK_SEARCH_TIMEOUT_MS = 300000; // search_deadline.DEFAULT_SEARCH_BUDGET_SECONDS
+let searchTimeoutMs = FALLBACK_SEARCH_TIMEOUT_MS + SEARCH_TIMEOUT_MARGIN_MS;
+
+// Exported for tests; callers get this applied automatically via getConfig().
+export const setSearchTimeoutFromConfig = (budgetSeconds: unknown): void => {
+  if (typeof budgetSeconds === 'number' && Number.isFinite(budgetSeconds) && budgetSeconds > 0) {
+    searchTimeoutMs = budgetSeconds * 1000 + SEARCH_TIMEOUT_MARGIN_MS;
+  }
+};
+
+export const getSearchTimeoutMs = (): number => searchTimeoutMs;

 // Utility function for JSON fetch with credentials and timeout
 async function fetchJSON<T>(
@@ -181,12 +220,15 @@ async function fetchJSON<T>(
        if (isRecord(parsed) && !Array.isArray(parsed)) {
          errorData = parsed;
        }
-        // Prefer user-friendly 'message' field, fall back to 'error'
-        if (typeof errorData?.message === 'string') {
-          errorMessage = errorData.message;
-          hasServerMessage = true;
-        } else if (typeof errorData?.error === 'string') {
-          errorMessage = errorData.error;
+        // Prefer user-friendly 'message' field, fall back to 'error'. Both must carry
+        // actual text: an empty string is not the server explaining itself, and treating
+        // it as one suppresses the placeholder below and shows the user a blank toast.
+        const explanation = [errorData?.message, errorData?.error].find(
+          (candidate): candidate is string =>
+            typeof candidate === 'string' && candidate.trim() !== '',
+        );
+        if (explanation !== undefined) {
+          errorMessage = explanation;
          hasServerMessage = true;
        }
      } catch (e) {
@@ -211,6 +253,7 @@ async function fetchJSON<T>(

      throw new ApiResponseError(errorMessage, {
        status: res.status,
+        serverMessage: hasServerMessage ? errorMessage : undefined,
        code: typeof errorData?.code === 'string' ? errorData.code : undefined,
        requiredMode:
          typeof errorData?.required_mode === 'string' ? errorData.required_mode : undefined,
@@ -241,7 +284,7 @@ export const searchBooks = async (query: string): Promise<Book[]> => {
  const response = await fetchJSON<ReleasesResponse>(
    `${API_BASE}/releases?source=direct_download&${query}`,
    {},
-    SEARCH_TIMEOUT_MS,
+    searchTimeoutMs,
  );
  return response.releases.map(transformReleaseToDirectBook);
 };
@@ -510,6 +553,18 @@ export type DownloadReleasePayload = {
  language?: string; // Release language code, for the {Language} naming variable
  search_author?: string;
  search_mode?: 'direct' | 'universal';
+  multi_book?: boolean; // Split a multi-book pack into one book per subfolder/file
+  book_plan?: PackBook[]; // The split the user approved before download
+};
+
+/** Inspect a release's file list before download (same body as downloadRelease). */
+export const inspectRelease = async (
+  release: DownloadReleasePayload,
+): Promise<InspectReleaseResponse> => {
+  return fetchJSON<InspectReleaseResponse>(`${API_BASE}/releases/inspect`, {
+    method: 'POST',
+    body: JSON.stringify(release),
+  });
 };

 export const downloadRelease = async (
@@ -572,7 +627,9 @@ export const retryDownload = async (id: string): Promise<void> => {
 };

 export const getConfig = async (): Promise<AppConfig> => {
-  return fetchJSON<AppConfig>(API.config);
+  const config = await fetchJSON<AppConfig>(API.config);
+  setSearchTimeoutFromConfig(config.release_search_timeout);
+  return config;
 };

 interface ActivityDismissedItem {
@@ -7,6 +7,7 @@ import {
  buildLanguageNormalizer,
  getReleaseSearchLanguageParams,
  releaseLanguageMatchesFilter,
+  resolveDefaultLanguageCodes,
 } from '../utils/languageFilters';

 const supportedLanguages: Language[] = [
@@ -67,3 +68,36 @@ describe('releaseLanguageMatchesFilter', () => {
    expect(visibleLanguages).toHaveLength(48);
  });
 });
+
+describe('resolveDefaultLanguageCodes', () => {
+  it('keeps an explicitly empty default as "no default filter"', () => {
+    // The backend stores [] to mean "do not filter"; substituting the first
+    // supported language here would make the UI filter where the server does not.
+    expect(resolveDefaultLanguageCodes([], supportedLanguages)).toEqual([]);
+  });
+
+  it('leaves a configured default untouched', () => {
+    expect(resolveDefaultLanguageCodes(['de', 'hu'], supportedLanguages)).toEqual(['de', 'hu']);
+  });
+
+  it('falls back to the first supported language only when nothing is configured', () => {
+    expect(resolveDefaultLanguageCodes(undefined, supportedLanguages)).toEqual(['en']);
+    expect(resolveDefaultLanguageCodes(null, [])).toEqual(['en']);
+  });
+
+  it('sends no language filter when an empty default is the whole selection', () => {
+    const defaults = resolveDefaultLanguageCodes([], supportedLanguages);
+
+    expect(
+      getReleaseSearchLanguageParams([LANGUAGE_OPTION_DEFAULT], supportedLanguages, defaults),
+    ).toBe(undefined);
+  });
+
+  it('does not smuggle the first language into a Default+German selection', () => {
+    const defaults = resolveDefaultLanguageCodes([], supportedLanguages);
+
+    expect(
+      getReleaseSearchLanguageParams([LANGUAGE_OPTION_DEFAULT, 'de'], supportedLanguages, defaults),
+    ).toEqual(['de']);
+  });
+});
@@ -0,0 +1,53 @@
+import { describe, it, expect } from 'vitest';
+
+import type { PackBook } from '../types';
+import {
+  describePackPlan,
+  parseSeriesPositionInput,
+  toBookPlanPayload,
+  updateReviewBook,
+} from '../utils/packReview';
+
+const books: PackBook[] = [
+  { title: 'Leviathan Wakes', series_position: 1, year: 2011, files: ['a.m4b'] },
+  { title: 'Caliban’s War', series_position: 2, year: 2012, files: ['b.m4b', 'b2.m4b'] },
+];
+
+describe('packReview.updateReviewBook', () => {
+  it('replaces one book without touching the others', () => {
+    const next = updateReviewBook(books, 1, { title: 'Caliban’s War (Unabridged)' });
+    expect(next[0]).toBe(books[0]);
+    expect(next[1]).toEqual({ ...books[1], title: 'Caliban’s War (Unabridged)' });
+    expect(books[1].title).toBe('Caliban’s War');
+  });
+});
+
+describe('packReview.parseSeriesPositionInput', () => {
+  it('accepts whole and fractional positions', () => {
+    expect(parseSeriesPositionInput('3')).toBe(3);
+    expect(parseSeriesPositionInput('2.5')).toBe(2.5);
+  });
+
+  it('treats blank or junk as no position', () => {
+    expect(parseSeriesPositionInput('')).toBeNull();
+    expect(parseSeriesPositionInput('abc')).toBeNull();
+  });
+});
+
+describe('packReview.toBookPlanPayload', () => {
+  it('trims titles, drops books without a title, and keeps file lists', () => {
+    const edited = updateReviewBook(books, 0, { title: '   ' });
+    expect(toBookPlanPayload(edited)).toEqual([
+      { title: 'Caliban’s War', series_position: 2, year: 2012, files: ['b.m4b', 'b2.m4b'] },
+    ]);
+  });
+});
+
+describe('packReview.describePackPlan', () => {
+  it('summarises books, files and ignored sidecars', () => {
+    expect(describePackPlan(books, ['a.txt', 'cover.jpg'])).toBe(
+      '2 books · 3 files · 2 files ignored',
+    );
+    expect(describePackPlan([books[0]], [])).toBe('1 book · 1 file');
+  });
+});
@@ -1,7 +1,7 @@
 import { describe, it, expect } from 'vitest';

 import type { Release } from '../types';
-import { getReleaseFormats } from '../utils/releaseFormats';
+import { getReleaseFormats, getUnrecognizedReleaseFormats } from '../utils/releaseFormats';

 function buildRelease(overrides: Partial<Release>): Release {
  return {
@@ -38,3 +38,26 @@ describe('releaseFormats.getReleaseFormats', () => {
    expect(getReleaseFormats(release)).toEqual(['pdf']);
  });
 });
+
+describe('releaseFormats.getUnrecognizedReleaseFormats', () => {
+  it('returns normalized, deduplicated unrecognized formats from extra', () => {
+    const release = buildRelease({
+      extra: { unrecognized_formats: ['AVI', ' avi ', 'WEBM'] },
+    });
+
+    expect(getUnrecognizedReleaseFormats(release)).toEqual(['avi', 'webm']);
+  });
+
+  it('accepts a single string value', () => {
+    const release = buildRelease({ extra: { unrecognized_formats: 'AVI' } });
+
+    expect(getUnrecognizedReleaseFormats(release)).toEqual(['avi']);
+  });
+
+  it('returns an empty list when nothing was flagged', () => {
+    expect(getUnrecognizedReleaseFormats(buildRelease({}))).toEqual([]);
+    expect(
+      getUnrecognizedReleaseFormats(buildRelease({ extra: { unrecognized_formats: null } })),
+    ).toEqual([]);
+  });
+});
@@ -0,0 +1,62 @@
+import { describe, it, expect } from 'vitest';
+
+import {
+  INITIAL_ENTER_ANIMATION,
+  nextEnterAnimation,
+  type EnterAnimationState,
+} from '../utils/releaseModalEnterAnimation';
+
+describe('nextEnterAnimation', () => {
+  it('animates the first session', () => {
+    const next = nextEnterAnimation(INITIAL_ENTER_ANIMATION, 'book-1', false);
+    expect(next).toEqual({ key: 'book-1', animate: true });
+  });
+
+  it('animates the first session in combined mode too', () => {
+    const next = nextEnterAnimation(INITIAL_ENTER_ANIMATION, 'book-1', true);
+    expect(next).toEqual({ key: 'book-1', animate: true });
+  });
+
+  it('does not animate a step transition between combined-mode sessions', () => {
+    const current: EnterAnimationState = { key: 'book-1', animate: true };
+    expect(nextEnterAnimation(current, 'book-2', true)).toEqual({
+      key: 'book-2',
+      animate: false,
+    });
+  });
+
+  it('animates a session swap outside combined mode', () => {
+    const current: EnterAnimationState = { key: 'book-1', animate: true };
+    expect(nextEnterAnimation(current, 'book-2', false)).toEqual({
+      key: 'book-2',
+      animate: true,
+    });
+  });
+
+  it('holds the decision across re-renders of the same session', () => {
+    // Regression: the decision used to flip back to `true` on the next render,
+    // replaying the enter animation mid-session.
+    const stepped = nextEnterAnimation({ key: 'book-1', animate: true }, 'book-2', true);
+    expect(stepped.animate).toBe(false);
+
+    let state = stepped;
+    for (let i = 0; i < 5; i++) {
+      state = nextEnterAnimation(state, 'book-2', true);
+      expect(state.animate).toBe(false);
+    }
+  });
+
+  it('returns the same reference when the session is unchanged', () => {
+    const current: EnterAnimationState = { key: 'book-1', animate: false };
+    expect(nextEnterAnimation(current, 'book-1', true)).toBe(current);
+  });
+
+  it('animates again after the modal closes and reopens', () => {
+    const open = nextEnterAnimation(INITIAL_ENTER_ANIMATION, 'book-1', true);
+    const closed = nextEnterAnimation(open, null, true);
+    expect(closed.key).toBeNull();
+
+    const reopened = nextEnterAnimation(closed, 'book-1', true);
+    expect(reopened.animate).toBe(true);
+  });
+});
@@ -0,0 +1,69 @@
+import { describe, it, expect } from 'vitest';
+
+import type { Book, Release } from '../types';
+import { buildReleaseDownloadPayload } from '../utils/releasePayload';
+
+const book: Book = {
+  id: 'hc-1',
+  title: 'Drive',
+  author: 'James S. A. Corey',
+  year: '2012',
+  preview: 'https://img/drive.jpg',
+  series_name: 'The Expanse',
+  series_position: 2.6,
+  subtitle: 'An Expanse Short Story',
+  provider: 'hardcover',
+  provider_id: 'hc-1',
+  source: 'direct_download',
+};
+
+const release: Release = {
+  source: 'audiobookbay',
+  source_id: 'abb-1',
+  title: 'James S. A. Corey - The Expanse Complete 2.0',
+  format: 'm4b',
+  language: 'en',
+  download_url: 'https://audiobookbay.lu/abss/expanse/',
+};
+
+describe('buildReleaseDownloadPayload', () => {
+  it('describes the searched book and the chosen release', () => {
+    const payload = buildReleaseDownloadPayload(book, release, 'audiobook');
+    expect(payload).toMatchObject({
+      source: 'audiobookbay',
+      source_id: 'abb-1',
+      title: 'Drive',
+      author: 'James S. A. Corey',
+      series_name: 'The Expanse',
+      series_position: 2.6,
+      language: 'en',
+      content_type: 'audiobook',
+    });
+    expect(payload.multi_book).toBeUndefined();
+    expect(payload.book_plan).toBeUndefined();
+  });
+
+  it('uses the release title and author for manual books', () => {
+    const manual: Book = { ...book, provider: 'manual', title: 'ignored' };
+    const withAuthor = { ...release, extra: { author: 'Release Author' } };
+    const payload = buildReleaseDownloadPayload(manual, withAuthor, 'audiobook');
+    expect(payload.title).toBe(release.title);
+    expect(payload.author).toBe('Release Author');
+  });
+
+  it('flags a manual multi-book pack', () => {
+    const payload = buildReleaseDownloadPayload(book, release, 'audiobook', { multiBook: true });
+    expect(payload.multi_book).toBe(true);
+    expect(payload.book_plan).toBeUndefined();
+  });
+
+  it('attaches the approved book plan', () => {
+    const plan = [{ title: 'Leviathan Wakes', series_position: 1, year: 2011, files: ['a.m4b'] }];
+    const payload = buildReleaseDownloadPayload(book, release, 'audiobook', {
+      multiBook: true,
+      bookPlan: plan,
+    });
+    expect(payload.multi_book).toBe(true);
+    expect(payload.book_plan).toEqual(plan);
+  });
+});
@@ -0,0 +1,77 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+
+import { searchBooks } from '../services/api';
+import {
+  describeSearchFailure,
+  CLIENT_TIMEOUT_MESSAGE,
+  UNREACHABLE_SOURCE_MESSAGE,
+} from '../utils/searchFailureMessage';
+
+/**
+ * What a failed direct-mode search tells the user.
+ *
+ * Every non-auth failure used to be relabelled "Unable to reach download source. Network
+ * may be restricted or mirrors blocked.", which threw away the server's explanation and
+ * blamed the user's network for a protection challenge. See issue #1285.
+ */
+
+const jsonResponse = (body: unknown, status: number): Response =>
+  new Response(JSON.stringify(body), {
+    status,
+    statusText: 'SERVICE UNAVAILABLE',
+    headers: { 'Content-Type': 'application/json' },
+  });
+
+/** Drive a real searchBooks() failure so the error is the one the hook actually sees. */
+const failedSearch = async (respond: () => Promise<Response>): Promise<unknown> => {
+  vi.stubGlobal('fetch', vi.fn(respond));
+  return searchBooks('q=dune').catch((error: unknown) => error);
+};
+
+describe('describeSearchFailure', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it('shows the sentence the server sent', async () => {
+    const sentence = 'The release search ran out of time (300s).';
+    const error = await failedSearch(() => Promise.resolve(jsonResponse({ error: sentence }, 503)));
+
+    expect(describeSearchFailure(error)).toBe(sentence);
+  });
+
+  it('names the wait when the client gave up first', async () => {
+    // The client's abort is the backstop for a server that never answered. It tells us
+    // nothing about mirrors or the network, and the old chain reported it as if it did.
+    const abort = Object.assign(new Error('The operation was aborted.'), { name: 'AbortError' });
+    const error = await failedSearch(() => Promise.reject(abort));
+
+    expect(describeSearchFailure(error)).toBe(CLIENT_TIMEOUT_MESSAGE);
+    expect(describeSearchFailure(error)).not.toBe(UNREACHABLE_SOURCE_MESSAGE);
+    expect(describeSearchFailure(error)).not.toContain('mirrors');
+  });
+
+  it('falls back to the mirrors line only when nothing explained itself', async () => {
+    const error = await failedSearch(() => Promise.resolve(jsonResponse({}, 503)));
+
+    expect(describeSearchFailure(error)).toBe(UNREACHABLE_SOURCE_MESSAGE);
+  });
+
+  it('keeps a reachability message that already says the right thing', () => {
+    const error = new Error('Unable to reach download source. Every mirror was quarantined.');
+
+    expect(describeSearchFailure(error)).toBe(error.message);
+  });
+
+  it('never produces an empty sentence from a blank server message', async () => {
+    // `{"message": ""}` is not the server explaining itself. Treating it as one used to
+    // reach showToast('') and render an empty error toast.
+    const error = await failedSearch(() => Promise.resolve(jsonResponse({ message: '' }, 503)));
+
+    expect(describeSearchFailure(error)).toBe(UNREACHABLE_SOURCE_MESSAGE);
+  });
+
+  it('handles a non-Error rejection without inventing detail', () => {
+    expect(describeSearchFailure('something odd')).toBe(UNREACHABLE_SOURCE_MESSAGE);
+  });
+});
@@ -0,0 +1,197 @@
+import { describe, it, expect, vi, afterEach, beforeEach } from 'vitest';
+
+import {
+  getConfig,
+  getSearchTimeoutMs,
+  setSearchTimeoutFromConfig,
+  searchBooks,
+  isApiResponseError,
+} from '../services/api';
+
+/**
+ * The client's abort must fire *after* the server's own search deadline.
+ *
+ * `/api/releases` bounds itself with RELEASE_SEARCH_TIMEOUT and answers a spent budget
+ * with a message naming the real cause. The client aborted at a fixed 180s against a
+ * 300s default, so it always won the race and replaced that message with "Request timed
+ * out. Check your network connection or proxy configuration." Raising the setting had no
+ * visible effect either, the 180s being baked into the hashed bundle. See issue #1285.
+ */
+
+// Must stay ahead of what the server still has to do after its budget trips: the deadline
+// is cooperative, and internal_bypasser._CDP_UNWIND_GRACE_SECONDS alone allows 15s for a
+// cancelled solve to close its browser before the response is even built.
+const MARGIN_MS = 45_000;
+const SERVER_UNWIND_GRACE_MS = 15_000;
+
+const jsonResponse = (body: unknown, status = 200): Response =>
+  new Response(JSON.stringify(body), {
+    status,
+    statusText: status === 200 ? 'OK' : 'SERVICE UNAVAILABLE',
+    headers: { 'Content-Type': 'application/json' },
+  });
+
+const configBody = (releaseSearchTimeout: number): Record<string, unknown> => ({
+  release_search_timeout: releaseSearchTimeout,
+});
+
+describe('release search timeout', () => {
+  beforeEach(() => {
+    setSearchTimeoutFromConfig(300);
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    setSearchTimeoutFromConfig(300);
+  });
+
+  it('defaults behind the server default rather than ahead of it', () => {
+    expect(getSearchTimeoutMs()).toBe(300 * 1000 + MARGIN_MS);
+  });
+
+  it('follows the budget the server reports', async () => {
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(() => Promise.resolve(jsonResponse(configBody(900)))),
+    );
+
+    await getConfig();
+
+    expect(getSearchTimeoutMs()).toBe(900 * 1000 + MARGIN_MS);
+  });
+
+  it('still outlasts the server when the budget is lowered', async () => {
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(() => Promise.resolve(jsonResponse(configBody(30)))),
+    );
+
+    await getConfig();
+
+    // Exact, not a lower bound: `> 30_000` is also satisfied by the 345_000 left over
+    // from the previous budget, so a setter that silently stopped applying the config
+    // would pass it.
+    expect(getSearchTimeoutMs()).toBe(30 * 1000 + MARGIN_MS);
+  });
+
+  it('leaves the server room to unwind a cancelled solve and answer', async () => {
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(() => Promise.resolve(jsonResponse(configBody(300)))),
+    );
+
+    await getConfig();
+
+    // The failure this exists for is a budget spent mid-solve. The server then has to
+    // close a browser before it can serialize anything, so a margin merely equal to that
+    // unwind is entirely spent by it and the client aborts first all over again.
+    expect(getSearchTimeoutMs() - 300 * 1000).toBeGreaterThan(SERVER_UNWIND_GRACE_MS);
+  });
+
+  it('ignores a missing or nonsensical budget instead of disabling the backstop', () => {
+    const before = getSearchTimeoutMs();
+
+    setSearchTimeoutFromConfig(undefined);
+    setSearchTimeoutFromConfig(0);
+    setSearchTimeoutFromConfig(-1);
+    setSearchTimeoutFromConfig('600');
+    setSearchTimeoutFromConfig(Number.NaN);
+
+    expect(getSearchTimeoutMs()).toBe(before);
+  });
+
+  it('applies the derived timeout to the direct_download search', async () => {
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(() => Promise.resolve(jsonResponse(configBody(600)))),
+    );
+    await getConfig();
+
+    const seen: Array<AbortSignal | undefined> = [];
+    vi.stubGlobal(
+      'fetch',
+      vi.fn((_url: string, init: RequestInit) => {
+        seen.push(init.signal ?? undefined);
+        return Promise.resolve(jsonResponse({ releases: [] }));
+      }),
+    );
+
+    await searchBooks('q=dune');
+
+    // The request carries an abort signal, and it is not yet aborted: the point is that
+    // the clock it runs on is the server's, not a constant.
+    expect(seen).toHaveLength(1);
+    expect(seen[0]?.aborted).toBe(false);
+    expect(getSearchTimeoutMs()).toBe(600 * 1000 + MARGIN_MS);
+  });
+});
+
+describe('server-provided failure messages', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it('carries the server sentence through instead of a status placeholder', async () => {
+    const sentence =
+      'The release search ran out of time (300s). Anna’s Archive is behind a ' +
+      'protection challenge the bypasser could not solve in that window.';
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(() => Promise.resolve(jsonResponse({ error: sentence }, 503))),
+    );
+
+    const error = await searchBooks('q=dune').catch((e: unknown) => e);
+
+    expect(isApiResponseError(error)).toBe(true);
+    if (isApiResponseError(error)) {
+      expect(error.serverMessage).toBe(sentence);
+    }
+  });
+
+  it('leaves serverMessage unset when the server explained nothing', async () => {
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(() => Promise.resolve(jsonResponse({}, 503))),
+    );
+
+    const error = await searchBooks('q=dune').catch((e: unknown) => e);
+
+    expect(isApiResponseError(error)).toBe(true);
+    if (isApiResponseError(error)) {
+      expect(error.serverMessage).toBeUndefined();
+      // Without this the UI would show a bare "503 SERVICE UNAVAILABLE".
+      expect(error.message).toContain('Server unavailable');
+    }
+  });
+
+  it('treats a blank message as no explanation at all', async () => {
+    // An empty string is not the server explaining itself. Taking it as one suppresses
+    // the placeholder below *and* survives a `??` fallback, leaving an empty toast.
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(() => Promise.resolve(jsonResponse({ message: '   ' }, 503))),
+    );
+
+    const error = await searchBooks('q=dune').catch((e: unknown) => e);
+
+    expect(isApiResponseError(error)).toBe(true);
+    if (isApiResponseError(error)) {
+      expect(error.serverMessage).toBeUndefined();
+      expect(error.message).toContain('Server unavailable');
+    }
+  });
+
+  it('falls back to `error` when `message` is blank', async () => {
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(() => Promise.resolve(jsonResponse({ message: '', error: 'the real reason' }, 503))),
+    );
+
+    const error = await searchBooks('q=dune').catch((e: unknown) => e);
+
+    expect(isApiResponseError(error)).toBe(true);
+    if (isApiResponseError(error)) {
+      expect(error.serverMessage).toBe('the real reason');
+    }
+  });
+});
@@ -285,6 +285,7 @@ export interface AppConfig {
  auto_open_downloads_sidebar: boolean; // Auto-open sidebar when download is queued
  hardcover_auto_remove_on_download: boolean; // Auto-remove from active Hardcover list on download
  download_to_browser_content_types: string[]; // Auto-download completed files to browser for selected content types
+  release_search_timeout: number; // Server-side budget for one release search, in seconds
  settings_enabled: boolean; // Whether config directory is mounted and writable
  onboarding_complete: boolean; // Whether the user has completed initial setup
  default_sort: string; // Default sort for direct mode
@@ -460,6 +461,27 @@ export interface SourceSearchInfo {
 }

 // Response from /api/releases endpoint
+/** One book split out of a multi-book pack release, files as release-relative paths. */
+export interface PackBook {
+  title: string;
+  series_position: number | null;
+  year: number | null;
+  files: string[];
+}
+
+export interface PackPlan {
+  is_pack: boolean;
+  books: PackBook[];
+  ignored: string[];
+}
+
+export interface InspectReleaseResponse {
+  inspected: boolean;
+  reason: string | null;
+  files: { path: string; size: number | null }[];
+  plan: PackPlan | null;
+}
+
 export interface ReleasesResponse {
  releases: Release[];
  book: {
@@ -146,7 +146,13 @@ export interface TableFieldColumnOption {
  childOf?: string;
 }

-export type TableFieldColumnType = 'text' | 'select' | 'multiselect' | 'checkbox' | 'path';
+export type TableFieldColumnType =
+  | 'text'
+  | 'password'
+  | 'select'
+  | 'multiselect'
+  | 'checkbox'
+  | 'path';

 export interface TableFieldColumn {
  key: string;
@@ -1,4 +1,4 @@
-type BookTargetChangeEvent = {
+export type BookTargetChangeEvent = {
  provider: string;
  bookId: string;
  target: string;
@@ -27,6 +27,24 @@ export const normalizeLanguageSelection = (selected: string[]): string[] => {
  return unique.length ? unique : [LANGUAGE_OPTION_DEFAULT];
 };

+/**
+ * Resolve the language codes the "Default" filter option stands for.
+ *
+ * An explicitly empty list is a deliberate "no default filter" and is returned as-is;
+ * only a missing value falls back to the first supported language. Substituting a
+ * language for the empty list would make the UI filter by a language the backend
+ * does not apply.
+ */
+export const resolveDefaultLanguageCodes = (
+  configuredDefault: string[] | null | undefined,
+  supportedLanguages: Language[],
+): string[] => {
+  if (Array.isArray(configuredDefault)) {
+    return configuredDefault;
+  }
+  return [supportedLanguages[0]?.code || 'en'];
+};
+
 export const getLanguageFilterValues = (
  selection: string[],
  supportedLanguages: Language[],
@@ -0,0 +1,39 @@
+import type { PackBook } from '../types';
+
+/** Return a copy of `books` with one entry patched; the input is not mutated. */
+export function updateReviewBook(
+  books: PackBook[],
+  index: number,
+  patch: Partial<PackBook>,
+): PackBook[] {
+  return books.map((book, i) => (i === index ? { ...book, ...patch } : book));
+}
+
+/** Parse a series-position text field: "3" → 3, "2.5" → 2.5, blank/junk → null. */
+export function parseSeriesPositionInput(value: string): number | null {
+  const trimmed = value.trim();
+  if (!trimmed) return null;
+  const parsed = Number(trimmed);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+/** The plan sent with the download: trimmed titles, untitled books dropped. */
+export function toBookPlanPayload(books: PackBook[]): PackBook[] {
+  return books
+    .map((book) => ({ ...book, title: book.title.trim() }))
+    .filter((book) => book.title.length > 0 && book.files.length > 0);
+}
+
+function plural(count: number, noun: string): string {
+  return `${count} ${noun}${count === 1 ? '' : 's'}`;
+}
+
+/** "2 books · 3 files · 2 files ignored" */
+export function describePackPlan(books: PackBook[], ignored: string[]): string {
+  const fileCount = books.reduce((sum, book) => sum + book.files.length, 0);
+  const parts = [plural(books.length, 'book'), plural(fileCount, 'file')];
+  if (ignored.length > 0) {
+    parts.push(`${plural(ignored.length, 'file')} ignored`);
+  }
+  return parts.join(' · ');
+}
--- a/Show More
+++ b/Show More