morpheasgr · Oct 12, 2026 · Oct 12, 2026 · Oct 12, 2026 · Oct 12, 2026 · Oct 12, 2026
diff --git a/docs/cookie-import.md b/docs/cookie-import.md
@@ -2,7 +2,19 @@
 
 ArcHive stores cookies encrypted per site for browse and yt-dlp downloads.
 
-## Recommended: Cookie-Editor extension
+## Recommended: Log in with browser (desktop + Android)
+
+1. In **Settings → Cookies**, select the site (or open a cookie-required site in Browse).
+2. Press **Log in with browser**. ArcHive opens the site in its own browser:
+   - **Desktop:** a separate window. Log in, then press **Save cookies** in ArcHive (or just close the window).
+   - **Android:** a full-screen browser with **Cancel** / **Save cookies** buttons at the top. The system back button navigates back inside the page.
+3. The captured cookies, including HttpOnly session cookies that page scripts cannot read, are converted to Netscape format and stored in the vault (on the LAN host when the app is in Remote LAN mode).
+
+Android does not let one app read another app's cookies (for example Chrome's), so the login has to happen inside ArcHive. Google sign-in may refuse embedded browsers; for YouTube, import cookies with Cookie-Editor instead.
+
+Implementation: `src-tauri/src/cookie_login.rs` (desktop window + Android bridge) and `src-tauri/android-overlays/CookieBrowserPlugin.kt` (installed by `scripts/patch-android-ytdlp.ps1` / `.sh`).
+
+## Cookie-Editor extension
 
 1. Install [Cookie-Editor](https://chromewebstore.google.com/detail/cookie-editor/hlkenndednhfkekhgcdicdfddnkalmdm) (Chrome, Edge, Brave) or the Firefox equivalent.
 2. Log in on the target site (PornHub, xHamster, etc.).
@@ -31,6 +43,8 @@ Export or build a Netscape cookie file and paste into the Netscape textarea →
 | xvideos  | xvideos.com                 |
 | thisvid  | thisvid.com                 |
 
+Lines exported as `#HttpOnly_<domain>` are treated as cookies, not comments.
+
 ## Security
 
 - Cookies are encrypted at rest (AES-256-GCM).

diff --git a/docs/mobile-android.md b/docs/mobile-android.md
@@ -177,20 +177,21 @@ Video playback uses `GET /api/scenes/{id}/media` and `GET /api/files/stream` wit
 
 ## Troubleshooting
 
-| Issue                                  | Fix                                                                                      |
-| -------------------------------------- | ---------------------------------------------------------------------------------------- |
-| `FrameInsert open fail` in logcat      | Usually MIUI noise — see [troubleshooting-android.md](troubleshooting-android.md)        |
-| `om.archhive.app` in logs              | Truncated `com.archhive.app` — verify with `android:regen` if UI is broken               |
-| -------------------------------------- | ---------------------------------------------------------------------------------------- |
-| `yt-dlp-aarch64-linux-android` missing | Sidecars are desktop-only; run `bun run android:regen`                                   |
-| `Unresolved reference: TauriActivity`  | Stale `gen/android` after identifier change; run `bun run android:regen`                 |
-| App runs but `invoke` is undefined     | Set Engine → **Remote LAN**; ensure desktop LAN is on. Rebuild after capability changes. |
-| Read-only filesystem on Android        | Mobile uses app data dir for DB; downloads go via Remote LAN desktop host                |
-| `ERR_CLEARTEXT_NOT_PERMITTED`          | Run `scripts/patch-android-lan.ps1` and rebuild                                          |
-| Connection refused                     | Firewall: allow TCP **8787** on PC (API). `:1420` is dev UI only.                        |
-| Used `:1420` in Remote LAN             | Remote LAN API is port **8787**, not the Vite dev port 1420                              |
-| 401 Unauthorized                       | Verify API token matches desktop LAN token                                               |
-| Empty browse results                   | Ensure desktop app is running and cookies are configured                                 |
+| Issue                                                       | Fix                                                                                                                                                                                 |
+| ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `FrameInsert open fail` in logcat                           | Usually MIUI noise — see [troubleshooting-android.md](troubleshooting-android.md)                                                                                                   |
+| `om.archhive.app` in logs                                   | Truncated `com.archhive.app` — verify with `android:regen` if UI is broken                                                                                                          |
+| --------------------------------------                      | ----------------------------------------------------------------------------------------                                                                                            |
+| `yt-dlp-aarch64-linux-android` missing                      | Sidecars are desktop-only; run `bun run android:regen`                                                                                                                              |
+| `Unresolved reference: TauriActivity`                       | Stale `gen/android` after identifier change; run `bun run android:regen`                                                                                                            |
+| App runs but `invoke` is undefined                          | Set Engine → **Remote LAN**; ensure desktop LAN is on. Rebuild after capability changes.                                                                                            |
+| Read-only filesystem on Android                             | Mobile uses app data dir for DB; downloads go via Remote LAN desktop host                                                                                                           |
+| `ERR_CLEARTEXT_NOT_PERMITTED`                               | Run `scripts/patch-android-lan.ps1` and rebuild                                                                                                                                     |
+| Connection refused                                          | Firewall: allow TCP **8787** on PC (API). `:1420` is dev UI only.                                                                                                                   |
+| Used `:1420` in Remote LAN                                  | Remote LAN API is port **8787**, not the Vite dev port 1420                                                                                                                         |
+| 401 Unauthorized                                            | Verify API token matches desktop LAN token                                                                                                                                          |
+| Empty browse results                                        | Ensure desktop app is running and cookies are configured                                                                                                                            |
+| `YoutubeDL/FFmpeg not initialized`, no versions in Settings | APK was packaged with compressed native libs (`extractNativeLibs=false`). `patch-android-ytdlp` sets `jniLibs.useLegacyPackaging = true`; run `bun run android:patches` and rebuild |
 
 ## Scripts
 

diff --git a/docs/sites.md b/docs/sites.md
@@ -2,21 +2,90 @@
 
 ## Tier A — yt-dlp (browse + download)
 
-| Site ID   | Display Name | Browse kinds                                 | Cookies                     |
-| --------- | ------------ | -------------------------------------------- | --------------------------- |
-| youtube   | YouTube      | channel, search, video                       | Optional                    |
-| tiktok    | TikTok       | channel, search, video                       | No                          |
-| twitter   | Twitter / X  | channel, video                               | Recommended                 |
-| instagram | Instagram    | channel, video                               | Yes                         |
-| thisvid   | ThisVid      | tag, search, video                           | Yes                         |
-| thothub   | ThotHub      | tag, model, search, video                    | Optional (`thethothub.com`) |
-| pornhub   | PornHub      | category, tag, search, channel, model, video | Yes                         |
-| youporn   | YouPorn      | category, model, search, video               | Optional                    |
-| xnxx      | XNXX         | search, tag, channel, video                  | Optional                    |
-| xhamster  | xHamster     | tag, search, channel, video                  | Yes                         |
-| xvideos   | XVIDEOS      | tag, search, channel, video                  | Yes                         |
-| reddit    | Reddit       | channel, search, video                       | OAuth for subreddits        |
-| eporner   | Eporner      | search, tag, category, video                 | No                          |
+| Site ID   | Display Name | Browse kinds                                 | Cookies                                                        |
+| --------- | ------------ | -------------------------------------------- | -------------------------------------------------------------- |
+| youtube   | YouTube      | channel, search, video                       | Optional                                                       |
+| tiktok    | TikTok       | channel, search, video                       | No                                                             |
+| twitter   | Twitter / X  | channel, video                               | Recommended                                                    |
+| instagram | Instagram    | channel, video                               | Yes                                                            |
+| thisvid   | ThisVid      | tag, search, video                           | Yes                                                            |
+| thothub   | ThotHub      | tag, model, search, video                    | Optional (`thethothub.com`)                                    |
+| pornhub   | PornHub      | category, tag, search, channel, model, video | Yes                                                            |
+| youporn   | YouPorn      | category, model, search, video               | Optional                                                       |
+| xnxx      | XNXX         | search, tag, channel, video                  | Optional                                                       |
+| xhamster  | xHamster     | tag, search, channel, video                  | Yes                                                            |
+| xvideos   | XVIDEOS      | tag, search, channel, video                  | Yes                                                            |
+| reddit    | Reddit       | channel, search, video                       | Login cookies (Reddit hides listings from logged-out visitors) |
+| eporner   | Eporner      | search, tag, category, video                 | No                                                             |
+
+## Aggregators
+
+| Site ID   | Display Name | Browse kinds            | Cookies |
+| --------- | ------------ | ----------------------- | ------- |
+| xpomelo   | xPomelo      | search, category, model | No      |
+| pornwitch | Pornwitch    | category, search        | No      |
+
+xPomelo hosts nothing: each result links to its source tube (PornHub,
+XVIDEOS, xHamster, XNXX, Eporner, SpankBang, …). Items keep the source URL
+and, where ArcHive has an adapter, the source site's id, so playback,
+downloads and the Info dialog run through that site's own pipeline; other
+sources go through plain yt-dlp. Category listings take any number of
+required and excluded categories (`/category/a%2Cb%2C-c`). Results from
+paysites (Brazzers, FapHouse, Clips4Sale, …) and unsupported sources (Beeg,
+SxyPrn, VipTube) are hidden unless the Source filter is set.
+Cloudflare blocks HTTP/1.1 clients on this site; the main HTTP/2 client passes.
+
+Pornwitch also hosts nothing. Its search matches titles plus the source
+site's tags, and every word is required (synonyms and plurals count), so a
+tag combination `a,b,-c` runs as the query `a b -c`; a Search keeps the
+site's own syntax (`"exact phrase"`, `-word`). PornHub, XVIDEOS, xHamster and
+Eporner results get their source URL (and adapter) straight from the card;
+TXXX, beeg and paysite results keep Pornwitch's `/go?id=` link, which is
+followed (one request) only when played or downloaded. Pages after the first
+continue from the previous page's last-card cursor. Word suggestions come
+from `/suggest` (`GET /api/sites/{id}/suggest?q=`), debounced and cached;
+requests to pornwitch.com are spaced 2.5–4.5 s apart.
+
+### Bot checks (Cloudflare)
+
+#### Desktop
+
+When yt-dlp is refused by a bot check, ArcHive retries it with browser
+impersonation (`--impersonate`, `sites/clearance.rs`). This needs the
+standalone yt-dlp builds that bundle curl_cffi (`yt-dlp.exe`, `yt-dlp_macos`,
+`yt-dlp_linux`); `setup-binaries` downloads those. If the site still refuses,
+a small verification window opens on the page and closes by itself once the
+check passes. Its cookies (`cf_clearance`, session) are saved encrypted per
+site and reused, together with the same User-Agent, by yt-dlp and by the KVS
+resolver.
+
+#### Android
+
+Some sources (SpankBang, KVS tubes such as CrazyPorn, Love4Porn, 4KPorn)
+answer the embedded engines with a Cloudflare challenge. When playback or a
+download fails that way on Android, ArcHive opens the page in its in-app
+browser, where the check passes by itself or after one tap. It then reads
+the video URL from the rendered page (`sites/challenge.rs`) and follows
+session-bound KVS `get_file` links inside the same browser session. Sites
+with dedicated adapters (PornHub, XVIDEOS, …) are excluded.
+
+### xPomelo sources: tested 2026-10-13
+
+From a datacenter connection. Cloudflare-protected sites then show an
+interactive check that can't be passed from there; on a home connection the
+bot-check fallbacks below are expected to get through. That part is
+unverified.
+
+| Result                                | Sources                                                                                                                                                                                                 |
+| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Play + download                       | XVIDEOS, xHamster, XNXX, Eporner, YouPorn, RedTube, PornZog, XGroovy, PornOne, Hoes, HDtube¹, SexVid¹, XXXBP², TXXX, EroThots, PornHat, YouJizz, Analdin, AnySex, Xozilla, Nuvid, Clips4Sale (trailers) |
+| Cloudflare check (bot-check fallback) | SpankBang, CrazyPorn, Love4Porn, 4KPorn, FapCat, TNAFlix, DrTuber, Noodlemagazine (intermittent)                                                                                                        |
+| Native resolver, CDN unreliable       | HQPorner (`mydaddy.cc` player; files often 404 or rate-limited)                                                                                                                                         |
+| Not supported                         | Beeg (API no longer returns streams; yt-dlp broken too), SxyPrn (yt-dlp marks it unsupported), VipTube (empty player config)                                                                            |
+| Stale listings                        | Some xPomelo results point at removed videos (HTTP 404/410, Tube8 `video-inactive`)                                                                                                                     |
+
+¹ yt-dlp can't extract these; playback and downloads use the KVS resolver.
+² No yt-dlp extractor; `api.xxxbp.tv/hls`.
 
 ## Tier B — Live Cam Sites (scraping + webview bridge)
 
@@ -27,9 +96,9 @@
 
 ## Tier C — gallery-dl
 
-| Site ID | Display Name | Notes                        |
-| ------- | ------------ | ---------------------------- |
-| redgifs | RedGifs      | Uses gallery-dl for download |
+| Site ID | Display Name | Notes                                                                |
+| ------- | ------------ | -------------------------------------------------------------------- |
+| redgifs | RedGifs      | Browse via the RedGifs v2 API (temporary token); direct MP4 download |
 
 ## Cookie Requirements
 
@@ -79,6 +148,35 @@ desktop host.
   the StashDB id, merges aliases (deduped, capped), and sets the portrait
   only when none is stored.
 
+## Sorting, filters and categories
+
+What each site can strictly combine (tags, categories, search + category,
+exclusions) is documented in [tag-combining.md](tag-combining.md).
+
+Adapters advertise what they support via `SiteAdapter::browse_options()`
+(returned in `SiteInfo.browse_options`); the browse page shows matching
+Sort / Date / Length / Quality selects and passes the chosen ids as
+`BrowseQuery.filters`. Unknown ids are dropped before they reach a URL.
+Every page also has on-device filters (words, `-exclude`, length) over
+loaded results. Category / tag indexes come from `list_categories()`
+(`list_site_categories` command, `GET /api/sites/{id}/categories`).
+
+| Site       | Sort                                    | Date / Length / Quality                | Categories            |
+| ---------- | --------------------------------------- | -------------------------------------- | --------------------- |
+| PornHub    | newest, views, rating, longest, hottest | period, duration, HD                   | JSON-embedded catalog |
+| XVIDEOS    | relevance, date, rating, views, length  | period, duration, HD/1080p             | `/tags` (top 400)     |
+| XNXX       | views, random                           | period, duration, HD/Full HD           | `/tags` (top 400)     |
+| xHamster   | search: 5 sorts; category: newest/best  | duration, 720p/1080p/4K                | `/categories`         |
+| YouPorn    | relevance, date, views, rating, length  | —                                      | `/categories/`        |
+| Eporner    | 7 API `order` values                    | —                                      | `/cats/`              |
+| xPomelo    | relevance, date, views, length          | period, duration, HD/4K, source        | `data-tags` JSON (6k) |
+| Pornwitch  | hottest, newest, oldest, longest, short | period, minutes range, 720p–4K, source | `/categories` (180)   |
+| ThotHub    | KVS `sort_by` (5)                       | —                                      | —                     |
+| ThisVid    | KVS `sort_by` (5)                       | —                                      | `/categories/`        |
+| Reddit     | hot, new, top, rising                   | period (top)                           | —                     |
+| RedGifs    | trending, latest, top                   | —                                      | —                     |
+| Chaturbate | —                                       | —                                      | top hashtags API      |
+
 ## SCrawler Parity Roadmap
 
 Future adapters: Threads, Pinterest, OnlyFans (cookie + DRM limitations), Bluesky, LPSG.