feat(offline): play downloaded video, and drain the offline sync queue (0.4.6)

Bundles this session's work plus the concurrent search/offline/player changes. Every gate passes on the combined tree: 885 frontend tests, 610 Rust tests, clippy clean, boundary clean, trace coverage 86%. Offline video playback — four separate defects, each of which alone stopped it: DR-133 A completed download's file_path is already absolute (the worker rewrites it on completion), but the player rooted it a second time and handed the webview /data/user/0/app//data/user/0/app/videos/x.mp4. DR-134 The asset protocol was never enabled: no protocol-asset feature and no assetProtocol config, so convertFileSrc produced URLs nothing answered. Also silently defeated the cached-thumbnail path, which fails soft to the server copy and hid it whenever the server was reachable. DR-137 Tauri's asset protocol answers a range-less request by reading the whole file into memory, and only advertises Accept-Ranges from inside its range branch, so the first request never learns ranges exist. Chromium gave up with PIPELINE_ERROR_READ after ~31s. Local media is now served by a loopback HTTP server: bounded 4 MiB chunks streamed from the file handle, every response length-delimited, and a range-less request answered with one chunk rather than the file. Confined by a per-session token and to the app data directory, because loopback is shared between apps on Android. DR-138 Release builds set usesCleartextTraffic=false, so Android rejected the request to that server before any I/O. A network-security-config exempts 127.0.0.1 only; a remote server must still be HTTPS. Downloads: DR-135 download_item never records media_type and the reconnect resolver read that NULL as 'audio', so a movie queued from a media card had its URL resolved by get_audio_stream_url and completed as an audio-only transcode. The item's own type now decides. DR-136 Rows already downloaded that way are requeued on reconnect, since prevention alone leaves them reading "downloaded" and still unplayable. Known limitation: a download taken at `original` quality is a byte copy of the source, so it can be any container. One such file is an AVI holding XVID, which the webview cannot play in any case — the media server serves it correctly and Chromium refuses it. That needs either a transcoded download preset or the native ExoPlayer surface work, and is not addressed here. Also fixes two ID collisions between concurrent work: DR-143 defined twice (search vs offline gate) and UT-131 defined twice (Episode Focus hero vs channel cap). The search requirement is now DR-147 and the channel-cap test UT-141, with their code references and matrix rows updated.
fix(player): pick a decodable track in the no-audio fallback (DR-146)
2026-08-09 16:38:07 +02:00 · 2026-08-09 15:07:18 +02:00 · 2026-08-09 15:06:49 +02:00 · 2026-08-09 15:05:16 +02:00 · 2026-08-09 15:01:57 +02:00 · 2026-08-09 14:47:03 +02:00
111 changed files with 16129 additions and 2621 deletions
@@ -6,6 +6,86 @@ Entries are grouped by the capability they change, not by commit. Requirement
 IDs in parentheses point at [docs/requirements.md](docs/requirements.md); the
 generated trace matrix lives in [docs/traceability.md](docs/traceability.md).

+## v0.4.1
+
+### 🐛 Fixes
+
+- **The lockscreen pause works while a video's audio plays in the background.**
+  The handoff starts native audio and only then tears the WebView `<video>`
+  down — and that teardown fires a DOM `pause` the frontend reports like any
+  other, which left the controller believing webview media was still the
+  player. Transport stayed aimed at it: pressing pause on the lockscreen sent a
+  control command to a `<video>` that no longer existed while the native player
+  carried on, and the element's parting position report dragged the displayed
+  time backwards. A handoff is now tracked explicitly, so it hands transport to
+  the native backend and ignores what the dying element still reports. A pause
+  made from the lockscreen also survives the return to the app, instead of being
+  undone by the play state captured when the handoff began.
+  (UR-040, UR-005 → DR-052, DR-097)
+
+## v0.4.0
+
+### ✨ Features
+
+- **Favourites, across libraries.** A `/library/favorites` page renders
+  favourites from every library with All / Movies / Shows / Music scope tabs,
+  reusing the standard grid so card shape still follows the media — a mixed All
+  tab reads as posters, squares and thumbnails side by side. Home carries
+  favourite rows below Recently Added, and a row with no items does not render
+  at all, so a fresh install shows no empty rows. Server favourite state is
+  mirrored into the local database as results are cached, so offline browsing
+  sees the same favourites as the server; a toggle made offline is never
+  overwritten by a stale server value before it has been pushed.
+  (UR-067, UR-069 → DR-113, DR-114, DR-115, DR-117, DR-118)
+
+- **Search answers from the local index.** The instant leg read only downloaded
+  items, so with no downloads it returned nothing and every keystroke fell
+  through to a full `Recursive=true` server query. It now reads the whole synced
+  catalog through the same availability CTE `get_items` uses, gated on the same
+  `include_catalog_browse` flag, so search and browse cannot diverge. The index
+  also gained MusicArtist, Playlist and People — the very groups search sorts
+  results into. Re-indexing moved from a frontend startup call to a Rust
+  background task with a 6h TTL, so a long session no longer searches a stale
+  catalog. (UR-065 → DR-108, DR-110, DR-111)
+
+### 🐛 Fixes
+
+- **Playback no longer restarts an episode at random on a flaky connection.**
+  Background audio-only playback of a video streams a progressive mp3 transcode
+  over plain HTTP, which is chunked and so declares no length: when the
+  connection dropped mid-episode, ExoPlayer saw end-of-input and reported
+  `STATE_ENDED`, indistinguishable from the real end. The app ran its
+  end-of-episode logic mid-episode and playback parked in `STATE_ENDED`, where
+  the next play intent from the lockscreen, notification or a Bluetooth
+  reconnect seeks an ended player to position 0 — surfacing as "the episode
+  randomly restarted". The item's runtime is now what decides: an end reported
+  well short of it re-opens the stream where it stopped. (UR-040 → DR-129)
+
+- **A network hiccup no longer kills playback outright.** Music and video
+  declare a length, so a cut connection reaches them as an *error* rather than a
+  phantom end — and every error stopped the player. A recoverable error now gets
+  one bounded attempt at re-opening the stream where it stopped, with a growing
+  backoff, leaving the rest of the queue intact. On Linux, MPV additionally
+  reconnects inside the demuxer so ordinary blips never surface at all, and
+  `EndFile(ERROR)` — previously a bare log line that left playback halted while
+  the UI still showed "playing" — is now reported and recovered.
+  (UR-004, UR-040 → DR-129, DR-130)
+
+- **The player no longer reads 0:00 as a track ends on Linux.** MPV exposes
+  `time-pos` and `duration` as properties of the *loaded* file, so at EOF it
+  unloads and both stop resolving — reporting zero at exactly the moment
+  end-of-file handling asks where playback reached. The last reading seen while
+  media was loaded is now kept and used as the fallback. (UR-005 → DR-130)
+
+- **Server-side deletions propagate to the local catalog.** `DELETE FROM items`
+  existed nowhere, so items removed on the server lingered locally forever. A
+  post-crawl mark-and-sweep now removes them, scoped to crawled types, skipping
+  downloaded items, and refusing to run after a partial crawl. Separately,
+  `items_fts` grew a full duplicate index on every catalog pass; it is now a
+  real upsert, with a migration rebuilding existing indexes. (DR-110)
+
+- **Android system bars and display cutout are handled correctly.** (UR-066)
+
 ## v0.2.0

 ### ✨ Features
@@ -75,6 +75,13 @@ For a narrative overview of the system design, see
 | UR-062 | Opening a TV series lands the viewer **where they are in it**, not at season 1: the series page scrolls the current season into view and highlights the current episode, and the hero button opens that episode (labelled `Resume S2E4` / `Play S1E1`). "Current" means the episode in progress, else the server's Next Up for that series, else the first unwatched episode, else the first — resolved by the backend so it also works offline. A season is **never a page of its own**: every route that names a season lands on the series with that season in view, so the episodes of all seasons are always one continuous scrollable list | High | Done |
 | UR-063 | Each video library is **one page**, not three. Browsing (hero, Continue Watching, Next Up, Recently Added, genre rows), the full title grid, and the genre browser are tabs of `/library/tv` and `/library/movies` rather than separate routes with inconsistent names (`/library/tv/shows` vs `/library/movies/all`, `/library/shows/genres` vs `/library/movies/genres`). The old routes redirect so existing links keep working | Medium | Done |
 | UR-064 | Watch history can be **erased**, per series and per season, from the series page. Clearing marks every episode inside unwatched and clears resume positions, so the show returns to "never watched" and reopens on its premiere. It asks for confirmation first (it cannot be undone) and requires a connection to the server, since history cleared only locally would be undone by the next sync | Medium | Done |
+| UR-065 | Search answers from a **locally indexed copy of the library**, so results appear as fast as the device can query rather than at the speed of a round trip to the server, and the same results are found with the server unreachable. A background job keeps the index current — refreshing on a schedule rather than only at app start, dropping media removed from the server, and covering everything the result groups can show (including artists and people). The server is still queried in the background so media added since the last index still turns up, merged in without reordering what is already on screen | High | Implemented |
+| UR-066 | The app's own chrome stays clear of the device's system chrome. On Android the bottom navigation sits above the navigation/gesture bar instead of underneath it, the header clears the status bar, and full-screen video and audio playback keep their controls inside the usable screen — clear of the gesture bar and, in landscape, of the display notch. This must hold across navigation modes (gesture and 3-button) and rotation, not only on the handsets it happened to be tested on | High | Done |
+| UR-067 | Favourited media can be **found again**. A Favourites page lists everything favourited across all libraries, scoped by tabs (All / Movies / Shows / Music); the home screen carries favourite rows for movies, shows and music, hidden when a category is empty; and each library page can be filtered to favourites in place. Without this the like button writes to a store nothing reads | Medium | Done |
+| UR-068 | Anything the app shows can be favourited where it is shown — from a movie, series, episode, album, artist or playlist page, and from any card in a grid or carousel — not only from the player while the item happens to be playing | Medium | Done |
+| UR-069 | Favourite state agrees with the server in both directions. An item favourited in another Jellyfin client shows as favourited here without being touched, and an item favourited here while the server is unreachable reaches the server once it returns — without the user going back to the screen where they marked it | Medium | Done |
+| UR-070 | Playback quality is the viewer's choice: the player offers the bitrates the server can produce for what is playing, and changing one resumes at the same point with the same audio and subtitle tracks. Because the chosen rendition can change at any moment, nothing that streams for playback is treated as a stored copy unless it happens to be byte-identical to the real file | Medium | Proposed |
+| UR-071 | Media the viewer is watching can be **kept**, by a whole-file download that runs in the background independently of playback and at its own quality, so it is unaffected by bitrate changes. Where the streamed bytes already are that file (direct play), they are kept rather than fetched twice. A completed download is then played from disk rather than streamed again | Medium | Proposed |

 ---

@@ -115,6 +122,9 @@ External system integrations and platform-specific implementations.
 | IR-027 | Jellyfin `/System/Info/Public` reachability probe used as an offline→online recovery detector | API | UR-043 | Done |
 | IR-028 | Jellyfin/LMS SyncGroups API client (list, create, join, unsync, dissolve sync groups) | API | UR-046 | Done |
 | IR-029 | Android `ConnectivityManager`/`NetworkCapabilities` transport probe with a `NetworkCallback` change subscription, surfaced to the frontend via the `AndroidNetworkType` JS bridge and the `jellytau-network-changed` WebView event (requires `ACCESS_NETWORK_STATE`) | Platform | UR-053 | Done (pending device verification) |
+| IR-030 | Scheduled full-catalog crawl of every library (`Recursive=true`, paged) feeding the local index, driven by a Rust background task and the `ConnectivityMonitor` reconnect signal rather than by the frontend | Storage | UR-065 | Implemented |
+| IR-031 | Android `WindowInsets` bridge: an `OnApplyWindowInsetsListener` on the decor view reports `systemBars() | displayCutout()` in CSS pixels, pushed into the WebView as `jt-inset` CSS custom properties plus a `jellytau-insets-changed` event, and pullable via the `AndroidInsets` JS bridge | Platform | UR-066 | Done (pending device verification) |
+| IR-032 | Whole-file background download of the item being played, reusing the existing resumable download worker and the Range-capable `/Videos/{id}/stream.mp4` endpoint; plus per-platform read-through caching hooks (ExoPlayer `CacheDataSource`, mpv `stream-record`) for direct-play sessions only | Storage | UR-071 | Proposed |

 ### 2.2 Jellyfin API Requirements

@@ -154,6 +164,9 @@ API endpoints and data contracts required for Jellyfin integration.
 | JA-030 | Get person details and filmography | Persons | UR-036 | Done |
 | JA-031 | Get items by person (actor/director filmography) | Items | UR-036 | Done |
 | JA-032 | Get audio-only stream URL for a video item (selected audio-stream index) | MediaInfo | UR-040 | Done |
+| JA-033 | Query favourite items (`Filters=IsFavorite`, recursive, scoped by item type) | Items | UR-067 | Done |
+| JA-034 | Read `UserData` (favourite, played, resume position) from item responses | UserData | UR-069 | Done |
+| JA-035 | Mark item played (`POST /Users/{userId}/PlayedItems/{itemId}`) | UserData | UR-025 | Done |

 ### 2.3 Development Requirements

@@ -264,6 +277,44 @@ Internal architecture, components, and application logic.
 | DR-105 | Video library routes collapse to one per library. `/library/tv` and `/library/movies` render browse / all-titles / genres as in-page tabs driven by `?view=`, omitted for the default `browse` (the convention `searchRouteUrl` already uses for the `all` scope); `resolveLibraryView` is pure and unit-tested. The four legacy routes become redirect-only `+page.ts` loads rather than deletions, because `GenreTags` links to them and users have them in history; `resolveSearchScope` keeps its `/library/shows` branch for the same reason. The "Browse" tile grid at the bottom of both landing pages is removed — it was a second navigation affordance to the same destinations the carousels' "Show all" links already reach | UI | UR-063 | Done |
 | DR-106 | Erasing watch history goes through the repository, not the local cache: `clear_watch_history(item_id)` maps to Jellyfin's `DELETE /Users/{userId}/PlayedItems/{itemId}`, which clears the played flag *and* zeroes the resume position, and which the server applies recursively to a folder — so one call handles a whole series or season. `OfflineRepository` returns `RepoError::Offline` rather than clearing locally, because history diverged only on the device would be silently undone by the next sync; the button disables itself while the server is unreachable. `ClearHistoryButton` is shared by the series hero and each `SeasonSection` header, confirms before acting (there is no undo), and reloads the page on success so the recomputed current episode — the premiere, for a fully cleared series — is what the viewer sees | Repository | UR-064 | Done |
 | DR-107 | Seasons on the series page are collapsible, and **only the current season is expanded** on load — the one holding the episode DR-101 resolved. A show with ten seasons otherwise renders every episode of every season at once, burying the one episode the viewer came for under hundreds of rows. Expansion state is per season and pure (`initialExpandedSeasons` in `seriesNavigation.ts`): the current season, or the first season when there is no current episode, so a never-watched show still opens on season 1 rather than fully collapsed. A `?episode=` deep link expands that episode's season too. Toggling is local and not persisted — it is a reading position, not a preference | UI | UR-062 | Done |
+| DR-108 | The instant (cache) leg of `repository_search` searches the **synced catalog**, not just downloads. `OfflineRepository::search` replaces its `downloaded_items` CTE with the `available_items` CTE `get_items` already uses — the same downloads branches plus a `synced_at IS NOT NULL` branch gated on the same `include_catalog_browse()` flag — so search and browse cannot diverge on what is visible. Online (flag true) search reads the whole index and answers before any HTTP request completes; offline with "Show all server media" off (flag false) it stays downloads-only, unchanged. Requires no frontend change, since the flag is already set correctly for all three states. The `include_item_types` filter is switched from string interpolation to bound parameters, as `SearchOptions` is settable from the frontend and not only from `SearchScope` | Backend | UR-065 | Implemented |
+| DR-109 | Index freshness is a Rust-owned policy, not a frontend startup call. A tokio task ticks every 30 min and runs a full pass when a repository is active, the server is reachable, and `last_catalog_sync` (already persisted to `app_settings`, previously read only for a UI hint) is older than `CATALOG_INDEX_TTL` (6 h); the `ConnectivityMonitor` reconnect signal re-evaluates the same condition immediately. An `AtomicBool` prevents concurrent passes, replacing `offlineCatalog.ts`'s `syncInProgress` — the frontend trigger is removed rather than left alongside, since two triggers with one guard each is how double-crawls happen. `RepositoryManager` gains an active-handle slot so the task has something to run against. Progress is emitted as the kebab-case `catalog-index-event` | Backend | UR-065 | Implemented |
+| DR-110 | Index hygiene. `save_to_cache` switches from `INSERT OR REPLACE INTO items` to `ON CONFLICT(id) DO UPDATE`: REPLACE fires no `AFTER DELETE` trigger unless `recursive_triggers` is on (it is not — only `foreign_keys` and `journal_mode` are set), so `items_ad` never ran, and because `items.id` is a `TEXT PRIMARY KEY` each replacement also took a fresh rowid and appended a second `items_fts` entry — a duplicate index per sync, invisible in results but permanently degrading `MATCH`. The upsert preserves the rowid `items_fts` keys on and fires `items_au`; migration `021_rebuild_items_fts` clears orphans on existing installs. Separately, a post-crawl sweep deletes synced-but-not-downloaded rows a successful library crawl did not return, so media removed from the server stops being searchable; it skips items with completed downloads and skips any library whose crawl errored, because `items.parent_id` is `ON DELETE CASCADE` and a partial crawl would cascade away a whole series | Storage | UR-065 | Implemented |
+| DR-111 | The index covers what the result groups render: `CATALOG_ITEM_TYPES` gains `MusicArtist` and `Playlist`, and migration `022_people_fts` adds a `people_fts` virtual table over the existing `people` table (which had no FTS, and is populated incidentally by item-detail fetches) with the same trigger pattern as `items_fts`. `OfflineRepository::search` UNIONs `people_fts` matches in as `Person` items when the resolved scope admits them — i.e. `SearchScope::All`, which expands to no filter (DR-063). Without this, the Artists and People groups UR-060 mandates can only ever be filled by the server leg | Storage | UR-065, UR-060 | Implemented |
+| DR-112 | Safe-area insets come from **native**, not from `env()` alone. `env(safe-area-inset-*)` is 0px without `viewport-fit=cover` (missing from `app.html`, so every safe-area rule in the app was already a no-op), and even with it Android WebView maps only the *display cutout* — never the status bar or navigation bar. Since `enableEdgeToEdge()` plus `targetSdk 36` make edge-to-edge unconditional, the WebView always spans the system bars, so CSS could not learn about them by any route. `WindowInsetsBridge` reads the real insets and publishes `jt-inset` custom properties; `app.css` folds them with `env()` via `max()` into `--safe-*`, which is the only thing components may pad from. Ownership is exactly one element per edge: the app shell takes top/left/right, and BottomUi takes bottom wherever it renders (`shellReservesBottomInset` hands it back to the shell on routes with no bottom UI) so the padding sits inside BottomUi's surface box and the colour extends behind the gesture bar. The full-screen players inset their control layers only, leaving video and artwork edge-to-edge. The theme's `fitsSystemWindows=true` — which claimed the opposite and was overridden at runtime and ignored at this target SDK — is removed | UI | UR-066 | Done |
+| DR-113 | `MediaItem.user_data` is populated from the server instead of being hardcoded `None`. `JellyfinItem` gains a `UserData` field (`#[serde(alias = "UserData")]` → the existing `UserData` type) and `to_media_item` maps it, so every list and detail response carries favourite/played/resume state. `UserData` is named explicitly in the `Fields=` list rather than relying on Jellyfin's default. Without this no card or detail page can render a favourite it did not itself set, and the mini player's per-track `storageGetPlaybackProgress` fetch is the only way to colour one heart | Repository | UR-069 | Done |
+| DR-114 | Server favourite state is mirrored into the local `user_data` table by `OfflineRepository::save_to_cache` — the single choke point every cached server result passes through — so offline browsing and the offline Favourites page see the same favourites as the server. The upsert carries `pending_sync = 0` and is guarded by `WHERE user_data.pending_sync = 0`, which is the conflict rule: a toggle made offline is never overwritten by a stale server value before it has been pushed | Storage | UR-069 | Done |
+| DR-115 | Cross-library favourites query: a `get_favorites(scope, options)` repository method plus the `repository_get_favorites` command. Online issues `Filters=IsFavorite&Recursive=true` with `IncludeItemTypes` expanded from `SearchScope::item_types()` in Rust (the frontend sends the opaque scope, never a type list — DR-063); offline reads `items ⨝ user_data (is_favorite = 1)` under the same `include_catalog_browse()` gate as browsing; hybrid races cache against server like `get_items` — saving server results through to the cache on a miss, so the favourites page does not re-query the server every visit and the DR-114 mirror is filled on a fresh install — and applies the DR-080 rule that an empty offline result is authoritative when the gate is off. The command falls back to this read when nothing is cached, rather than painting an empty state it will correct a round trip later. A separate method rather than `get_items` because favourites span libraries and `get_items` is `ParentId`-shaped | Repository | UR-067 | Done |
+| DR-116 | `GetItemsOptions.favorites_only` filters an existing library listing in place — online by appending `Filters=IsFavorite`, offline by joining `user_data` into the existing `available_items` CTE so the downloads-only gate still applies. This is what backs the per-library favourites toggle, and composes with the genre and item-type filters already there | Repository | UR-067 | Done |
+| DR-117 | The Favourites page (`/library/favorites`) renders favourites across libraries with All / Movies / Shows / Music scope tabs, reusing `LibraryViewTabs` + `LibraryGrid` + `MediaCard` so card shape still follows the media (§5A.1) and a mixed All tab reads as posters, squares and thumbnails side by side. Each tab sends a `SearchScope` value and nothing else. Reached from the library overview and from "See all" on the home rows | UI | UR-067 | Done |
+| DR-118 | Home carries favourite rows for movies, shows and music, loaded via `repository_get_favorites` per scope and rendered below Recently Added. A row with no items does not render at all, so a fresh install shows no empty favourite rows | UI | UR-067 | Done |
+| DR-119 | `FavoriteButton` is mounted wherever a whole item is shown — movie/series/episode detail heroes, album/artist/playlist headers, and as a `MediaCard` artwork overlay — and a `favorites` store holds in-session optimistic state so un-hearting on one surface updates every other without a refetch. Resolution order is `store override ?? item.userData?.isFavorite ?? false`. On a card the heart is its own button and stops propagation, so hearting never also opens, plays, or triggers the §5B.5 long-press; it is suppressed on server-only (greyed) cards | UI | UR-068 | Done |
+| DR-120 | Favourite toggles made while offline reach the server. A Rust drain, triggered by the `ConnectivityMonitor` offline→online transition, pushes every `user_data` row with `pending_sync = 1` and clears the flag on success, leaving failures pending for the next transition. It lives in Rust rather than the frontend because a frontend drain dies with the component that started it. Both the drain and the hybrid background refresh emit the kebab-case `favorites-changed` event (`{ itemIds }`) so open views update — without it a favourite marked on another client appears only on the *second* visit to a page, since the cache-first read returns local rows and the server refresh is invisible to the frontend. Supersedes the unused `syncService.queueFavorite`, which is deleted rather than left as a second queue | Backend | UR-069 | Done |
+| DR-121 | Player quality selector: Rust reports the bitrates available for the current media source and owns the quality→transcode-parameter mapping (the one `get_video_download_url` already holds — playback calls into it rather than restating it, or the two tables drift). Changing quality re-negotiates the stream URL and resumes at the current position with audio/subtitle selection preserved. On Linux, video re-negotiates *within* HLS: returning `stream.mp4` is the documented cause of transcoded playback never starting. The frontend renders the list and remembers the choice; it does not decide what the choice resolves to | UI | UR-070 | Proposed |
+| DR-122 | The playback path is ephemeral. Streamed bytes are never persisted unless DR-124 rules them keepable, and any in-flight capture is abandoned — partial file deleted, never promoted — the moment the viewer changes quality, because a capture spanning a rendition change is a splice of two encodings rather than a playable file | Playback | UR-070 | Proposed |
+| DR-123 | The download path is independent of playback: a whole-file fetch through the existing download manager at one canonical quality (default `original`, the direct static copy) over the Range-capable `/Videos/{id}/stream.mp4`, unaffected by bitrate changes and completing into an ordinary `downloads` row so offline browsing and `refresh_queue_local_sources` pick it up unchanged. Prerequisite: downloaded video is currently never played locally — `repository_get_video_stream_url` goes straight to the online repo and the player route calls it with no local check, so a completed video download is still streamed. Without that fix nothing in this spec is observable for video | Repository | UR-071 | In Progress |
+| DR-124 | Streamed bytes are kept only where they *are* the download artifact — a direct-play session. Android uses ExoPlayer `SimpleCache`/`CacheDataSource` keyed by item **and** media-source id so renditions cannot collide, sharing the existing smart-cache storage budget rather than opening a second one over the same disk; Linux audio uses mpv `stream-record`, abandoned on seek because it is documented as intended for linear streams and seeking breaks the recording. Transcoded Linux video is **not** captured: HLS segments are not a file, and assembling one needs ffmpeg, which is not a dependency and which CI may not install at job time — DR-123 covers that case instead | Playback | UR-071 | Proposed |
+| DR-125 | A capture is promoted to a completed `downloads` row only when it covers the whole resource; partials stay evictable cache. A new `downloads.source_rendition` column records the negotiated quality/container/codec (`NULL` for the existing paths, which are always `original`) so a captured transcode and a real download are distinguishable rows and an "upgrade to original" remains possible. A quality change never touches a file that already exists — not a permanent download, and not a completed temporary one, both of which stay valid copies of the rendition they hold. It invalidates only an **in-flight** capture or background download of cached media, which is abandoned and restarted at the newly chosen quality, because a capture spanning a rendition change is a splice of two encodings rather than a playable file | Storage | UR-071 | Proposed |
+| DR-126 | Cache eviction only reclaims the *temporary* tier. `evict_lru_async` selected every completed download ordered by `completed_at ASC` with no `download_source` filter, so hitting the 10 GB storage limit deleted the **oldest** download — typically a film saved deliberately for offline — to make room for a newly precached track. It now evicts only `COALESCE(download_source, 'user') = 'auto'` rows; `COALESCE` rather than a bare equality because rows predating migration 012 can be NULL and unknown provenance must be treated as the user's, never as disposable. Freeing less than requested is the correct outcome when only user downloads remain — the caller reports "unable to free enough space" instead of silently deleting them | Storage | UR-071 | Done |
+| DR-127 | A cache entry *is* a download with a shorter life: same `downloads` row and same file handling, distinguished by `download_source = 'auto'` plus an expiry, so there is one storage model rather than a cache and a download library that can disagree. Temporary rows are reclaimed on whichever comes first — the life limit elapsing, or eviction under space pressure (DR-126). Permanent (`'user'`) rows have no expiry. A temporary row can be promoted to permanent by the user choosing to keep it, which only clears the expiry and flips the source; the bytes never move | Storage | UR-071 | Done |
+| DR-128 | Audio-only playback of *downloaded* media reads the local file rather than fetching an audio-only stream. No transcode is involved or wanted: the Linux backend already runs MPV with `video: no`, so handing it the downloaded video file decodes the audio track and ignores the video, and ExoPlayer disables its video renderer equivalently. Transcoding to a separate audio artifact would cost CPU and battery, need an encoder the project does not ship, and produce a second file to keep in step — for no gain over simply not decoding the video | Playback | UR-071 | Done |
+| DR-129 | A stream that stops delivering is recovered, not treated as terminal. Two failure shapes, because the streams differ. (a) *Phantom end* — the background audio-only handoff uses a progressive mp3 transcode over plain HTTP, chunked and therefore length-less, so a dropped connection reaches the player as end-of-input and ExoPlayer reports `STATE_ENDED` indistinguishably from the real end. The item's runtime is the only thing that can tell them apart: an end reported more than a tolerance short of it (comparing the *absolute* position — handoff base plus the player's relative position) is a truncation. Left unhandled, playback parked in `STATE_ENDED` and the next play intent from the lockscreen, notification or a Bluetooth reconnect seeks an ended player to position 0 — the user-visible "the episode randomly restarted". (b) *Recoverable error* — music (`/Audio/{id}/stream?Static=true`) and video (`/Videos/{id}/master.m3u8`) declare their length, so the player detects the truncation itself and raises an error; the frontend's handler stopped playback outright, turning a hiccup into silence. Both resume the current item **in place** (never via `play_item`, which would replace the queue with a single item and lose the album), the error path after a per-attempt backoff. Seekable streams are re-prepared at the URL they already have and seeked; the length-less transcode, which cannot be seeked, has `StartTimeTicks` rewritten into its existing URL so the user's audio-track selection survives and recovery needs no network round-trip. Only `Remote` sources qualify — a local file cannot fail from the network. A shared budget of consecutive attempts at the same position, refilled whenever playback progresses, stops an unreachable server from looping | Playback | UR-040, UR-004 | Done |
+| DR-130 | A backend's position and duration must survive the end of the file they describe. MPV exposes `time-pos`/`duration` as properties of the *loaded* file, so at EOF it unloads and both stop resolving — the accessors reported `0.0`/unknown at exactly the moment end-of-file handling asks where playback reached, and any position-versus-runtime check would have read every natural end as a truncation. The poll thread records the last reading and the accessors fall back to it. Linux resilience is layered on the same principle that the stream, not the player, is what failed: MPV is configured with ffmpeg reconnection (`stream-lavf-o`, `network-timeout`) so ordinary blips never surface, and `EndFile(ERROR)` — previously a bare log, which left playback halted while the UI still showed "playing" — is emitted as a *recoverable* error. Because MpvBackend is constructed before `PlayerController` exists, it cannot decide in-process like the Android JNI callback: the frontend echoes the error into `player_recover_stream`, which keeps the decision in Rust (the same shape as `PlaybackEnded` → `player_on_playback_ended`). Android reports errors it has already declined as *unrecoverable*, so the echo never asks twice | Playback | UR-004, UR-040 | Done |
+| DR-131 | The offline mutation queue is drained. `sync_queue` had producers and no consumer: `PlaybackReporter::queue_for_sync` writes a row for every start/stop/mark-played that cannot reach the server, `sync_mark_processing`/`_completed`/`_failed` were registered commands with no callers, and no Rust task processed the table — so queued watch positions never reached Jellyfin and the offline banner's count only ever grew. A drain hangs off the same `connectivity:reconnected` transition as DR-120 (in Rust, because a drain started by a component dies with it) and replays rows oldest-first, so a stale start cannot move the server's resume position backwards after a later stop. `update_progress` replays as *stopped at N* rather than as progress — replaying a mid-playback report hours later would claim the item is still playing — and payloads are read in both dialects that exist in users' databases (`position_ticks` from Rust, camelCase `positionMs` from the frontend helper). A failed row stays queued for the next reconnect; after `MAX_SYNC_ATTEMPTS` it is `abandoned` and stops counting, because a row nothing can ever push is what turns the queue into a counter that only grows. An *unreachable* server is not counted as an attempt at all — the row goes back to `pending` untouched — so opening the app offline a few times cannot abandon good rows; only a server that answers and refuses spends the budget. The drain also runs once at startup, because a queue built in a previous session would otherwise sit untouched for a whole run whenever the server was reachable the entire time and no offline→online transition ever fired. Requires `MediaRepository::mark_played` (JA-035) — the previous stand-in reported a stop at `i64::MAX` | Backend | UR-025, UR-002 | Done |
+| DR-132 | The pending-sync count is answerable. The offline banner's badge read "N pending sync(s)" and led nowhere, so it was taken for pending *transfers* and looked for on the Downloads page — which lists the `downloads` table and structurally cannot show `sync_queue` rows. The badge becomes a button opening the queue it counts: each row's operation, the item's title (resolved by a `LEFT JOIN items` in `sync_get_pending`, not a per-row frontend fetch), when it was queued, and the error of anything failing, plus a "Sync now" that runs the DR-131 drain on demand. The same list is a Settings section, because a row that keeps failing is still queued when the server is reachable and no banner is on screen. The drain emits `sync-queue-changed` so the badge updates on reconnect instead of lagging by up to one 10s poll | UI | UR-025 | Done |
+| DR-133 | A downloaded file has exactly one on-disk path, and the row that names it is authoritative. `downloads.file_path` starts relative to the storage root, but the worker rewrites it to the absolute path it actually wrote when the transfer completes — so a *completed* row is already rooted. The video player's offline branch rooted it a second time, handing the asset protocol `/data/user/0/app//data/user/0/app/videos/x.mp4`; the webview reported `MEDIA_ERR_SRC_NOT_SUPPORTED` with `NETWORK_NO_SOURCE`, so every downloaded video failed to play while audio — which resolves the same column through Rust's `resolve_local_media_path`, without re-rooting — played fine. The join is absolute-aware (POSIX, Windows drive letters and UNC) so rows written before completion still resolve | Playback | UR-071 | Done |
+| DR-134 | The webview can actually fetch the local files it is handed. `convertFileSrc` rewrites a path to `http://asset.localhost/…` unconditionally, but Tauri only answers that origin when the `protocol-asset` cargo feature is compiled in *and* `app.security.assetProtocol.enable` is set — neither was, so every such URL reached a protocol with no handler and the webview reported `NETWORK_NO_SOURCE`. This silently defeated both offline video (`<video src>`) and the cached-thumbnail path in `imageCache`, which fails soft to the server copy and so hid the breakage whenever the server was reachable. The scope is `$APPDATA/**` — the storage root under which the database, `downloads/` and the thumbnail cache all live — rather than an unrestricted grant, so the webview can read the app's own media and nothing else | Security | UR-071 | Done |
+| DR-140 | An audio track is pinned only when the user picked one. Jellyfin's `MediaStream.Index` is global across every stream in a media source, so index 0 is the *video* stream on virtually all files — yet `AudioStreamIndex=0` was sent as "the first audio track" on the HLS transcode URL, the background audio-only handoff URL, the direct-play fallback URL, and the `PlaybackInfo` negotiation body. A server that honours the request literally then transcodes the video stream into the audio slot and the result plays as a picture with no sound; only servers that silently correct the index hid the bug, which is why it presented as "some videos have no audio". The parameter is now omitted whenever no track has been chosen, so the server resolves the source's `DefaultAudioStreamIndex`; an explicit selection from `player_switch_audio_track` is still carried through unchanged. On the `static=true` direct-play URL it is dropped outright — the original file is served untouched, so the parameter could only mislead | Playback | UR-004, UR-040 | Done |
+| DR-147 | One search input per screen, and the URL is the search's single source of truth. The header bar rendered only under `/library/**` and merely *navigated* to `/search` (DR-063), so a desktop search handed the user to a screen whose input was a different element — the header box cleared itself and vanished, and the page's own box took over mid-word. That page then re-derived its input from `?q=` against `library.searchQuery` on every store write, so the next keystroke re-ran the effect and snapped the text back to the query the header had sent (and a scope chip back to the URL's scope); entering from the bottom-nav Search tab skipped it only because the effect early-returned on an empty query. The bar now renders on `/search` too (`showHeaderSearch`) and is the sole md+ input — the page's own input is `md:hidden` — and on that route it republishes the query into the URL with `replaceState`, so a whole session of typing costs one history entry. The page *consumes* that URL once per distinct value (`seedFromSearchUrl` against a non-reactive `applied` marker) instead of continuously reconciling it, and the scope chips publish through the same URL so the bar and the chips cannot disagree. Landing on `/search` with a seeded query focuses the bar and puts the caret at the end, because the box the user was typing in belonged to the unmounted route | UI | UR-049, UR-054 | Done |
+| DR-142 | An episode has exactly **one** surface, and it is complete. Two divergent renderings existed: `EpisodeFocusView` (reached from Continue Watching, the series episode list, the TV landing page and Downloads — i.e. every real entry point) offered only Play and Favourite, while the bare `/library/<episodeId>` page nobody routed to carried the download button, the series/season breadcrumbs and the cast section. Opening an episode the normal way therefore silently lost the ability to download it. The Focus View is now the single surface and carries the full §5B.2 composition — hero action row `Play / Download / Favourite`, series name and `SxEy` badge as links back to the series and to that season's anchor, then genres → cast → similar shows *below* the episode strip, never above it (DR-062). `/library/<episodeId>` redirects into it (`episodeRedirectTarget`, the same rule seasons follow under DR-103), and an episode with no `seriesId` renders the same component series-less rather than falling back to a second, lesser page. The focused episode is fetched in full rather than reused from the season fan-out, because that is a *list* query and carries neither cast nor genres — the sections would have rendered empty. The strip hides itself when the episode has no siblings, a card that only shows the episode you are already on being noise | UI | UR-048, UR-058 | Done |
+| DR-141 | The device profile states how many channels the audio route can actually voice. `MediaCodecList` answers "can this device *decode* 5.1", which is not the question that decides whether the user hears anything — a phone decodes an AC-3 5.1 track happily and still has two channels to play it out of. With no `MaxAudioChannels` in the profile, Jellyfin was free to direct-play the multichannel track, and the result is device dependent: a failed `AudioSink` configuration (silence) or dialogue folded into surround channels that go nowhere. media3's `AudioCapabilities.maxChannelCount` for the current route is reported over JNI alongside the codec lists, and bounds both the direct-play profile and the transcoding profiles, so the server downmixes rather than shipping channels the sink cannot take. Codecs are never removed from the profile — a device with genuine surround output keeps direct-playing it. A missing or zero reading means "route not yet established", not "no audio", and falls back to stereo, the one capability every sink has | Playback | UR-004 | Done |
+| DR-145 | Video playback starts only once the app actually holds audio focus. Video manages focus by hand (`handleAudioFocus=false`, because ExoPlayer's automatic handling is reserved for the audio path), and the request's three outcomes were all treated as success: `AUDIOFOCUS_REQUEST_DELAYED` — which `setAcceptsDelayedFocusGain(true)` explicitly invites, and which means the system is *withholding our audio* until it calls back — and an outright `REQUEST_FAILED` were logged and then followed by `playWhenReady = true`. The picture rolled with no sound, indistinguishable to the user from a broken stream. Playback is now held when focus is not granted and started from the `AUDIOFOCUS_GAIN` callback; an explicit `play()` re-requests focus rather than resuming into a stream the system is still muting, guarded by a held-focus flag so repeated plays do not leak focus requests. A `LOSS` clears the pending flag, so an unrelated later `GAIN` cannot start playback the user never asked for | Playback | UR-004 | Done |
+| DR-146 | The no-audio-track fallback picks a track the renderer can actually play. When ExoPlayer selected no audio track, the recovery forced group 0 / track 0 unconditionally — but the most likely reason nothing was selected is that this very track cannot be decoded on this device, so the override reinstated the silence it was meant to fix. It now scans the groups for the first `isTrackSupported` track and overrides to that, and clears `setTrackTypeDisabled(TRACK_TYPE_AUDIO)` because audio may equally have been off at the type level, which an override alone does not undo. When no group holds a supported track the condition is logged as an error — the server was expected to transcode — rather than leaving a silent video with no explanation in the log | Playback | UR-004 | Done |
+| DR-143 | Flipping the offline downloaded-only gate actually re-queries the listing. The gate (DR-078) is a process-wide flag in Rust consulted only *while a query runs*, but no library surface re-queried when its inputs changed: `useServerReachabilityReload` fires only on the offline → **online** transition, and `GenericMediaListPage`, `GenericGenreBrowser` and the favourites page never even called its `checkServerReachability`. So going offline left the full server catalog on screen under a now-closed gate, and toggling "Show all server media" only greyed cards — `MediaCard.isServerOnly` is a pure frontend derivation that updates instantly — without adding or removing a single row. The filter therefore read as "shows everything until I filter, then greys some of it" while the backend gate was correct and simply never exercised. `catalogFilterVersion` is the refetch signal: `pushCatalogVisibility` now awaits `set_show_server_catalog` and bumps the version only **after** the backend accepts the new flag, since a reload racing the push would re-query under the old gate and undo itself. A failed push clears `lastIncludeCatalog` instead of latching it, so the next identical transition is retried rather than skipped as a no-op and left permanently disagreeing with the backend. `useOfflineFilterReload` subscribes pages to that signal, skipping the value they already loaded under; it is wired into both generic list components and the movies/music/tv/favourites landing pages and the `/library/[id]` detail page | UI | UR-052 | Done |
+| DR-135 | A download's media type comes from the item, not a default. `download_item` — the path a media card uses to queue an item while offline — never records `media_type`, and the reconnect resolver read that NULL as `'audio'`, so a **movie** queued from a card had its URL resolved by `get_audio_stream_url`. The file that landed on disk was an audio-only transcode, which is why a "downloaded" film could never play offline no matter how the path or protocol was fixed. The resolver now falls back to the item's own `item_type` (`VIDEO_ITEM_TYPES` in Rust, so the frontend never learns which types are video) and only defaults to audio when the item is not cached locally. An explicit `media_type` on the row still wins | Downloads | UR-071, UR-052 | Done |
+| DR-136 | Rows already downloaded under the audio default are repaired, not just prevented. They are identifiable after the fact — no `media_type`, but a video item — so on reconnect they are reset to `pending` with their audio URL cleared and re-resolved by DR-135's corrected logic, overwriting the audio file in place. Without this the fix is invisible to anyone who had already queued a film: the row still reads "downloaded" and still fails to play. Rows carrying an explicit `media_type` and genuine audio downloads are left untouched | Downloads | UR-071 | Done |
+| DR-137 | Local media is served to the player over a loopback HTTP server, not the asset protocol. Tauri's `asset` protocol answers a request carrying no `Range` header by reading the whole file into memory, and only advertises `Accept-Ranges: bytes` from *inside* its range branch — so the first request never learns ranges exist and a multi-gigabyte body is attempted instead. Chromium abandoned it with `PIPELINE_ERROR_READ` after ~31s, which reached the user as "downloaded video does not play offline". Real HTTP on `127.0.0.1` is chosen over a custom URI scheme deliberately: range support becomes a property of the transport rather than depending on whether a platform's webview forwards `Range` to a custom scheme. No response ever exceeds a 4 MiB chunk and bodies stream from the file handle, so memory is bounded regardless of file size. Because **loopback is shared between apps on Android**, the server binds `127.0.0.1` only and every URL carries a random per-session token; paths are additionally confined to the app data directory, so a leaked URL cannot read outside it. This is stage 1 of making the server the single media origin — remote passthrough and download-while-watching are deliberately out of scope here | Playback | UR-071 | Done |
+| DR-138 | Loopback is exempted from Android's cleartext ban, and nothing else is. Release builds set `usesCleartextTraffic="false"`, so the webview's request to the local media server (DR-137) was rejected by network security policy before any I/O — `<video>` failed in the same millisecond as `loadstart`, with `NETWORK_NO_SOURCE` and no server-side log at all, which is why it looked identical to a missing file. A `network-security-config` resource permits cleartext for `127.0.0.1` only and keeps `base-config cleartextTrafficPermitted="false"`, so a remote server must still be HTTPS; this is deliberately not a blanket opt-in. The manifest attribute is ignored once the config is present, so the config is the single authority. `sync-android-sources.sh` also had to learn to copy `res/xml`, which it skipped — the manifest references the resource, so a missed copy fails the resource link rather than degrading quietly | Security | UR-071 | Done |
 | DR-093 | Traceability coverage gate derives its requirement denominators from `requirements.md` at run time rather than hardcoded literals: `countDefinedRequirements` counts an ID only where it leads a markdown table row (ignoring the "Traces To" column and prose) and deduplicates IDs listed both in the definition tables and in the §3 traceability matrix; `computeCoverage` reports the *intersection* of traced and defined IDs so an ID traced in code but absent from `requirements.md` is surfaced as `orphaned` instead of inflating the ratio past 100%. UT/IT test identifiers are excluded as a separate taxonomy. CI and `bun run traces:coverage` share this computation and fail on both a sub-threshold and an impossible >100% result | Tooling | - | Done |

 ---
@@ -277,7 +328,7 @@ Internal architecture, components, and application logic.
 | UR-001 | IR-001, IR-002 | - |
 | UR-002 | IR-013 | DR-003, DR-012, DR-013, DR-014 |
 | UR-003 | IR-003, IR-004, IR-011 | DR-002, DR-004, DR-010 |
-| UR-004 | IR-003, IR-004, IR-008, IR-011 | DR-002, DR-004, DR-006 |
+| UR-004 | IR-003, IR-004, IR-008, IR-011 | DR-002, DR-004, DR-006, DR-129 |
 | UR-005 | - | DR-001, DR-005, DR-009 |
 | UR-006 | IR-005, IR-006, IR-007, IR-008 | - |
 | UR-007 | IR-010 | DR-007, DR-008, DR-016 |
@@ -298,7 +349,7 @@ Internal architecture, components, and application logic.
 | UR-022 | IR-017 | DR-025 |
 | UR-023 | IR-010 | DR-026, DR-047, DR-048, DR-049 |
 | UR-024 | IR-010 | DR-027 |
-| UR-025 | IR-015 | DR-028 |
+| UR-025 | IR-015 | DR-028, DR-131, DR-132 |
 | UR-026 | - | DR-029, DR-048, DR-050 |
 | UR-027 | IR-020 | DR-030 |
 | UR-028 | - | DR-031 |
@@ -313,7 +364,7 @@ Internal architecture, components, and application logic.
 | UR-037 | IR-010 | DR-042 |
 | UR-038 | IR-010 | DR-043 |
 | UR-039 | - | DR-045, DR-046 |
-| UR-040 | IR-025 | DR-051, DR-052 |
+| UR-040 | IR-025 | DR-051, DR-052, DR-129, DR-130 |
 | UR-041 | IR-026 | DR-053 |
 | UR-042 | IR-009, IR-014 | DR-054 |
 | UR-043 | IR-027 | DR-055 |
@@ -321,22 +372,29 @@ Internal architecture, components, and application logic.
 | UR-045 | - | DR-057 |
 | UR-046 | IR-028 | DR-058 |
 | UR-047 | IR-013 | DR-060 |
-| UR-048 | - | DR-061, DR-062 |
-| UR-049 | IR-010 | DR-063, DR-064, DR-065 |
+| UR-048 | - | DR-061, DR-062, DR-142 |
+| UR-049 | IR-010 | DR-063, DR-064, DR-065, DR-147 |
 | UR-050 | - | DR-066, DR-067 |
 | UR-051 | - | DR-068, DR-069, DR-070 |
-| UR-052 | IR-027 | DR-078, DR-079, DR-080 |
+| UR-052 | IR-027 | DR-078, DR-079, DR-080, DR-143 |
 | UR-053 | IR-029 | DR-074 |
-| UR-054 | - | DR-075, DR-076, DR-077 |
+| UR-054 | - | DR-075, DR-076, DR-077, DR-147 |
 | UR-055 | - | DR-081, DR-082, DR-083, DR-084 |
 | UR-056 | - | DR-085 |
 | UR-057 | - | DR-086 |
-| UR-058 | - | DR-087 |
-| UR-060 | - | DR-090, DR-091 |
+| UR-058 | - | DR-087, DR-142 |
+| UR-060 | - | DR-090, DR-091, DR-111 |
 | UR-061 | - | DR-092 |
 | UR-062 | - | DR-101, DR-102, DR-103, DR-104, DR-107 |
 | UR-063 | - | DR-105 |
 | UR-064 | - | DR-106 |
+| UR-065 | IR-030 | DR-108, DR-109, DR-110, DR-111 |
+| UR-066 | IR-031 | DR-112 |
+| UR-067 | - | DR-115, DR-116, DR-117, DR-118 |
+| UR-068 | - | DR-119 |
+| UR-069 | - | DR-113, DR-114, DR-120 |
+| UR-070 | - | DR-121, DR-122 |
+| UR-071 | IR-032 | DR-123, DR-124, DR-125, DR-126, DR-127, DR-128, DR-133, DR-134, DR-135, DR-136, DR-137, DR-138 |

 ---

@@ -436,6 +494,52 @@ Internal architecture, components, and application logic.
 | UT-091 | Transport intents (play/pause/toggle) reach the backend even while a video adapter is registered, and never call the adapter's own `play`/`pause`/`toggle` — the webview must not decide play-vs-pause from the DOM | DR-097 | Done |
 | UT-092 | `shouldReuseActivePlayback` reuses backend playback for an already-loaded audio track but never for video, and never when an explicit start position or a next-episode restart was requested | DR-100 | Done |
 | UT-093 | `resolvePlayerSurface` returns `video` only with a stream URL, `pending` for video whose stream URL is still missing (never `audio`), and `audio` for audio content | DR-100 | Done |
+| UT-094 | `parseNativeInsets` accepts the bridge's JSON or a decoded object, and coerces missing/negative/non-finite edges to 0 rather than emitting `NaNpx` (which would invalidate the whole padding declaration) | DR-112 | Done |
+| UT-095 | `safeAreaCssVars`/`applySafeAreaInsets` emit px-suffixed `jt-inset` custom properties for all four edges | DR-112 | Done |
+| UT-096 | `readNativeInsets` returns null with no bridge and survives a stale WebView proxy (missing or throwing `get`) instead of throwing out of layout init | IR-031, DR-112 | Done |
+| UT-097 | `initSafeArea` primes the document on start, re-applies on `jellytau-insets-changed` (rotation, nav-mode switch), unsubscribes on teardown, and writes nothing without a bridge so `env()` still wins on iOS/desktop | IR-031, DR-112 | Done |
+| UT-098 | `shellReservesBottomInset` gives the bottom inset to BottomUi wherever one renders and to the app shell only on routes without one, so the gesture bar is never ignored nor double-padded | DR-112 | Done |
+| UT-099 | A Jellyfin item payload carrying `UserData.IsFavorite` maps to `MediaItem.user_data.is_favorite` | DR-113, JA-034 | Done |
+| UT-100 | `OnlineRepository::get_favorites` builds `Filters=IsFavorite` + `Recursive=true` + the scope's `IncludeItemTypes`, and omits the type filter entirely for `SearchScope::All` | DR-115, JA-033 | Done |
+| UT-101 | `OfflineRepository::get_favorites` returns only `is_favorite = 1` rows, honours the scope type filter, and stays downloads-only when the catalog-browse gate is off | DR-115 | Done |
+| UT-102 | The `save_to_cache` favourite mirror does not overwrite a row with `pending_sync = 1` | DR-114 | Done |
+| UT-103 | The reconnect drain pushes pending favourites, clears `pending_sync`, and leaves failed rows pending | DR-120 | Done |
+| UT-104 | `get_items` with `favorites_only` filters online (endpoint) and offline (SQL) | DR-116 | Done |
+| UT-105 | `favorites` store precedence: override beats `userData.isFavorite` beats `false` | DR-119 | Done |
+| UT-106 | Un-favouriting removes an item from a favourites listing view | DR-117, DR-119 | Done |
+| UT-107 | The hybrid background refresh emits `favorites-changed` only for ids whose favourite state actually flipped | DR-120 | Done |
+| UT-109 | Search covers synced-but-not-downloaded items when catalog browse is on, and stays downloads-only when off | DR-108 | Done |
+| UT-110 | Search item-type filter is bound, not interpolated: a quote-bearing type neither errors nor widens results | DR-108 | Done |
+| UT-111 | FTS prefix queries quote each token, so apostrophes/hyphens/slashes are data; empty or punctuation-only input returns no rows rather than erroring | DR-108 | Done |
+| UT-112 | Repeated catalog passes leave one `items_fts` entry per item, not one per pass | DR-110 | Done |
+| UT-113 | The stale-catalog sweep removes vanished synced rows, keeps downloaded ones, keeps uncrawled types, and stays scoped to one server | DR-110 | Done |
+| UT-114 | Cached people are reachable from unscoped search and excluded from scoped search | DR-111 | Done |
+| UT-115 | Re-index staleness policy: never-indexed and unparseable timestamps are due, fresh ones are not, future ones are not | DR-109 | Done |
+| UT-116 | `resolve_local_media_path` returns a completed download's file, and `None` for an in-progress download, a row whose file has been deleted, or an unknown item | DR-123 | Done |
+| UT-118 | `resolveVideoSource` prefers a downloaded file, never marks a local file as needing transcoding, and falls back to streaming for a blank path | DR-123 | Done |
+| UT-119 | The audio-only handoff picks a downloaded file over the audio-only stream URL, preserving the Jellyfin id for progress sync | DR-128 | Done |
+| UT-120 | Expiry reclaim takes only expired temporary entries: derived from `completed_at`+TTL, honouring an `expires_at` override, never a user download, and disabled by a zero TTL | DR-127 | Done |
+| UT-108 | LRU eviction reclaims only `'auto'` downloads and never a user's own, even when the user's is the oldest | DR-126 | Done |
+| UT-117 | A background audio-only stream cut short resumes where it died instead of ending the episode; a real end still advances; the absolute position is compared against the runtime; retries at a stuck position give up. A recoverable error resumes music and video too, with growing backoff, leaving the rest of the queue intact and the seekable stream's URL untouched; local and DirectUrl sources are excluded | DR-129 | Done |
+| UT-124 | `downloadedFilePath` leaves a completed download's absolute path alone (POSIX and Windows) and only roots one that is still relative | DR-133 | Done |
+| UT-125 | A NULL `media_type` resolves from the item type — Movie and Episode as video, a track as audio — an uncached item still defaults to audio, and an explicit `media_type` overrides the item | DR-135 | Done |
+| UT-126 | Requeueing takes only video rows downloaded under the audio default, clearing their URL, and leaves correctly-typed video rows and real audio downloads alone | DR-136 | Done |
+| UT-127 | The media server bounds and confines every response: a range-less request yields one chunk rather than the whole file, no range exceeds the chunk cap, explicit/open-ended/suffix ranges resolve correctly, a range past the end is unsatisfiable rather than clamped, a malformed header falls back to the first chunk, path traversal and unrelated absolute paths are refused, a wrong or absent token is rejected, and content type comes from the extension then the magic bytes | DR-137 | Done |
+| UT-121 | An EOF reads as the last observed timestamp, not zero: live readings win while the file is loaded, a not-yet-established duration is not recorded as a real zero, a seek updates the position before the next poll, and loading a new file clears the previous one's | DR-130 | Done |
+| UT-122 | The sync-queue drain pushes queued playback reports oldest-first, defers failures for the next reconnect, abandons a row after `MAX_SYNC_ATTEMPTS`, ignores other users' rows, and parses both payload dialects | DR-131 | Done |
+| UT-123 | Pending-sync rows describe themselves: every queueable operation has a label, an unknown one still renders, the item title falls back to its id, and rows list oldest-first | DR-132 | Done |
+| UT-130 | Video and background-audio stream URLs omit `AudioStreamIndex` when no track was chosen, and carry the exact index when one was | DR-140 | Done |
+| UT-131 | The Episode Focus View hero offers a download control | DR-142 | Done |
+| UT-132 | The series name links to the series and the `SxEy` badge to that season's anchor | DR-142 | Done |
+| UT-133 | Cast renders below the "More Episodes" strip, never above it | DR-062, DR-142 | Done |
+| UT-134 | The episode strip is hidden when the episode has no siblings | DR-142 | Done |
+| UT-135 | An episode with no `seriesId` still renders the Focus View, with title, Play and download | DR-142 | Done |
+| UT-136 | `episodeRedirectTarget` sends a bare episode page into its series' Focus View, and returns null with no series | DR-142 | Done |
+| UT-137 | Going offline with the toggle off pushes the closed gate and bumps `catalogFilterVersion` | DR-143 | Done |
+| UT-138 | The version bumps only after `set_show_server_catalog` resolves, never before | DR-143 | Done |
+| UT-139 | A failed visibility push is retried on the next identical transition rather than latched | DR-143 | Done |
+| UT-140 | `useOfflineFilterReload` skips the value a page already loaded under and reloads on each later change | DR-143 | Done |
+| UT-141 | The advertised channel cap: an unknown or zero reading falls back to stereo, a real route keeps its channels, an absurd driver reading is capped at 7.1, and mono is taken at its word | DR-141 | Done |

 ### Integration Tests

@@ -0,0 +1,334 @@
+# Spec: Locally-indexed search
+
+**Status:** Implemented
+**Requirements:** UR-065 → DR-108, DR-109, DR-110, DR-111; IR-030
+**UX spec:** [ux-flows.md §6.1](../ux-flows.md) (search surface is unchanged)
+**Revises:** [scoped-search.md](scoped-search.md) and
+[scoped-search-boundary.md](scoped-search-boundary.md) — scope semantics are
+untouched; this changes only *which corpus* the cache leg searches.
+
+## Summary
+
+Search stops depending on a per-keystroke round trip to Jellyfin. The local
+SQLite catalog — which is already synced and already FTS5-indexed — becomes the
+corpus the instant leg of search reads, so results appear as fast as SQLite can
+answer, online or offline. A background indexer keeps that catalog fresh on a
+schedule instead of only at app start, prunes content deleted on the server, and
+covers the item types search groups results by. The server query stays, demoted
+to a background reconciliation that merges in late results for anything indexed
+since the last pass.
+
+## Motivation
+
+The pieces are already built and simply not wired together:
+
+- [`sync_full_catalog`](../../src-tauri/src/commands/catalog.rs) already walks
+  every library `Recursive=true` and persists items with `synced_at`.
+- `items_fts` (schema.rs migration 001) already indexes `name`, `overview`,
+  `album_name`, `album_artist`, `artists`, `series_name` with keep-in-sync
+  triggers.
+- `repository_search` is already two-phase — synchronous cache result, then a
+  spawned server query merged in via the `search-event`.
+
+What breaks the chain is that the cache leg is hard-restricted to *downloaded*
+items. `OfflineRepository::search` wraps its FTS query in a `downloaded_items`
+CTE requiring `d.status = 'completed'`:
+
+```sql
+FROM items i
+ JOIN items_fts fts ON fts.rowid = i.rowid
+ INNER JOIN downloaded_items di ON i.id = di.id
+ WHERE i.server_id = ? AND items_fts MATCH ?
+```
+
+So for a user with no downloads, phase 1 returns nothing on every query, and
+every debounced keystroke falls through to a full `Recursive=true` server
+request with `Limit=10000`. The populated local index is never read.
+
+`get_items` does not have this problem — it gates a third `synced_at IS NOT NULL`
+branch on `include_catalog_browse()` (offline.rs, the "Show all server media"
+toggle). The asymmetry is the bug: **offline you can already browse the whole
+catalog but cannot search it.**
+
+Three further defects found while confirming the above:
+
+1. **The FTS index grows without bound.** `save_to_cache` uses
+   `INSERT OR REPLACE INTO items`, but `recursive_triggers` is never enabled
+   (`storage/mod.rs` sets only `foreign_keys` and `journal_mode`). SQLite fires
+   `AFTER DELETE` triggers on a REPLACE *only* with recursive triggers on — so
+   `items_ad` never runs, the old FTS row is orphaned, and because `items.id` is
+   a `TEXT PRIMARY KEY` the replacement row takes a **new rowid** and inserts a
+   second FTS entry. Every sync appends a duplicate index. Results stay correct
+   (the `INNER JOIN … ON fts.rowid = i.rowid` hides orphans, and no rowid is ever
+   reused because nothing is deleted) but `MATCH` degrades permanently.
+2. **Server-side deletions never propagate.** There is no `DELETE FROM items`
+   anywhere in the codebase. The local catalog is append-only, so media removed
+   from the server would stay searchable forever — tolerable when the cache was
+   only a browse accelerator, not acceptable when it is the search corpus.
+3. **The index omits types search groups by.** `CATALOG_ITEM_TYPES` is
+   `MusicAlbum, Movie, Series, Season, Episode, Audio, BoxSet` — no
+   `MusicArtist`, no `Playlist`, and People live in a separate `people` table
+   with no FTS at all. UR-060 mandates Artists and People result groups, so today
+   those can *only* come from the server.
+
+## Layer assignment
+
+| Logic / responsibility | Layer | Why it belongs there |
+|------------------------|-------|----------------------|
+| Which corpus search reads (downloads-only vs full synced catalog) | **Rust** | Sync/availability policy over domain data. Changes if Jellyfin's API or the offline rules change, not if the UI is redesigned. Reuses the existing `include_catalog_browse()` flag so search and browse cannot diverge again. |
+| Index freshness policy — TTL, when a re-index is due, skip-while-offline | **Rust** | Explicitly named as domain policy in [SPEC-REVIEW-CHECKLIST.md](SPEC-REVIEW-CHECKLIST.md) ("reachability/sync policy"). It is currently frontend-driven in `offlineCatalog.ts`; this spec moves it. |
+| Which Jellyfin item types get indexed (`CATALOG_ITEM_TYPES`) | **Rust** | Textbook domain taxonomy — a category→item-type set. Must never appear in `src/`. |
+| Reconciling a crawl against local rows (what to prune) | **Rust** | Operates on domain data and depends on crawl completeness semantics. |
+| FTS query construction, ranking, scope→type expansion | **Rust** | Already there (`search_rank.rs`, `SearchScope::item_types()`); unchanged by this spec. |
+| Rendering a "catalog last indexed N ago" hint and any re-index button | **Frontend** | Pure presentation of a backend-supplied timestamp. |
+| Debounce interval, result group order, scope chips | **Frontend** | Input handling and view preference; changes only if the UI is redesigned. |
+
+Borderline call, recorded: the **TTL value itself** (how many hours before a
+re-index is due) could be argued as a user preference and therefore frontend. It
+is placed in Rust because the frontend must not be able to decide *whether the
+cache is authoritative* — that is the same class of decision as
+`include_catalog_browse`, which already lives in Rust. If the TTL later becomes
+user-configurable it stays a Rust-owned setting the frontend edits through a
+command, not a frontend constant. Borderline defaults to Rust.
+
+## Design
+
+### 1. Search the full synced catalog (DR-108)
+
+`OfflineRepository::search` mirrors `get_items` exactly: rename the CTE to
+`available_items` and add the same third branch, gated on the same flag.
+
+```rust
+let catalog_branch = if include_catalog_browse() {
+    "UNION
+
+        -- Synced catalog: fast online search, or the offline 'Show all
+        -- server media' view. Mirrors get_items; see set_include_catalog_browse.
+        SELECT DISTINCT i.id
+        FROM items i
+        WHERE i.synced_at IS NOT NULL"
+} else {
+    ""
+};
+```
+
+No new IPC surface and no frontend change: `set_include_catalog_browse` is
+already called with `true` when online or when the offline toggle is on, and
+`false` only when offline with the toggle off. Search inherits the correct
+behaviour in all three states, and the "search is restricted to downloads" case
+survives for users who deliberately asked for downloads-only.
+
+Also fix, in the same function, the `type_filter` built by **string
+interpolation** of `include_item_types` rather than bound parameters. It is
+currently safe only because callers pass `SearchScope`-derived values, but
+`SearchOptions.include_item_types` is settable directly from the frontend (as
+`GenericMediaListPage` does). Bind the values.
+
+Phase 2 (the server query) is unchanged and still merges via `search-event`, so
+content added to the server since the last index still surfaces — just late
+rather than first.
+
+### 2. Scheduled background indexer (DR-109, IR-030)
+
+A Rust-owned task replaces the frontend's startup-only trigger.
+
+```rust
+/// How long a full-catalog index stays fresh before a re-index is due.
+const CATALOG_INDEX_TTL: Duration = Duration::from_secs(6 * 60 * 60);
+```
+
+Behaviour:
+
+- On app setup, spawn a tokio task that ticks every 30 min.
+- Each tick: if a repository is active **and** the server is reachable **and**
+  `now - last_catalog_sync > CATALOG_INDEX_TTL`, run a full index pass.
+- On the existing `ConnectivityMonitor` reconnect signal, evaluate the same
+  staleness condition immediately rather than waiting for the next tick.
+- Never run two passes concurrently (the existing `syncInProgress` guard moves
+  into Rust as an `AtomicBool`).
+
+`last_catalog_sync` is already written to `app_settings` by `sync_full_catalog`
+and is currently read only for a UI hint; this makes it load-bearing.
+
+`RepositoryManager` (`commands/repository.rs`) is a `HashMap<String, …>` with no
+notion of an active handle, so the task has nothing to run against. Add:
+
+```rust
+pub struct RepositoryManager {
+    repositories: Arc<Mutex<HashMap<String, Arc<HybridRepository>>>>,
+    active: Arc<Mutex<Option<String>>>,   // set in create(), cleared in destroy()
+}
+```
+
+Progress is reported with a **kebab-case** event (per the project convention):
+
+```rust
+// event name: "catalog-index-event"
+#[derive(specta::Type, Serialize, Clone)]
+#[serde(rename_all = "camelCase")]
+pub struct CatalogIndexEvent {
+    pub state: CatalogIndexState,   // #[serde(tag = "type")] Idle | Running | Complete | Failed
+    pub libraries_done: usize,
+    pub libraries_total: usize,
+    pub items_indexed: usize,
+}
+```
+
+`sync_full_catalog` stays a command so the UI can still force a pass; it and the
+scheduler share one internal `run_index_pass()`.
+
+### 3. Index hygiene — no orphans, and deletions propagate (DR-110)
+
+**Orphan growth.** Replace `INSERT OR REPLACE INTO items (…)` in `save_to_cache`
+with a true upsert:
+
+```sql
+INSERT INTO items (id, server_id, …) VALUES (…)
+ON CONFLICT(id) DO UPDATE SET
+    name = excluded.name, overview = excluded.overview, …,
+    synced_at = excluded.synced_at
+```
+
+This preserves the rowid (which `items_fts` keys on via `content_rowid`) and
+fires `items_au` instead of silently orphaning a row. Preferred over
+`PRAGMA recursive_triggers = ON` because it also stops the rowid churn, and the
+three FTS triggers are the only triggers in the schema so nothing else depends
+on REPLACE semantics.
+
+A new migration `021_rebuild_items_fts` clears the orphans already accumulated on
+existing installs:
+
+```sql
+INSERT INTO items_fts(items_fts) VALUES('rebuild');
+```
+
+**Deletions.** After a library crawls *successfully and completely*, reconcile:
+delete local rows for that library whose `id` was not seen in the crawl. Two
+constraints the implementation must respect:
+
+- Skip any item with a completed download — the user has the file; removing the
+  row would orphan it. Prune only synced-but-not-downloaded rows.
+- Only sweep libraries whose crawl succeeded. `sync_full_catalog` is
+  deliberately best-effort per library, and `items.parent_id` is
+  `ON DELETE CASCADE` — sweeping on a partial crawl would cascade a whole series
+  away because one request timed out.
+
+### 4. Index the types search groups by (DR-111)
+
+Add `MusicArtist` and `Playlist` to `CATALOG_ITEM_TYPES`.
+
+People need a different mechanism: they live in `people` (`id`, `server_id`,
+`name`, `overview`, `primary_image_tag`, `synced_at`), populated incidentally by
+item-detail fetches, with no FTS table. Migration `022_people_fts` adds one
+mirroring the `items_fts` pattern:
+
+```sql
+CREATE VIRTUAL TABLE IF NOT EXISTS people_fts USING fts5(
+    name, overview, content='people', content_rowid='rowid'
+);
+-- plus people_ai / people_ad / people_au triggers
+```
+
+`OfflineRepository::search` UNIONs `people_fts` matches into its result set as
+`Person`-typed items when the resolved scope permits them (i.e. when
+`include_item_types` is `None` — `SearchScope::All`). `search_rank.rs` already
+handles `MediaKind::Person`, so ranking needs no change.
+
+## Out of scope
+
+- **Incremental indexing** (e.g. Jellyfin's `MinDateLastSaved`). A full crawl is
+  what makes the deletion sweep in §3 sound — it yields the authoritative id set
+  per library. An incremental pass cannot detect deletions, so it would need a
+  separate reconciliation strategy. Worth revisiting if full crawls prove too
+  slow on large libraries; measure first.
+- **Changing search UX** — scope chips, group order, the debounce, and the
+  `/search` route are untouched.
+- **Removing the server leg.** Phase 2 stays.
+- The two dead search implementations (`storage_search_items` in
+  `commands/storage/mod.rs`, `offline_search` in `commands/offline.rs`) — both
+  registered in `lib.rs` and exported to `bindings.ts`, neither called from the
+  frontend. Deleting them is correct but is cleanup, not this feature; file
+  separately so this spec's diff stays reviewable.
+- `GenericMediaListPage` passing raw `includeItemTypes` and re-implementing the
+  store's request-id/event protocol. A real boundary smell, tracked separately.
+
+## Acceptance criteria
+
+- [ ] With a synced catalog and **zero downloads**, typing a query returns
+      results from the local index before any server request completes.
+- [ ] Offline with "Show all server media" **on**, search returns the full
+      catalog (non-downloaded entries greyed out, matching browse).
+- [ ] Offline with the toggle **off**, search returns downloaded media only —
+      the behaviour that exists today.
+- [ ] Re-running a full index pass N times does not grow `items_fts` row count
+      beyond the `items` row count.
+- [ ] An item deleted server-side disappears from local search after one index
+      pass; a **downloaded** item deleted server-side does not.
+- [ ] A library that fails mid-crawl prunes nothing.
+- [ ] Searching an artist or actor name returns results with the server
+      unreachable.
+- [ ] `bun run check` and `bun run test` pass.
+- [ ] `cargo fmt` clean, `cargo clippy` clean, `bun run test:rust` passes.
+- [ ] `bun run check:boundary` passes.
+- [ ] New requirement-implementing code carries `// TRACES:` comments.
+- [ ] `bindings.ts` regenerated (new `CatalogIndexEvent` type).
+
+## Testing
+
+Per CLAUDE.md, each defect gets a **failing test first**.
+
+Rust (`cargo test`), against an in-memory DB seeded with synced-but-not-
+downloaded items:
+
+- `search` returns synced items when `include_catalog_browse()` is true, and
+  only downloaded items when false. *Fails today* — the current CTE returns
+  empty in the first case.
+- Upserting the same item twice leaves exactly one `items_fts` row. *Fails
+  today.*
+- The sweep removes a vanished synced item, retains a vanished downloaded item,
+  and no-ops for a library whose crawl errored.
+- `type_filter` binds parameters — a type string containing a quote does not
+  alter the query.
+- Staleness: a `last_catalog_sync` inside the TTL does not trigger a pass; one
+  outside it does; offline never does.
+- `people_fts` matches surface as `Person` items under `SearchScope::All` and
+  are excluded under `Music`/`Movies`/`Tv`.
+
+Frontend (`vitest`): the catalog-index event maps to the staleness hint; no
+change to the search store's request-id/stale-response handling, which stays
+covered by its existing tests.
+
+## TRACES
+
+| Piece | Tag |
+|---|---|
+| `OfflineRepository::search` availability CTE | `// TRACES: UR-065 \| DR-108` |
+| Background indexer task + scheduling | `// TRACES: UR-065 \| DR-109, IR-030` |
+| `save_to_cache` upsert + FTS rebuild migration | `// TRACES: UR-065 \| DR-110` |
+| Deletion reconciliation | `// TRACES: UR-065 \| DR-110` |
+| `CATALOG_ITEM_TYPES` widening + `people_fts` | `// TRACES: UR-065, UR-060 \| DR-111` |
+
+## Notes for the implementer
+
+- **A parallel Claude session may be active in this repo.** Run `git diff`
+  before "repairing" changes you did not make (CLAUDE.md gotchas).
+- The frontend's `offlineCatalog.ts` startup trigger should be **removed**, not
+  left alongside the Rust scheduler — two independent triggers with one
+  `syncInProgress` guard each is how double-crawls happen.
+- `downloads` has a relaxed FK to `items` (migration 005). Verify the deletion
+  sweep's interaction with it before enabling the sweep, and check whether
+  `parent_id`'s `ON DELETE CASCADE` reaches further than intended.
+- The existing 100 ms `cache_with_timeout` in `hybrid.rs` returns *empty* on
+  timeout rather than erroring. Once the cache leg is the primary path, that
+  budget may need raising — an FTS query over a large catalog on cold page cache
+  can exceed it, and the failure mode is a silently empty result.
+- Keep `SearchScope` semantics as-is: `All => None` (no filter), deliberately
+  not a union, so People and folders are not filtered out (DR-063).
+- Noted but deliberately not fixed here: `pushCatalogVisibility` in
+  `offlineCatalog.ts` derives the flag as `connected || showCatalog` — the
+  frontend computing an availability *policy*, even though the flag itself is
+  Rust-stored. DR-108 depends on that derivation being correct and it is, so
+  this spec leaves it alone. Once DR-109 has moved sync policy into Rust, the
+  derivation belongs there too, with the frontend pushing only the raw user
+  toggle. Folding it into this change would enlarge the diff for no behavioural
+  gain — but do not add *new* policy on the frontend side of that line.
@@ -0,0 +1,403 @@
+# Spec: Favourites — marking, browsing, and sync
+
+**Status:** Implemented
+**Requirements:** UR-067, UR-068, UR-069 → DR-113 … DR-120; JA-033, JA-034
+(allocated in [requirements.md](../requirements.md); tests UT-099 … UT-107).
+Note: UR-066/DR-112/IR-031 were claimed by the concurrent safe-area work while
+this spec was being written, so the ids here start one higher than first drafted.
+Existing: UR-017 → DR-021, JA-017, JA-018 (the toggle itself, already built).
+**UX spec:** [ux-flows.md](../ux-flows.md) §3.2 (full-player favourite), §5.2
+(album detail favourite), §5B.3 (movie detail hero: *Play / Download / Favorite*)
+— all three already specify favourite affordances that **do not exist in the
+build**. This spec closes those, and adds a new §5C for the Favourites browse
+surface.
+**Supersedes / revises:** nothing.
+
+## Summary
+
+JellyTau can favourite an item but can never show you what you favourited. The
+heart is mounted in exactly one place (the mini player), no query anywhere asks
+Jellyfin or the local database for favourites, and favourites marked on any other
+client are invisible here. This spec adds the read side (a Favourites page, home
+carousels, an in-library filter), puts the heart on detail pages and media cards,
+teaches the backend to ingest server-side favourite state, and drains favourite
+toggles made while offline.
+
+## Background: what exists today
+
+Verified in code, 2026-08-04. The **write** path is real and mostly correct; the
+**read** path does not exist at all.
+
+1. **Toggling works, from one place only.**
+   [FavoriteButton.svelte](../../src/lib/components/FavoriteButton.svelte) is
+   mounted solely in
+   [MiniPlayer.svelte:381](../../src/lib/components/player/MiniPlayer.svelte#L381).
+   Nothing else in `src/` renders it — so the only favouritable item in the app
+   is the one currently playing.
+
+2. **The toggle's plumbing is sound.**
+   [favorites.ts](../../src/lib/services/favorites.ts) writes local first
+   (`storage_toggle_favorite`,
+   [storage/mod.rs:908](../../src-tauri/src/commands/storage/mod.rs#L908) — sets
+   `user_data.is_favorite` + `pending_sync = 1`), then POST/DELETEs
+   `/Users/{uid}/FavoriteItems/{id}`
+   ([online.rs:1652](../../src-tauri/src/repository/online.rs#L1652)) only when
+   connected. Leave this design intact.
+
+3. **`MediaItem.user_data` is always `None` from the server.**
+   `JellyfinItem` has no `UserData` field, and `to_media_item` hardcodes
+   [`user_data: None`](../../src-tauri/src/repository/online.rs#L656) with the
+   comment *"User data not included in basic item responses"*. The only
+   populated `user_data` in the app comes from
+   [series_progress.rs](../../src-tauri/src/repository/series_progress.rs#L244)
+   and the local read in
+   [offline.rs:115](../../src-tauri/src/repository/offline.rs#L115). **Nothing
+   ingests server favourite state**, which is why the mini player has to fetch
+   `storageGetPlaybackProgress` per track to colour one heart
+   ([MiniPlayer.svelte:75-93](../../src/lib/components/player/MiniPlayer.svelte#L75-L93)).
+
+4. **No favourites query exists.**
+   [`GetItemsOptions`](../../src-tauri/src/repository/types.rs#L278) has no
+   favourites field; `Filters=IsFavorite` appears nowhere; no SQL selects
+   `is_favorite = 1`; there is no `/library/favorites` route and no favourites
+   carousel in [home.ts](../../src/lib/stores/home.ts).
+
+5. **Offline favourites are silently lossy.** Offline `mark_favorite` /
+   `unmark_favorite` are no-ops
+   ([offline.rs:1620](../../src-tauri/src/repository/offline.rs#L1620)), so an
+   offline toggle survives only as a local row with `pending_sync = 1` — and
+   **nothing ever drains that flag**. `syncService.queueFavorite`
+   ([syncService.ts:91](../../src/lib/services/syncService.ts#L91)) exists with
+   no callers.
+
+## Motivation
+
+Favouriting is a promise: the app takes the input and shows a "Added to
+favorites" toast, then discards it as far as the user can tell. Three of the UX
+flows already specify favourite buttons that were never built, and the one that
+was built (mini player) writes to a store nothing reads. Either the feature gets
+its read side or the heart should be removed — this spec takes the first option.
+
+## Layer assignment
+
+| Logic / responsibility | Layer | Why it belongs there |
+|------------------------|-------|----------------------|
+| Favourites **scope** → set of Jellyfin item types | Rust | Domain taxonomy. Changes when Jellyfin adds/renames a type, never when the UI is redesigned. Reuses the canonical `SearchScope::item_types()` ([types.rs:324](../../src-tauri/src/repository/types.rs#L324)) — the exact leak class of [scoped-search-boundary.md](scoped-search-boundary.md). |
+| Cross-library favourites query (`Filters=IsFavorite`, `Recursive`, paging, sort field) | Rust | Query shaping against the Jellyfin API is domain logic; the endpoint's contract changes with the server, not the UI. |
+| Offline favourites SQL (join `user_data`, downloaded/catalog gating) | Rust | Storage + domain. Must obey the existing catalog-browse gate (DR-080) which the frontend cannot see. |
+| Deserialising Jellyfin `UserData` into `MediaItem.user_data` | Rust | Provider payload mapping. |
+| Mirroring server favourite state into the local `user_data` table | Rust | Cache/sync policy. |
+| Conflict rule: a local row with `pending_sync = 1` beats the server value | Rust | Business rule about which write wins; nothing to do with rendering. |
+| Draining pending favourite toggles on reconnect | Rust | Sync policy, and it must run whether or not any view is mounted — a frontend-driven drain dies with the component. Consistent with *reachability from real traffic* (DR-055). |
+| Which surfaces show favourites, tab order, row placement on home | Frontend | Pure presentation; changes only if the UI is redesigned. |
+| Heart placement, animation, toast, haptics, empty-state copy | Frontend | Presentation. |
+| In-session optimistic heart state shared across views | Frontend | View state, not persisted truth; the durable write already goes to Rust. |
+
+**Borderline, and the tie-breaker used:** *which* scopes appear as tabs (All /
+Movies / Shows / Music) is a presentation choice — the frontend picks which
+`SearchScope` values to offer. What each scope *means* is Rust's. The frontend
+sends the enum value and never names an item type in connection with favourites.
+Single-type pages (`itemType: "Movie"` on the Movies list page) stay as they are;
+this rule targets category taxonomy, not every mention of a type.
+
+## Design
+
+### 1. Server user data reaches `MediaItem` (Rust, DR-113, JA-034)
+
+Jellyfin returns `UserData` on `/Users/{uid}/Items*` responses. Add the field to
+`JellyfinItem` and map it in `to_media_item`, replacing the hardcoded `None`:
+
+```rust
+// in JellyfinItem
+#[serde(alias = "UserData")]
+pub user_data: Option<JellyfinUserData>,
+```
+
+`JellyfinUserData` deserialises `IsFavorite`, `Played`, `PlaybackPositionTicks`,
+`PlayCount`, `LastPlayedDate` into the existing
+[`UserData`](../../src-tauri/src/repository/types.rs#L44) type (which already
+carries `is_favorite` and already serialises camelCase, so `bindings.ts` needs no
+new type — only regeneration). Add `UserData` to the `Fields=` list in `get_items`
+/ `get_item` so the shape is explicit rather than relying on the default.
+
+Wire shape, unchanged from today's `UserData`:
+
+```ts
+item.userData?.isFavorite // boolean | null | undefined
+```
+
+Delete the now-false `// User data not included in basic item responses` comment.
+
+### 2. Local mirror of server favourites (Rust, DR-114)
+
+Choke point: `save_to_cache(parent_id, &items)` in
+[offline.rs](../../src-tauri/src/repository/offline.rs) — every server result
+that gets cached (including via
+[`cache_items_from_server`](../../src-tauri/src/repository/hybrid.rs#L124) and
+the background cache refresh) passes through it.
+
+For each item carrying `user_data.is_favorite`, upsert:
+
+```sql
+INSERT INTO user_data (user_id, item_id, is_favorite, synced_at, pending_sync)
+VALUES (?, ?, ?, ?, 0)
+ON CONFLICT(user_id, item_id) DO UPDATE SET
+  is_favorite = excluded.is_favorite,
+  synced_at   = excluded.synced_at
+WHERE user_data.pending_sync = 0;      -- local unsynced change wins
+```
+
+The `WHERE` on the conflict clause is the whole conflict rule: a toggle made
+offline is never overwritten by a stale server value before it has been pushed.
+
+### 3. Favourites queries (Rust, DR-115, DR-116, JA-033)
+
+**(a) In-library filter** — one new field on `GetItemsOptions`:
+
+```rust
+#[serde(skip_serializing_if = "Option::is_none")]
+pub favorites_only: Option<bool>,
+```
+
+- online `get_items`: append `&Filters=IsFavorite` when true.
+- offline `get_items`: add `INNER JOIN user_data ud ON ud.item_id = i.id AND ud.user_id = ? AND ud.is_favorite = 1`, composed with the existing `available_items` CTE so the downloads-only gate still applies.
+
+Frontend sends `{ favoritesOnly: true }` (camelCase — nested struct field, needs
+the existing `#[serde(rename_all = "camelCase")]` on `GetItemsOptions`, already
+present).
+
+**(b) Cross-library favourites** — a new trait method, because favourites span
+libraries and `get_items` is `ParentId`-shaped:
+
+```rust
+/// TRACES: UR-067 | DR-115 | JA-033
+async fn get_favorites(
+    &self,
+    scope: SearchScope,
+    options: Option<GetItemsOptions>,
+) -> Result<SearchResult, RepoError>;
+```
+
+```rust
+#[tauri::command]
+#[specta::specta]
+pub async fn repository_get_favorites(
+    manager: State<'_, RepositoryManagerWrapper>,
+    handle: String,
+    scope: SearchScope,
+    options: Option<GetItemsOptions>,
+) -> Result<SearchResult, String>
+```
+
+Frontend call (command name matches the Rust fn exactly; top-level params
+auto-camelCase; `SearchScope` is `#[serde(rename_all = "camelCase")]` so the wire
+values are `"all" | "music" | "movies" | "tv"`):
+
+```ts
+await commands.repositoryGetFavorites(handle, "movies", { limit: 100 });
+```
+
+- **online**: `/Users/{uid}/Items?Filters=IsFavorite&Recursive=true&SortBy=SortName&SortOrder=Ascending` + `&IncludeItemTypes=…` from `scope.item_types()` (omit entirely on `None`, per that function's contract) + the standard `Fields=`.
+- **offline**: `items ⨝ user_data (is_favorite = 1)`, type filter from the same `scope.item_types()`, honouring `include_catalog_browse()`.
+- **hybrid**: same cache-first race as `get_items`, **including the DR-080 rule** — with the catalog-browse gate off, an empty offline result is authoritative and must not fall through to the server. Getting this wrong reproduces Defect B from [offline-downloaded-only-filter.md](offline-downloaded-only-filter.md).
+
+**The cache-first result arrives stale, and there is no second payload.** On a
+cache hit, `hybrid::get_items` returns the local rows and refreshes the cache in
+a background task whose result the frontend never sees — fine for a library
+listing that changes daily, wrong for favourites, where the *point* is that
+another client just changed something. Favourites is the second read path (after
+search) that needs the deferred update, so the background refresh in
+`get_favorites` must emit the same `favorites-changed` event as §4 when the
+server's favourite set differs from what was returned:
+
+```
+favorites-changed  →  { itemIds: string[] }   // union of ids whose is_favorite flipped
+```
+
+Both producers (background refresh, reconnect drain) emit the identical payload,
+and the frontend has one handler that refreshes the `favorites` store. Without
+this, a favourite marked on another client appears in JellyTau only on the
+*second* visit to the page.
+
+### 4. Draining offline toggles (Rust, DR-120)
+
+On the offline→online transition already detected by `ConnectivityMonitor`,
+select `user_data WHERE pending_sync = 1 AND is_favorite IS NOT NULL`, POST or
+DELETE `/Users/{uid}/FavoriteItems/{id}` per row, then set `pending_sync = 0` and
+`synced_at`. Failures leave the row pending for the next transition.
+
+Emit a kebab-case event when anything changed, so open views refresh without
+polling:
+
+```
+favorites-changed  →  { itemIds: string[] }
+```
+
+`syncService.queueFavorite` is dead code once this lands — delete it or point it
+at the backend drain; do not leave two competing queues.
+
+### 5. Frontend surfaces (DR-117, DR-118, DR-119)
+
+**Favourites page** — new route `/library/favorites`:
+- Scope tabs *All / Movies / Shows / Music* via the existing `LibraryViewTabs`; each tab sends a `SearchScope` value, nothing more.
+- Renders through `LibraryGrid` + `MediaCard` (tracklist for Music→tracks if the tab is later split; not in this pass).
+- Entry points: a card on the library overview ([library/+page.svelte](../../src/routes/library/+page.svelte)) and "See all" on the home rows.
+- Empty state per tab: "Nothing favourited yet — tap the heart on anything you like."
+
+**Home carousels** — `favoriteMovies`, `favoriteShows`, `favoriteMusic` added to
+[home.ts](../../src/lib/stores/home.ts), each `repositoryGetFavorites(scope, { limit: 20 })`,
+rendered after *Recently Added* and **only when non-empty** (no empty rows on a
+fresh install).
+
+**In-library filter** — a favourites toggle in the header of
+[GenericMediaListPage](../../src/lib/components/library/GenericMediaListPage.svelte)
+and the Movies/TV landing pages, passing `favoritesOnly: true` into the existing
+`repo.getItems(...)` options. Session-scoped state; not persisted (a persisted
+filter that hides most of a library is a support call waiting to happen).
+
+**Hearts** — mount `FavoriteButton`:
+- Movie / series detail hero button row, beside the download buttons ([library/[id]/+page.svelte:528-553](../../src/routes/library/%5Bid%5D/+page.svelte#L528-L553)) — closes ux-flows §5B.3.
+- `EpisodeFocusView`, `ArtistDetailView`, `PlaylistDetailView`, album detail — closes ux-flows §5.2.
+- `MediaCard` artwork overlay (top-right). Suppressed on `isServerOnly` cards, and must not fight the existing long-press/scroll-guard handlers ([MediaCard.svelte:60-70](../../src/lib/components/library/MediaCard.svelte#L60-L70)) — the heart is its own button and stops propagation.
+
+**Shared optimistic state** — a small `favorites` store (`Map<string, boolean>`
+overlay + `favorites.set(id, value)`), so un-hearting an item on the Favourites
+page removes it from the grid and from any home row without a refetch, and a
+heart tapped on a card is reflected on the detail page. Resolution order:
+
+```
+favorites store override  ??  item.userData?.isFavorite  ??  false
+```
+
+`toggleFavorite()` updates the store alongside its existing local + server
+writes; the `favorites-changed` event refreshes it. This removes the mini
+player's per-track `storageGetPlaybackProgress` fetch once items carry
+`userData`.
+
+### 6. Offline behaviour
+
+Toggling offline keeps working exactly as now (local write + `pending_sync`), and
+now actually reaches the server on reconnect (§4). The Favourites page offline
+shows favourites among downloaded/cached items, subject to the existing
+catalog-browse gate. The offline repo's no-op `mark_favorite`/`unmark_favorite`
+stay no-ops — the local write plus the drain is the offline path.
+
+## Out of scope
+
+- Favouriting people, genres, or collections; favourite **playlists** are included only insofar as they fall under the Music scope.
+- Sorting by "date favourited" — Jellyfin does not expose it. Favourites sort by name.
+- A dedicated bottom-nav tab for favourites (reachable from library overview + home).
+- Building a playlist or download batch from favourites.
+- Reconciling favourites for items that no longer exist on the server.
+- Splitting the Music tab into albums/artists/tracks sub-tabs.
+
+## Acceptance criteria
+
+- [ ] Favouriting is possible from movie, series, episode, album, artist and playlist detail pages, and from media cards in any grid.
+- [ ] A favourite marked in another Jellyfin client shows a filled heart in JellyTau without toggling it here.
+- [ ] `/library/favorites` lists favourites across libraries, filtered by the All/Movies/Shows/Music tabs.
+- [ ] Home shows favourite rows for movies, shows and music, and shows no row when a category has none.
+- [ ] Movies/TV/Music list pages can be filtered to favourites only.
+- [ ] Un-hearting an item on one surface updates the others without a manual refresh.
+- [ ] A favourite toggled while offline reaches the server after reconnect (verified against a real server or a fake repository).
+- [ ] Offline, the Favourites page respects the "Show all server media" gate — with it off, an empty result stays empty and does not fall through to the server.
+- [ ] No item-type set appears in `src/` in connection with favourites; the frontend sends `SearchScope` only.
+- [ ] `bun run check` and `bun run test` pass.
+- [ ] `cargo fmt` clean, `cargo clippy` clean, `bun run test:rust` passes.
+- [ ] `bun run check:boundary` passes (necessary, not sufficient — see CLAUDE.md).
+- [ ] New requirement-implementing code carries `// TRACES:` comments.
+- [ ] `bindings.ts` regenerated from Rust, not hand-edited.
+
+## Testing
+
+**🔴 §4 (the pending-sync drain) is a bug fix — failing test first.** Write a
+test that toggles a favourite with the repository offline, transitions to online,
+and asserts the server call happened; watch it fail before writing the drain.
+
+Rust (`cd src-tauri && cargo test`):
+
+| Test | Covers |
+|------|--------|
+| UT-099 | A Jellyfin item JSON fixture with `UserData.IsFavorite: true` maps to `MediaItem.user_data.is_favorite == Some(true)` |
+| UT-100 | `online::get_favorites` builds an endpoint with `Filters=IsFavorite`, `Recursive=true`, and the scope's `IncludeItemTypes`; `SearchScope::All` omits the type filter entirely |
+| UT-101 | `offline::get_favorites` returns only `is_favorite = 1` rows, respects the scope type filter, and returns nothing extra when the catalog-browse gate is off |
+| UT-102 | `save_to_cache` mirror does **not** overwrite a row with `pending_sync = 1` |
+| UT-103 | Drain pushes pending rows, clears `pending_sync`, sets `synced_at`, and leaves failed rows pending |
+| UT-104 | `get_items` with `favorites_only: true` filters both online (endpoint) and offline (SQL) |
+| UT-107 | The background refresh in `hybrid::get_favorites` emits `favorites-changed` with the flipped ids, and emits nothing when the server set matches the cache |
+
+Frontend (`bun run test`):
+
+| Test | Covers |
+|------|--------|
+| UT-105 | `favorites` store override precedence: store value beats `userData.isFavorite` beats `false` |
+| UT-106 | Un-hearting removes the item from a favourites list view (pure logic extracted to a `.ts` module, per the TrackList/episodeStrip pattern) |
+| IT-0xx | `repositoryGetFavorites` param naming — add to [tauriIntegration.test.ts](../../src/lib/utils/tauriIntegration.test.ts): camelCase top-level params, scope serialised as `"movies"` etc. |
+
+Any component logic worth testing gets extracted into a plain `.ts` module first
+(`favoritesView.ts`), rather than tested through the component.
+
+## TRACES
+
+| Piece | Tag |
+|-------|-----|
+| `JellyfinUserData` + `to_media_item` mapping | `// TRACES: UR-069 \| DR-113, JA-034 \| UT-099` |
+| `save_to_cache` user_data mirror | `// TRACES: UR-069 \| DR-114 \| UT-102` |
+| `get_favorites` (trait, online, offline, hybrid) + command | `// TRACES: UR-067 \| DR-115, JA-033 \| UT-100, UT-101` |
+| `GetItemsOptions.favorites_only` handling | `// TRACES: UR-067 \| DR-116 \| UT-104` |
+| `/library/favorites` route + tabs | `// TRACES: UR-067 \| DR-117` |
+| Home favourite carousels | `// TRACES: UR-067 \| DR-118` |
+| `FavoriteButton` mounts + `favorites` store | `// TRACES: UR-068 \| DR-119 \| UT-105, UT-106` |
+| Pending-favourite drain + `favorites-changed` | `// TRACES: UR-069 \| DR-120 \| UT-103` |
+
+New requirement rows to add to [requirements.md](../requirements.md):
+
+- **UR-067** — Browse favourited media across libraries (page, home rows, in-library filter).
+- **UR-068** — Mark/unmark favourites from browse and detail surfaces, not only the player.
+- **UR-069** — Favourite state stays consistent with the server in both directions.
+- **DR-113 … DR-120** — as tabled above.
+- **JA-033** — Query favourite items (`Filters=IsFavorite`).
+- **JA-034** — Read `UserData` from item responses.
+
+## Implementation notes (as built)
+
+Two things landed differently from the design above, both forced by where the
+`AppHandle` lives:
+
+1. **The `favorites-changed` event is emitted from the command layer, not the
+   repository.** `HybridRepository` has no `AppHandle` — the same reason
+   `search-event` is emitted from `repository_search`. `repository_get_favorites`
+   therefore does the two-phase read itself (cache leg returned, server leg
+   spawned) and diffs the two id sets via `changed_favorite_ids`, which is
+   extracted and unit-tested (UT-107) rather than buried in the spawn.
+2. **The drain hooks the existing `connectivity:reconnected` event** via
+   `app.listen` in `commands/favorites.rs`, rather than reaching into
+   `ConnectivityMonitor` (which knows nothing about repositories). It drains
+   through a narrow `FavoriteSink` trait so it can be tested against a recording
+   double instead of a forty-method `MediaRepository` mock.
+
+3. **The command falls back to `HybridRepository::get_favorites` when nothing is
+   cached.** The two-phase read alone paints "Nothing favourited yet" on a fresh
+   install and corrects it a server round trip later, which is a wrong answer
+   shown to the user. An empty cache leg therefore defers to the repository's
+   own cache-first-then-server read. That read was also fixed to *save through*
+   on a server hit — without it the page re-queried the server on every visit
+   and the DR-114 mirror was never filled by this path.
+
+Also as built: `DatabaseService` is not object-safe (generic methods), so the
+drain takes `Arc<RusqliteService>` like the rest of the storage code, and
+`get_items`' endpoint construction was extracted to `build_get_items_endpoint`
+so the `favorites_only` filter could be asserted without an HTTP server.
+
+**Not built:** the full-player heart. ux-flows §3.2 lists one among the full
+player's secondary controls and it remains unbuilt — recorded as a known
+deviation in ux-flows §5C.5 rather than silently dropped.
+
+## Notes for the implementer
+
+- A parallel Claude session may be active in this repo — `git diff` before "repairing" unexpected changes.
+- Do **not** try to reuse `get_items` with an empty `ParentId` for cross-library favourites; that endpoint is built as `?ParentId={}` ([online.rs:731](../../src-tauri/src/repository/online.rs#L731)) and an empty value is not a reliable "all libraries" request. Use `get_favorites`.
+- `SearchScope` is reused rather than a new `FavoritesScope` so there is one taxonomy expansion in the codebase, not two that can drift. If the name grates once favourites ship, rename the type across search + favourites in one commit — don't fork it.
+- `SearchScope::All` returns `None` from `item_types()` **on purpose**; callers must omit `IncludeItemTypes` entirely rather than sending a union (see the doc comment at [types.rs:316](../../src-tauri/src/repository/types.rs#L316)).
+- Ship order that keeps each step demonstrable: §1+§2 (state becomes visible) → §5 hearts (marking becomes possible) → §3+§5 browse surfaces (finding becomes possible) → §4 drain.
+- Regenerate `bindings.ts` after the Rust types change; never hand-edit it.
@@ -0,0 +1,219 @@
+# Spec: Two-path media — selectable playback bitrate, independent whole-file download
+
+**Status:** Proposed
+**Requirements:** UR-070, UR-071 → DR-121, DR-122, DR-123, DR-124, DR-125; IR-032
+**UX spec:** player quality selector — needs a `ux-flows.md` section before build
+**Related:** [catalog-index-search.md](catalog-index-search.md),
+[downloads-as-offline-library.md](downloads-as-offline-library.md)
+
+## Summary
+
+Two things that are today tangled become explicitly separate:
+
+- **The playback path** streams at a bitrate the viewer can change from the
+  player. It is ephemeral and its rendition is volatile.
+- **The download path** fetches the whole file at one canonical quality, in the
+  background, independently of whatever playback is doing.
+
+Bytes fetched for playback are kept **only** when the playback rendition happens
+to be the same artifact the download path would produce — i.e. direct play.
+Otherwise playback bytes are discarded and the download path does its own fetch.
+
+## Motivation
+
+The appealing version of this — "stream and download at once, switch when enough
+has arrived" — breaks the moment the viewer can change bitrate. A capture taken
+while the rendition changes underneath it is a splice of two encodings: not a
+playable file, and not something that can be honestly recorded as a download.
+Once bitrate is selectable, one stream cannot serve both jobs.
+
+Separating the paths also removes the thing that made the original idea
+expensive: there is no mid-playback source swap to engineer, because the download
+never has to take over the live session. It lands on disk and is used at the next
+natural boundary — next episode, or next time the item is played.
+
+What exists already and is *not* this: `SmartCache` predictively downloads *other*
+items, `player_preload_upcoming` warms the next one, and
+`refresh_queue_local_sources` swaps queue entries to local at boundaries. All of
+it concerns items you are not currently playing.
+
+## Layer assignment
+
+| Logic / responsibility | Layer | Why it belongs there |
+|------------------------|-------|----------------------|
+| Available bitrate options for an item | **Rust** | Derived from Jellyfin's media sources and playback-info negotiation; changes with the API. |
+| Mapping a chosen bitrate to transcode parameters | **Rust** | Domain vocabulary. `get_video_download_url` already owns the quality→params mapping; playback must reuse it, not restate it. |
+| Deciding whether playback bytes are keepable (direct play vs transcode) | **Rust** | Depends on the negotiated session. |
+| Canonical download quality | **Rust** | Policy over domain data. |
+| Cache eviction, storage budget, sparse-range bookkeeping | **Rust** | Storage policy. |
+| Promotion to a `downloads` row, and what invalidates a cache entry | **Rust** | Domain state. |
+| Rendering the quality selector; remembering the last choice | **Frontend** | Presentation and a view preference. The *list* comes from Rust. |
+| WiFi-only / opt-in toggles | **Frontend collects, Rust enforces** | The control is UI; the gate must hold even if the UI never calls. |
+
+Borderline, recorded: the **default** playback bitrate could look like a user
+preference (frontend). It goes to Rust because it must be reconcilable with what
+the server can actually produce for a given media source — a preference the
+backend has to validate is not a preference the frontend can own alone. The
+frontend stores the user's *choice*; Rust decides what that choice resolves to.
+
+## Design
+
+### DR-121 — Bitrate selection in the player
+
+The player exposes the qualities Rust reports for the current item. Changing it
+re-negotiates the stream URL at the new quality and resumes at the current
+position. This is a deliberate, user-initiated interruption — a brief rebuffer is
+expected and acceptable, unlike the involuntary swap the earlier design would
+have needed.
+
+Constraints that must not be broken:
+
+- On Linux, video playback must keep using the HLS `master.m3u8` URL. CLAUDE.md
+  records that returning `stream.mp4` means transcoded playback never starts.
+  A quality change re-negotiates *within* HLS.
+- The quality→transcode-parameter mapping already exists in
+  `get_video_download_url` ([online.rs:1702-1717](../../src-tauri/src/repository/online.rs#L1702-L1717)).
+  Playback must call into the same mapping. Two copies of that table will drift.
+- Track selection (audio/subtitle) already survives a stream re-negotiation
+  elsewhere in the player; a quality change must preserve it too.
+
+### DR-122 — The playback path is ephemeral
+
+Playback bytes are not persisted unless DR-124 says they are keepable. No partial
+capture is ever retained across a quality change: on change, any in-flight capture
+for that session is abandoned and its partial file deleted.
+
+### DR-123 — The download path is independent
+
+Downloading the whole file is a separate operation through the existing download
+manager, at one canonical quality (default `original`, the direct static copy),
+using `/Videos/{id}/stream.mp4` — progressive and Range-capable, which is what
+the resumable download worker relies on. It is unaffected by what playback is
+doing, and playback is unaffected by it.
+
+Once complete it becomes an ordinary download row, so everything already built on
+top of downloads — offline browsing, `refresh_queue_local_sources`, the Downloads
+page — picks it up with no further work.
+
+**Prerequisite:** downloaded *video* is currently never played locally.
+`repository_get_video_stream_url` goes straight to the online repo and
+[player/[id]/+page.svelte:316](../../src/routes/player/[id]/+page.svelte#L316)
+calls it with no local check — so a completed video download is still streamed.
+This must be fixed or the whole feature is invisible for video.
+
+### DR-124 — Keep playback bytes only when they *are* the download
+
+Capture is enabled only where the played bytes and the canonical download artifact
+are the same thing — a **direct-play** session. Then:
+
+| Path | Mechanism |
+|---|---|
+| Android / ExoPlayer | `SimpleCache` + `CacheDataSource`, keyed by item id **and** media-source id so renditions never collide. LRU evictor sharing the existing smart-cache budget — not a second budget over the same disk. |
+| Linux audio / MPV | `stream-record`, set through the existing `set_property` plumbing. |
+| Linux video (HLS transcode) | **Not captured.** Segments are not a file; assembling one needs ffmpeg, which is not a dependency and which CI is forbidden from installing at job time. The download path (DR-123) covers this case instead. |
+
+Two abandonment rules, both of which must delete the partial rather than promote
+it:
+
+- **Seek during an mpv capture.** `stream-record` is documented as intended for
+  linear streams; seeking breaks the recording. Straight-through listening
+  captures, scrubbing does not.
+- **Any quality change** (DR-122).
+
+### DR-125 — Promotion, rendition, and invalidation
+
+A capture is promoted to a `downloads` row (`status = 'completed'`) only when it
+covers the whole resource. Partial captures stay cache and remain evictable.
+
+A new `downloads.source_rendition` column records the negotiated
+quality/container/codec of whatever produced the bytes; `NULL` for rows fetched by
+the existing paths, which are always `original`. This is what makes an "upgrade to
+original" action possible later, and what stops a 720p capture and a 4K download
+being indistinguishable rows.
+
+**Invalidation.** A quality change never touches a file that already exists —
+neither a permanent download nor a completed temporary one. Both remain valid
+copies of the rendition they hold, and deleting either would throw away bytes
+already paid for.
+
+What a quality change *does* invalidate is an **in-flight** capture or background
+download of cached media: it is abandoned and restarted at the newly chosen
+quality, because a capture spanning a rendition change is a splice of two
+encodings rather than a playable file (DR-122).
+
+So the rule is about *ongoing* work, not stored files. Nothing in this spec
+deletes user data.
+
+### Gating
+
+Capture and background download obey the existing WiFi-only gate and storage
+budget, and are off unless opted in. Enforcement is in Rust.
+
+## Out of scope
+
+- **Mid-playback switch onto a completing download.** Two independent paths make
+  it unnecessary; the download is used from the next boundary.
+- **Backfilling the unplayed remainder of a capture.** Watch 40 minutes and you
+  have 40 minutes; completing it needs sparse-range bookkeeping and a resumable
+  tail fetch. The DR-123 download path already produces a complete file, which is
+  the reason this can wait.
+- **Bundling ffmpeg** to make transcoded video capturable. Real option, large
+  packaging decision, its own proposal.
+- **Routing Linux video playback through `stream.mp4`.** Regresses a documented,
+  hard-won fix.
+
+## Acceptance criteria
+
+- [ ] The player offers the qualities Rust reports, and changing one resumes at
+      the same position with audio/subtitle selection preserved.
+- [ ] A quality change abandons any in-flight capture and leaves no partial file.
+- [ ] A quality change never deletes a `downloads` row.
+- [ ] A completed background download of a video is *played from disk* on the next
+      play (the DR-123 prerequisite).
+- [ ] A direct-play session played start-to-finish leaves a complete local file
+      with no second fetch; replaying it fetches no media bytes.
+- [ ] Seeking during an mpv capture abandons it; no truncated file is promoted.
+- [ ] A transcoded Linux video session is never captured, and never partially
+      promoted.
+- [ ] Promoted rows record their rendition; existing paths still record
+      `NULL`/`original`.
+- [ ] Gates hold with the setting off *and* with the frontend never sending it.
+- [ ] Eviction cannot delete bytes backing a promoted download row.
+- [ ] `bun run check`, `bun run test`, `cargo fmt`, `cargo clippy`,
+      `bun run test:rust`, `bun run check:boundary` pass; `bindings.ts`
+      regenerated if Rust types changed.
+
+## Testing
+
+Rust, table-driven and pure where possible: quality→params resolution shared with
+the download path; keepability (direct play vs transcode vs gate off); promotion
+(complete → promoted, partial → not, seek-abandoned → not, quality-changed → not);
+invalidation (evicts cache, never a download row); rendition round-trip.
+
+Android: instrumented — a played direct-play item yields cache entries, and a
+replay issues no media network request.
+
+Frontend: the quality list renders from backend data with no item-type or
+codec taxonomy in `src/`; the selector's remembered choice is a view preference.
+
+## TRACES
+
+| Piece | Tag |
+|---|---|
+| Quality selector + re-negotiation | `// TRACES: UR-070 \| DR-121` |
+| Ephemeral playback / capture abandonment | `// TRACES: UR-070 \| DR-122` |
+| Independent whole-file download + local video playback fix | `// TRACES: UR-071 \| DR-123, IR-032` |
+| ExoPlayer cache / mpv stream-record / keepability | `// TRACES: UR-071 \| DR-124` |
+| Promotion, `source_rendition`, invalidation | `// TRACES: UR-071 \| DR-125` |
+
+## Notes for the implementer
+
+- **A parallel Claude session is active in this repo.** `git diff` before
+  "repairing" anything you did not write.
+- Do not duplicate the quality→transcode-parameter table. Call the existing one.
+- Reuse the smart-cache storage budget; two budgets over one disk is how devices
+  fill up.
+- The `downloads` FK to `items` is relaxed (migration 005) — exercise promotion
+  for an item that was never cached.
+- Build DR-123's local-playback fix first. Without it nothing in this spec is
+  observable for video.
@@ -634,7 +634,7 @@ episode strip.
 │   │  S2E4 • 48m • ★8.1                        │ │
 │   │  Overview…                                │ │
 │   │  ▓▓▓▓▓░░░░░  32m left                     │ │
-│   │  [▶ Play]                                 │ │
+│   │  [▶ Play]  [⬇]  [♡]                       │ │
 │   └───────────────────────────────────────────┘ │
 │                                                 │
 │  More Episodes                                  │  ← 2. EPISODE STRIP
@@ -688,7 +688,7 @@ A movie has no continuation set, so cast follows the hero directly.
 ### 5B.4 Series detail — section order

 ```
-Hero (poster, title, metadata, Resume SxEy / Download / Clear history)
+Hero (poster, title, metadata, Resume SxEy / Download / Favorite / Clear history)
  → Crew links
  → Genre tags
  → Seasons (collapsible; only the current season expanded)
@@ -757,6 +757,130 @@ opt-in. Grids and other surfaces keep tap-to-open with no long-press.

 ---

+## 5C. Favourites
+
+Favouriting is a two-sided promise: the heart takes the input, and the app must
+be able to give it back. This section covers both sides — where you can mark a
+favourite, and where marked favourites resurface.
+
+See [specs/favorites-browsing.md](specs/favorites-browsing.md) for the layer
+assignment and wire shapes.
+
+### 5C.1 The heart appears wherever an item does
+
+A favourite is a property of an *item*, so the affordance follows the item
+rather than living on one privileged screen. Any surface that shows a whole
+item shows its heart.
+
+| Surface | Heart position | Notes |
+|---------|----------------|-------|
+| Movie / Series detail hero | In the button row, after Play and Download | §5B.3, §5B.4 |
+| Episode Focus View hero | Same row as Play / Download | §5B.2 |
+| Album, Artist, Playlist detail | In the header button row | §5.2 |
+| Media card (any grid or carousel) | Top-right overlay on the artwork | Hidden on server-only (greyed) cards |
+| Mini player | Right of the track metadata | Existing behaviour, unchanged |
+| Full player | Secondary controls row | §3.2 — **not yet built**, see §5C.5 |
+
+Rules:
+
+- **The heart never competes with the card.** On a media card it is its own
+  button and swallows the tap, so hearting an item never also opens or plays
+  it, and never triggers the §5B.5 long-press.
+- **State is shown, not guessed.** A filled heart means the *server* considers
+  the item a favourite (or you just tapped it). An item favourited in Jellyfin
+  Web, on another device, or by another client renders filled here without
+  being touched in JellyTau.
+- **Feedback is immediate.** The heart fills on tap and a toast confirms;
+  neither waits for the server round-trip.
+
+### 5C.2 Three ways back to what you favourited
+
+Favourites are not one destination — they are a lens, and the right surface
+depends on whether the user is *browsing*, *deciding*, or *hunting*.
+
+```mermaid
+flowchart TB
+    User[User wants their favourites] --> How{Intent}
+
+    How -->|Passive: show me something| Home[Home carousels<br/>Favourite Movies / Shows / Music]
+    How -->|Deliberate: my whole collection| Page[Favourites page<br/>/library/favorites]
+    How -->|Narrowing: within this library| Filter[Favourites filter<br/>on a library page]
+
+    Home -->|See all| Page
+    Page --> Detail[Item detail page]
+    Filter --> Detail
+```
+
+**Home carousels.** Rows for favourite movies, shows and music sit below
+*Recently Added*. A row with nothing in it **does not render** — a fresh install
+shows no empty favourite rows. Each row ends with *See all*, landing on the
+matching tab of the Favourites page.
+
+**The Favourites page** (`/library/favorites`) is the complete collection,
+scoped by tabs:
+
+```
+┌─────────────────────────────────────────────────┐
+│ [←]  Favourites                                 │
+│  ┌─────┬────────┬───────┬───────┐               │
+│  │ All │ Movies │ Shows │ Music │  ← scope tabs │
+│  └─────┴────────┴───────┴───────┘               │
+│                                                 │
+│  ┌────┐┌────┐┌────┐┌────┐┌────┐                 │
+│  │ ♥  ││ ♥  ││ ♥  ││ ♥  ││ ♥  │   grid/list    │
+│  └────┘└────┘└────┘└────┘└────┘   per §5A      │
+└─────────────────────────────────────────────────┘
+```
+
+- Cards obey §5A in full — shape follows the media, so a mixed *All* tab reads
+  as posters, squares and thumbnails side by side rather than one forced shape.
+- Reached from a card on the library overview (`/library`) and from *See all*
+  on any home favourites row.
+- Sorted by name. Jellyfin does not record *when* an item was favourited, so
+  "recently favourited" is not offerable — see §5C.5.
+- Empty state, per tab: *"Nothing favourited yet — tap the heart on anything
+  you like."*
+
+**The in-library filter** is for narrowing where the user already is: a
+favourites toggle in the header of the Movies, TV and Music browse pages,
+filtering the current list in place. It is **session-scoped and not persisted** —
+a sticky filter that silently hides most of a library reads as data loss on the
+next launch.
+
+### 5C.3 Removing a favourite removes it everywhere, at once
+
+Un-hearting an item on the Favourites page removes its card from the grid
+immediately; the same item disappears from the home rows and shows an empty
+heart on its detail page without a manual refresh. The reverse holds for
+favouriting. There is no confirmation prompt — the action is one tap to undo.
+
+### 5C.4 Offline
+
+- **Marking works offline.** The heart fills, the toast confirms, and the change
+  is held locally.
+- **It reaches the server on reconnect**, without the user returning to the
+  screen where they made it.
+- **Browsing offline shows favourites among media on the device**, subject to
+  the same "Show all server media" gate as every other browse surface (§7.2) —
+  with the gate off, an empty Favourites tab means *nothing favourited is
+  downloaded*, and the page does not quietly fall back to the server catalog.
+
+### 5C.5 Known deviations
+
+- **The full player has no heart.** §3.2 and §3.3 list a Favorite button among
+  the full player's secondary controls; it was never built, and this pass does
+  not add it. The mini player heart above it is the only in-player affordance.
+  *(UR-067)*
+- **No "recently favourited" sort.** Jellyfin's API does not expose a favourite
+  timestamp, so favourites can only be ordered by name. Recording the
+  timestamp locally at toggle time would order *this device's* favourites only,
+  which is worse than a consistent name sort.
+- **Music is one tab, not three.** The Music scope mixes albums, artists and
+  tracks in a single grid rather than offering sub-tabs. Acceptable while
+  favourite counts are small; revisit if the tab becomes unscannable.
+
+---
+
 ## 6. Search Flow

 Search is **context-scoped**: what you are looking at when you start a search
@@ -1,6 +1,6 @@
 {
  "name": "jellytau",
-  "version": "0.3.0",
+  "version": "0.4.6",
  "description": "",
  "type": "module",
  "packageManager": "bun@1.3.5",
@@ -173,10 +173,10 @@ describe("live requirements.md", () => {
    );
    const defined = countDefinedRequirements(md);

-    expect(defined.UR).toBe(64);
-    expect(defined.IR).toBe(29);
-    expect(defined.DR).toBe(104);
-    expect(defined.JA).toBe(32);
-    expect(defined.total).toBe(229);
+    expect(defined.UR).toBe(71);
+    expect(defined.IR).toBe(32);
+    expect(defined.DR).toBe(142);
+    expect(defined.JA).toBe(35);
+    expect(defined.total).toBe(280);
  });
 });
@@ -87,6 +87,16 @@ if [ -d "$RES_SRC" ]; then
        cp "$RES_SRC"/values/*.xml "$RES_DST/values/"
        echo "  Copied res: values"
    fi
+
+    # xml/ (network_security_config.xml): referenced from the manifest, so a
+    # missing copy fails the resource link rather than degrading quietly.
+    # Merged into Tauri's generated xml/ (which holds file_paths.xml) rather
+    # than replacing it.
+    if [ -d "$RES_SRC/xml" ]; then
+        mkdir -p "$RES_DST/xml"
+        cp "$RES_SRC"/xml/*.xml "$RES_DST/xml/"
+        echo "  Copied res: xml"
+    fi
    # We ship only the color adaptive icon (background + foreground). Drop any
    # monochrome layer Tauri may generate: the themed-icon monochrome doesn't
    # render well, and our adaptive-icon xml no longer references it, so a stray
@@ -150,6 +150,12 @@ version = "1.0.100"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a23eb6b1614318a8071c9b2521f36b424b2c83db5eb3a0fead4a6c0809af6e61"

+[[package]]
+name = "ascii"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d92bec98840b8f03a5ff5413de5293bfcd8bf96467cf5452609f939ec6f5de16"
+
 [[package]]
 name = "async-broadcast"
 version = "0.7.2"
@@ -552,6 +558,12 @@ dependencies = [
 "windows-link 0.2.1",
 ]

+[[package]]
+name = "chunked_transfer"
+version = "1.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6e4de3bc4ea267985becf712dc6d9eed8b04c953b3fcfb339ebc87acd9804901"
+
 [[package]]
 name = "cipher"
 version = "0.4.4"
@@ -1671,12 +1683,24 @@ dependencies = [
 "pin-project-lite",
 ]

+[[package]]
+name = "http-range"
+version = "0.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "21dec9db110f5f872ed9699c3ecf50cf16f423502706ba5c72462e28d3157573"
+
 [[package]]
 name = "httparse"
 version = "1.10.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "6dbf3de79e51f3d586ab4cb9d5c3e2c14aa28ed23d180cf89b4df0454a69cc87"

+[[package]]
+name = "httpdate"
+version = "1.0.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "df3b46402a9d5adb4c86a0cf463f42e19994e3ee891101b1841f30a545cb49a9"
+
 [[package]]
 name = "hyper"
 version = "1.8.1"
@@ -1994,7 +2018,7 @@ dependencies = [

 [[package]]
 name = "jellytau"
-version = "0.3.0"
+version = "0.4.6"
 dependencies = [
 "aes-gcm",
 "async-trait",
@@ -2025,6 +2049,7 @@ dependencies = [
 "tauri-plugin-os",
 "tauri-specta",
 "tempfile",
+ "tiny_http",
 "tokio",
 "tokio-rusqlite",
 "tokio-util",
@@ -4192,6 +4217,7 @@ dependencies = [
 "gtk",
 "heck 0.5.0",
 "http",
+ "http-range",
 "jni",
 "libc",
 "log",
@@ -4571,6 +4597,18 @@ dependencies = [
 "time-core",
 ]

+[[package]]
+name = "tiny_http"
+version = "0.12.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "389915df6413a2e74fb181895f933386023c71110878cd0825588928e64cdc82"
+dependencies = [
+ "ascii",
+ "chunked_transfer",
+ "httpdate",
+ "log",
+]
+
 [[package]]
 name = "tinystr"
 version = "0.8.2"
@@ -1,6 +1,6 @@
 [package]
 name = "jellytau"
-version = "0.3.0"
+version = "0.4.6"
 description = "A Tauri App"
 authors = ["you"]
 edition = "2021"
@@ -23,7 +23,12 @@ debug = "line-tables-only"
 tauri-build = { version = "2", features = [] }

 [dependencies]
-tauri = { version = "2", features = [] }
+# protocol-asset serves downloaded media and cached thumbnails to the webview
+# over http://asset.localhost; without it convertFileSrc yields a URL nothing
+# answers. Paired with app.security.assetProtocol in tauri.conf.json, which
+# scopes it to $APPDATA/**.
+# TRACES: UR-071 | DR-134
+tauri = { version = "2", features = ["protocol-asset"] }
 tauri-plugin-opener = "2"
 tauri-plugin-os = "2"
 serde = { version = "1", features = ["derive"] }
@@ -54,6 +59,7 @@ env_logger = "0.11"
 tauri-specta = { version = "=2.0.0-rc.21", features = ["derive", "typescript"] }
 specta-typescript = "=0.0.9"
 specta = { version = "=2.0.0-rc.22", features = ["chrono", "derive"] }
+tiny_http = { version = "0.12.0", default-features = false }

 # Linux-specific dependencies
 [target.'cfg(target_os = "linux")'.dependencies]
@@ -15,6 +15,7 @@
 # breaking the PiP button in release builds only.
 -keep class com.dtourolle.jellytau.PictureInPictureManager { *; }
 -keep class com.dtourolle.jellytau.VideoOverlayManager { *; }
+-keep class com.dtourolle.jellytau.WindowInsetsBridge { *; }
 -keepclassmembers class * {
    @android.webkit.JavascriptInterface <methods>;
 }
@@ -29,6 +29,7 @@
        android:label="@string/app_name"
        android:theme="@style/Theme.jellytau"
        android:hardwareAccelerated="true"
+        android:networkSecurityConfig="@xml/network_security_config"
        android:usesCleartextTraffic="${usesCleartextTraffic}">
        <activity
            android:configChanges="orientation|keyboardHidden|keyboard|screenSize|locale|smallestScreenSize|screenLayout|uiMode|density"
@@ -56,6 +56,14 @@ class MainActivity : TauriActivity() {
    enableEdgeToEdge()
    super.onCreate(savedInstanceState)

+    // enableEdgeToEdge() puts the WebView under the status bar, the navigation/
+    // gesture bar and the display cutout — and targeting SDK 36 makes that
+    // non-optional anyway. Android WebView never surfaces the *system bar*
+    // insets to CSS (only the display cutout), so the web layer has to be told.
+    // Without this the bottom nav renders underneath the navigation bar, badly
+    // so on devices with a tall opaque 3-button bar. (UR-066)
+    WindowInsetsBridge.install(this)
+
    // Configure WebView for media playback after Tauri initialization
    handler.postDelayed({
      configureWebViewForMedia()
@@ -179,6 +187,12 @@ class MainActivity : TauriActivity() {
      //
      // The settings/WebChromeClient work below is idempotent and must keep
      // running on resume; only the bridge injection is one-shot.
+
+      // Re-push the safe-area insets. Unlike addJavascriptInterface this is
+      // idempotent and MUST re-run: a page load discards the inline style the
+      // last push set, so the WebView would otherwise be left with no insets.
+      WindowInsetsBridge.attachWebView(webView)
+
      if (webView === bridgesInstalledOn) {
        android.util.Log.d("MainActivity", "JS bridges already installed on this WebView - skipping re-injection")
        configureWebViewSettings(webView)
@@ -257,6 +271,11 @@ class MainActivity : TauriActivity() {
      }, "AndroidNetworkType")
      android.util.Log.d("MainActivity", "JavaScript interface 'AndroidNetworkType' added")

+      // Window insets (safe areas). The push path above races the page load, so
+      // the frontend pulls the current values on mount through this bridge.
+      webView.addJavascriptInterface(WindowInsetsBridge.jsInterface(), "AndroidInsets")
+      android.util.Log.d("MainActivity", "JavaScript interface 'AndroidInsets' added")
+
      // Push network changes into the WebView so a queue blocked on "waiting for
      // WiFi" resumes the moment an acceptable network appears.
      NetworkTypeMonitor.startWatching(this) {
@@ -0,0 +1,140 @@
+package com.dtourolle.jellytau
+
+import android.app.Activity
+import android.webkit.JavascriptInterface
+import android.webkit.WebView
+import androidx.core.view.ViewCompat
+import androidx.core.view.WindowInsetsCompat
+
+/**
+ * Publishes the Activity's real window insets to the WebView as CSS custom
+ * properties.
+ *
+ * TRACES: UR-066 | IR-031, DR-112
+ *
+ * ## Why this is necessary
+ *
+ * MainActivity calls `enableEdgeToEdge()`, and the app targets SDK 36 —
+ * edge-to-edge is mandatory from SDK 35 and the opt-out is ignored from SDK 36
+ * — so the Tauri WebView always spans the whole window, underneath the status
+ * bar, the navigation/gesture bar and the display cutout.
+ *
+ * The web layer cannot discover that by itself. Android WebView maps only the
+ * **display cutout** into `env(safe-area-inset-*)` (and only with
+ * `viewport-fit=cover`); the status bar and navigation bar are never reported.
+ * Unlike iOS Safari there is no CSS-visible system-bar inset. So the frontend's
+ * `env()`-based padding evaluated to 0 on every device and the bottom nav
+ * rendered underneath the navigation bar.
+ *
+ * How badly that showed depended entirely on the device's navigation mode: a
+ * thin translucent gesture pill overlaps almost harmlessly, while a tall opaque
+ * 3-button bar swallows the nav outright.
+ *
+ * ## Contract with the frontend
+ *
+ * Insets are reported in **CSS pixels** (density-independent), because that is
+ * the unit CSS will use them in — dividing by `displayMetrics.density` here is
+ * what keeps the padding correct across screen densities.
+ *
+ * - **Push**: on every inset change (rotation, navigation-mode switch, PiP
+ *   enter/exit) the four `--jt-inset-*` custom properties are written onto
+ *   `document.documentElement` and `jellytau-insets-changed` is dispatched.
+ * - **Pull**: `AndroidInsets.get()` returns the same payload as JSON. Required
+ *   because the first inset pass normally lands before the SvelteKit document
+ *   exists, and a page load discards any inline style a push had set.
+ *
+ * See `src/lib/utils/safeArea.ts` and the `--safe-*` vars in `src/app.css`.
+ */
+object WindowInsetsBridge {
+
+    /** Latest insets in CSS pixels. Written on the main thread, read from the WebView binder thread. */
+    @Volatile
+    private var top = 0
+    @Volatile
+    private var right = 0
+    @Volatile
+    private var bottom = 0
+    @Volatile
+    private var left = 0
+
+    /** Cached so a WebView found later (or re-found on resume) can be primed. */
+    private var webView: WebView? = null
+
+    /**
+     * Start listening for window insets on [activity].
+     *
+     * Call from `onCreate` right after `enableEdgeToEdge()`. The listener
+     * returns the insets **unconsumed** so the WebView still receives them for
+     * its own display-cutout handling.
+     */
+    fun install(activity: Activity) {
+        val density = activity.resources.displayMetrics.density
+
+        ViewCompat.setOnApplyWindowInsetsListener(activity.window.decorView) { _, insets ->
+            // systemBars() covers the status bar and the navigation/gesture bar;
+            // displayCutout() covers notches and punch-holes, which in landscape
+            // land on a side edge that systemBars() does not describe.
+            val i = insets.getInsets(
+                WindowInsetsCompat.Type.systemBars() or WindowInsetsCompat.Type.displayCutout()
+            )
+
+            val toCssPx = { px: Int -> if (density > 0f) Math.round(px / density) else px }
+            top = toCssPx(i.top)
+            right = toCssPx(i.right)
+            bottom = toCssPx(i.bottom)
+            left = toCssPx(i.left)
+
+            android.util.Log.d(
+                "WindowInsetsBridge",
+                "insets (css px): top=$top right=$right bottom=$bottom left=$left"
+            )
+            push()
+
+            // Do NOT return CONSUMED - other views (and the WebView's own cutout
+            // handling) still need to see these.
+            insets
+        }
+
+        // The first pass may already have happened before the listener existed.
+        ViewCompat.requestApplyInsets(activity.window.decorView)
+    }
+
+    /**
+     * Adopt the WebView carrying the UI and push the current insets into it.
+     *
+     * Safe to call repeatedly (MainActivity re-finds the WebView on every
+     * resume): this only writes CSS properties, unlike `addJavascriptInterface`,
+     * which must run exactly once per WebView.
+     */
+    fun attachWebView(view: WebView) {
+        webView = view
+        push()
+    }
+
+    /** Current insets as JSON in CSS pixels — the payload `AndroidInsets.get()` returns. */
+    fun currentJson(): String =
+        """{"top":$top,"right":$right,"bottom":$bottom,"left":$left}"""
+
+    /** The `AndroidInsets` @JavascriptInterface object for the pull path. */
+    fun jsInterface(): Any = object : Any() {
+        @JavascriptInterface
+        fun get(): String = currentJson()
+    }
+
+    /** Write the custom properties into the live document and signal the change. */
+    private fun push() {
+        val view = webView ?: return
+        val js = """
+            (function() {
+              var s = document.documentElement.style;
+              s.setProperty('--jt-inset-top', '${top}px');
+              s.setProperty('--jt-inset-right', '${right}px');
+              s.setProperty('--jt-inset-bottom', '${bottom}px');
+              s.setProperty('--jt-inset-left', '${left}px');
+              window.dispatchEvent(new CustomEvent('jellytau-insets-changed'));
+            })();
+        """.trimIndent()
+
+        view.post { view.evaluateJavascript(js, null) }
+    }
+}
@@ -1,7 +1,11 @@
 package com.dtourolle.jellytau.player

+import android.content.Context
 import android.media.MediaCodecList
 import android.util.Log
+import androidx.media3.common.AudioAttributes
+import androidx.media3.common.util.UnstableApi
+import androidx.media3.exoplayer.audio.AudioCapabilities

 /**
 * Detects hardware codec capabilities using MediaCodecList.
@@ -75,6 +79,36 @@ object CodecDetector {
        )
    }

+    /**
+     * Report how many channels the *current audio output route* can voice.
+     *
+     * This is a different question from "can this device decode 5.1", which the
+     * codec list already answers: a phone decodes a 5.1 AC-3 track happily and
+     * still has only two channels to play it out of. Left unreported, Jellyfin
+     * is free to direct-play the multichannel track, and what the user hears is
+     * device dependent — a failed AudioSink configuration (silence) or dialogue
+     * folded into the surround channels and lost.
+     *
+     * Returns 0 when there is no answer; Rust reads that as "unknown" and falls
+     * back to stereo rather than claiming a capability we have not observed.
+     */
+    @UnstableApi
+    fun detectMaxAudioChannels(context: Context): Int {
+        return try {
+            val capabilities = AudioCapabilities.getCapabilities(
+                context,
+                AudioAttributes.DEFAULT,
+                /* routedDevice= */ null
+            )
+            val channels = capabilities.maxChannelCount
+            Log.i(TAG, "Audio route max channel count: $channels")
+            channels.coerceAtLeast(0)
+        } catch (e: Exception) {
+            Log.e(TAG, "Error querying audio capabilities", e)
+            0
+        }
+    }
+
    /**
     * Map Android MIME types to Jellyfin codec names.
     *
@@ -130,7 +130,7 @@ class JellyTauPlayer(private val appContext: Context) {
                        }

                        // Detect and report hardware codec capabilities to Rust
-                        detectAndReportCodecs()
+                        detectAndReportCodecs(context.applicationContext)
                    }
                }
            }
@@ -141,23 +141,31 @@ class JellyTauPlayer(private val appContext: Context) {
         * Called during player initialization.
         */
        @JvmStatic
-        fun detectAndReportCodecs() {
+        fun detectAndReportCodecs(context: Context) {
            val capabilities = CodecDetector.detectHardwareCodecs()

            // Convert lists to comma-separated strings for JNI transfer
            val videoCodecsStr = capabilities.videoCodecs.joinToString(",")
            val audioCodecsStr = capabilities.audioCodecs.joinToString(",")

-            android.util.Log.i("JellyTauPlayer", "Reporting codecs to Rust: video=$videoCodecsStr, audio=$audioCodecsStr")
+            // What the route can *voice*, which the codec list does not answer.
+            // 0 means "no answer"; Rust falls back to stereo.
+            val maxAudioChannels = CodecDetector.detectMaxAudioChannels(context)
+
+            android.util.Log.i("JellyTauPlayer", "Reporting codecs to Rust: video=$videoCodecsStr, audio=$audioCodecsStr, maxAudioChannels=$maxAudioChannels")

            // Call native method to store in Rust
-            nativeOnCodecsDetected(videoCodecsStr, audioCodecsStr)
+            nativeOnCodecsDetected(videoCodecsStr, audioCodecsStr, maxAudioChannels)
        }

        /**
         * Native method to report detected codecs to Rust.
         */
-        private external fun nativeOnCodecsDetected(videoCodecs: String, audioCodecs: String)
+        private external fun nativeOnCodecsDetected(
+            videoCodecs: String,
+            audioCodecs: String,
+            maxAudioChannels: Int
+        )

        /**
         * Check if the player is initialized.
@@ -232,6 +240,20 @@ class JellyTauPlayer(private val appContext: Context) {
    }
    private var audioFocusRequest: AudioFocusRequest? = null

+    /**
+     * Set when a video was loaded but audio focus was not granted outright.
+     *
+     * `setAcceptsDelayedFocusGain(true)` means the system may answer DELAYED and
+     * hand us focus later; until then it withholds our audio. Starting playback
+     * anyway plays the video silently, which is exactly the "video has no sound"
+     * symptom. We hold playback and start it from the AUDIOFOCUS_GAIN callback.
+     */
+    private var pendingPlayOnFocusGain = false
+
+    /** Whether we currently hold audio focus, so `play()` does not re-request
+     *  (and leak) a focus request we already own. */
+    private var hasAudioFocus = false
+
    init {
        // Configure audio attributes for music playback with audio focus handling
        val audioAttributes = AudioAttributes.Builder()
@@ -361,29 +383,61 @@ class JellyTauPlayer(private val appContext: Context) {
                    android.util.Log.d("JellyTauPlayer", "    Video group: ${group.length} tracks, selected=${group.isSelected}")
                }

-                // CRITICAL FIX: Auto-select first audio track if none is selected
-                // This fixes the issue where some videos play without audio
+                // TRACES: UR-004 | DR-146
+                // Auto-select an audio track if none is selected — some videos
+                // otherwise play with no sound. Pick a track the renderer says it
+                // *supports*: when nothing was selected because track 0 failed to
+                // initialize, forcing track 0 again just reinstates the silence.
                if (!hasSelectedAudio && audioTracks.isNotEmpty() && currentMediaType == MediaType.VIDEO) {
-                    android.util.Log.w("JellyTauPlayer", "⚠️  NO AUDIO TRACK SELECTED! Auto-selecting first audio track...")
+                    android.util.Log.w("JellyTauPlayer", "⚠️  NO AUDIO TRACK SELECTED! Looking for a supported audio track...")

                    val trackSelector = exoPlayer.trackSelector
                    if (trackSelector != null) {
                        try {
-                            // Select the first audio track group
-                            val firstAudioGroup = audioTracks[0]
-                            val override = androidx.media3.common.TrackSelectionOverride(
-                                firstAudioGroup.mediaTrackGroup,
-                                0 // Select the first track in this group
-                            )
+                            var chosenGroup: androidx.media3.common.Tracks.Group? = null
+                            var chosenIndex = -1
+                            outer@ for (group in audioTracks) {
+                                for (i in 0 until group.length) {
+                                    if (group.isTrackSupported(i)) {
+                                        chosenGroup = group
+                                        chosenIndex = i
+                                        break@outer
+                                    }
+                                }
+                            }

-                            val parameters = trackSelector.parameters
-                                .buildUpon()
-                                .clearOverridesOfType(C.TRACK_TYPE_AUDIO)
-                                .addOverride(override)
-                                .build()
+                            if (chosenGroup == null) {
+                                // Every track is undecodable on this device. The
+                                // server should have transcoded; say so loudly
+                                // rather than leaving a silent video unexplained.
+                                android.util.Log.e(
+                                    "JellyTauPlayer",
+                                    "✗ No supported audio track in ${audioTracks.size} group(s) - " +
+                                        "device cannot decode any of them, expected a transcode"
+                                )
+                            } else {
+                                val format = chosenGroup.getTrackFormat(chosenIndex)
+                                val override = androidx.media3.common.TrackSelectionOverride(
+                                    chosenGroup.mediaTrackGroup,
+                                    chosenIndex
+                                )

-                            trackSelector.setParameters(parameters)
-                            android.util.Log.d("JellyTauPlayer", "✓ Auto-selected first audio track")
+                                val parameters = trackSelector.parameters
+                                    .buildUpon()
+                                    // Audio may also be off because the track type
+                                    // was disabled; an override alone would not
+                                    // bring it back.
+                                    .setTrackTypeDisabled(C.TRACK_TYPE_AUDIO, false)
+                                    .clearOverridesOfType(C.TRACK_TYPE_AUDIO)
+                                    .addOverride(override)
+                                    .build()
+
+                                trackSelector.setParameters(parameters)
+                                android.util.Log.d(
+                                    "JellyTauPlayer",
+                                    "✓ Auto-selected supported audio track $chosenIndex (${format.sampleMimeType}, ${format.channelCount}ch)"
+                                )
+                            }
                        } catch (e: Exception) {
                            android.util.Log.e("JellyTauPlayer", "Failed to auto-select audio track", e)
                        }
@@ -423,6 +477,15 @@ class JellyTauPlayer(private val appContext: Context) {
     */
    fun play() {
        mainHandler.post {
+            // Video manages focus by hand, so an explicit play after a refusal (or
+            // after a LOSS paused us) has to ask again — otherwise it resumes into
+            // a stream the system is still muting.
+            if (currentMediaType == MediaType.VIDEO && !hasAudioFocus && !requestAudioFocus()) {
+                pendingPlayOnFocusGain = true
+                android.util.Log.d("JellyTauPlayer", "play() without audio focus - holding until GAIN")
+                return@post
+            }
+            pendingPlayOnFocusGain = false
            exoPlayer.play()
        }
    }
@@ -811,14 +874,17 @@ class JellyTauPlayer(private val appContext: Context) {
            android.util.Log.d("JellyTauPlayer", "ExoPlayer audio session ID: ${exoPlayer.audioSessionId}")

            // Setup video surface if needed
+            var focusGranted = true
            if (currentMediaType == MediaType.VIDEO) {
                getOrCreateSurfaceView()
                android.util.Log.d("JellyTauPlayer", "Video surface created for playback")
                // Automatically attach the surface to the Activity
                autoAttachSurface()

-                // CRITICAL: Request audio focus for video playback
-                requestAudioFocus()
+                // CRITICAL: Request audio focus for video playback. Video manages
+                // focus by hand (handleAudioFocus=false above), so nothing else
+                // will hold playback back if the request is delayed or refused.
+                focusGranted = requestAudioFocus()
            } else {
                clearVideoSurface()
                // Abandon audio focus when switching to audio (audio uses ExoPlayer's built-in handling)
@@ -888,8 +954,13 @@ class JellyTauPlayer(private val appContext: Context) {
            }
            android.util.Log.d("JellyTauPlayer", "✓ Current volume: ${exoPlayer.volume}, deviceVolume: ${audioManager.getStreamVolume(AudioManager.STREAM_MUSIC)}/${audioManager.getStreamMaxVolume(AudioManager.STREAM_MUSIC)}")

-            exoPlayer.playWhenReady = true
-            android.util.Log.d("JellyTauPlayer", "playWhenReady set to TRUE. Current state: ${exoPlayer.playbackState}")
+            // Only roll if we hold audio focus. A DELAYED grant means the system
+            // is withholding our audio until it calls back with AUDIOFOCUS_GAIN;
+            // playing through it produces picture with no sound. Playback resumes
+            // from the focus listener instead.
+            pendingPlayOnFocusGain = !focusGranted
+            exoPlayer.playWhenReady = focusGranted
+            android.util.Log.d("JellyTauPlayer", "playWhenReady set to $focusGranted (pendingPlayOnFocusGain=$pendingPlayOnFocusGain). Current state: ${exoPlayer.playbackState}")

            // Start the foreground service for lockscreen controls
            startPlaybackService()
@@ -1146,8 +1217,14 @@ class JellyTauPlayer(private val appContext: Context) {
    /**
     * Request audio focus for video playback.
     * This is critical for video to have audio on Android.
+     *
+     * TRACES: UR-004 | DR-145
+     *
+     * @return true if focus was granted outright and playback may start now.
+     *   false for a DELAYED or refused request — the caller must hold playback
+     *   and let the AUDIOFOCUS_GAIN callback start it, or the video plays mute.
     */
-    private fun requestAudioFocus() {
+    private fun requestAudioFocus(): Boolean {
        android.util.Log.d("JellyTauPlayer", "Requesting audio focus for video playback")

        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
@@ -1164,17 +1241,29 @@ class JellyTauPlayer(private val appContext: Context) {
                    when (focusChange) {
                        AudioManager.AUDIOFOCUS_GAIN -> {
                            android.util.Log.d("JellyTauPlayer", "✓ Audio focus GAINED - ensuring full volume")
+                            hasAudioFocus = true
                            if (exoPlayer.volume < 1.0f) {
                                exoPlayer.volume = 1.0f
                                android.util.Log.d("JellyTauPlayer", "  Volume restored to 1.0 from ${exoPlayer.volume}")
                            }
+                            // A delayed grant arriving: this is the point at which
+                            // the video may actually be heard, so start it now.
+                            if (pendingPlayOnFocusGain) {
+                                pendingPlayOnFocusGain = false
+                                android.util.Log.d("JellyTauPlayer", "  Delayed focus granted - starting held playback")
+                                exoPlayer.playWhenReady = true
+                            }
                        }
                        AudioManager.AUDIOFOCUS_LOSS -> {
                            android.util.Log.d("JellyTauPlayer", "Audio focus LOST - pausing")
+                            hasAudioFocus = false
+                            pendingPlayOnFocusGain = false
                            pause()
                        }
                        AudioManager.AUDIOFOCUS_LOSS_TRANSIENT -> {
                            android.util.Log.d("JellyTauPlayer", "Audio focus LOST TRANSIENT - pausing")
+                            hasAudioFocus = false
+                            pendingPlayOnFocusGain = false
                            pause()
                        }
                        AudioManager.AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCK -> {
@@ -1185,16 +1274,25 @@ class JellyTauPlayer(private val appContext: Context) {
                }
                .build()

-            val result = audioManager.requestAudioFocus(audioFocusRequest!!)
-            when (result) {
+            return when (val result = audioManager.requestAudioFocus(audioFocusRequest!!)) {
                AudioManager.AUDIOFOCUS_REQUEST_GRANTED -> {
                    android.util.Log.d("JellyTauPlayer", "✓ Audio focus GRANTED")
+                    hasAudioFocus = true
+                    true
                }
                AudioManager.AUDIOFOCUS_REQUEST_FAILED -> {
-                    android.util.Log.e("JellyTauPlayer", "✗ Audio focus REQUEST FAILED!")
+                    // Something holds exclusive focus (a call, say). Playing now
+                    // would be a silent video, so hold and wait for the grant.
+                    android.util.Log.e("JellyTauPlayer", "✗ Audio focus REQUEST FAILED - holding playback")
+                    false
                }
                AudioManager.AUDIOFOCUS_REQUEST_DELAYED -> {
-                    android.util.Log.d("JellyTauPlayer", "⏳ Audio focus DELAYED")
+                    android.util.Log.d("JellyTauPlayer", "⏳ Audio focus DELAYED - holding playback until GAIN")
+                    false
+                }
+                else -> {
+                    android.util.Log.w("JellyTauPlayer", "Unknown audio focus result: $result - holding playback")
+                    false
                }
            }
        } else {
@@ -1206,10 +1304,15 @@ class JellyTauPlayer(private val appContext: Context) {
                AudioManager.STREAM_MUSIC,
                AudioManager.AUDIOFOCUS_GAIN
            )
-            if (result == AudioManager.AUDIOFOCUS_REQUEST_GRANTED) {
+            return if (result == AudioManager.AUDIOFOCUS_REQUEST_GRANTED) {
                android.util.Log.d("JellyTauPlayer", "✓ Audio focus GRANTED (legacy)")
+                hasAudioFocus = true
+                true
            } else {
+                // Pre-O has no delayed grant and no listener to resume from, so a
+                // refusal is terminal for this attempt; the user can hit play again.
                android.util.Log.e("JellyTauPlayer", "✗ Audio focus REQUEST FAILED (legacy)!")
+                false
            }
        }
    }
@@ -1220,6 +1323,11 @@ class JellyTauPlayer(private val appContext: Context) {
    private fun abandonAudioFocus() {
        android.util.Log.d("JellyTauPlayer", "Abandoning audio focus")

+        // No focus, nothing to resume: a stale flag would start playback the next
+        // time some unrelated GAIN arrives.
+        pendingPlayOnFocusGain = false
+        hasAudioFocus = false
+
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
            audioFocusRequest?.let {
                val result = audioManager.abandonAudioFocusRequest(it)
@@ -1,13 +1,30 @@
 <resources xmlns:tools="http://schemas.android.com/tools">
-    <!-- Base application theme -->
+    <!--
+      Base application theme.
+
+      This app is EDGE-TO-EDGE: MainActivity calls enableEdgeToEdge(), and
+      targeting SDK 36 makes it mandatory anyway (enforced from SDK 35, with the
+      opt-out ignored from SDK 36). The WebView therefore spans the whole window,
+      under the status bar, the navigation/gesture bar and the display cutout.
+
+      This theme used to declare `android:fitsSystemWindows=true` with a "don't
+      draw behind system bars" comment. That was never true: enableEdgeToEdge()
+      calls setDecorFitsSystemWindows(false) at runtime and wins, and the
+      platform ignores the attribute at this target SDK regardless. Leaving it
+      in only hid the fact that nothing was insetting the content.
+
+      Insets are handled where they can actually be honoured: WindowInsetsBridge
+      reads them and hands them to CSS as jt-inset custom properties.
+      See UR-066 / DR-112.
+    -->
    <style name="Theme.jellytau" parent="Theme.MaterialComponents.DayNight.NoActionBar">
-        <!-- Status bar color -->
+        <!-- System bars are transparent; the app draws its own background behind
+             them (e.g. BottomUi's surface extends under the gesture bar). -->
        <item name="android:statusBarColor">@android:color/transparent</item>
-        <!-- Make status bar icons dark or light based on background -->
+        <item name="android:navigationBarColor">@android:color/transparent</item>
+        <!-- Light icons on our dark background, both bars. -->
        <item name="android:windowLightStatusBar" tools:targetApi="m">false</item>
-        <!-- Don't draw behind status bar -->
+        <item name="android:windowLightNavigationBar" tools:targetApi="o_mr1">false</item>
        <item name="android:windowDrawsSystemBarBackgrounds">true</item>
-        <!-- Ensure content doesn't extend into system bars -->
-        <item name="android:fitsSystemWindows">true</item>
    </style>
 </resources>
@@ -0,0 +1,23 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+  Cleartext HTTP stays blocked everywhere except loopback.
+
+  Downloaded media is served to the webview by a local HTTP server on
+  127.0.0.1 (see media_server.rs / DR-137). Release builds set
+  usesCleartextTraffic="false", so Android's network security policy rejected
+  those requests before any I/O happened and offline video failed instantly with
+  NETWORK_NO_SOURCE.
+
+  Only 127.0.0.1 is exempted. The base config keeps the release default, so a
+  remote server still has to be HTTPS — this must not become a blanket
+  cleartext opt-in.
+
+  TRACES: UR-071 | DR-138
+-->
+<network-security-config>
+    <base-config cleartextTrafficPermitted="false" />
+
+    <domain-config cleartextTrafficPermitted="true">
+        <domain includeSubdomains="false">127.0.0.1</domain>
+    </domain-config>
+</network-security-config>
@@ -14,10 +14,12 @@
 //!   that were queued offline (they have `stream_url IS NULL`), mirroring the
 //!   heal-and-pump pattern in `player_preload_upcoming`.

+use std::sync::atomic::{AtomicBool, Ordering};
 use std::sync::Arc;
+use std::time::Duration;

 use log::{info, warn};
-use tauri::State;
+use tauri::{Emitter, Manager, State};

 use crate::commands::download::{pump_download_queue, DownloadManagerWrapper};
 use crate::commands::repository::RepositoryManagerWrapper;
@@ -29,18 +31,89 @@ use crate::storage::db_service::{DatabaseService, Query, QueryParam};
 /// full-catalog sync.
 const LAST_CATALOG_SYNC_KEY: &str = "last_catalog_sync";

+/// How long an index stays fresh before a re-index is due.
+///
+/// This lives in Rust rather than being a frontend constant because it decides
+/// *whether the local cache is authoritative* — the same class of decision as
+/// `include_catalog_browse`, and squarely the "sync policy" the spec review
+/// checklist keeps out of the presentation layer. If it later becomes
+/// user-configurable it stays a Rust-owned setting edited through a command.
+const CATALOG_INDEX_TTL: Duration = Duration::from_secs(6 * 60 * 60);
+
+/// How often the scheduler wakes to *check* staleness. Far shorter than the TTL
+/// because a tick is nearly free — one indexed `app_settings` lookup — and it is
+/// what makes the indexer responsive to events it cannot subscribe to: signing
+/// in, and coming back online. The TTL, not the tick, decides whether a crawl
+/// actually happens.
+const CATALOG_INDEX_TICK: Duration = Duration::from_secs(5 * 60);
+
+/// Delay before the first staleness check, to let sign-in complete and the
+/// repository be registered. Without it the first check runs against an empty
+/// repository manager and a fresh install would sit unindexed until the next
+/// tick.
+const CATALOG_INDEX_FIRST_CHECK: Duration = Duration::from_secs(15);
+
+/// Kebab-case, per the project's event convention.
+pub const CATALOG_INDEX_EVENT: &str = "catalog-index-event";
+
+/// Guards against two passes running at once. Replaces the frontend's
+/// `syncInProgress` boolean in `offlineCatalog.ts`, which could not see a pass
+/// started by the scheduler.
+static INDEX_IN_PROGRESS: AtomicBool = AtomicBool::new(false);
+
+/// Clears [`INDEX_IN_PROGRESS`] however the pass leaves — including on the `?`
+/// early return when `get_libraries` fails, which a plain store at the end of
+/// the function would leak.
+struct IndexPassGuard;
+
+impl Drop for IndexPassGuard {
+    fn drop(&mut self) {
+        INDEX_IN_PROGRESS.store(false, Ordering::SeqCst);
+    }
+}
+
+/// Progress of a background index pass, for the staleness hint in the UI.
+#[derive(specta::Type, Debug, Clone, serde::Serialize, serde::Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct CatalogIndexEvent {
+    /// `started` | `finished` | `failed`
+    pub state: String,
+    pub items_cached: usize,
+    pub items_pruned: usize,
+    pub libraries_failed: usize,
+    /// Present on `failed`.
+    pub error: Option<String>,
+}
+
 /// Item types worth caching for offline browsing: containers the library
 /// landing pages render plus the playable leaves users queue for download.
+/// `MusicArtist` and `Playlist` are here because search groups results by them
+/// (UR-060's Artists group). Without them in the crawl, the local index can
+/// never answer an artist query and those groups can only ever be filled by the
+/// server leg. Keep this in step with what `prune_stale_catalog` is allowed to
+/// sweep — the crawl is only authoritative for the types it asks for.
+///
+/// TRACES: UR-065, UR-060 | DR-111
 const CATALOG_ITEM_TYPES: &[&str] = &[
    "MusicAlbum",
+    "MusicArtist",
    "Movie",
    "Series",
    "Season",
    "Episode",
    "Audio",
    "BoxSet",
+    "Playlist",
 ];

+/// Jellyfin item types whose download is a *video* stream rather than an audio
+/// one. The download queue stores an opaque `media_type` ('audio'/'video'); this
+/// is where the taxonomy that produces it lives, so the frontend never has to
+/// know which item types are video.
+///
+/// TRACES: UR-071 | DR-135
+const VIDEO_ITEM_TYPES: &[&str] = &["Movie", "Episode", "Video", "MusicVideo"];
+
 #[derive(specta::Type, Debug, Clone, serde::Serialize, serde::Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct CatalogSyncResult {
@@ -48,6 +121,9 @@ pub struct CatalogSyncResult {
    pub items_cached: usize,
    /// Libraries that failed to sync (e.g. server hiccup); best-effort.
    pub libraries_failed: usize,
+    /// Entries removed because the server no longer has them. Always 0 when any
+    /// library failed, since a partial crawl cannot prove an item is gone.
+    pub items_pruned: usize,
 }

 #[derive(specta::Type, Debug, Clone, serde::Serialize, serde::Deserialize)]
@@ -71,8 +147,6 @@ pub async fn sync_full_catalog(
    db: State<'_, DatabaseWrapper>,
    handle: String,
 ) -> Result<CatalogSyncResult, String> {
-    use crate::repository::MediaRepository;
-
    let repo = repository.0.get(&handle).ok_or("Repository not found")?;

    let db_service = {
@@ -80,6 +154,27 @@ pub async fn sync_full_catalog(
        Arc::new(database.service())
    };

+    run_index_pass(repo, db_service).await
+}
+
+/// One full-catalog indexing pass, shared by the [`sync_full_catalog`] command
+/// and the background scheduler (DR-109) so there is exactly one implementation
+/// and one concurrency guard.
+///
+/// TRACES: UR-065 | DR-109, DR-110
+pub(crate) async fn run_index_pass(
+    repo: Arc<crate::repository::HybridRepository>,
+    db_service: Arc<crate::storage::db_service::RusqliteService>,
+) -> Result<CatalogSyncResult, String> {
+    use crate::repository::MediaRepository;
+
+    // One pass at a time. The command and the scheduler can both land here, and
+    // two concurrent crawls would double the server load and race on the sweep.
+    if INDEX_IN_PROGRESS.swap(true, Ordering::SeqCst) {
+        return Err("A catalog index pass is already running".to_string());
+    }
+    let _guard = IndexPassGuard;
+
    let libraries = repo.get_libraries().await.map_err(|e| e.to_string())?;
    info!(
        "[Catalog] Full sync starting across {} libraries",
@@ -88,6 +183,10 @@ pub async fn sync_full_catalog(

    let include_types: Vec<String> = CATALOG_ITEM_TYPES.iter().map(|s| s.to_string()).collect();

+    // Taken before the crawl: every row the crawl writes gets a `synced_at`
+    // newer than this, so anything still older afterwards is gone server-side.
+    let pass_started_at = chrono::Utc::now().to_rfc3339();
+
    let mut items_cached = 0usize;
    let mut libraries_failed = 0usize;

@@ -118,6 +217,35 @@ pub async fn sync_full_catalog(
        }
    }

+    // Propagate server-side deletions — but only after a *complete* crawl.
+    // `sync_full_catalog` is best-effort per library, and `items.parent_id` is
+    // ON DELETE CASCADE, so sweeping when a library failed to fetch could
+    // cascade a whole series away because one request timed out.
+    let mut items_pruned = 0usize;
+    if libraries_failed == 0 && !libraries.is_empty() {
+        match repo
+            .prune_stale_catalog(&pass_started_at, &include_types)
+            .await
+        {
+            Ok(removed) => {
+                items_pruned = removed;
+                if removed > 0 {
+                    info!(
+                        "[Catalog] Pruned {} entries no longer on the server",
+                        removed
+                    );
+                }
+            }
+            Err(e) => warn!("[Catalog] Prune of stale catalog entries failed: {:?}", e),
+        }
+    } else if libraries_failed > 0 {
+        info!(
+            "[Catalog] Skipping stale-entry prune: {} librar{} failed to sync, so the crawl is not authoritative",
+            libraries_failed,
+            if libraries_failed == 1 { "y" } else { "ies" }
+        );
+    }
+
    // Record the sync time so callers can skip re-syncing too eagerly.
    let now = chrono::Utc::now().to_rfc3339();
    let upsert = Query::with_params(
@@ -133,16 +261,169 @@ pub async fn sync_full_catalog(
    }

    info!(
-        "[Catalog] Full sync complete: {} items cached, {} libraries failed",
-        items_cached, libraries_failed
+        "[Catalog] Full sync complete: {} items cached, {} pruned, {} libraries failed",
+        items_cached, items_pruned, libraries_failed
    );

    Ok(CatalogSyncResult {
        items_cached,
        libraries_failed,
+        items_pruned,
    })
 }

+/// Whether an index pass is due, given when one last completed.
+///
+/// Pure so the policy is unit-testable without a clock, a server, or a database.
+/// `None` (never indexed) and an unparseable stored value both mean "due" — a
+/// corrupt timestamp should trigger a re-index, not silently freeze the catalog.
+///
+/// TRACES: UR-065 | DR-109 | UT-115
+pub(crate) fn index_is_due(
+    last_synced_at: Option<&str>,
+    now: chrono::DateTime<chrono::Utc>,
+    ttl: Duration,
+) -> bool {
+    let Some(raw) = last_synced_at else {
+        return true;
+    };
+    let Ok(last) = chrono::DateTime::parse_from_rfc3339(raw) else {
+        return true;
+    };
+    now.signed_duration_since(last.with_timezone(&chrono::Utc))
+        .to_std()
+        .map(|elapsed| elapsed >= ttl)
+        // Negative elapsed => the stored stamp is in the future (clock skew).
+        // Not due; a future stamp will age into due-ness on its own.
+        .unwrap_or(false)
+}
+
+/// Read the last-sync timestamp straight from `app_settings`.
+async fn read_last_sync(
+    db_service: &Arc<crate::storage::db_service::RusqliteService>,
+) -> Option<String> {
+    db_service
+        .query_optional(
+            Query::with_params(
+                "SELECT value FROM app_settings WHERE key = ?",
+                vec![QueryParam::String(LAST_CATALOG_SYNC_KEY.to_string())],
+            ),
+            |row| row.get(0),
+        )
+        .await
+        .ok()
+        .flatten()
+}
+
+/// Start the background catalog indexer.
+///
+/// Replaces the frontend's startup-only `syncCatalog()` call: index freshness is
+/// sync policy and belongs in Rust (see the layer assignment in
+/// docs/specs/catalog-index-search.md). Ticks every [`CATALOG_INDEX_TICK`] and
+/// runs a pass when a repository exists, the server is reachable, and the index
+/// is older than [`CATALOG_INDEX_TTL`].
+///
+/// TRACES: UR-065 | DR-109, IR-030
+pub fn spawn_catalog_indexer(app: tauri::AppHandle) {
+    tauri::async_runtime::spawn(async move {
+        // Check shortly after launch, then on every tick — not tick-then-check,
+        // which would leave a fresh install unindexed for a full tick.
+        tokio::time::sleep(CATALOG_INDEX_FIRST_CHECK).await;
+
+        loop {
+            if let Err(e) = maybe_run_scheduled_pass(&app).await {
+                // Never fatal — a failed pass leaves the existing index in place
+                // and we retry on the next tick.
+                warn!("[Catalog] Scheduled index pass skipped: {}", e);
+            }
+
+            tokio::time::sleep(CATALOG_INDEX_TICK).await;
+        }
+    });
+}
+
+/// One scheduler tick: check the preconditions, then index if due.
+async fn maybe_run_scheduled_pass(app: &tauri::AppHandle) -> Result<(), String> {
+    if INDEX_IN_PROGRESS.load(Ordering::SeqCst) {
+        return Ok(());
+    }
+
+    let db_service = {
+        let db = app.state::<DatabaseWrapper>();
+        let database = db.0.lock().map_err(|e| e.to_string())?;
+        Arc::new(database.service())
+    };
+
+    if !index_is_due(
+        read_last_sync(&db_service).await.as_deref(),
+        chrono::Utc::now(),
+        CATALOG_INDEX_TTL,
+    ) {
+        return Ok(());
+    }
+
+    // Offline: leave the index alone. The crawl would fail every library and,
+    // more importantly, a partial crawl must never reach the deletion sweep.
+    {
+        let monitor = app.state::<crate::commands::connectivity::ConnectivityMonitorWrapper>();
+        let monitor = monitor.0.lock().await;
+        if !monitor.get_status().await.is_server_reachable {
+            return Ok(());
+        }
+    }
+
+    let repo = {
+        let manager = app.state::<RepositoryManagerWrapper>();
+        let handles = manager.0.handles();
+        let Some(handle) = handles.first() else {
+            // Not signed in yet.
+            return Ok(());
+        };
+        manager.0.get(handle).ok_or("Repository not found")?
+    };
+
+    info!("[Catalog] Index is stale; starting a scheduled pass");
+    let _ = app.emit(
+        CATALOG_INDEX_EVENT,
+        CatalogIndexEvent {
+            state: "started".to_string(),
+            items_cached: 0,
+            items_pruned: 0,
+            libraries_failed: 0,
+            error: None,
+        },
+    );
+
+    match run_index_pass(repo, db_service).await {
+        Ok(result) => {
+            let _ = app.emit(
+                CATALOG_INDEX_EVENT,
+                CatalogIndexEvent {
+                    state: "finished".to_string(),
+                    items_cached: result.items_cached,
+                    items_pruned: result.items_pruned,
+                    libraries_failed: result.libraries_failed,
+                    error: None,
+                },
+            );
+            Ok(())
+        }
+        Err(e) => {
+            let _ = app.emit(
+                CATALOG_INDEX_EVENT,
+                CatalogIndexEvent {
+                    state: "failed".to_string(),
+                    items_cached: 0,
+                    items_pruned: 0,
+                    libraries_failed: 0,
+                    error: Some(e.clone()),
+                },
+            );
+            Err(e)
+        }
+    }
+}
+
 /// Report the last-synced timestamp so the UI can show a hint / decide whether
 /// to trigger a fresh sync.
 #[tauri::command]
@@ -190,6 +471,51 @@ pub struct ResumeQueuedResult {
    pub failed: usize,
 }

+/// Requeue video downloads that were fetched as audio.
+///
+/// Before [`resolve_pending_download_urls`] consulted the item's type, a row
+/// with no `media_type` — which is every row queued from a media card, since
+/// `download_item` does not record one — resolved against
+/// `get_audio_stream_url`. A movie queued that way completed with an audio-only
+/// transcode on disk, so playing it offline could only ever fail. Those rows are
+/// identifiable after the fact (no `media_type`, but a video item), so reset them
+/// to pending with no URL and let the resolver fetch the real video.
+///
+/// Rows carrying an explicit `media_type` were resolved correctly and are left
+/// alone, as are genuine audio downloads.
+///
+/// Returns the number of rows requeued.
+///
+/// TRACES: UR-071 | DR-136 | UT-126
+pub(crate) async fn requeue_mistyped_video_downloads(
+    db_service: &Arc<crate::storage::db_service::RusqliteService>,
+) -> Result<usize, String> {
+    let video_types = VIDEO_ITEM_TYPES
+        .iter()
+        .map(|t| format!("'{t}'"))
+        .collect::<Vec<_>>()
+        .join(", ");
+
+    let query = Query::new(&format!(
+        "UPDATE downloads
+         SET status = 'pending', stream_url = NULL, progress = 0,
+             bytes_downloaded = 0, started_at = NULL, completed_at = NULL
+         WHERE media_type IS NULL
+           AND status = 'completed'
+           AND item_id IN (SELECT id FROM items WHERE item_type IN ({video_types}))"
+    ));
+
+    let n = db_service.execute(query).await.map_err(|e| e.to_string())? as usize;
+
+    if n > 0 {
+        info!(
+            "[Catalog] Requeued {} video download(s) that were fetched as audio",
+            n
+        );
+    }
+    Ok(n)
+}
+
 /// Core of [`resume_queued_downloads`], factored out for testing: select every
 /// `pending`/`stream_url IS NULL` row, resolve each via `resolve` (returning
 /// `None` leaves the row pending), and heal the row so the pump can start it.
@@ -203,11 +529,31 @@ where
    F: Fn(String, String, String) -> Fut,
    Fut: std::future::Future<Output = Option<String>>,
 {
-    let rows_query = Query::new(
-        "SELECT id, item_id, COALESCE(media_type, 'audio'), COALESCE(quality_preset, 'original')
-         FROM downloads
-         WHERE status = 'pending' AND stream_url IS NULL",
-    );
+    // A row's own media_type wins; otherwise the *item's* type decides. Rows
+    // queued from a media card never carry one (`download_item` does not record
+    // it), and defaulting that NULL to 'audio' resolved movies against
+    // `get_audio_stream_url` — the file on disk was an audio-only transcode, so
+    // offline video could never play. Falling back to 'audio' only when the item
+    // is unknown keeps the historical behaviour for uncached items.
+    // TRACES: UR-071, UR-052 | DR-135
+    let video_types = VIDEO_ITEM_TYPES
+        .iter()
+        .map(|t| format!("'{t}'"))
+        .collect::<Vec<_>>()
+        .join(", ");
+    let rows_query = Query::new(&format!(
+        "SELECT d.id, d.item_id,
+                COALESCE(
+                    d.media_type,
+                    CASE WHEN i.item_type IN ({video_types}) THEN 'video'
+                         WHEN i.item_type IS NOT NULL THEN 'audio'
+                    END,
+                    'audio'),
+                COALESCE(d.quality_preset, 'original')
+         FROM downloads d
+         LEFT JOIN items i ON i.id = d.item_id
+         WHERE d.status = 'pending' AND d.stream_url IS NULL"
+    ));
    let rows: Vec<(i64, String, String, String)> = db_service
        .query_many(rows_query, |row| {
            Ok((row.get(0)?, row.get(1)?, row.get(2)?, row.get(3)?))
@@ -317,6 +663,16 @@ pub async fn resume_queued_downloads(
        Err(e) => warn!("[Catalog] Failed to reset stale downloads: {}", e),
    }

+    // Repair rows that completed as audio because their media_type was missing;
+    // they hold an audio-only transcode where a video should be, so requeue them
+    // for the resolver below. TRACES: UR-071 | DR-136
+    if let Err(e) = requeue_mistyped_video_downloads(&db_service).await {
+        warn!(
+            "[Catalog] Failed to requeue mis-typed video downloads: {}",
+            e
+        );
+    }
+
    // Resolve each row's URL against the (now reachable) repository.
    let repo_for_resolve = Arc::clone(&repo);
    let outcome = resolve_pending_download_urls(
@@ -378,6 +734,43 @@ mod tests {
    use rusqlite::Connection;
    use std::sync::Mutex;

+    /// The re-index policy. Pure, so it is testable without a clock, a server or
+    /// a database — which is the reason it was factored out of the scheduler.
+    ///
+    /// TRACES: UR-065 | DR-109 | UT-115
+    #[test]
+    fn test_index_is_due() {
+        let ttl = Duration::from_secs(6 * 60 * 60);
+        let now = chrono::DateTime::parse_from_rfc3339("2026-08-04T12:00:00+00:00")
+            .unwrap()
+            .with_timezone(&chrono::Utc);
+
+        // Never indexed => due. This is the first-run case.
+        assert!(index_is_due(None, now, ttl));
+
+        // Indexed 7 hours ago => past the 6h TTL => due.
+        assert!(index_is_due(Some("2026-08-04T05:00:00+00:00"), now, ttl));
+
+        // Indexed 1 hour ago => fresh => not due. This is what stops the
+        // scheduler re-crawling every tick.
+        assert!(!index_is_due(Some("2026-08-04T11:00:00+00:00"), now, ttl));
+
+        // Exactly at the TTL boundary counts as due.
+        assert!(index_is_due(Some("2026-08-04T06:00:00+00:00"), now, ttl));
+
+        // A corrupt stored value must trigger a re-index, not freeze the
+        // catalog forever behind an unparseable timestamp.
+        assert!(index_is_due(Some("not-a-timestamp"), now, ttl));
+        assert!(index_is_due(Some(""), now, ttl));
+
+        // A timestamp in the future (clock skew, or a restored backup) is not
+        // due — it ages into due-ness rather than causing a crawl every tick.
+        assert!(!index_is_due(Some("2026-08-05T00:00:00+00:00"), now, ttl));
+
+        // Offsets other than UTC are compared as instants, not as strings.
+        assert!(!index_is_due(Some("2026-08-04T13:30:00+02:00"), now, ttl));
+    }
+
    fn test_db() -> Arc<RusqliteService> {
        let conn = Connection::open_in_memory().unwrap();
        conn.execute_batch(
@@ -389,7 +782,15 @@ mod tests {
                stream_url TEXT,
                target_dir TEXT,
                media_type TEXT,
-                quality_preset TEXT
+                quality_preset TEXT,
+                progress REAL DEFAULT 0,
+                bytes_downloaded INTEGER DEFAULT 0,
+                started_at TEXT,
+                completed_at TEXT
+            );
+            CREATE TABLE items (
+                id TEXT PRIMARY KEY,
+                item_type TEXT
            );
            "#,
        )
@@ -397,6 +798,18 @@ mod tests {
        Arc::new(RusqliteService::new(Arc::new(Mutex::new(conn))))
    }

+    async fn insert_item(db: &Arc<RusqliteService>, item_id: &str, item_type: &str) {
+        db.execute(Query::with_params(
+            "INSERT INTO items (id, item_type) VALUES (?, ?)",
+            vec![
+                QueryParam::String(item_id.to_string()),
+                QueryParam::String(item_type.to_string()),
+            ],
+        ))
+        .await
+        .unwrap();
+    }
+
    async fn insert_download(
        db: &Arc<RusqliteService>,
        item_id: &str,
@@ -489,6 +902,137 @@ mod tests {
        assert_eq!(url, None);
    }

+    /// A movie queued from a media card has no `media_type` — `download_item`
+    /// never records one. Defaulting that NULL to 'audio' resolved the row
+    /// against `get_audio_stream_url`, so the "downloaded movie" on disk was an
+    /// audio-only transcode and offline video playback could never work. The
+    /// item's own type is the authority.
+    ///
+    /// TRACES: UR-071, UR-052 | DR-135 | UT-125
+    #[tokio::test]
+    async fn null_media_type_resolves_from_the_item_type_not_audio() {
+        let db = test_db();
+        insert_item(&db, "movie-1", "Movie").await;
+        insert_item(&db, "ep-1", "Episode").await;
+        insert_item(&db, "track-1", "Audio").await;
+        for id in ["movie-1", "ep-1", "track-1"] {
+            insert_download(&db, id, "pending", None, None).await;
+        }
+
+        let seen = Arc::new(Mutex::new(Vec::new()));
+        let seen_c = Arc::clone(&seen);
+        resolve_pending_download_urls(&db, "/data", move |item_id, media_type, _q| {
+            let seen = Arc::clone(&seen_c);
+            async move {
+                seen.lock().unwrap().push((item_id.clone(), media_type));
+                Some(format!("http://resolved/{item_id}"))
+            }
+        })
+        .await
+        .unwrap();
+
+        let seen = seen.lock().unwrap().clone();
+        let of = |id: &str| {
+            seen.iter()
+                .find(|(i, _)| i == id)
+                .map(|(_, m)| m.clone())
+                .unwrap()
+        };
+        assert_eq!(of("movie-1"), "video", "a Movie must download as video");
+        assert_eq!(of("ep-1"), "video", "an Episode must download as video");
+        assert_eq!(of("track-1"), "audio", "a track is still audio");
+    }
+
+    /// An unknown item (never cached locally) has no type to derive from, so it
+    /// keeps the historical audio default rather than failing the row.
+    ///
+    /// TRACES: UR-071 | DR-135 | UT-125
+    #[tokio::test]
+    async fn unknown_item_falls_back_to_audio() {
+        let db = test_db();
+        insert_download(&db, "ghost", "pending", None, None).await;
+
+        let seen = Arc::new(Mutex::new(String::new()));
+        let seen_c = Arc::clone(&seen);
+        resolve_pending_download_urls(&db, "/data", move |_id, media_type, _q| {
+            let seen = Arc::clone(&seen_c);
+            async move {
+                *seen.lock().unwrap() = media_type;
+                Some("http://x".to_string())
+            }
+        })
+        .await
+        .unwrap();
+
+        assert_eq!(*seen.lock().unwrap(), "audio");
+    }
+
+    /// An explicit `media_type` on the row always wins over the item's type.
+    ///
+    /// TRACES: UR-071 | DR-135 | UT-125
+    #[tokio::test]
+    async fn explicit_media_type_beats_the_item_type() {
+        let db = test_db();
+        insert_item(&db, "odd", "Audio").await;
+        insert_download(&db, "odd", "pending", None, Some("video")).await;
+
+        let seen = Arc::new(Mutex::new(String::new()));
+        let seen_c = Arc::clone(&seen);
+        resolve_pending_download_urls(&db, "/data", move |_id, media_type, _q| {
+            let seen = Arc::clone(&seen_c);
+            async move {
+                *seen.lock().unwrap() = media_type;
+                Some("http://x".to_string())
+            }
+        })
+        .await
+        .unwrap();
+
+        assert_eq!(*seen.lock().unwrap(), "video");
+    }
+
+    /// Rows already downloaded under the audio default hold an audio-only
+    /// transcode on disk, so they play as a broken video forever. They are
+    /// identifiable — no `media_type` but a video item — and are requeued so the
+    /// resolver fetches the real video. Correctly-typed rows and genuine audio
+    /// downloads must be left alone.
+    ///
+    /// TRACES: UR-071 | DR-136 | UT-126
+    #[tokio::test]
+    async fn requeues_video_downloaded_under_the_audio_default() {
+        let db = test_db();
+        insert_item(&db, "movie-1", "Movie").await;
+        insert_item(&db, "track-1", "Audio").await;
+        insert_item(&db, "movie-ok", "Movie").await;
+        // Mis-downloaded: completed, no media_type, video item.
+        insert_download(&db, "movie-1", "completed", Some("http://audio/url"), None).await;
+        // A real audio download: untouched.
+        insert_download(&db, "track-1", "completed", Some("http://audio/ok"), None).await;
+        // A correctly-typed video download: untouched.
+        insert_download(
+            &db,
+            "movie-ok",
+            "completed",
+            Some("http://video/ok"),
+            Some("video"),
+        )
+        .await;
+
+        let requeued = requeue_mistyped_video_downloads(&db).await.unwrap();
+        assert_eq!(requeued, 1);
+
+        let (status, url, _t) = get_row(&db, "movie-1").await;
+        assert_eq!(status, "pending", "the mis-typed row must download again");
+        assert_eq!(url, None, "its audio URL must be cleared so it re-resolves");
+
+        let (status, url, _t) = get_row(&db, "track-1").await;
+        assert_eq!(status, "completed", "a real audio download is untouched");
+        assert_eq!(url.as_deref(), Some("http://audio/ok"));
+
+        let (status, _u, _t) = get_row(&db, "movie-ok").await;
+        assert_eq!(status, "completed", "a correct video download is untouched");
+    }
+
    #[tokio::test]
    async fn video_rows_use_media_type_in_resolver() {
        let db = test_db();
@@ -270,6 +270,19 @@ pub async fn download_item(
        if !can_download {
            warn!("Storage limit reached. Attempting to free space...");

+            // Reclaim expired temporary entries first: they are dead weight, so
+            // freeing them may avoid evicting cache that is still within its
+            // life. Best-effort — a failure here just means eviction does more.
+            // TRACES: UR-071 | DR-127
+            match cache_arc
+                .reclaim_expired_async(&db_service, &user_id, &chrono::Utc::now().to_rfc3339())
+                .await
+            {
+                Ok(n) if n > 0 => info!("Reclaimed {} expired cache entries", n),
+                Ok(_) => {}
+                Err(e) => warn!("Expired-entry reclaim failed: {}", e),
+            }
+
            // Try to evict LRU items to make space
            match cache_arc
                .evict_lru_async(&db_service, &user_id, size as u64)
@@ -0,0 +1,367 @@
+//! Pushing favourite toggles made while the server was unreachable.
+//!
+//! Favouriting works offline: `storage_toggle_favorite` writes the local
+//! `user_data` row and sets `pending_sync = 1`. Until DR-120 nothing ever
+//! cleared that flag — the offline `mark_favorite`/`unmark_favorite` are no-ops
+//! and `syncService.queueFavorite` had no callers — so an offline toggle was
+//! silently lost.
+//!
+//! The drain lives in Rust, not the frontend, because it must run whether or
+//! not any view is mounted; a drain started by a component dies with it.
+//!
+//! TRACES: UR-069 | DR-120 | UT-103
+
+use std::sync::Arc;
+
+use async_trait::async_trait;
+use log::{debug, info, warn};
+use tauri::{Emitter, Listener, Manager};
+
+use crate::repository::types::RepoError;
+use crate::repository::MediaRepository;
+use crate::storage::db_service::{DatabaseService, Query, QueryParam, RusqliteService};
+
+/// The subset of the repository the drain needs.
+///
+/// Narrow on purpose: a test double for `MediaRepository` would be forty
+/// unimplemented methods, which is how a drain ends up untested.
+#[async_trait]
+pub trait FavoriteSink: Send + Sync {
+    async fn push_favorite(&self, item_id: &str, is_favorite: bool) -> Result<(), RepoError>;
+}
+
+#[async_trait]
+impl<T: MediaRepository + ?Sized> FavoriteSink for T {
+    async fn push_favorite(&self, item_id: &str, is_favorite: bool) -> Result<(), RepoError> {
+        if is_favorite {
+            self.mark_favorite(item_id).await
+        } else {
+            self.unmark_favorite(item_id).await
+        }
+    }
+}
+
+/// A local favourite change still waiting to reach the server.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct PendingFavorite {
+    pub item_id: String,
+    pub is_favorite: bool,
+}
+
+/// Read every favourite change this user has pending.
+async fn read_pending(
+    db: &Arc<RusqliteService>,
+    user_id: &str,
+) -> Result<Vec<PendingFavorite>, String> {
+    db.query_many(
+        Query::with_params(
+            "SELECT item_id, is_favorite FROM user_data \
+             WHERE user_id = ? AND pending_sync = 1 AND is_favorite IS NOT NULL",
+            vec![QueryParam::String(user_id.to_string())],
+        ),
+        |row| {
+            Ok(PendingFavorite {
+                item_id: row.get::<_, String>(0)?,
+                is_favorite: row.get::<_, Option<i32>>(1)?.unwrap_or(0) != 0,
+            })
+        },
+    )
+    .await
+}
+
+/// Push pending favourite changes to the server and clear their flags.
+///
+/// Returns the ids that reached the server, for the `favorites-changed` event.
+/// A row whose push fails keeps `pending_sync = 1` and is retried on the next
+/// reconnect rather than being dropped.
+///
+/// TRACES: UR-069 | DR-120 | UT-103
+pub async fn drain_pending_favorites(
+    db: &Arc<RusqliteService>,
+    sink: &dyn FavoriteSink,
+    user_id: &str,
+) -> Result<Vec<String>, String> {
+    let pending = read_pending(db, user_id).await?;
+    if pending.is_empty() {
+        return Ok(Vec::new());
+    }
+
+    info!(
+        "[Favorites] Pushing {} favourite change(s) queued while offline",
+        pending.len()
+    );
+
+    let mut pushed = Vec::new();
+    for change in pending {
+        match sink
+            .push_favorite(&change.item_id, change.is_favorite)
+            .await
+        {
+            Ok(()) => {
+                let cleared = db
+                    .execute(Query::with_params(
+                        "UPDATE user_data SET pending_sync = 0, synced_at = ? \
+                         WHERE user_id = ? AND item_id = ?",
+                        vec![
+                            QueryParam::String(chrono::Utc::now().to_rfc3339()),
+                            QueryParam::String(user_id.to_string()),
+                            QueryParam::String(change.item_id.clone()),
+                        ],
+                    ))
+                    .await;
+
+                match cleared {
+                    Ok(_) => pushed.push(change.item_id),
+                    // The server took it; failing to clear the flag only means
+                    // we push it again next time, which is harmless.
+                    Err(e) => warn!(
+                        "[Favorites] Pushed {} but could not clear pending_sync: {}",
+                        change.item_id, e
+                    ),
+                }
+            }
+            Err(e) => {
+                // Still pending — retried on the next reconnect.
+                debug!(
+                    "[Favorites] Deferring {}, server rejected the push: {:?}",
+                    change.item_id, e
+                );
+            }
+        }
+    }
+
+    Ok(pushed)
+}
+
+/// Drain on every offline→online transition.
+///
+/// Hooks the `connectivity:reconnected` event the `ConnectivityMonitor`
+/// already emits, rather than polling — reachability is derived from real
+/// traffic (DR-055) and this just reacts to it.
+///
+/// TRACES: UR-069 | DR-120
+pub fn spawn_favorites_drain(app: tauri::AppHandle) {
+    let handle = app.clone();
+    app.listen("connectivity:reconnected", move |_event| {
+        let app = handle.clone();
+        tauri::async_runtime::spawn(async move {
+            if let Err(e) = run_drain(&app).await {
+                warn!("[Favorites] Drain skipped: {}", e);
+            }
+        });
+    });
+}
+
+async fn run_drain(app: &tauri::AppHandle) -> Result<(), String> {
+    let db_service: Arc<RusqliteService> = {
+        let db = app.state::<crate::commands::storage::DatabaseWrapper>();
+        let database = db.0.lock().map_err(|e| e.to_string())?;
+        Arc::new(database.service())
+    };
+
+    let (repo, user_id) = {
+        let manager = app.state::<crate::commands::repository::RepositoryManagerWrapper>();
+        let handles = manager.0.handles();
+        let Some(handle) = handles.first() else {
+            // Not signed in — nothing to push on behalf of.
+            return Ok(());
+        };
+        let repo = manager.0.get(handle).ok_or("Repository not found")?;
+        let user_id = repo.user_id().to_string();
+        (repo, user_id)
+    };
+
+    let pushed = drain_pending_favorites(&db_service, repo.as_ref(), &user_id).await?;
+
+    if !pushed.is_empty() {
+        let event = crate::commands::repository::FavoritesChangedEvent { item_ids: pushed };
+        if let Err(e) = app.emit(crate::commands::repository::FAVORITES_CHANGED_EVENT, &event) {
+            warn!("[Favorites] Failed to emit change event: {}", e);
+        }
+    }
+
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use rusqlite::Connection;
+    use std::sync::Mutex;
+
+    /// Records what the server was asked to do, and can be told to fail.
+    struct RecordingSink {
+        calls: Mutex<Vec<(String, bool)>>,
+        fail_for: Option<String>,
+    }
+
+    impl RecordingSink {
+        fn new() -> Self {
+            Self {
+                calls: Mutex::new(Vec::new()),
+                fail_for: None,
+            }
+        }
+
+        fn failing_for(item_id: &str) -> Self {
+            Self {
+                calls: Mutex::new(Vec::new()),
+                fail_for: Some(item_id.to_string()),
+            }
+        }
+
+        fn calls(&self) -> Vec<(String, bool)> {
+            let mut calls = self.calls.lock().unwrap().clone();
+            calls.sort();
+            calls
+        }
+    }
+
+    #[async_trait]
+    impl FavoriteSink for RecordingSink {
+        async fn push_favorite(&self, item_id: &str, is_favorite: bool) -> Result<(), RepoError> {
+            if self.fail_for.as_deref() == Some(item_id) {
+                return Err(RepoError::Offline);
+            }
+            self.calls
+                .lock()
+                .unwrap()
+                .push((item_id.to_string(), is_favorite));
+            Ok(())
+        }
+    }
+
+    fn test_db() -> Arc<RusqliteService> {
+        let conn = Connection::open_in_memory().unwrap();
+        conn.execute_batch(
+            r#"
+            CREATE TABLE user_data (
+                user_id TEXT NOT NULL,
+                item_id TEXT NOT NULL,
+                is_favorite INTEGER,
+                synced_at TEXT,
+                pending_sync INTEGER DEFAULT 0,
+                PRIMARY KEY (user_id, item_id)
+            );
+            "#,
+        )
+        .unwrap();
+        Arc::new(RusqliteService::new(Arc::new(Mutex::new(conn))))
+    }
+
+    async fn seed(db: &Arc<RusqliteService>, rows: &[(&str, &str, i32, i32)]) {
+        for (user, item, fav, pending) in rows {
+            db.execute(Query::with_params(
+                "INSERT INTO user_data (user_id, item_id, is_favorite, pending_sync) \
+                 VALUES (?, ?, ?, ?)",
+                vec![
+                    QueryParam::String(user.to_string()),
+                    QueryParam::String(item.to_string()),
+                    QueryParam::Int(*fav),
+                    QueryParam::Int(*pending),
+                ],
+            ))
+            .await
+            .unwrap();
+        }
+    }
+
+    async fn pending_flag(db: &Arc<RusqliteService>, item_id: &str) -> Option<i32> {
+        db.query_optional(
+            Query::with_params(
+                "SELECT pending_sync FROM user_data WHERE item_id = ?",
+                vec![QueryParam::String(item_id.to_string())],
+            ),
+            |row| row.get::<_, Option<i32>>(0),
+        )
+        .await
+        .unwrap()
+        .flatten()
+    }
+
+    /// UT-103 — the core of the bug: a favourite toggled while offline reaches
+    /// the server on reconnect, and stops being pending.
+    ///
+    /// TRACES: UR-069 | DR-120 | UT-103
+    #[tokio::test]
+    async fn test_drain_pushes_pending_favorites_and_clears_the_flag() {
+        let db = test_db();
+        seed(
+            &db,
+            &[
+                ("u1", "marked-offline", 1, 1),
+                ("u1", "unmarked-offline", 0, 1),
+                // Already synced — must not be pushed again.
+                ("u1", "already-synced", 1, 0),
+            ],
+        )
+        .await;
+
+        let sink = RecordingSink::new();
+        let pushed = drain_pending_favorites(&db, &sink, "u1").await.unwrap();
+
+        assert_eq!(
+            sink.calls(),
+            vec![
+                ("marked-offline".to_string(), true),
+                ("unmarked-offline".to_string(), false),
+            ],
+            "both pending changes push, with their direction preserved"
+        );
+        assert_eq!(pushed.len(), 2);
+        assert_eq!(pending_flag(&db, "marked-offline").await, Some(0));
+        assert_eq!(pending_flag(&db, "unmarked-offline").await, Some(0));
+    }
+
+    /// A push that fails keeps its row pending, so the change is retried rather
+    /// than dropped on the floor.
+    ///
+    /// TRACES: UR-069 | DR-120 | UT-103
+    #[tokio::test]
+    async fn test_drain_leaves_failed_pushes_pending() {
+        let db = test_db();
+        seed(&db, &[("u1", "ok", 1, 1), ("u1", "boom", 1, 1)]).await;
+
+        let sink = RecordingSink::failing_for("boom");
+        let pushed = drain_pending_favorites(&db, &sink, "u1").await.unwrap();
+
+        assert_eq!(pushed, vec!["ok".to_string()]);
+        assert_eq!(pending_flag(&db, "ok").await, Some(0));
+        assert_eq!(
+            pending_flag(&db, "boom").await,
+            Some(1),
+            "a failed push must stay queued for the next reconnect"
+        );
+    }
+
+    /// Another user's queued changes are not pushed with this user's token.
+    ///
+    /// TRACES: UR-069 | DR-120 | UT-103
+    #[tokio::test]
+    async fn test_drain_only_touches_the_given_user() {
+        let db = test_db();
+        seed(&db, &[("u1", "mine", 1, 1), ("u2", "theirs", 1, 1)]).await;
+
+        let sink = RecordingSink::new();
+        let pushed = drain_pending_favorites(&db, &sink, "u1").await.unwrap();
+
+        assert_eq!(pushed, vec!["mine".to_string()]);
+        assert_eq!(pending_flag(&db, "theirs").await, Some(1));
+    }
+
+    /// Nothing pending means no server calls at all — a reconnect must not
+    /// generate traffic just because it happened.
+    ///
+    /// TRACES: UR-069 | DR-120 | UT-103
+    #[tokio::test]
+    async fn test_drain_is_a_noop_when_nothing_is_pending() {
+        let db = test_db();
+        seed(&db, &[("u1", "synced", 1, 0)]).await;
+
+        let sink = RecordingSink::new();
+        let pushed = drain_pending_favorites(&db, &sink, "u1").await.unwrap();
+
+        assert!(pushed.is_empty());
+        assert!(sink.calls().is_empty());
+    }
+}
@@ -7,6 +7,7 @@ pub mod connectivity;
 pub mod conversions;
 pub mod device;
 pub mod download;
+pub mod favorites;
 pub mod offline;
 pub mod playback_mode;
 pub mod playback_reporting;
@@ -16,6 +17,7 @@ pub mod repository;
 pub mod sessions;
 pub mod storage;
 pub mod sync;
+pub mod sync_drain;

 pub use auth::*;
 pub use catalog::*;
@@ -33,3 +35,4 @@ pub use repository::{RepositoryManager, RepositoryManagerWrapper, *};
 pub use sessions::*;
 pub use storage::*;
 pub use sync::*;
+pub use sync_drain::*;
@@ -379,16 +379,49 @@ pub(super) async fn create_media_item(
    })
 }

-/// Check if an item has a completed download
-pub(super) async fn check_for_local_download(
-    db: &DatabaseWrapper,
+/// Pick the source for an audio-only handoff.
+///
+/// A downloaded file wins over the audio-only stream URL. No transcode or audio
+/// extraction is involved or wanted: the native backends already play a video
+/// container without decoding its video — the Linux MPV backend is configured
+/// with `video: no`, and ExoPlayer simply has no surface to render to when the
+/// item is `MediaType::Audio`. Producing a separate audio-only file would cost
+/// CPU and battery, need an encoder the project does not ship, and leave a
+/// second artifact to keep in step with the first.
+///
+/// TRACES: UR-071 | DR-128 | UT-119
+pub(super) fn background_audio_source(
+    local_path: Option<String>,
+    stream_url: String,
+    item_id: &str,
+) -> MediaSource {
+    match local_path {
+        Some(path) => MediaSource::Local {
+            file_path: PathBuf::from(path),
+            jellyfin_item_id: Some(item_id.to_string()),
+        },
+        None => MediaSource::Remote {
+            stream_url,
+            jellyfin_item_id: item_id.to_string(),
+        },
+    }
+}
+
+/// Resolve the on-disk file backing a completed download, if there is one.
+///
+/// A `downloads` row is not proof of a file: it can outlive the bytes (manual
+/// deletion, a cleared cache directory, a restored database). Every caller wants
+/// "can I play this from disk right now", so existence is checked here rather
+/// than trusted from the row.
+///
+/// Split out from [`check_for_local_download`] so the resolution is testable
+/// without a `DatabaseWrapper`, and reusable by the video path.
+///
+/// TRACES: UR-071 | DR-123 | UT-116
+pub(super) async fn resolve_local_media_path<S: DatabaseService>(
+    db_service: &Arc<S>,
    item_id: &str,
 ) -> Result<Option<String>, String> {
-    let db_service = {
-        let database = db.0.lock().map_err(|e| e.to_string())?;
-        Arc::new(database.service())
-    };
-
    let query = Query::with_params(
        "SELECT file_path FROM downloads WHERE item_id = ? AND status = 'completed' LIMIT 1",
        vec![QueryParam::String(item_id.to_string())],
@@ -399,22 +432,58 @@ pub(super) async fn check_for_local_download(
        .await
        .map_err(|e| e.to_string())?;

-    // Verify the file actually exists on disk
-    if let Some(ref file_path) = path {
-        if std::path::Path::new(file_path).exists() {
-            Ok(path)
-        } else {
+    match path {
+        Some(ref file_path) if std::path::Path::new(file_path).exists() => Ok(path),
+        Some(file_path) => {
            warn!(
                "[Player] Download entry exists in DB but file not found: {}",
                file_path
            );
            Ok(None)
        }
-    } else {
-        Ok(None)
+        None => Ok(None),
    }
 }

+/// Check if an item has a completed download
+pub(super) async fn check_for_local_download(
+    db: &DatabaseWrapper,
+    item_id: &str,
+) -> Result<Option<String>, String> {
+    let db_service = {
+        let database = db.0.lock().map_err(|e| e.to_string())?;
+        Arc::new(database.service())
+    };
+
+    resolve_local_media_path(&db_service, item_id).await
+}
+
+/// The on-disk path for a downloaded item, for playback surfaces that resolve
+/// their own source rather than going through the queue.
+///
+/// The video player is the reason this exists: audio has preferred local files
+/// since queue construction, but video asks the repository for a stream URL and
+/// never consults `downloads`, so a downloaded film was still streamed — costing
+/// bandwidth that had already been spent and failing outright when offline.
+///
+/// Returns `None` when nothing is downloaded *or* the file is missing, so the
+/// caller falls back to streaming.
+///
+/// TRACES: UR-071 | DR-123 | UT-116
+#[tauri::command]
+#[specta::specta]
+pub async fn player_local_media_path(
+    db: State<'_, DatabaseWrapper>,
+    item_id: String,
+) -> Result<Option<String>, String> {
+    let db_service = {
+        let database = db.0.lock().map_err(|e| e.to_string())?;
+        Arc::new(database.service())
+    };
+
+    resolve_local_media_path(&db_service, &item_id).await
+}
+
 /// Re-point queued streaming items at completed local downloads.
 ///
 /// Sources are resolved once when the queue is built, so downloads that finish
@@ -574,6 +643,7 @@ pub async fn player_play_item(
 pub async fn player_enter_background_audio(
    player: State<'_, PlayerStateWrapper>,
    session: State<'_, MediaSessionManagerWrapper>,
+    db: State<'_, DatabaseWrapper>,
    item: PlayItemRequest,
    position_seconds: f64,
 ) -> Result<PlayerStatus, String> {
@@ -582,6 +652,19 @@ pub async fn player_enter_background_audio(
        item.title, position_seconds
    );

+    // Prefer the downloaded file over the audio-only stream URL the frontend
+    // resolved. Handing the native backend a local video container yields
+    // audio-only playback for free — no transcode, no second artifact.
+    // TRACES: UR-071 | DR-128
+    let local_path = check_for_local_download(&db, &item.id).await?;
+    if local_path.is_some() {
+        info!(
+            "player_enter_background_audio: using downloaded file for {}",
+            item.id
+        );
+    }
+    let source = background_audio_source(local_path, item.stream_url, &item.id);
+
    // Build an AUDIO media item pointing at the audio-only stream. We do not use
    // create_media_item() because that hardcodes MediaType::Video; background
    // audio must be Audio so no video decode is started.
@@ -605,10 +688,7 @@ pub async fn player_enter_background_audio(
        duration: item.duration_seconds,
        artwork_url: None,
        media_type: MediaType::Audio,
-        source: MediaSource::Remote {
-            stream_url: item.stream_url,
-            jellyfin_item_id: item.id.clone(),
-        },
+        source,
        video_codec: None,
        needs_transcoding: false,
        video_width: None,
@@ -634,7 +714,7 @@ pub async fn player_enter_background_audio(
    // this base to the native player's relative position to get the absolute one.
    // The controller owns it so a backend-driven advance to the next episode
    // clears it along with the stream it described.
-    controller.set_background_audio_base(position_seconds);
+    controller.enter_background_audio(position_seconds);
    controller
        .play_item(media_item)
        .map_err(|e| e.to_string())?;
@@ -673,7 +753,7 @@ pub async fn player_exit_background_audio(
    // The base offset (handoff position) + native player's relative position =
    // the absolute position to resume the video at. Zero after a backend-driven
    // episode advance, whose stream already starts at its own zero.
-    let base = controller.take_background_audio_base();
+    let base = controller.exit_background_audio();
    // Capture position into a `let` BEFORE stop() — never hold work across a lock
    // re-entrant call (deadlock discipline, CLAUDE.md).
    let relative = controller.position();
@@ -2379,6 +2459,128 @@ pub async fn player_disable_jellyfin(player: State<'_, PlayerStateWrapper>) -> R

 #[cfg(test)]
 mod tests {
+    /// The audio-only handoff must play a downloaded file when there is one,
+    /// rather than fetching an audio-only stream for media already on disk.
+    ///
+    /// TRACES: UR-071 | DR-128 | UT-119
+    #[test]
+    fn test_background_audio_source_prefers_local_file() {
+        use super::background_audio_source;
+        use crate::player::MediaSource;
+        use std::path::PathBuf;
+
+        let local = background_audio_source(
+            Some("/downloads/ep1.mkv".to_string()),
+            "https://server/audio-only".to_string(),
+            "ep-1",
+        );
+        match local {
+            MediaSource::Local {
+                file_path,
+                jellyfin_item_id,
+            } => {
+                assert_eq!(file_path, PathBuf::from("/downloads/ep1.mkv"));
+                // The Jellyfin id must survive so progress still syncs back.
+                assert_eq!(jellyfin_item_id.as_deref(), Some("ep-1"));
+            }
+            other => panic!("expected a local source, got {:?}", other),
+        }
+
+        let remote = background_audio_source(None, "https://server/audio-only".to_string(), "ep-1");
+        match remote {
+            MediaSource::Remote {
+                stream_url,
+                jellyfin_item_id,
+            } => {
+                assert_eq!(stream_url, "https://server/audio-only");
+                assert_eq!(jellyfin_item_id, "ep-1");
+            }
+            other => panic!("expected a remote source, got {:?}", other),
+        }
+    }
+
+    /// A downloaded item must resolve to its file, and a `downloads` row whose
+    /// file has gone must resolve to `None` so the caller falls back to
+    /// streaming instead of handing the player a path that cannot be opened.
+    ///
+    /// TRACES: UR-071 | DR-123 | UT-116
+    #[tokio::test]
+    async fn test_resolve_local_media_path() {
+        use super::resolve_local_media_path;
+        use crate::storage::db_service::{DatabaseService, Query, RusqliteService};
+        use rusqlite::Connection;
+        use std::sync::{Arc, Mutex};
+
+        let conn = Connection::open_in_memory().unwrap();
+        conn.execute(
+            "CREATE TABLE downloads (id INTEGER PRIMARY KEY, item_id TEXT, status TEXT, file_path TEXT)",
+            [],
+        )
+        .unwrap();
+        let db_service = Arc::new(RusqliteService::new(Arc::new(Mutex::new(conn))));
+
+        // A real file on disk, so the existence check passes.
+        let present = std::env::temp_dir().join("jellytau-resolve-local-test.mp4");
+        std::fs::write(&present, b"x").unwrap();
+        let present_str = present.to_string_lossy().to_string();
+
+        for (item, status, path) in [
+            ("downloaded", "completed", present_str.as_str()),
+            ("still-going", "downloading", present_str.as_str()),
+            (
+                "file-gone",
+                "completed",
+                "/nonexistent/jellytau/missing.mp4",
+            ),
+        ] {
+            db_service
+                .execute(Query::with_params(
+                    "INSERT INTO downloads (item_id, status, file_path) VALUES (?, ?, ?)",
+                    vec![
+                        crate::storage::db_service::QueryParam::String(item.to_string()),
+                        crate::storage::db_service::QueryParam::String(status.to_string()),
+                        crate::storage::db_service::QueryParam::String(path.to_string()),
+                    ],
+                ))
+                .await
+                .unwrap();
+        }
+
+        assert_eq!(
+            resolve_local_media_path(&db_service, "downloaded")
+                .await
+                .unwrap()
+                .as_deref(),
+            Some(present_str.as_str()),
+            "a completed download with its file present must resolve"
+        );
+
+        assert_eq!(
+            resolve_local_media_path(&db_service, "still-going")
+                .await
+                .unwrap(),
+            None,
+            "an in-progress download is not playable from disk"
+        );
+
+        assert_eq!(
+            resolve_local_media_path(&db_service, "file-gone")
+                .await
+                .unwrap(),
+            None,
+            "a row whose file has gone must fall back to streaming, not hand over a dead path"
+        );
+
+        assert_eq!(
+            resolve_local_media_path(&db_service, "never-heard-of-it")
+                .await
+                .unwrap(),
+            None
+        );
+
+        let _ = std::fs::remove_file(&present);
+    }
+
    /// Queue items enqueued as Remote must flip to Local once a completed
    /// download exists on disk — this is what makes preloaded tracks (and
    /// offline playback after a connection drop) actually use the cache.
@@ -142,7 +142,7 @@ pub async fn player_play_next_episode(
 /// - Frontend when audio track ends via backend event - no itemId/repositoryHandle needed
 /// - Android JNI callback also triggers this logic directly
 ///
-/// TRACES: UR-023, UR-026, UR-040 | DR-047, DR-052
+/// TRACES: UR-023, UR-026, UR-040 | DR-047, DR-052, DR-129
 #[tauri::command]
 #[specta::specta]
 pub async fn player_on_playback_ended(
@@ -257,11 +257,75 @@ pub async fn player_on_playback_ended(
                    .await;
            }
        }
+        AutoplayDecision::ResumeStream { position } => {
+            // The stream was cut short by the network, not by the media ending.
+            // Re-open it where it died — no queue clearing, no PlaybackEnded, and
+            // above all no leaving the player parked in ExoPlayer's STATE_ENDED,
+            // where the next play intent restarts the item from 0:00.
+            log::info!(
+                "[Autoplay] Decision: Resume truncated stream at {:.1}s",
+                position
+            );
+            let controller = controller_arc.lock().await;
+            if let Err(e) = controller.resume_stream_at(position).await {
+                log::error!("[Autoplay] Failed to resume truncated stream: {}", e);
+                if let Some(emitter) = controller.event_emitter() {
+                    emitter.emit(PlayerStatusEvent::PlaybackEnded);
+                }
+            }
+        }
    }

    Ok(())
 }

+/// Try to recover playback after a **recoverable** player error, reporting
+/// whether it was handled.
+///
+/// The frontend's error handler stops the player, which is right for a real
+/// failure and wrong for a network blip — it turned every hiccup into "playback
+/// died". This is the echo path for backends that cannot decide in-process:
+/// MpvBackend is constructed before `PlayerController` exists ([`lib.rs`]), so
+/// its event thread has no controller to ask. It emits the error, the frontend
+/// echoes it here, and the decision stays in Rust — the same shape as
+/// `PlaybackEnded` → `player_on_playback_ended`.
+///
+/// Returns `true` when the stream was re-opened and the caller must NOT stop the
+/// player; `false` when the error is real and should be surfaced as before.
+/// Android decides inside its JNI callback and only emits errors it has already
+/// declined to recover, so this reports `false` for those without a second
+/// opinion — the shared attempt budget is spent by then either way.
+///
+/// TRACES: UR-004, UR-040 | DR-130 | UT-117
+#[tauri::command]
+#[specta::specta]
+pub async fn player_recover_stream(player: State<'_, PlayerStateWrapper>) -> Result<bool, String> {
+    let (position, delay_secs) = {
+        let controller = player.0.lock().await;
+        match controller.recoverable_error_resume() {
+            Some(resume) => resume,
+            None => return Ok(false),
+        }
+    };
+
+    log::warn!(
+        "[Recovery] Stream failed — re-opening at {:.1}s in {}s",
+        position,
+        delay_secs
+    );
+    // Give a brief outage time to clear; retrying instantly just burns the budget.
+    tokio::time::sleep(std::time::Duration::from_secs(delay_secs)).await;
+
+    let controller = player.0.lock().await;
+    match controller.resume_stream_at(position).await {
+        Ok(()) => Ok(true),
+        Err(e) => {
+            log::error!("[Recovery] Failed to re-open stream: {}", e);
+            Ok(false)
+        }
+    }
+}
+
 // ===== HTML5 video state-report commands =====
 //
 // On platforms where video renders in the webview (Linux WebKitGTK HTML5
@@ -41,6 +41,19 @@ impl RepositoryManager {
        repos.get(handle).cloned()
    }

+    /// Handles of every live repository.
+    ///
+    /// The background catalog indexer (DR-109) runs outside any command, so it
+    /// has no handle passed in and needs to discover one. In practice there is a
+    /// single signed-in repository; returning all of them avoids inventing an
+    /// "active" concept the rest of the code does not have.
+    ///
+    /// TRACES: UR-065 | DR-109
+    pub fn handles(&self) -> Vec<String> {
+        let repos = self.repositories.lock_safe();
+        repos.keys().cloned().collect()
+    }
+
    pub fn destroy(&self, handle: &str) {
        let mut repos = self.repositories.lock_safe();
        repos.remove(handle);
@@ -780,6 +793,125 @@ pub async fn repository_mark_favorite(
        .map_err(|e| format!("{:?}", e))
 }

+/// Tauri event announcing that favourite state changed behind the UI's back —
+/// either because the server disagreed with the cache on a background refresh,
+/// or because pending offline toggles were pushed on reconnect.
+///
+/// TRACES: UR-069 | DR-120
+pub const FAVORITES_CHANGED_EVENT: &str = "favorites-changed";
+
+/// Payload for [`FAVORITES_CHANGED_EVENT`] — the ids whose favourite state
+/// actually flipped, so the frontend refreshes those rather than everything.
+///
+/// TRACES: UR-069 | DR-120 | UT-107
+#[derive(specta::Type, Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct FavoritesChangedEvent {
+    pub item_ids: Vec<String>,
+}
+
+/// Ids whose favourite state differs between what we showed and what the server
+/// has — favourited elsewhere since the cache was written, or un-favourited
+/// elsewhere.
+///
+/// Pulled out of the command so the "emit nothing when nothing changed" rule is
+/// testable: an unchanged set must leave a quiet page quiet rather than
+/// triggering a refetch on every visit.
+///
+/// TRACES: UR-069 | DR-120 | UT-107
+fn changed_favorite_ids(
+    cached: &std::collections::HashSet<String>,
+    server: &std::collections::HashSet<String>,
+) -> Vec<String> {
+    let mut changed: Vec<String> = server.symmetric_difference(cached).cloned().collect();
+    // Deterministic order so the event payload does not depend on hash seeding.
+    changed.sort();
+    changed
+}
+
+/// Everything the viewer has favourited, across libraries, narrowed by scope.
+///
+/// Two-phase like `repository_search`: the local answer returns immediately and
+/// a background server pass emits `favorites-changed` when the server's set
+/// differs. Without the second phase a favourite marked in another client shows
+/// up only on the *second* visit to the page, since the cache-first read hands
+/// back local rows and the refresh is invisible to the frontend.
+///
+/// TRACES: UR-067 | DR-115, DR-120, JA-033 | UT-107
+#[tauri::command]
+#[specta::specta]
+pub async fn repository_get_favorites(
+    app: AppHandle,
+    manager: State<'_, RepositoryManagerWrapper>,
+    handle: String,
+    scope: SearchScope,
+    options: Option<GetItemsOptions>,
+) -> Result<SearchResult, String> {
+    let repo = manager.0.get(&handle).ok_or("Repository not found")?;
+
+    let cache_result = repo
+        .get_favorites_cache_only(scope, options.clone())
+        .await
+        .unwrap_or_else(|e| {
+            debug!("[Favorites] Cache miss/timeout: {:?}", e);
+            SearchResult {
+                items: Vec::new(),
+                total_record_count: 0,
+            }
+        });
+
+    // With "Show all server media" off the local answer is authoritative
+    // (DR-080) — don't go behind the user's back to the server.
+    if !crate::repository::offline::include_catalog_browse() {
+        return Ok(cache_result);
+    }
+
+    // Nothing cached yet — a fresh install, or a viewer whose favourites were
+    // all marked on another client. Returning the empty result here paints
+    // "Nothing favourited yet — tap the heart on anything you like", which is a
+    // *wrong* answer, corrected a server round trip later when the background
+    // refresh fires `favorites-changed`. Ask the repository for a real answer
+    // instead: its `get_favorites` is exactly this read — cache first, server on
+    // a miss, saving through — and it applies the same DR-080 gate.
+    //
+    // TRACES: UR-067 | DR-115
+    if !cache_result.has_content() {
+        debug!("[Favorites] Nothing cached; answering from the server");
+        return repo
+            .get_favorites(scope, options)
+            .await
+            .map_err(|e| format!("{:?}", e));
+    }
+
+    let repo_bg = repo.clone();
+    let cached_ids: std::collections::HashSet<String> =
+        cache_result.items.iter().map(|i| i.id.clone()).collect();
+    tauri::async_runtime::spawn(async move {
+        match repo_bg.get_favorites_server_only(scope, options).await {
+            Ok(server_result) => {
+                let server_ids: std::collections::HashSet<String> =
+                    server_result.items.iter().map(|i| i.id.clone()).collect();
+                let changed = changed_favorite_ids(&cached_ids, &server_ids);
+
+                if !changed.is_empty() {
+                    let event = FavoritesChangedEvent { item_ids: changed };
+                    if let Err(e) = app.emit(FAVORITES_CHANGED_EVENT, &event) {
+                        error!("[Favorites] Failed to emit change event: {}", e);
+                    }
+                }
+            }
+            Err(e) => {
+                warn!(
+                    "[Favorites] Server refresh failed, keeping cached favourites: {:?}",
+                    e
+                );
+            }
+        }
+    });
+
+    Ok(cache_result)
+}
+
 /// Unmark an item as favorite
 #[tauri::command]
 #[specta::specta]
@@ -853,6 +985,44 @@ mod tests {
        assert!(manager.get("any-handle").is_none());
    }

+    fn ids(values: &[&str]) -> std::collections::HashSet<String> {
+        values.iter().map(|v| v.to_string()).collect()
+    }
+
+    /// UT-107 — the background refresh reports only what actually changed.
+    ///
+    /// TRACES: UR-069 | DR-120 | UT-107
+    #[test]
+    fn test_changed_favorite_ids_reports_both_directions() {
+        // Favourited in another client since we cached.
+        assert_eq!(
+            changed_favorite_ids(&ids(&["a"]), &ids(&["a", "b"])),
+            vec!["b".to_string()]
+        );
+
+        // Un-favourited in another client.
+        assert_eq!(
+            changed_favorite_ids(&ids(&["a", "b"]), &ids(&["a"])),
+            vec!["b".to_string()]
+        );
+
+        // Both at once, in a stable order.
+        assert_eq!(
+            changed_favorite_ids(&ids(&["a", "b"]), &ids(&["b", "c"])),
+            vec!["a".to_string(), "c".to_string()]
+        );
+    }
+
+    /// An unchanged set emits nothing — otherwise every visit to the page would
+    /// fire an event and trigger a pointless refetch.
+    ///
+    /// TRACES: UR-069 | DR-120 | UT-107
+    #[test]
+    fn test_changed_favorite_ids_is_empty_when_nothing_moved() {
+        assert!(changed_favorite_ids(&ids(&["a", "b"]), &ids(&["b", "a"])).is_empty());
+        assert!(changed_favorite_ids(&ids(&[]), &ids(&[])).is_empty());
+    }
+
    #[test]
    fn test_repository_manager_wrapper_structure() {
        let manager = RepositoryManager::new();
@@ -80,6 +80,30 @@ pub fn storage_init(db: State<DatabaseWrapper>) -> Result<String, String> {
    Ok(database.path().to_string_lossy().to_string())
 }

+/// A playable URL for a downloaded file on disk.
+///
+/// Local media is served over a loopback HTTP server rather than handed to the
+/// webview as a `file://`/asset URL, because the asset protocol cannot stream a
+/// large file — it answers a range-less request with the whole thing, which
+/// Chromium abandons. See `media_server` for why real HTTP is used.
+///
+/// The returned URL carries the server's per-session token, so it is only valid
+/// for this run of the app and must not be persisted.
+///
+/// TRACES: UR-071 | DR-137
+#[tauri::command]
+#[specta::specta]
+pub fn media_local_url(
+    server: State<crate::media_server::MediaServerWrapper>,
+    path: String,
+) -> Result<String, String> {
+    server
+        .0
+        .as_ref()
+        .map(|s| s.url_for(&path))
+        .ok_or_else(|| "Local media server is not running".to_string())
+}
+
 /// Get storage directory path (parent directory of the database file)
 #[tauri::command]
 #[specta::specta]
@@ -47,10 +47,25 @@ pub async fn storage_save_person(
    };

    let query = Query::with_params(
-        "INSERT OR REPLACE INTO people (
+        // A real UPSERT, not INSERT OR REPLACE — `people` is now backed by the
+        // `people_fts` index (migration 022), and REPLACE would orphan an index
+        // entry on every re-cache: it fires no AFTER DELETE trigger without
+        // `recursive_triggers`, and reassigns the rowid that `content_rowid`
+        // refers to. Same defect as DR-110 fixed for `items`.
+        //
+        // TRACES: UR-065 | DR-110, DR-111
+        "INSERT INTO people (
            id, server_id, name, overview, primary_image_tag,
            premiere_date, end_date, synced_at
-        ) VALUES (?, ?, ?, ?, ?, ?, ?, CURRENT_TIMESTAMP)",
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, CURRENT_TIMESTAMP)
+        ON CONFLICT(id) DO UPDATE SET
+            server_id = excluded.server_id,
+            name = excluded.name,
+            overview = excluded.overview,
+            primary_image_tag = excluded.primary_image_tag,
+            premiere_date = excluded.premiere_date,
+            end_date = excluded.end_date,
+            synced_at = CURRENT_TIMESTAMP",
        vec![
            QueryParam::String(person.id),
            QueryParam::String(person.server_id),
@@ -2,7 +2,9 @@
 //!
 //! The sync queue stores mutations (favorites, playback progress, etc.)
 //! that need to be synced to the Jellyfin server when connectivity is restored.
-//! TRACES: UR-002, UR-017, UR-025 | DR-014
+//! Draining it lives in `sync_drain` (DR-131); this module is the storage and
+//! read side the UI lists from (DR-132).
+//! TRACES: UR-002, UR-017, UR-025 | DR-014, DR-131, DR-132

 use serde::{Deserialize, Serialize};
 use std::sync::Arc;
@@ -24,6 +26,12 @@ pub struct SyncQueueItem {
    pub retry_count: i32,
    pub created_at: Option<String>,
    pub error_message: Option<String>,
+    /// Cached title of the item the operation is about, when the catalog knows
+    /// it. Resolved here rather than by a per-row frontend fetch — the queue
+    /// list is otherwise a wall of opaque ids.
+    ///
+    /// TRACES: UR-025 | DR-132
+    pub item_name: Option<String>,
 }

 /// Queue a mutation for sync to server
@@ -74,20 +82,20 @@ pub async fn sync_get_pending(
        Arc::new(database.service())
    };

-    let sql = if let Some(l) = limit {
-        format!(
-            "SELECT id, user_id, operation, item_id, payload, status, retry_count, created_at, error_message
-             FROM sync_queue
-             WHERE user_id = ? AND status IN ('pending', 'failed')
-             ORDER BY created_at ASC
-             LIMIT {}",
-            l
-        )
-    } else {
-        "SELECT id, user_id, operation, item_id, payload, status, retry_count, created_at, error_message
-         FROM sync_queue
-         WHERE user_id = ? AND status IN ('pending', 'failed')
-         ORDER BY created_at ASC".to_string()
+    // The `items` join names the queued item where the catalog has it; a row for
+    // an item that was never cached still lists, with a null name.
+    // `abandoned` rows (DR-131 gave up on them) are excluded here for the same
+    // reason they are excluded from the count — they are no longer waiting.
+    const SELECT: &str = "SELECT q.id, q.user_id, q.operation, q.item_id, q.payload, q.status,
+                                 COALESCE(q.retry_count, 0), q.created_at, q.error_message, i.name
+                          FROM sync_queue q
+                          LEFT JOIN items i ON i.id = q.item_id
+                          WHERE q.user_id = ? AND q.status IN ('pending', 'failed')
+                          ORDER BY q.created_at ASC, q.id ASC";
+
+    let sql = match limit {
+        Some(l) => format!("{} LIMIT {}", SELECT, l),
+        None => SELECT.to_string(),
    };

    let query = Query::with_params(sql, vec![QueryParam::String(user_id)]);
@@ -104,6 +112,7 @@ pub async fn sync_get_pending(
                retry_count: row.get(6)?,
                created_at: row.get(7)?,
                error_message: row.get(8)?,
+                item_name: row.get(9)?,
            })
        })
        .await
@@ -256,6 +265,7 @@ mod tests {
            retry_count: 0,
            created_at: Some("2024-02-14T08:00:00Z".to_string()),
            error_message: None,
+            item_name: None,
        };

        // Should serialize successfully
@@ -280,6 +290,7 @@ mod tests {
            retry_count: 3,
            created_at: Some("2024-02-14T07:00:00Z".to_string()),
            error_message: Some("Connection timeout".to_string()),
+            item_name: None,
        };

        let json = serde_json::to_string(&item).unwrap();
@@ -300,6 +311,7 @@ mod tests {
            retry_count: 0,
            created_at: None,
            error_message: None,
+            item_name: None,
        };

        let json = serde_json::to_string(&item).unwrap();
@@ -323,6 +335,7 @@ mod tests {
                retry_count: 0,
                created_at: None,
                error_message: None,
+                item_name: None,
            };

            let json = serde_json::to_string(&item).unwrap();
@@ -363,6 +376,7 @@ mod tests {
            retry_count: 0,
            created_at: None,
            error_message: None,
+            item_name: None,
        };

        // Simulate retries
@@ -0,0 +1,838 @@
+//! Draining the offline mutation queue (`sync_queue`) to the server.
+//!
+//! `sync_queue` had producers but no consumer: `PlaybackReporter::queue_for_sync`
+//! inserts a row whenever a start/stop/mark-played cannot reach the server, and
+//! nothing ever pushed one. `sync_mark_processing`/`_completed`/`_failed` were
+//! registered commands with no callers, so the queue only grew — the offline
+//! banner's "N pending" climbed forever and the watch positions those rows stood
+//! for never reached Jellyfin.
+//!
+//! Same shape as the favourites drain (DR-120), and for the same reason: a drain
+//! started by a component dies with it, so it lives in Rust and hangs off the
+//! `connectivity:reconnected` transition the `ConnectivityMonitor` already emits.
+//!
+//! TRACES: UR-025, UR-002 | DR-131 | UT-122
+
+use std::sync::Arc;
+
+use async_trait::async_trait;
+use log::{debug, info, warn};
+use tauri::{Emitter, Listener, Manager};
+
+use crate::repository::types::RepoError;
+use crate::repository::MediaRepository;
+use crate::storage::db_service::{DatabaseService, Query, QueryParam, RusqliteService};
+
+/// How many times a row may fail before it stops being retried.
+///
+/// A row that can never succeed (a deleted item, an operation this build does
+/// not know how to push) must eventually leave the queue, or it re-creates the
+/// bug this module fixes: a count that only ever goes up.
+pub const MAX_SYNC_ATTEMPTS: i32 = 5;
+
+/// Emitted after a drain so open views can re-read the queue instead of waiting
+/// for the frontend's 10s poll.
+pub const SYNC_QUEUE_CHANGED_EVENT: &str = "sync-queue-changed";
+
+/// A queued mutation, resolved from its stored `operation` + JSON `payload`.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum QueuedOp {
+    PlaybackStart {
+        item_id: String,
+        position_ticks: i64,
+    },
+    /// Also where `update_progress` lands: replaying a mid-playback progress
+    /// report long after the fact would tell the server we are still playing.
+    /// What the row actually carries is a resume position, and "stopped at N"
+    /// is how that reaches Jellyfin's `UserData`.
+    PlaybackStopped {
+        item_id: String,
+        position_ticks: i64,
+    },
+    MarkPlayed {
+        item_id: String,
+    },
+    /// Legacy rows only — live favourite toggles drain via `user_data.pending_sync`
+    /// (DR-120). Supported so a row written by an older build still lands.
+    Favorite {
+        item_id: String,
+        is_favorite: bool,
+    },
+}
+
+/// Turn a stored row into something pushable.
+///
+/// Payload keys differ by producer: the Rust reporter writes `position_ticks`,
+/// while `syncService.queuePlaybackProgress` writes camelCase `positionMs`.
+/// Both are accepted rather than normalised at the producer, because rows
+/// already in users' databases were written by both.
+///
+/// TRACES: UR-025 | DR-131 | UT-122
+pub fn parse_queued_op(
+    operation: &str,
+    item_id: Option<&str>,
+    payload: Option<&str>,
+) -> Result<QueuedOp, String> {
+    let json: serde_json::Value = match payload {
+        Some(raw) if !raw.trim().is_empty() => {
+            serde_json::from_str(raw).map_err(|e| format!("Unreadable payload: {}", e))?
+        }
+        _ => serde_json::Value::Null,
+    };
+
+    let item_id = item_id
+        .filter(|id| !id.is_empty())
+        .ok_or_else(|| format!("Operation '{}' has no item id", operation))?
+        .to_string();
+
+    let ticks = || -> i64 {
+        if let Some(t) = json.get("position_ticks").and_then(|v| v.as_i64()) {
+            return t;
+        }
+        if let Some(ms) = json.get("positionMs").and_then(|v| v.as_i64()) {
+            return ms * 10_000; // ms → Jellyfin ticks (100ns)
+        }
+        0
+    };
+
+    match operation {
+        "report_playback_start" => Ok(QueuedOp::PlaybackStart {
+            item_id,
+            position_ticks: ticks(),
+        }),
+        "report_playback_stopped" | "update_progress" => Ok(QueuedOp::PlaybackStopped {
+            item_id,
+            position_ticks: ticks(),
+        }),
+        "mark_played" => Ok(QueuedOp::MarkPlayed { item_id }),
+        "mark_favorite" => Ok(QueuedOp::Favorite {
+            item_id,
+            is_favorite: true,
+        }),
+        "unmark_favorite" => Ok(QueuedOp::Favorite {
+            item_id,
+            is_favorite: false,
+        }),
+        other => Err(format!("Unsupported operation '{}'", other)),
+    }
+}
+
+/// The slice of the repository the drain needs — narrow so it can be doubled in
+/// a test without forty `unimplemented!()` methods.
+#[async_trait]
+pub trait SyncSink: Send + Sync {
+    async fn push(&self, op: &QueuedOp) -> Result<(), RepoError>;
+}
+
+#[async_trait]
+impl<T: MediaRepository + ?Sized> SyncSink for T {
+    async fn push(&self, op: &QueuedOp) -> Result<(), RepoError> {
+        match op {
+            QueuedOp::PlaybackStart {
+                item_id,
+                position_ticks,
+            } => self.report_playback_start(item_id, *position_ticks).await,
+            QueuedOp::PlaybackStopped {
+                item_id,
+                position_ticks,
+            } => self.report_playback_stopped(item_id, *position_ticks).await,
+            QueuedOp::MarkPlayed { item_id } => self.mark_played(item_id).await,
+            QueuedOp::Favorite {
+                item_id,
+                is_favorite,
+            } => {
+                if *is_favorite {
+                    self.mark_favorite(item_id).await
+                } else {
+                    self.unmark_favorite(item_id).await
+                }
+            }
+        }
+    }
+}
+
+/// What a drain did, for logging and for the frontend's "Sync now" button.
+#[derive(
+    Debug, Clone, Default, PartialEq, Eq, serde::Serialize, serde::Deserialize, specta::Type,
+)]
+#[serde(rename_all = "camelCase")]
+pub struct DrainReport {
+    /// Rows that reached the server and are now `completed`.
+    pub pushed: i32,
+    /// Rows that failed and will be retried on the next reconnect.
+    pub deferred: i32,
+    /// Rows that exhausted `MAX_SYNC_ATTEMPTS` and were given up on.
+    pub abandoned: i32,
+    /// Rows still waiting afterwards (what the badge counts).
+    pub remaining: i32,
+}
+
+/// Why a push failed, and whether the row should be charged an attempt for it.
+struct PushFailure {
+    reason: String,
+    /// The server could not be reached at all — retry later, free of charge.
+    transient: bool,
+}
+
+#[derive(Debug, Clone)]
+struct QueuedRow {
+    id: i64,
+    operation: String,
+    item_id: Option<String>,
+    payload: Option<String>,
+    retry_count: i32,
+}
+
+async fn read_queue(db: &Arc<RusqliteService>, user_id: &str) -> Result<Vec<QueuedRow>, String> {
+    db.query_many(
+        Query::with_params(
+            "SELECT id, operation, item_id, payload, COALESCE(retry_count, 0) \
+             FROM sync_queue \
+             WHERE user_id = ? AND status IN ('pending', 'failed') \
+             ORDER BY created_at ASC, id ASC",
+            vec![QueryParam::String(user_id.to_string())],
+        ),
+        |row| {
+            Ok(QueuedRow {
+                id: row.get(0)?,
+                operation: row.get(1)?,
+                item_id: row.get(2)?,
+                payload: row.get(3)?,
+                retry_count: row.get(4)?,
+            })
+        },
+    )
+    .await
+}
+
+async fn remaining_count(db: &Arc<RusqliteService>, user_id: &str) -> Result<i32, String> {
+    db.query_one(
+        Query::with_params(
+            "SELECT COUNT(*) FROM sync_queue WHERE user_id = ? AND status IN ('pending', 'failed')",
+            vec![QueryParam::String(user_id.to_string())],
+        ),
+        |row| row.get(0),
+    )
+    .await
+}
+
+/// Push every queued mutation for this user, oldest first.
+///
+/// Chronological order matters: a stale start replayed after a later stop would
+/// otherwise move the server's resume position backwards.
+///
+/// A row that fails keeps its place and is retried on the next reconnect, until
+/// `MAX_SYNC_ATTEMPTS` — after which it is abandoned, because a row nothing can
+/// ever push is exactly what turned this queue into a counter that only grew.
+///
+/// TRACES: UR-025, UR-002 | DR-131 | UT-122
+pub async fn drain_sync_queue(
+    db: &Arc<RusqliteService>,
+    sink: &dyn SyncSink,
+    user_id: &str,
+) -> Result<DrainReport, String> {
+    let queued = read_queue(db, user_id).await?;
+    if queued.is_empty() {
+        return Ok(DrainReport::default());
+    }
+
+    info!(
+        "[SyncQueue] Pushing {} operation(s) queued while offline",
+        queued.len()
+    );
+
+    let mut report = DrainReport::default();
+
+    for row in queued {
+        let outcome = match parse_queued_op(
+            &row.operation,
+            row.item_id.as_deref(),
+            row.payload.as_deref(),
+        ) {
+            Ok(op) => sink.push(&op).await.map_err(|e| PushFailure {
+                // An unreachable server is not the row's fault: burning its
+                // budget would abandon perfectly good rows just because the app
+                // was opened offline a few times.
+                transient: matches!(e, RepoError::Offline | RepoError::Network { .. }),
+                reason: e.to_string(),
+            }),
+            // An unreadable or unsupported row can never succeed, so it does
+            // burn attempts rather than being deleted outright — the panel shows
+            // the reason until it is abandoned.
+            Err(reason) => Err(PushFailure {
+                reason,
+                transient: false,
+            }),
+        };
+
+        match outcome {
+            Ok(()) => {
+                mark_completed(db, row.id).await?;
+                report.pushed += 1;
+            }
+            Err(failure) if failure.transient => {
+                mark_deferred(db, row.id, &failure.reason).await?;
+                debug!(
+                    "[SyncQueue] Server unreachable, {} stays queued: {}",
+                    row.operation, failure.reason
+                );
+                report.deferred += 1;
+            }
+            Err(failure) => {
+                let attempts = row.retry_count + 1;
+                let give_up = attempts >= MAX_SYNC_ATTEMPTS;
+                mark_failed(db, row.id, attempts, give_up, &failure.reason).await?;
+                if give_up {
+                    warn!(
+                        "[SyncQueue] Giving up on {} after {} attempts: {}",
+                        row.operation, attempts, failure.reason
+                    );
+                    report.abandoned += 1;
+                } else {
+                    debug!(
+                        "[SyncQueue] Deferring {} (attempt {}): {}",
+                        row.operation, attempts, failure.reason
+                    );
+                    report.deferred += 1;
+                }
+            }
+        }
+    }
+
+    report.remaining = remaining_count(db, user_id).await?;
+    info!(
+        "[SyncQueue] Drain finished: {} pushed, {} deferred, {} abandoned, {} remaining",
+        report.pushed, report.deferred, report.abandoned, report.remaining
+    );
+
+    Ok(report)
+}
+
+async fn mark_completed(db: &Arc<RusqliteService>, id: i64) -> Result<(), String> {
+    db.execute(Query::with_params(
+        "UPDATE sync_queue \
+         SET status = 'completed', processed_at = CURRENT_TIMESTAMP, error_message = NULL \
+         WHERE id = ?",
+        vec![QueryParam::Int64(id)],
+    ))
+    .await?;
+    Ok(())
+}
+
+/// Put a row back in the queue untouched apart from its error note — used when
+/// the server was simply unreachable.
+async fn mark_deferred(db: &Arc<RusqliteService>, id: i64, reason: &str) -> Result<(), String> {
+    db.execute(Query::with_params(
+        "UPDATE sync_queue SET status = 'pending', error_message = ? WHERE id = ?",
+        vec![
+            QueryParam::String(reason.to_string()),
+            QueryParam::Int64(id),
+        ],
+    ))
+    .await?;
+    Ok(())
+}
+
+async fn mark_failed(
+    db: &Arc<RusqliteService>,
+    id: i64,
+    attempts: i32,
+    give_up: bool,
+    reason: &str,
+) -> Result<(), String> {
+    db.execute(Query::with_params(
+        "UPDATE sync_queue \
+         SET status = ?, retry_count = ?, error_message = ?, processed_at = CURRENT_TIMESTAMP \
+         WHERE id = ?",
+        vec![
+            QueryParam::String(if give_up { "abandoned" } else { "failed" }.to_string()),
+            QueryParam::Int(attempts),
+            QueryParam::String(reason.to_string()),
+            QueryParam::Int64(id),
+        ],
+    ))
+    .await?;
+    Ok(())
+}
+
+/// Drain on every offline→online transition.
+///
+/// TRACES: UR-025 | DR-131
+pub fn spawn_sync_queue_drain(app: tauri::AppHandle) {
+    let handle = app.clone();
+    app.listen("connectivity:reconnected", move |_event| {
+        let app = handle.clone();
+        tauri::async_runtime::spawn(async move {
+            if let Err(e) = run_drain(&app).await {
+                warn!("[SyncQueue] Drain skipped: {}", e);
+            }
+        });
+    });
+}
+
+/// Resolve app state and drain. Shared by the reconnect hook and the manual
+/// "Sync now" command.
+pub async fn run_drain(app: &tauri::AppHandle) -> Result<DrainReport, String> {
+    let db_service: Arc<RusqliteService> = {
+        let db = app.state::<crate::commands::storage::DatabaseWrapper>();
+        let database = db.0.lock().map_err(|e| e.to_string())?;
+        Arc::new(database.service())
+    };
+
+    let (repo, user_id) = {
+        let manager = app.state::<crate::commands::repository::RepositoryManagerWrapper>();
+        let handles = manager.0.handles();
+        let Some(handle) = handles.first() else {
+            // Not signed in — nothing to push on behalf of.
+            return Ok(DrainReport::default());
+        };
+        let repo = manager.0.get(handle).ok_or("Repository not found")?;
+        let user_id = repo.user_id().to_string();
+        (repo, user_id)
+    };
+
+    let report = drain_sync_queue(&db_service, repo.as_ref(), &user_id).await?;
+
+    if report.pushed > 0 || report.abandoned > 0 {
+        if let Err(e) = app.emit(SYNC_QUEUE_CHANGED_EVENT, &report) {
+            warn!("[SyncQueue] Failed to emit change event: {}", e);
+        }
+    }
+
+    Ok(report)
+}
+
+/// Push the queue now, on the user's say-so, instead of waiting for a reconnect.
+///
+/// TRACES: UR-025 | DR-132
+#[tauri::command]
+#[specta::specta]
+pub async fn sync_process_pending(app: tauri::AppHandle) -> Result<DrainReport, String> {
+    run_drain(&app).await
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use rusqlite::Connection;
+    use std::sync::Mutex;
+
+    /// Records what the server was asked to do, and can be told to fail.
+    struct RecordingSink {
+        calls: Mutex<Vec<QueuedOp>>,
+        fail_with: Option<RepoError>,
+    }
+
+    impl RecordingSink {
+        fn new() -> Self {
+            Self {
+                calls: Mutex::new(Vec::new()),
+                fail_with: None,
+            }
+        }
+
+        /// The server is there and refuses the operation — the row's own fault.
+        fn always_rejecting() -> Self {
+            Self {
+                calls: Mutex::new(Vec::new()),
+                fail_with: Some(RepoError::Server {
+                    message: "HTTP 400".to_string(),
+                }),
+            }
+        }
+
+        /// The server cannot be reached at all — nothing to do with the row.
+        fn unreachable() -> Self {
+            Self {
+                calls: Mutex::new(Vec::new()),
+                fail_with: Some(RepoError::Offline),
+            }
+        }
+
+        fn calls(&self) -> Vec<QueuedOp> {
+            self.calls.lock().unwrap().clone()
+        }
+    }
+
+    #[async_trait]
+    impl SyncSink for RecordingSink {
+        async fn push(&self, op: &QueuedOp) -> Result<(), RepoError> {
+            if let Some(err) = &self.fail_with {
+                return Err(err.clone());
+            }
+            self.calls.lock().unwrap().push(op.clone());
+            Ok(())
+        }
+    }
+
+    fn test_db() -> Arc<RusqliteService> {
+        let conn = Connection::open_in_memory().unwrap();
+        conn.execute_batch(
+            r#"
+            CREATE TABLE sync_queue (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                user_id TEXT NOT NULL,
+                operation TEXT NOT NULL,
+                item_id TEXT,
+                payload TEXT,
+                status TEXT DEFAULT 'pending',
+                retry_count INTEGER DEFAULT 0,
+                created_at TEXT DEFAULT CURRENT_TIMESTAMP,
+                processed_at TEXT,
+                error_message TEXT
+            );
+            "#,
+        )
+        .unwrap();
+        Arc::new(RusqliteService::new(Arc::new(Mutex::new(conn))))
+    }
+
+    /// (user, operation, item_id, payload, status, retry_count, created_at)
+    type Seed<'a> = (
+        &'a str,
+        &'a str,
+        &'a str,
+        Option<&'a str>,
+        &'a str,
+        i32,
+        &'a str,
+    );
+
+    async fn seed(db: &Arc<RusqliteService>, rows: &[Seed<'_>]) {
+        for (user, op, item, payload, status, retries, created) in rows {
+            db.execute(Query::with_params(
+                "INSERT INTO sync_queue (user_id, operation, item_id, payload, status, retry_count, created_at) \
+                 VALUES (?, ?, ?, ?, ?, ?, ?)",
+                vec![
+                    QueryParam::String(user.to_string()),
+                    QueryParam::String(op.to_string()),
+                    QueryParam::String(item.to_string()),
+                    payload
+                        .map(|p| QueryParam::String(p.to_string()))
+                        .unwrap_or(QueryParam::Null),
+                    QueryParam::String(status.to_string()),
+                    QueryParam::Int(*retries),
+                    QueryParam::String(created.to_string()),
+                ],
+            ))
+            .await
+            .unwrap();
+        }
+    }
+
+    async fn row_state(db: &Arc<RusqliteService>, item_id: &str) -> (String, i32) {
+        db.query_one(
+            Query::with_params(
+                "SELECT status, COALESCE(retry_count, 0) FROM sync_queue WHERE item_id = ?",
+                vec![QueryParam::String(item_id.to_string())],
+            ),
+            |row| Ok((row.get::<_, String>(0)?, row.get::<_, i32>(1)?)),
+        )
+        .await
+        .unwrap()
+    }
+
+    /// UT-122 — the bug itself: rows queued while offline reach the server on
+    /// reconnect and stop counting towards the offline banner's badge.
+    ///
+    /// TRACES: UR-025 | DR-131 | UT-122
+    #[tokio::test]
+    async fn test_drain_pushes_queued_operations_and_clears_the_queue() {
+        let db = test_db();
+        seed(
+            &db,
+            &[
+                (
+                    "u1",
+                    "report_playback_start",
+                    "ep1",
+                    Some(r#"{"position_ticks": 100}"#),
+                    "pending",
+                    0,
+                    "2026-08-01T10:00:00Z",
+                ),
+                (
+                    "u1",
+                    "report_playback_stopped",
+                    "ep2",
+                    Some(r#"{"position_ticks": 5000}"#),
+                    "pending",
+                    0,
+                    "2026-08-01T10:01:00Z",
+                ),
+                (
+                    "u1",
+                    "mark_played",
+                    "ep3",
+                    None,
+                    "pending",
+                    0,
+                    "2026-08-01T10:02:00Z",
+                ),
+            ],
+        )
+        .await;
+
+        let sink = RecordingSink::new();
+        let report = drain_sync_queue(&db, &sink, "u1").await.unwrap();
+
+        assert_eq!(
+            sink.calls(),
+            vec![
+                QueuedOp::PlaybackStart {
+                    item_id: "ep1".to_string(),
+                    position_ticks: 100
+                },
+                QueuedOp::PlaybackStopped {
+                    item_id: "ep2".to_string(),
+                    position_ticks: 5000
+                },
+                QueuedOp::MarkPlayed {
+                    item_id: "ep3".to_string()
+                },
+            ],
+            "every queued operation pushes, oldest first"
+        );
+        assert_eq!(report.pushed, 3);
+        assert_eq!(report.remaining, 0, "the badge must reach zero");
+        assert_eq!(row_state(&db, "ep1").await.0, "completed");
+    }
+
+    /// A push that fails stays queued for the next reconnect rather than being
+    /// dropped.
+    ///
+    /// TRACES: UR-025 | DR-131 | UT-122
+    #[tokio::test]
+    async fn test_drain_defers_failed_pushes() {
+        let db = test_db();
+        seed(
+            &db,
+            &[(
+                "u1",
+                "report_playback_stopped",
+                "ep1",
+                Some(r#"{"position_ticks": 42}"#),
+                "pending",
+                0,
+                "2026-08-01T10:00:00Z",
+            )],
+        )
+        .await;
+
+        let report = drain_sync_queue(&db, &RecordingSink::always_rejecting(), "u1")
+            .await
+            .unwrap();
+
+        assert_eq!(report.deferred, 1);
+        assert_eq!(report.remaining, 1);
+        assert_eq!(row_state(&db, "ep1").await, ("failed".to_string(), 1));
+    }
+
+    /// An unreachable server does not charge the row an attempt — otherwise
+    /// opening the app offline a few times abandons perfectly good rows.
+    ///
+    /// TRACES: UR-025 | DR-131 | UT-122
+    #[tokio::test]
+    async fn test_unreachable_server_does_not_burn_the_retry_budget() {
+        let db = test_db();
+        seed(
+            &db,
+            &[(
+                "u1",
+                "mark_played",
+                "ep1",
+                None,
+                "pending",
+                MAX_SYNC_ATTEMPTS - 1,
+                "2026-08-01T10:00:00Z",
+            )],
+        )
+        .await;
+
+        let report = drain_sync_queue(&db, &RecordingSink::unreachable(), "u1")
+            .await
+            .unwrap();
+
+        assert_eq!(report.deferred, 1);
+        assert_eq!(report.abandoned, 0);
+        assert_eq!(
+            row_state(&db, "ep1").await,
+            ("pending".to_string(), MAX_SYNC_ATTEMPTS - 1),
+            "still queued, with its budget intact"
+        );
+    }
+
+    /// A row that can never succeed must eventually leave the queue, or the
+    /// count climbs forever — which is the bug this module exists to fix.
+    ///
+    /// TRACES: UR-025 | DR-131 | UT-122
+    #[tokio::test]
+    async fn test_drain_abandons_a_row_after_max_attempts() {
+        let db = test_db();
+        seed(
+            &db,
+            &[(
+                "u1",
+                "report_playback_stopped",
+                "doomed",
+                Some(r#"{"position_ticks": 1}"#),
+                "failed",
+                MAX_SYNC_ATTEMPTS - 1,
+                "2026-08-01T10:00:00Z",
+            )],
+        )
+        .await;
+
+        let report = drain_sync_queue(&db, &RecordingSink::always_rejecting(), "u1")
+            .await
+            .unwrap();
+
+        assert_eq!(report.abandoned, 1);
+        assert_eq!(report.remaining, 0, "an abandoned row stops being counted");
+        assert_eq!(row_state(&db, "doomed").await.0, "abandoned");
+    }
+
+    /// An operation this build cannot push does not wedge the queue behind it.
+    ///
+    /// TRACES: UR-025 | DR-131 | UT-122
+    #[tokio::test]
+    async fn test_unsupported_operation_records_a_reason_and_lets_others_through() {
+        let db = test_db();
+        seed(
+            &db,
+            &[
+                (
+                    "u1",
+                    "playlist_reorder_item",
+                    "pl1",
+                    None,
+                    "pending",
+                    0,
+                    "2026-08-01T10:00:00Z",
+                ),
+                (
+                    "u1",
+                    "mark_played",
+                    "ep1",
+                    None,
+                    "pending",
+                    0,
+                    "2026-08-01T10:01:00Z",
+                ),
+            ],
+        )
+        .await;
+
+        let sink = RecordingSink::new();
+        let report = drain_sync_queue(&db, &sink, "u1").await.unwrap();
+
+        assert_eq!(
+            sink.calls(),
+            vec![QueuedOp::MarkPlayed {
+                item_id: "ep1".to_string()
+            }],
+            "the unsupported row must not block the ones behind it"
+        );
+        assert_eq!(report.pushed, 1);
+        assert_eq!(report.deferred, 1);
+        assert_eq!(row_state(&db, "pl1").await, ("failed".to_string(), 1));
+    }
+
+    /// Another user's queued changes are not pushed with this user's token.
+    ///
+    /// TRACES: UR-025 | DR-131 | UT-122
+    #[tokio::test]
+    async fn test_drain_only_touches_the_given_user() {
+        let db = test_db();
+        seed(
+            &db,
+            &[
+                (
+                    "u1",
+                    "mark_played",
+                    "mine",
+                    None,
+                    "pending",
+                    0,
+                    "2026-08-01T10:00:00Z",
+                ),
+                (
+                    "u2",
+                    "mark_played",
+                    "theirs",
+                    None,
+                    "pending",
+                    0,
+                    "2026-08-01T10:00:00Z",
+                ),
+            ],
+        )
+        .await;
+
+        let sink = RecordingSink::new();
+        drain_sync_queue(&db, &sink, "u1").await.unwrap();
+
+        assert_eq!(
+            sink.calls(),
+            vec![QueuedOp::MarkPlayed {
+                item_id: "mine".to_string()
+            }]
+        );
+        assert_eq!(row_state(&db, "theirs").await.0, "pending");
+    }
+
+    /// Nothing queued means no server calls at all — a reconnect must not
+    /// generate traffic just because it happened.
+    ///
+    /// TRACES: UR-025 | DR-131 | UT-122
+    #[tokio::test]
+    async fn test_drain_is_a_noop_when_the_queue_is_empty() {
+        let db = test_db();
+        let sink = RecordingSink::new();
+
+        let report = drain_sync_queue(&db, &sink, "u1").await.unwrap();
+
+        assert_eq!(report, DrainReport::default());
+        assert!(sink.calls().is_empty());
+    }
+
+    /// Both payload dialects parse: `position_ticks` from the Rust reporter and
+    /// camelCase `positionMs` from the frontend's queue helper.
+    ///
+    /// TRACES: UR-025 | DR-131 | UT-122
+    #[test]
+    fn test_parse_accepts_both_payload_dialects() {
+        assert_eq!(
+            parse_queued_op(
+                "report_playback_stopped",
+                Some("ep1"),
+                Some(r#"{"position_ticks": 1234}"#)
+            )
+            .unwrap(),
+            QueuedOp::PlaybackStopped {
+                item_id: "ep1".to_string(),
+                position_ticks: 1234
+            }
+        );
+
+        assert_eq!(
+            parse_queued_op("update_progress", Some("ep1"), Some(r#"{"positionMs": 5}"#)).unwrap(),
+            QueuedOp::PlaybackStopped {
+                item_id: "ep1".to_string(),
+                position_ticks: 50_000
+            },
+            "milliseconds convert to ticks"
+        );
+
+        assert_eq!(
+            parse_queued_op("mark_played", Some("ep1"), None).unwrap(),
+            QueuedOp::MarkPlayed {
+                item_id: "ep1".to_string()
+            },
+            "a payload-less operation is not an error"
+        );
+
+        assert!(parse_queued_op("mark_played", None, None).is_err());
+        assert!(parse_queued_op("teleport", Some("ep1"), None).is_err());
+    }
+}
@@ -26,6 +26,12 @@ pub struct CacheConfig {
    pub storage_limit: u64,
    /// Only cache on WiFi
    pub wifi_only: bool,
+    /// How long a temporary (`download_source = 'auto'`) download lives before
+    /// it is reclaimed, in hours. 0 disables expiry, leaving space pressure as
+    /// the only reclaim trigger.
+    ///
+    /// TRACES: UR-071 | DR-127
+    pub temporary_ttl_hours: u64,
 }

 impl Default for CacheConfig {
@@ -37,6 +43,10 @@ impl Default for CacheConfig {
            album_affinity_threshold: 3,
            storage_limit: 10 * 1024 * 1024 * 1024, // 10GB
            wifi_only: false,                       // Allow preloading on any connection by default
+            // A week: long enough that re-watching over a weekend still hits
+            // disk, short enough that a one-off play does not hold space
+            // indefinitely.
+            temporary_ttl_hours: 24 * 7,
        }
    }
 }
@@ -183,7 +193,92 @@ impl SmartCache {
        current_size + new_size <= storage_limit
    }

-    /// Evict least recently used items to make space (async version)
+    /// Reclaim temporary downloads whose life limit has passed.
+    ///
+    /// The time-based half of the temporary tier (DR-127); [`evict_lru_async`]
+    /// is the space-pressure half. A row is reclaimed by whichever fires first.
+    ///
+    /// Scoped to `download_source = 'auto'` for the same reason eviction is: a
+    /// `'user'` row is someone's own download and has no expiry. `COALESCE`
+    /// guards rows predating migration 012, whose source is NULL and whose
+    /// provenance must therefore be treated as the user's.
+    ///
+    /// Expiry is normally *derived* — `completed_at` plus the configured TTL —
+    /// rather than stamped at completion. That means a TTL change applies to
+    /// entries already on disk instead of only to future ones, and entries
+    /// predating the column expire without a backfill. `expires_at` is honoured
+    /// as a per-row override when something sets it.
+    ///
+    /// `now` is passed in rather than read from the clock so the policy is
+    /// testable without sleeping. Both sides go through SQLite's `datetime()`
+    /// because `completed_at` is written as `CURRENT_TIMESTAMP`
+    /// (`YYYY-MM-DD HH:MM:SS`) while callers pass RFC-3339 (`…T…+00:00`) — a raw
+    /// string comparison between the two formats is wrong, since `' ' < 'T'`.
+    ///
+    /// Returns the number of entries reclaimed.
+    ///
+    /// TRACES: UR-071 | DR-127 | UT-120
+    pub async fn reclaim_expired_async<S: DatabaseService>(
+        &self,
+        db_service: &Arc<S>,
+        user_id: &str,
+        now: &str,
+    ) -> Result<usize, String> {
+        let ttl_hours = {
+            let config = self.config.lock().map_err(|e| e.to_string())?;
+            config.temporary_ttl_hours
+        };
+        // 0 disables time-based reclaim; space pressure remains the only trigger.
+        if ttl_hours == 0 {
+            return Ok(0);
+        }
+
+        let expired: Vec<(i64, String)> = db_service
+            .query_many(
+                Query::with_params(
+                    "SELECT id, file_path FROM downloads
+                      WHERE user_id = ?
+                        AND COALESCE(download_source, 'user') = 'auto'
+                        AND status = 'completed'
+                        AND datetime(
+                              COALESCE(expires_at, datetime(completed_at, '+' || ? || ' hours'))
+                            ) < datetime(?)",
+                    vec![
+                        QueryParam::String(user_id.to_string()),
+                        QueryParam::String(ttl_hours.to_string()),
+                        QueryParam::String(now.to_string()),
+                    ],
+                ),
+                |row| Ok((row.get(0)?, row.get(1)?)),
+            )
+            .await
+            .map_err(|e| e.to_string())?;
+
+        let mut reclaimed = 0usize;
+        for (id, file_path) in expired {
+            // Best-effort on the file: a missing one still needs its row gone,
+            // or the sweep retries it forever.
+            let _ = std::fs::remove_file(&file_path);
+            db_service
+                .execute(Query::with_params(
+                    "DELETE FROM downloads WHERE id = ?",
+                    vec![QueryParam::Int64(id)],
+                ))
+                .await
+                .map_err(|e| e.to_string())?;
+            reclaimed += 1;
+        }
+
+        if reclaimed > 0 {
+            info!("[SmartCache] Reclaimed {} expired entries", reclaimed);
+        }
+        Ok(reclaimed)
+    }
+
+    /// Evict least recently used items to make space (async version).
+    ///
+    /// The space-pressure half of the temporary tier; [`reclaim_expired_async`]
+    /// is the time-based half.
    pub async fn evict_lru_async<S: DatabaseService>(
        &self,
        db_service: &Arc<S>,
@@ -207,10 +302,26 @@ impl SmartCache {
        let to_free = (current_size + space_needed) - limit;
        let mut freed: u64 = 0;

-        // Get downloads ordered by last access (oldest first)
+        // Only the *temporary* tier is evictable. `download_source = 'auto'` is
+        // precache — the cache put it there, the cache may reclaim it. A 'user'
+        // row is a download someone explicitly asked for; deleting it to make
+        // room for a predictive fetch is data loss, and because the old query
+        // ordered purely by `completed_at ASC` it took the oldest — typically
+        // exactly the film saved for a flight.
+        //
+        // COALESCE, not `= 'auto'` alone: migration 012 added the column with a
+        // 'user' default, but rows predating it can be NULL, and an unknown
+        // provenance must be treated as the user's, never as disposable.
+        //
+        // Freeing less than requested is the correct outcome when only user
+        // downloads remain — the caller surfaces "unable to free enough space"
+        // rather than silently deleting them.
+        //
+        // TRACES: UR-071 | DR-126 | UT-108
        let query = Query::with_params(
            "SELECT id, file_size, file_path FROM downloads
             WHERE user_id = ? AND status = 'completed'
+               AND COALESCE(download_source, 'user') = 'auto'
             ORDER BY completed_at ASC",
            vec![QueryParam::String(user_id.to_string())],
        );
@@ -304,6 +415,205 @@ mod tests {
        assert!(cache.should_precache_queue());
    }

+    /// Expiry reclaims only temporary entries that are actually past their life
+    /// limit — never a user's download (which has no expiry), and never a
+    /// temporary entry still within its life.
+    ///
+    /// TRACES: UR-071 | DR-127 | UT-120
+    #[tokio::test]
+    async fn test_reclaim_expired_only_takes_expired_temporary_entries() {
+        use crate::storage::db_service::{DatabaseService, RusqliteService};
+        use rusqlite::Connection;
+        use std::sync::{Arc, Mutex};
+
+        let conn = Connection::open_in_memory().unwrap();
+        conn.execute(
+            "CREATE TABLE downloads (
+                id INTEGER PRIMARY KEY,
+                user_id TEXT,
+                status TEXT,
+                file_size INTEGER,
+                file_path TEXT,
+                completed_at TEXT,
+                download_source TEXT DEFAULT 'user',
+                expires_at TEXT
+            )",
+            [],
+        )
+        .unwrap();
+
+        // `completed_at` is in SQLite's CURRENT_TIMESTAMP format (space, not
+        // 'T'), deliberately: the query has to compare it against an RFC-3339
+        // "now" and must not do so as raw strings.
+        for (path, source, completed, expires) in [
+            // Completed long ago, no override => derived expiry has passed.
+            ("/tmp/jt-expired.mp4", "auto", "2026-01-01 00:00:00", None),
+            // Completed yesterday => still inside the 7-day default TTL.
+            ("/tmp/jt-fresh.mp4", "auto", "2026-05-31 00:00:00", None),
+            // Old, but an explicit override keeps it alive.
+            (
+                "/tmp/jt-override.mp4",
+                "auto",
+                "2026-01-01 00:00:00",
+                Some("2026-12-01T00:00:00+00:00"),
+            ),
+            // A user download must never carry an expiry, but assert the sweep
+            // ignores it even if one were somehow set.
+            (
+                "/tmp/jt-user.mp4",
+                "user",
+                "2026-01-01 00:00:00",
+                Some("2026-01-01T00:00:00+00:00"),
+            ),
+            (
+                "/tmp/jt-user-noexp.mp4",
+                "user",
+                "2026-01-01 00:00:00",
+                None,
+            ),
+        ] {
+            conn.execute(
+                "INSERT INTO downloads (user_id, status, file_size, file_path, download_source, completed_at, expires_at)
+                 VALUES ('user1', 'completed', 10, ?1, ?2, ?3, ?4)",
+                rusqlite::params![path, source, completed, expires],
+            )
+            .unwrap();
+        }
+
+        let conn_arc = Arc::new(Mutex::new(conn));
+        let db_service = Arc::new(RusqliteService::new(conn_arc.clone()));
+        let cache = SmartCache::new(CacheConfig::default());
+
+        let reclaimed = cache
+            .reclaim_expired_async(&db_service, "user1", "2026-06-01T00:00:00+00:00")
+            .await
+            .unwrap();
+        assert_eq!(
+            reclaimed, 1,
+            "only the expired temporary entry is reclaimed"
+        );
+
+        let surviving: Vec<String> = {
+            let guard = conn_arc.lock_safe();
+            let mut stmt = guard
+                .prepare("SELECT file_path FROM downloads ORDER BY id")
+                .unwrap();
+            let rows = stmt
+                .query_map([], |row| row.get::<_, String>(0))
+                .unwrap()
+                .map(|r| r.unwrap())
+                .collect();
+            rows
+        };
+        assert_eq!(
+            surviving,
+            vec![
+                "/tmp/jt-fresh.mp4".to_string(),
+                "/tmp/jt-override.mp4".to_string(),
+                "/tmp/jt-user.mp4".to_string(),
+                "/tmp/jt-user-noexp.mp4".to_string(),
+            ],
+            "entries within their life, those with a later override, and every user download must survive"
+        );
+
+        // TTL of 0 disables time-based reclaim entirely.
+        let cache_no_ttl = SmartCache::new(CacheConfig {
+            temporary_ttl_hours: 0,
+            ..Default::default()
+        });
+        assert_eq!(
+            cache_no_ttl
+                .reclaim_expired_async(&db_service, "user1", "2027-01-01T00:00:00+00:00")
+                .await
+                .unwrap(),
+            0,
+            "a zero TTL leaves space pressure as the only reclaim trigger"
+        );
+    }
+
+    /// Eviction must only reclaim *temporary* (`download_source = 'auto'`)
+    /// downloads — the precache tier. A download the user explicitly asked for
+    /// is their file: it may be deleted by them, never by the cache making room
+    /// for a predictive fetch.
+    ///
+    /// Before the fix, `evict_lru_async` selected every completed row ordered by
+    /// `completed_at ASC` with no source filter, so hitting the storage limit
+    /// deleted the *oldest* download — typically the film someone downloaded for
+    /// a flight — in favour of a newer auto-precached track.
+    ///
+    /// TRACES: UR-071 | DR-126 | UT-108
+    #[tokio::test]
+    async fn test_evict_lru_never_deletes_user_downloads() {
+        use crate::storage::db_service::RusqliteService;
+        use rusqlite::Connection;
+        use std::sync::{Arc, Mutex};
+
+        let conn = Connection::open_in_memory().unwrap();
+        conn.execute(
+            "CREATE TABLE downloads (
+                id INTEGER PRIMARY KEY,
+                user_id TEXT,
+                status TEXT,
+                file_size INTEGER,
+                file_path TEXT,
+                completed_at TEXT,
+                download_source TEXT DEFAULT 'user'
+            )",
+            [],
+        )
+        .unwrap();
+
+        // The user's own download is the OLDEST, so a purely time-ordered
+        // eviction would take it first.
+        conn.execute(
+            "INSERT INTO downloads (user_id, status, file_size, file_path, completed_at, download_source)
+             VALUES ('user1', 'completed', 600, '/tmp/jellytau-test-user.mp4', '2026-01-01', 'user')",
+            [],
+        )
+        .unwrap();
+        // A newer, auto-precached item.
+        conn.execute(
+            "INSERT INTO downloads (user_id, status, file_size, file_path, completed_at, download_source)
+             VALUES ('user1', 'completed', 600, '/tmp/jellytau-test-auto.mp4', '2026-06-01', 'auto')",
+            [],
+        )
+        .unwrap();
+
+        let conn_arc = Arc::new(Mutex::new(conn));
+        let db_service = Arc::new(RusqliteService::new(conn_arc.clone()));
+
+        let cache = SmartCache::new(CacheConfig {
+            storage_limit: 1000,
+            ..Default::default()
+        });
+
+        // 1200 bytes held against a 1000 limit: eviction must free something.
+        let freed = cache
+            .evict_lru_async(&db_service, "user1", 0)
+            .await
+            .unwrap();
+        assert!(freed > 0, "eviction should have reclaimed the auto entry");
+
+        let surviving: Vec<String> = {
+            let guard = conn_arc.lock_safe();
+            let mut stmt = guard
+                .prepare("SELECT download_source FROM downloads ORDER BY id")
+                .unwrap();
+            let rows = stmt
+                .query_map([], |row| row.get::<_, String>(0))
+                .unwrap()
+                .map(|r| r.unwrap())
+                .collect();
+            rows
+        };
+
+        assert_eq!(
+            surviving,
+            vec!["user".to_string()],
+            "the user's own download must survive; only the 'auto' entry is evictable"
+        );
+    }
+
    #[tokio::test]
    async fn test_storage_limit_check() {
        use crate::storage::db_service::RusqliteService;
@@ -5,6 +5,7 @@ mod credentials;
 mod domain;
 mod download;
 mod jellyfin;
+mod media_server;
 mod playback_mode;
 mod playback_reporting;
 mod player;
@@ -85,6 +86,7 @@ use commands::{
    lms_unsync_player,
    mark_download_completed,
    mark_download_failed,
+    media_local_url,
    offline_get_items,
    offline_is_available,
    offline_search,
@@ -128,6 +130,8 @@ use commands::{
    player_get_sleep_timer,
    player_get_status,
    player_get_video_settings,
+    // Preload commands
+    player_local_media_path,
    player_move_in_queue,
    player_next,
    player_on_playback_ended,
@@ -138,9 +142,9 @@ use commands::{
    player_play_next_episode,
    player_play_queue,
    player_play_tracks,
-    // Preload commands
    player_preload_upcoming,
    player_previous,
+    player_recover_stream,
    player_remove_from_queue,
    player_report_media_loaded,
    player_report_position,
@@ -187,6 +191,7 @@ use commands::{
    repository_get_download_disk_usage,
    repository_get_downloaded_items,
    repository_get_downloaded_libraries,
+    repository_get_favorites,
    repository_get_genres,
    repository_get_image_url,
    repository_get_item,
@@ -270,6 +275,7 @@ use commands::{
    sync_mark_completed,
    sync_mark_failed,
    sync_mark_processing,
+    sync_process_pending,
    // Sync queue commands
    sync_queue_mutation,
    thumbnail_clear_cache,
@@ -696,10 +702,12 @@ fn specta_builder() -> Builder<tauri::Wry> {
            player_cancel_autoplay_countdown,
            player_play_next_episode,
            player_on_playback_ended,
+            player_recover_stream,
            player_report_state,
            player_report_position,
            player_report_media_loaded,
            // Preload commands
+            player_local_media_path,
            player_preload_upcoming,
            player_set_cache_config,
            player_get_cache_config,
@@ -801,6 +809,7 @@ fn specta_builder() -> Builder<tauri::Wry> {
            get_download_storage_stats,
            mark_download_completed,
            mark_download_failed,
+            media_local_url,
            start_download,
            enqueue_download,
            enqueue_video_downloads,
@@ -841,6 +850,7 @@ fn specta_builder() -> Builder<tauri::Wry> {
            sync_mark_completed,
            sync_mark_failed,
            sync_get_pending_count,
+            sync_process_pending,
            sync_cleanup_completed,
            sync_clear_user,
            // Thumbnail cache and image commands
@@ -893,6 +903,7 @@ fn specta_builder() -> Builder<tauri::Wry> {
            repository_get_image_url,
            repository_mark_favorite,
            repository_unmark_favorite,
+            repository_get_favorites,
            repository_get_person,
            repository_get_items_by_person,
            repository_get_similar_items,
@@ -995,6 +1006,16 @@ fn set_env_if_unset(key: &str, value: &str) {
    }
 }

+/// Downloaded media and cached thumbnails are handed to the webview as
+/// `http://asset.localhost/…` URLs by `convertFileSrc`. Tauri only answers that
+/// origin when the `protocol-asset` cargo feature is compiled in *and*
+/// `app.security.assetProtocol.enable` is set in `tauri.conf.json`, which also
+/// scopes it to `$APPDATA/**` — the storage root holding the database,
+/// `downloads/` and the thumbnail cache. Both are required together: with either
+/// missing the URL resolves to nothing and the webview reports
+/// `NETWORK_NO_SOURCE`, which is how offline video came to fail silently.
+///
+/// TRACES: UR-071 | DR-134
 #[cfg_attr(mobile, tauri::mobile_entry_point)]
 pub fn run() {
    // Initialize logger
@@ -1222,6 +1243,22 @@ pub fn run() {
            let smart_cache_wrapper = SmartCacheWrapper(Mutex::new(smart_cache));
            app.manage(smart_cache_wrapper);

+            // Serve downloaded media over loopback HTTP. The webview cannot
+            // stream a large file through the asset protocol (see media_server),
+            // so local playback resolves its URL from here instead.
+            // TRACES: UR-071 | DR-137
+            info!("[INIT] Starting local media server...");
+            let media_server = match media_server::start(app_data_dir.clone()) {
+                Ok(s) => Some(s),
+                Err(e) => {
+                    // Not fatal: streaming still works, and the command reports
+                    // a clear error if local playback is attempted.
+                    error!("[INIT ERROR] Local media server failed to start: {}", e);
+                    None
+                }
+            };
+            app.manage(media_server::MediaServerWrapper(media_server));
+
            // Initialize download manager
            info!("[INIT] Initializing download manager...");
            let download_dir = app_data_dir.join("downloads");
@@ -1288,6 +1325,28 @@ pub fn run() {
            let playback_reporter_wrapper = PlaybackReporterWrapper(playback_reporter.clone());
            app.manage(playback_reporter_wrapper);

+            // Keep the local search index fresh. Ownership of *when* to re-index
+            // sits here rather than in the frontend: it is sync policy over
+            // domain data, and a startup-only trigger left a long session
+            // searching a stale catalog.
+            // TRACES: UR-065 | DR-109, IR-030
+            info!("[INIT] Starting background catalog indexer...");
+            commands::catalog::spawn_catalog_indexer(app.handle().clone());
+
+            // Push favourite toggles made while the server was unreachable, on
+            // every reconnect. In Rust rather than the frontend so it runs
+            // whether or not the screen that made the change is still mounted.
+            // TRACES: UR-069 | DR-120
+            info!("[INIT] Starting favourites drain...");
+            commands::favorites::spawn_favorites_drain(app.handle().clone());
+
+            // Push playback reports queued while the server was unreachable.
+            // Without this the `sync_queue` rows the reporter writes offline
+            // are never sent and the offline banner's count only grows.
+            // TRACES: UR-025, UR-002 | DR-131
+            info!("[INIT] Starting sync-queue drain...");
+            commands::sync_drain::spawn_sync_queue_drain(app.handle().clone());
+
            info!("[INIT] Application setup completed successfully");
            Ok(())
        })
@@ -0,0 +1,588 @@
+//! A loopback HTTP server for locally downloaded media.
+//!
+//! Tauri's built-in `asset` protocol cannot serve a downloaded film to the
+//! webview. Its response to a request *without* a `Range` header reads the whole
+//! file into a `Vec<u8>`, and it only advertises `Accept-Ranges: bytes` from
+//! inside the range branch — so the first request never learns ranges are
+//! available and a multi-gigabyte body is attempted instead. Chromium abandoned
+//! it with `PIPELINE_ERROR_READ` after ~31s, which reached the user as
+//! "downloaded video does not play offline".
+//!
+//! Serving over real HTTP on 127.0.0.1 rather than a custom URI scheme is
+//! deliberate: it makes range support a property of the transport instead of
+//! depending on whether a platform's webview forwards `Range` to a custom
+//! scheme, which differs between Android and the desktop webviews.
+//!
+//! Two things confine it, because **loopback is shared between apps on
+//! Android** — any other installed app can connect to this port:
+//!
+//! - it binds `127.0.0.1` only, so nothing off-device can reach it; and
+//! - every URL carries a random per-session token, so another app cannot guess a
+//!   working URL, and paths are confined to the app data directory even if one
+//!   did.
+//!
+//! Phase 1 serves local files only. The same origin is the intended home for
+//! remote passthrough (and download-while-watching) later; see the stage-2 spec.
+//!
+//! TRACES: UR-071 | DR-137 | UT-127
+
+use std::fs::File;
+use std::io::{Read, Seek, SeekFrom};
+use std::path::{Path, PathBuf};
+use std::sync::Arc;
+
+use log::{debug, error, info, warn};
+use rand::Rng;
+use tiny_http::{Header, Response, Server, StatusCode};
+
+/// Bytes per response. Large enough that a film needs relatively few round
+/// trips, small enough that one response is never a memory problem on a phone.
+/// Tauri's asset protocol uses 1 MiB; 4 MiB quarters the request count for the
+/// multi-gigabyte files this exists to serve.
+const CHUNK_LEN: u64 = 4 * 1024 * 1024;
+
+/// Managed state. `None` when the server could not bind — local playback then
+/// fails with a clear error instead of the app refusing to start.
+pub struct MediaServerWrapper(pub Option<MediaServer>);
+
+/// A running server. Dropping this does not stop the thread; the server lives
+/// for the life of the process by design, since playback can start at any time.
+pub struct MediaServer {
+    port: u16,
+    token: String,
+}
+
+impl MediaServer {
+    /// The base a media URL is built on, e.g. `http://127.0.0.1:53412/<token>`.
+    pub fn base_url(&self) -> String {
+        format!("http://127.0.0.1:{}/{}", self.port, self.token)
+    }
+
+    /// A playable URL for an absolute on-disk path.
+    pub fn url_for(&self, path: &str) -> String {
+        format!("{}/{}", self.base_url(), urlencoding::encode(path))
+    }
+}
+
+/// Bind to an ephemeral loopback port and start serving `root` in a background
+/// thread.
+///
+/// TRACES: UR-071 | DR-137
+pub fn start(root: PathBuf) -> Result<MediaServer, String> {
+    // Port 0 → the OS picks a free one. Binding 127.0.0.1 (not 0.0.0.0) keeps
+    // this off the network.
+    let server =
+        Server::http("127.0.0.1:0").map_err(|e| format!("Failed to bind media server: {e}"))?;
+
+    let port = server
+        .server_addr()
+        .to_ip()
+        .ok_or_else(|| "Media server bound to a non-IP address".to_string())?
+        .port();
+
+    let token: String = {
+        let mut rng = rand::thread_rng();
+        (0..32)
+            .map(|_| char::from_digit(rng.gen_range(0..16), 16).unwrap())
+            .collect()
+    };
+
+    info!(
+        "[MediaServer] Serving {} on 127.0.0.1:{}",
+        root.display(),
+        port
+    );
+
+    let server = Arc::new(server);
+    let shared = Arc::new((root, token.clone()));
+
+    std::thread::Builder::new()
+        .name("media-server".into())
+        .spawn(move || loop {
+            let request = match server.recv() {
+                Ok(r) => r,
+                Err(e) => {
+                    error!("[MediaServer] accept failed: {e}");
+                    continue;
+                }
+            };
+            let shared = Arc::clone(&shared);
+            // A thread per request: media clients open several connections at
+            // once, and a blocking read of one must not stall the others.
+            if let Err(e) = std::thread::Builder::new()
+                .name("media-server-req".into())
+                .spawn(move || {
+                    let (root, token) = &*shared;
+                    handle(request, root, token);
+                })
+            {
+                error!("[MediaServer] could not spawn handler: {e}");
+            }
+        })
+        .map_err(|e| format!("Failed to start media server thread: {e}"))?;
+
+    Ok(MediaServer { port, token })
+}
+
+fn header(name: &str, value: &str) -> Header {
+    Header::from_bytes(name.as_bytes(), value.as_bytes())
+        .expect("static header name/value are valid")
+}
+
+fn empty(status: u16) -> Response<std::io::Empty> {
+    Response::empty(StatusCode(status)).with_header(header("Accept-Ranges", "bytes"))
+}
+
+fn handle(request: tiny_http::Request, root: &Path, token: &str) {
+    let url = request.url().to_string();
+    let method = request.method().as_str().to_string();
+
+    let outcome = match route(&url, root, token) {
+        Ok(path) => path,
+        Err(status) => {
+            let _ = request.respond(empty(status));
+            return;
+        }
+    };
+
+    if method != "GET" && method != "HEAD" {
+        let _ = request.respond(empty(405));
+        return;
+    }
+
+    let mut file = match File::open(&outcome) {
+        Ok(f) => f,
+        Err(e) => {
+            warn!("[MediaServer] {}: {}", outcome.display(), e);
+            let _ = request.respond(empty(404));
+            return;
+        }
+    };
+    let len = match file.metadata() {
+        Ok(m) => m.len(),
+        Err(e) => {
+            warn!(
+                "[MediaServer] metadata failed for {}: {}",
+                outcome.display(),
+                e
+            );
+            let _ = request.respond(empty(404));
+            return;
+        }
+    };
+
+    let range = request
+        .headers()
+        .iter()
+        .find(|h| h.field.equiv("Range"))
+        .map(|h| h.value.as_str().to_string());
+
+    debug!(
+        "[MediaServer] {} {} ({} bytes) range={:?}",
+        method,
+        outcome.display(),
+        len,
+        range
+    );
+
+    let Some(span) = span_for(range.as_deref(), len) else {
+        let _ = request
+            .respond(empty(416).with_header(header("Content-Range", &format!("bytes */{len}"))));
+        return;
+    };
+
+    // Sniff before seeking to the span, for extension-less files.
+    let mut head = [0u8; 16];
+    let head_len = file.read(&mut head).unwrap_or(0);
+    let mime = content_type(&outcome, &head[..head_len]);
+
+    if method == "HEAD" {
+        let _ = request.respond(
+            empty(200)
+                .with_header(header("Content-Type", mime))
+                .with_header(header("Content-Length", &len.to_string())),
+        );
+        return;
+    }
+
+    if let Err(e) = file.seek(SeekFrom::Start(span.start)) {
+        warn!("[MediaServer] seek failed for {}: {}", outcome.display(), e);
+        let _ = request.respond(empty(500));
+        return;
+    }
+
+    // Streamed straight from the file handle: at no point is more than the
+    // span in memory, and the span is capped at CHUNK_LEN.
+    let nbytes = span.len();
+    let body = file.take(nbytes);
+    // tiny_http switches to chunked transfer above a 32 KiB default, which drops
+    // Content-Length — and a 206 without one is unusable to Chromium's media
+    // loader, which needs the range's size. Raising the threshold past our own
+    // cap keeps every response length-delimited.
+    let response = Response::new(
+        StatusCode(206),
+        vec![
+            header("Accept-Ranges", "bytes"),
+            header("Content-Type", mime),
+            header(
+                "Content-Range",
+                &format!("bytes {}-{}/{}", span.start, span.end, len),
+            ),
+        ],
+        body,
+        Some(nbytes as usize),
+        None,
+    )
+    .with_chunked_threshold(usize::MAX);
+
+    if let Err(e) = request.respond(response) {
+        // A client that seeks away closes the connection mid-body; that is
+        // normal and must not be logged as a failure.
+        debug!("[MediaServer] response ended early: {e}");
+    }
+}
+
+/// Check the token and resolve the path, or return the status to answer with.
+fn route(url: &str, root: &Path, token: &str) -> Result<PathBuf, u16> {
+    let trimmed = url.trim_start_matches('/');
+    let (got_token, rest) = trimmed.split_once('/').ok_or(404u16)?;
+
+    // Constant-time-ish: length check first, then a byte compare. The token is
+    // the only thing standing between another app on the device and this server.
+    if got_token.len() != token.len() || got_token != token {
+        warn!("[MediaServer] Rejected a request with a bad token");
+        return Err(403);
+    }
+
+    // Strip any query string before decoding.
+    let raw = rest.split('?').next().unwrap_or("");
+    match resolve_path(raw, root) {
+        Resolved::Allow(p) => Ok(p),
+        Resolved::Forbidden => {
+            warn!("[MediaServer] Refused a path outside the app data directory");
+            Err(403)
+        }
+    }
+}
+
+/// What a request path resolved to, before any file is touched.
+#[derive(Debug, PartialEq, Eq)]
+pub enum Resolved {
+    Allow(PathBuf),
+    /// Escaped the allowed root.
+    Forbidden,
+}
+
+/// Resolve a percent-encoded request path to a file inside `root`.
+///
+/// `..` segments are folded away lexically rather than through `canonicalize`,
+/// so a missing file still resolves (and then 404s) instead of being reported as
+/// a scope violation.
+///
+/// TRACES: UR-071 | DR-137 | UT-127
+pub fn resolve_path(raw: &str, root: &Path) -> Resolved {
+    let decoded = match urlencoding::decode(raw) {
+        Ok(d) => d.into_owned(),
+        Err(_) => raw.to_string(),
+    };
+
+    let mut normalised = PathBuf::new();
+    for part in Path::new(&decoded).components() {
+        match part {
+            std::path::Component::ParentDir => {
+                normalised.pop();
+            }
+            std::path::Component::CurDir => {}
+            other => normalised.push(other),
+        }
+    }
+
+    if normalised.starts_with(root) {
+        Resolved::Allow(normalised)
+    } else {
+        Resolved::Forbidden
+    }
+}
+
+/// The byte range a response should carry. `end` is inclusive.
+#[derive(Debug, PartialEq, Eq)]
+pub struct Span {
+    pub start: u64,
+    pub end: u64,
+}
+
+impl Span {
+    pub fn len(&self) -> u64 {
+        self.end + 1 - self.start
+    }
+}
+
+/// Decide which span to send for a `Range` header (or its absence).
+///
+/// `None` means unsatisfiable — answer 416. A missing or unparseable header
+/// yields the first chunk, so a client that did not ask for a range still gets a
+/// bounded response it can continue from, which is exactly the case the asset
+/// protocol answered with the whole file.
+///
+/// TRACES: UR-071 | DR-137 | UT-127
+pub fn span_for(range: Option<&str>, len: u64) -> Option<Span> {
+    if len == 0 {
+        return Some(Span { start: 0, end: 0 });
+    }
+    let last = len - 1;
+    let first_chunk = Span {
+        start: 0,
+        end: (CHUNK_LEN - 1).min(last),
+    };
+
+    let Some(raw) = range else {
+        return Some(first_chunk);
+    };
+    let Some(spec) = raw.trim().strip_prefix("bytes=") else {
+        return Some(first_chunk);
+    };
+    // Only the first range of a multi-range request is honoured; media clients
+    // ask for one, and a single 206 is a valid answer either way.
+    let spec = spec.split(',').next().unwrap_or("").trim();
+    let Some((from, to)) = spec.split_once('-') else {
+        return Some(first_chunk);
+    };
+
+    let (start, end) = if from.is_empty() {
+        // Suffix form: `-500` is the final 500 bytes.
+        let suffix: u64 = match to.parse() {
+            Ok(n) => n,
+            Err(_) => return Some(first_chunk),
+        };
+        if suffix == 0 {
+            return None;
+        }
+        (len.saturating_sub(suffix), last)
+    } else {
+        let start: u64 = match from.parse() {
+            Ok(n) => n,
+            Err(_) => return Some(first_chunk),
+        };
+        let end = if to.is_empty() {
+            last
+        } else {
+            match to.parse::<u64>() {
+                Ok(n) => n.min(last),
+                Err(_) => return Some(first_chunk),
+            }
+        };
+        (start, end)
+    };
+
+    if start > last || end < start {
+        return None;
+    }
+
+    Some(Span {
+        start,
+        end: end.min(start + CHUNK_LEN - 1),
+    })
+}
+
+/// Guess a content type.
+///
+/// **Magic bytes win over the extension.** Downloading at `original` quality
+/// asks Jellyfin for a direct static copy, which returns the *source file's*
+/// bytes under a `.mp4` name whatever the real container is — a downloaded film
+/// named `.mp4` turned out to be an AVI holding XVID. Trusting the extension
+/// there labels it `video/mp4` and the player is handed a container that is not
+/// what the header claims. The extension is only a fallback for a file whose
+/// bytes are unrecognised, and for the extension-less files the offline queue
+/// writes under an item id.
+///
+/// TRACES: UR-071 | DR-137 | UT-127
+fn content_type(path: &Path, head: &[u8]) -> &'static str {
+    // `ftyp` at offset 4 marks an ISO base media file (mp4 and friends).
+    if head.len() > 11 && &head[4..8] == b"ftyp" {
+        return "video/mp4";
+    }
+    if head.len() > 11 && head.starts_with(b"RIFF") && &head[8..11] == b"AVI" {
+        return "video/x-msvideo";
+    }
+    if head.starts_with(b"\x1aE\xdf\xa3") {
+        return "video/x-matroska";
+    }
+    if head.starts_with(b"ID3") || head.starts_with(b"\xff\xfb") {
+        return "audio/mpeg";
+    }
+    if head.starts_with(b"OggS") {
+        return "audio/ogg";
+    }
+    if head.starts_with(b"fLaC") {
+        return "audio/flac";
+    }
+
+    match path
+        .extension()
+        .and_then(|e| e.to_str())
+        .map(|e| e.to_ascii_lowercase())
+        .as_deref()
+    {
+        Some("mp4" | "m4v" | "mov") => return "video/mp4",
+        Some("mkv") => return "video/x-matroska",
+        Some("webm") => return "video/webm",
+        Some("mp3") => return "audio/mpeg",
+        Some("m4a" | "aac") => return "audio/mp4",
+        Some("flac") => return "audio/flac",
+        Some("ogg" | "opus") => return "audio/ogg",
+        Some("wav") => return "audio/wav",
+        Some("avi") => return "video/x-msvideo",
+        _ => {}
+    }
+
+    "application/octet-stream"
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// The whole point: a request with no `Range` must still come back bounded.
+    /// That is the case Tauri's asset protocol answers with the entire file —
+    /// the read Chromium abandoned after 31s.
+    ///
+    /// TRACES: UR-071 | DR-137 | UT-127
+    #[test]
+    fn a_rangeless_request_is_answered_with_one_chunk_not_the_file() {
+        let huge = 8 * 1024 * 1024 * 1024; // 8 GiB
+        let span = span_for(None, huge).unwrap();
+        assert_eq!(span.start, 0);
+        assert_eq!(span.len(), CHUNK_LEN);
+    }
+
+    /// TRACES: UR-071 | DR-137 | UT-127
+    #[test]
+    fn no_response_ever_exceeds_one_chunk() {
+        let len = 8 * 1024 * 1024 * 1024;
+        for h in [
+            "bytes=0-",
+            "bytes=0-99999999999",
+            "bytes=1024-",
+            "bytes=-99999999",
+        ] {
+            let span = span_for(Some(h), len).unwrap();
+            assert!(span.len() <= CHUNK_LEN, "{h} produced {} bytes", span.len());
+        }
+    }
+
+    /// TRACES: UR-071 | DR-137 | UT-127
+    #[test]
+    fn ranges_are_honoured() {
+        let len = 1000u64;
+        assert_eq!(
+            span_for(Some("bytes=100-199"), len).unwrap(),
+            Span {
+                start: 100,
+                end: 199
+            }
+        );
+        // Open-ended runs to the end of a small file.
+        assert_eq!(
+            span_for(Some("bytes=900-"), len).unwrap(),
+            Span {
+                start: 900,
+                end: 999
+            }
+        );
+        // Suffix form.
+        assert_eq!(
+            span_for(Some("bytes=-100"), len).unwrap(),
+            Span {
+                start: 900,
+                end: 999
+            }
+        );
+        // Past the end is unsatisfiable, not a clamp — a clamp would make a
+        // seek past the end silently replay earlier bytes.
+        assert!(span_for(Some("bytes=1000-"), len).is_none());
+    }
+
+    /// A malformed header must not fail the request: playing from the start is
+    /// strictly better than refusing to open the file.
+    ///
+    /// TRACES: UR-071 | DR-137 | UT-127
+    #[test]
+    fn a_malformed_range_falls_back_to_the_first_chunk() {
+        assert_eq!(span_for(Some("pages=1-2"), 5000).unwrap().start, 0);
+        assert_eq!(span_for(Some("bytes=abc-def"), 5000).unwrap().start, 0);
+    }
+
+    /// TRACES: UR-071 | DR-137 | UT-127
+    #[test]
+    fn reads_are_confined_to_the_app_data_directory() {
+        let root = Path::new("/data/user/0/app");
+
+        assert_eq!(
+            resolve_path("/data/user/0/app/videos/f.mp4", root),
+            Resolved::Allow(PathBuf::from("/data/user/0/app/videos/f.mp4"))
+        );
+        // Percent-encoded, as the URL builder produces.
+        assert_eq!(
+            resolve_path("%2Fdata%2Fuser%2F0%2Fapp%2Fa%20b.mp4", root),
+            Resolved::Allow(PathBuf::from("/data/user/0/app/a b.mp4"))
+        );
+        // Traversal out of the root, and an unrelated absolute path, are refused.
+        assert_eq!(
+            resolve_path("/data/user/0/app/../../../etc/passwd", root),
+            Resolved::Forbidden
+        );
+        assert_eq!(resolve_path("/etc/passwd", root), Resolved::Forbidden);
+    }
+
+    /// Loopback is shared between apps on Android, so the token is the only
+    /// thing stopping another installed app from reading downloaded media.
+    ///
+    /// TRACES: UR-071 | DR-137 | UT-127
+    #[test]
+    fn a_request_without_the_right_token_is_refused() {
+        let root = Path::new("/data/user/0/app");
+        let good = "0123456789abcdef0123456789abcdef";
+
+        assert_eq!(
+            route(
+                &format!("/{good}/%2Fdata%2Fuser%2F0%2Fapp%2Ff.mp4"),
+                root,
+                good
+            ),
+            Ok(PathBuf::from("/data/user/0/app/f.mp4"))
+        );
+        assert_eq!(
+            route("/wrong-token/%2Fdata%2Fuser%2F0%2Fapp%2Ff.mp4", root, good),
+            Err(403)
+        );
+        // No token segment at all.
+        assert_eq!(route("/f.mp4", root, good), Err(404));
+        // Right token, but a path outside the root is still refused.
+        assert_eq!(
+            route(&format!("/{good}/%2Fetc%2Fpasswd"), root, good),
+            Err(403)
+        );
+    }
+
+    /// TRACES: UR-071 | DR-137 | UT-127
+    #[test]
+    fn content_type_uses_the_extension_then_the_magic_bytes() {
+        assert_eq!(content_type(Path::new("/a/f.mp4"), &[]), "video/mp4");
+        assert_eq!(content_type(Path::new("/a/f.mp3"), &[]), "audio/mpeg");
+        // A `.mp4` that is really an AVI: downloading at `original` quality
+        // copies the source bytes under an mp4 name, so the extension lies and
+        // the magic bytes must win.
+        let avi_head = b"RIFF\xcc\xf3\xbc\x2bAVI LIST";
+        assert_eq!(
+            content_type(Path::new("/a/film.mp4"), avi_head),
+            "video/x-msvideo"
+        );
+        // Extension-less, as the offline queue writes them: sniff instead.
+        let mp4_head = b"\x00\x00\x00\x20ftypisom\x00\x00\x02\x00";
+        assert_eq!(content_type(Path::new("/a/abc123"), mp4_head), "video/mp4");
+        assert_eq!(
+            content_type(Path::new("/a/abc123"), b"ID3\x03junk"),
+            "audio/mpeg"
+        );
+    }
+}
@@ -58,11 +58,20 @@ static POSITION_THROTTLER: OnceLock<Arc<EventThrottler>> = OnceLock::new();
 struct DetectedCodecs {
    video_codecs: Vec<String>,
    audio_codecs: Vec<String>,
+    /// Channels the *current audio output route* accepts, as reported by
+    /// media3's `AudioCapabilities`. Distinct from the codec lists: a device
+    /// decodes 5.1 happily and still has only two channels to play it out of.
+    /// `None` when the platform had no answer.
+    max_audio_channels: Option<u32>,
 }

 impl DetectedCodecs {
    /// Create from comma-separated codec strings (from JNI)
-    fn from_jni_strings(video_codecs: &str, audio_codecs: &str) -> Self {
+    fn from_jni_strings(
+        video_codecs: &str,
+        audio_codecs: &str,
+        max_audio_channels: Option<u32>,
+    ) -> Self {
        Self {
            video_codecs: video_codecs
                .split(',')
@@ -74,6 +83,7 @@ impl DetectedCodecs {
                .filter(|s| !s.is_empty())
                .map(|s| s.to_string())
                .collect(),
+            max_audio_channels,
        }
    }

@@ -88,11 +98,19 @@ impl DetectedCodecs {
    }
 }

-/// Public function to get detected codecs (for use in repository layer)
-pub fn get_detected_codecs() -> Option<(String, String)> {
-    DETECTED_CODECS
-        .get()
-        .map(|codecs| (codecs.video_codecs_string(), codecs.audio_codecs_string()))
+/// Public function to get detected codecs (for use in repository layer).
+///
+/// Returns `(video, audio, max_audio_channels)` — the third element is how many
+/// channels the current audio output can actually voice, which bounds what the
+/// server may direct-play.
+pub fn get_detected_codecs() -> Option<(String, String, Option<u32>)> {
+    DETECTED_CODECS.get().map(|codecs| {
+        (
+            codecs.video_codecs_string(),
+            codecs.audio_codecs_string(),
+            codecs.max_audio_channels,
+        )
+    })
 }

 /// Trait for handling media commands from Android MediaSession.
@@ -930,6 +948,25 @@ pub extern "system" fn Java_com_dtourolle_jellytau_player_JellyTauPlayer_nativeO
                            .await;
                    }
                }
+                Ok(AutoplayDecision::ResumeStream { position }) => {
+                    // ExoPlayer reported ENDED because the progressive transcode's
+                    // connection dropped, not because the episode finished. This
+                    // is the arm that matters while backgrounded: it needs no
+                    // frontend echo, so the stream re-opens even with the webview
+                    // suspended — and playback never parks in STATE_ENDED, where
+                    // the next lockscreen/Bluetooth play restarts the item at 0:00.
+                    log::info!(
+                        "[Autoplay] Decision: Resume truncated stream at {:.1}s",
+                        position
+                    );
+                    let ctrl = controller.lock().await;
+                    if let Err(e) = ctrl.resume_stream_at(position).await {
+                        log::error!("[Autoplay] Failed to resume truncated stream: {}", e);
+                        if let Some(emitter) = EVENT_EMITTER.get() {
+                            emitter.emit(PlayerStatusEvent::PlaybackEnded);
+                        }
+                    }
+                }
                Err(e) => {
                    log::error!("[Autoplay] Decision failed: {}", e);
                    // Emit PlaybackEnded event on error
@@ -974,11 +1011,61 @@ pub extern "system" fn Java_com_dtourolle_jellytau_player_JellyTauPlayer_nativeO
        .get_string(&message)
        .map(|s| s.into())
        .unwrap_or_else(|_| "Unknown error".to_string());
+    let recoverable = recoverable != 0;
+
+    // A background audio-only handoff is an mp3 the device was already decoding,
+    // so a recoverable failure part-way through is the network. Surfacing it as a
+    // player error stops playback for good (the frontend's handler calls
+    // player_stop); re-opening the stream where it died is the "buffer and
+    // resume" this actually is. Everything else keeps reporting the error.
+    if recoverable {
+        if let Some(controller) = PLAYER_CONTROLLER.get() {
+            let controller = controller.clone();
+            let message_str = message_str.clone();
+            tauri::async_runtime::spawn(async move {
+                let resume = controller.lock().await.recoverable_error_resume();
+                let Some((position, delay_secs)) = resume else {
+                    // Declined here, so report it as NOT recoverable: the frontend
+                    // would otherwise echo it into player_recover_stream and ask
+                    // the same question a second time.
+                    if let Some(emitter) = EVENT_EMITTER.get() {
+                        emitter.emit(PlayerStatusEvent::Error {
+                            message: message_str,
+                            recoverable: false,
+                        });
+                    }
+                    return;
+                };
+
+                log::warn!(
+                    "[ExoPlayer] Recoverable stream error ({}) — re-opening at {:.1}s in {}s",
+                    message_str,
+                    position,
+                    delay_secs
+                );
+                // Give a brief outage time to clear before asking the server for
+                // the stream again; retrying instantly just burns the budget.
+                tokio::time::sleep(std::time::Duration::from_secs(delay_secs)).await;
+
+                let ctrl = controller.lock().await;
+                if let Err(e) = ctrl.resume_stream_at(position).await {
+                    log::error!("[ExoPlayer] Failed to resume after error: {}", e);
+                    if let Some(emitter) = EVENT_EMITTER.get() {
+                        emitter.emit(PlayerStatusEvent::Error {
+                            message: message_str,
+                            recoverable: false,
+                        });
+                    }
+                }
+            });
+            return;
+        }
+    }

    if let Some(emitter) = EVENT_EMITTER.get() {
        emitter.emit(PlayerStatusEvent::Error {
            message: message_str,
-            recoverable: recoverable != 0,
+            recoverable,
        });
    }
 }
@@ -1056,6 +1143,7 @@ pub extern "system" fn Java_com_dtourolle_jellytau_player_JellyTauPlayer_00024Co
    _class: JClass,
    video_codecs: JString,
    audio_codecs: JString,
+    max_audio_channels: jint,
 ) {
    let video_str: String = env
        .get_string(&video_codecs)
@@ -1067,7 +1155,10 @@ pub extern "system" fn Java_com_dtourolle_jellytau_player_JellyTauPlayer_00024Co
        .map(|s| s.into())
        .unwrap_or_default();

-    let codecs = DetectedCodecs::from_jni_strings(&video_str, &audio_str);
+    // Kotlin sends 0 when AudioCapabilities had no answer for the current route.
+    let channels = u32::try_from(max_audio_channels).ok().filter(|c| *c > 0);
+
+    let codecs = DetectedCodecs::from_jni_strings(&video_str, &audio_str, channels);

    log::info!(
        "[CodecDetection] Detected {} video codecs: {}",
@@ -1079,6 +1170,10 @@ pub extern "system" fn Java_com_dtourolle_jellytau_player_JellyTauPlayer_00024Co
        codecs.audio_codecs.len(),
        codecs.audio_codecs_string()
    );
+    log::info!(
+        "[CodecDetection] Audio route max channels: {:?}",
+        codecs.max_audio_channels
+    );

    // Store in global state
    if DETECTED_CODECS.set(codecs).is_err() {
@@ -11,6 +11,10 @@ pub enum AutoplayDecision {
    Stop,
    /// Advance to next track in queue (for audio/movies)
    AdvanceToNext,
+    /// The stream ended well short of the item's runtime — the connection
+    /// dropped, not the media. Re-open the same stream at `position` instead of
+    /// running any end-of-item logic (UR-040).
+    ResumeStream { position: f64 },
    /// Show next episode popup with countdown
    ShowNextEpisodePopup {
        current_episode: MediaItem,
@@ -11,6 +11,7 @@ pub mod seek;
 pub mod session;
 pub mod sleep_timer;
 pub mod state;
+pub mod stream_end;

 #[cfg(test)]
 mod mpv_backend_test;
@@ -54,6 +55,16 @@ pub use android::{
    set_remote_volume_handler, MediaCommandHandler, RemoteVolumeHandler,
 };

+/// Seconds added per attempt before retrying a stream that failed with an error.
+///
+/// Attempt 1 waits this long, attempt 2 twice as long, and so on — a spread that
+/// covers roughly a quarter-minute of outage across the retry budget without
+/// leaving the user staring at a dead notification when the network is truly gone.
+/// Only *read* by the Android error callback (`#[cfg(android)]`), but compiled
+/// and unit-tested on the host, hence `allow(dead_code)` off-Android.
+#[cfg_attr(not(target_os = "android"), allow(dead_code))]
+const RESUME_BACKOFF_STEP_SECS: u64 = 2;
+
 /// Metadata for the lockscreen / media notification.
 ///
 /// Used to drive the Android MediaSession from Rust in remote (cast) mode, where
@@ -168,6 +179,26 @@ pub struct PlayerController {
    // TRACES: UR-040 | DR-052
    background_audio_base: Arc<Mutex<f64>>,

+    // True while a background-audio handoff owns playback: the native audio
+    // player is the real player and the webview <video> has been torn down.
+    //
+    // The teardown is what makes this necessary. It fires a DOM `pause` that the
+    // frontend reports like any other, which would otherwise leave the controller
+    // believing webview media is still active — aiming lockscreen transport at an
+    // element that no longer exists (see `is_html5_active`).
+    //
+    // TRACES: UR-040 | DR-052, DR-097
+    background_audio_active: Arc<Mutex<bool>>,
+
+    // Budget for re-opening a stream that ended short of the item's runtime.
+    //
+    // A resume re-requests the same URL, so a server that is genuinely gone would
+    // otherwise end → resume → end without limit. The tracker only bounds retries
+    // that make no progress; a resume that plays on refills it.
+    //
+    // TRACES: UR-040 | DR-129
+    stream_resume: Arc<Mutex<stream_end::ResumeTracker>>,
+
    // Last state reported by a webview-rendered HTML5 <video>/<audio> element.
    //
    // Webview-rendered media is played by an element the native backend cannot
@@ -201,6 +232,8 @@ impl PlayerController {
            end_reason: Arc::new(Mutex::new(None)),
            autoplay_episode_count: Arc::new(Mutex::new(0)),
            background_audio_base: Arc::new(Mutex::new(0.0)),
+            background_audio_active: Arc::new(Mutex::new(false)),
+            stream_resume: Arc::new(Mutex::new(stream_end::ResumeTracker::default())),
            html5_playing: Arc::new(Mutex::new(None)),
        };

@@ -271,6 +304,16 @@ impl PlayerController {
        self.end_reason.lock_safe().take()
    }

+    /// Read the end reason WITHOUT consuming it.
+    ///
+    /// `take_end_reason` has an owner: on Android the JNI ended-callback consumes
+    /// the `NewTrackLoaded` every load sets, and the frontend's echoed call is the
+    /// one that sees `None` and decides. The truncated-stream check runs in both
+    /// calls and must not disturb that hand-off, so it peeks.
+    fn peek_end_reason(&self) -> Option<EndReason> {
+        *self.end_reason.lock_safe()
+    }
+
    /// Record that playback is being stopped by an expiring sleep timer.
    ///
    /// Stopping the backend makes it fire its ended callback (ExoPlayer does on
@@ -969,6 +1012,14 @@ impl PlayerController {
    /// Re-emits a `StateChanged` event identical to what MpvBackend/ExoPlayer
    /// would emit, so `playerEvents.ts` needs no HTML5-specific branch.
    pub fn report_html5_state(&self, state: String, media_id: Option<String>) {
+        // A background-audio handoff has already moved playback to the native
+        // player and torn the element down; anything it still reports describes
+        // a video that is no longer playing. Dropping it keeps the UI on the
+        // audio that IS playing and leaves transport with the native backend.
+        if self.is_background_audio_active() {
+            debug!("[PlayerController] Ignoring HTML5 state '{state}' during background audio");
+            return;
+        }
        // Track it: this is the authoritative play/pause state for
        // webview-rendered media, and what transport decisions read (DR-097).
        // "stopped"/"idle" mean the element is gone, so hand authority back to
@@ -996,6 +1047,11 @@ impl PlayerController {
    /// Re-emits a `PositionUpdate` event mirroring the native backends' periodic
    /// position updates (the adapter is expected to throttle to ~250ms like MPV).
    pub fn report_html5_position(&self, position: f64, duration: f64) {
+        // Stale by definition during a handoff — the native player's ticks are
+        // the real position. See `report_html5_state`.
+        if self.is_background_audio_active() {
+            return;
+        }
        if let Some(emitter) = self.event_emitter.lock_safe().as_ref() {
            emitter.emit(PlayerStatusEvent::PositionUpdate { position, duration });
        }
@@ -1004,6 +1060,10 @@ impl PlayerController {
    /// Report that the HTML5 <video> element finished loading and knows its
    /// duration. Mirrors the native `MediaLoaded` event.
    pub fn report_html5_media_loaded(&self, duration: f64) {
+        // See `report_html5_state` — the element is not the player right now.
+        if self.is_background_audio_active() {
+            return;
+        }
        if let Some(emitter) = self.event_emitter.lock_safe().as_ref() {
            emitter.emit(PlayerStatusEvent::MediaLoaded { duration });
        }
@@ -1034,6 +1094,15 @@ impl PlayerController {
    /// Only triggers autoplay if the track finished naturally (EndReason::Finished or None).
    /// If EndReason is NewTrackLoaded, UserStop, UserSkip, or Error, returns Stop without autoplay.
    pub async fn on_playback_ended(&self) -> Result<AutoplayDecision, String> {
+        // A truncated stream is not an end at all, so this is decided BEFORE the
+        // end-reason gate below — which returns early for the `NewTrackLoaded`
+        // that every load sets, and would therefore swallow the whole question on
+        // Android's JNI callback: the one call guaranteed to run while the app is
+        // backgrounded and the webview cannot echo anything back.
+        if let Some(position) = self.truncated_stream_resume_position() {
+            return Ok(AutoplayDecision::ResumeStream { position });
+        }
+
        // Check why playback ended
        let end_reason = self.take_end_reason();

@@ -1194,6 +1263,42 @@ impl PlayerController {
        *self.background_audio_base.lock_safe() = seconds.max(0.0);
    }

+    /// Enter a background-audio handoff at `position` (the video's position, and
+    /// therefore the audio stream's zero).
+    ///
+    /// Hands transport authority to the native audio player: the webview
+    /// `<video>` is about to be torn down, so its last reports — including the
+    /// `pause` the teardown itself fires — must not keep it looking like the
+    /// player. Without this the lockscreen pause emitted a ControlCommand at a
+    /// dead element and the audio played straight through it.
+    ///
+    /// TRACES: UR-040, UR-005 | DR-052, DR-097
+    pub fn enter_background_audio(&self, position: f64) {
+        self.set_background_audio_base(position);
+        *self.background_audio_active.lock_safe() = true;
+        *self.html5_playing.lock_safe() = None;
+    }
+
+    /// Leave a background-audio handoff, returning the base offset to add to the
+    /// native player's relative position.
+    ///
+    /// The webview `<video>` becomes the player again once it reloads, so its
+    /// reports are honoured from here on.
+    ///
+    /// TRACES: UR-040, UR-005 | DR-052, DR-097
+    pub fn exit_background_audio(&self) -> f64 {
+        *self.background_audio_active.lock_safe() = false;
+        self.take_background_audio_base()
+    }
+
+    /// True while the native audio player owns playback via a background-audio
+    /// handoff.
+    ///
+    /// TRACES: UR-040 | DR-052
+    pub fn is_background_audio_active(&self) -> bool {
+        *self.background_audio_active.lock_safe()
+    }
+
    /// Read and clear the background-audio base offset.
    ///
    /// TRACES: UR-040 | DR-052
@@ -1248,6 +1353,196 @@ impl PlayerController {
        self.start_autoplay_countdown(next_episode, countdown_seconds);
    }

+    /// A video item played through the native *audio* path — i.e. the background
+    /// audio-only handoff, the only place a length-less progressive transcode is
+    /// used. Jellyfin's item-type taxonomy stays in Rust (CLAUDE.md).
+    fn is_audio_only_video(item: &MediaItem) -> bool {
+        item.media_type == MediaType::Audio
+            && matches!(item.item_type.as_deref(), Some("Episode") | Some("Movie"))
+    }
+
+    /// Claim a resume attempt for the current stream, returning the absolute
+    /// position to re-open at and the 1-based attempt number. `None` when the
+    /// current item cannot meaningfully be re-requested, or when retrying at this
+    /// position has stopped helping.
+    ///
+    /// Only `Remote` sources qualify. A downloaded file cannot fail because of
+    /// the network, so re-opening one would paper over a real read error; a
+    /// `DirectUrl` is a plugin's endpoint with no Jellyfin item behind it.
+    ///
+    /// The player's position is relative to the stream's own zero (the handoff
+    /// URL's `StartTimeTicks`), so the base is added back to get an absolute one.
+    /// It is zero for everything else, where positions are already absolute.
+    ///
+    /// TRACES: UR-040, UR-004 | DR-129 | UT-117
+    fn claim_stream_resume(&self) -> Option<(f64, u32)> {
+        let current = {
+            let queue = self.queue.lock_safe();
+            queue.current().cloned()
+        }?;
+        if !matches!(current.source, MediaSource::Remote { .. }) {
+            return None;
+        }
+
+        let base = *self.background_audio_base.lock_safe();
+        let absolute = (base + self.position()).max(0.0);
+
+        match self.stream_resume.lock_safe().allow_attempt(absolute) {
+            Some(attempt) => Some((absolute, attempt)),
+            None => {
+                warn!(
+                    "[PlayerController] Stream for {} keeps failing at {:.1}s — giving up on resuming",
+                    current.id, absolute
+                );
+                None
+            }
+        }
+    }
+
+    /// The absolute position to re-open the current stream at, when the reported
+    /// end was really a dropped connection — `None` when the end looks genuine,
+    /// when this is not an audio-only handoff, or when retrying has stopped
+    /// helping.
+    ///
+    /// TRACES: UR-040 | DR-129 | UT-117
+    fn truncated_stream_resume_position(&self) -> Option<f64> {
+        // An explicit user intent already explains the end; never resume over it.
+        if matches!(
+            self.peek_end_reason(),
+            Some(EndReason::UserStop) | Some(EndReason::UserSkip) | Some(EndReason::Error)
+        ) {
+            return None;
+        }
+
+        // One lock at a time — `position()` reaches into the backend, and nesting
+        // that inside the queue lock would invent a lock order nothing else here
+        // takes.
+        let item_duration = {
+            let queue = self.queue.lock_safe();
+            let current = queue.current()?;
+            if !Self::is_audio_only_video(current) {
+                return None;
+            }
+            current.duration
+        };
+        let base = *self.background_audio_base.lock_safe();
+        let absolute = (base + self.position()).max(0.0);
+
+        // Only spend a resume attempt once the runtime says this really was cut
+        // short — a genuine end must stay a genuine end.
+        if !stream_end::is_truncated_end(
+            absolute,
+            item_duration,
+            stream_end::TRUNCATED_STREAM_TOLERANCE_SECS,
+        ) {
+            return None;
+        }
+
+        self.claim_stream_resume().map(|(position, _)| position)
+    }
+
+    /// Where to re-open the current stream after a *recoverable* playback error,
+    /// plus how many seconds to wait first.
+    ///
+    /// The media was decoding fine a moment ago, so a mid-playback failure on a
+    /// server stream is the network — and stopping the player (the previous
+    /// behaviour, via the frontend's error handler) turns a hiccup into "playback
+    /// just died". Applies to every streamed item, not only the audio-only
+    /// handoff: music and video reach here instead of the truncation path because
+    /// their streams declare a length, so a cut connection surfaces as an error
+    /// rather than a phantom end.
+    ///
+    /// The wait grows with the attempt number so a short outage has time to
+    /// clear, and the shared budget stops the retries when it doesn't.
+    ///
+    /// Called from the Android error callback, which decides in-process, and from
+    /// `player_recover_stream`, which is how the same decision reaches the
+    /// backends whose event thread has no controller to call — MPV is built
+    /// before the controller exists, so on Linux the error is emitted, echoed by
+    /// the frontend, and decided here.
+    ///
+    /// TRACES: UR-040, UR-004 | DR-129, DR-130 | UT-117
+    pub fn recoverable_error_resume(&self) -> Option<(f64, u64)> {
+        self.claim_stream_resume()
+            .map(|(position, attempt)| (position, attempt as u64 * RESUME_BACKOFF_STEP_SECS))
+    }
+
+    /// Re-open the current stream at `position` after the network cut it short.
+    ///
+    /// Single place every dispatcher agrees on, for the same reason
+    /// `auto_advance_to_next_episode` is: the Android JNI callbacks and the
+    /// frontend-invoked command must not disagree about what a failed stream
+    /// means. None of them emits `PlaybackEnded` for this, so nothing downstream
+    /// clears the queue or tears the session down — from the outside this is a
+    /// buffering hiccup, which is what it actually was.
+    ///
+    /// Reloads the item **in place** rather than through `play_item`, which
+    /// replaces the queue with a single item: recovering a track that way would
+    /// throw away the rest of the album, turning a network blip into lost state.
+    ///
+    /// Two shapes of stream, two ways back to `position`:
+    ///
+    /// - The audio-only handoff's `/Audio/{id}/universal` transcode is chunked
+    ///   with no length, so it cannot be seeked. Its URL is rewritten to start at
+    ///   the position instead — edited, not rebuilt from the repository, since it
+    ///   already carries the user's audio track and media source and recovering
+    ///   from a network failure must not itself need a network round-trip.
+    /// - Everything else (a static file with byte ranges, an HLS playlist)
+    ///   declares its whole timeline, so re-preparing the URL it already has and
+    ///   seeking lands in the right place — and leaves any transcode session
+    ///   behind it alone.
+    ///
+    /// TRACES: UR-040, UR-004 | DR-129 | UT-117
+    pub async fn resume_stream_at(&self, position: f64) -> Result<(), String> {
+        let current = {
+            let queue = self.queue.lock_safe();
+            queue.current().cloned()
+        }
+        .ok_or_else(|| "No current item to resume".to_string())?;
+
+        let MediaSource::Remote { stream_url, .. } = &current.source else {
+            return Err(format!(
+                "Cannot resume a non-remote source for {}",
+                current.id
+            ));
+        };
+
+        info!(
+            "[PlayerController] Stream for {} failed — re-opening at {:.1}s",
+            current.id, position
+        );
+
+        if !Self::is_audio_only_video(&current) {
+            self.load_and_play(&current).map_err(|e| e.to_string())?;
+            if position > 0.5 {
+                self.seek(position).map_err(|e| e.to_string())?;
+            }
+            return Ok(());
+        }
+
+        let restarted_url = stream_end::with_start_time(stream_url, position);
+        {
+            let queue_arc = self.queue.clone();
+            let mut queue = queue_arc.lock_safe();
+            if !queue.update_current_stream_url(restarted_url) {
+                return Err(format!("Failed to update stream URL for {}", current.id));
+            }
+        }
+        let resumed = {
+            let queue = self.queue.lock_safe();
+            queue.current().cloned()
+        }
+        .ok_or_else(|| "Current item vanished mid-resume".to_string())?;
+
+        // The re-opened stream's timeline starts at `position` (StartTimeTicks),
+        // so that is its zero: the exit-to-foreground maths and the lockscreen
+        // scrubber both read absolute positions off this base.
+        self.set_background_audio_base(position);
+        let _ = set_lockscreen_position_offset(position.max(0.0));
+
+        self.load_and_play(&resumed).map_err(|e| e.to_string())
+    }
+
    /// Advance to the next episode while playing audio-only in the background.
    ///
    /// The normal autoplay-next path navigates the frontend to `/player/<id>`,
@@ -1322,6 +1617,9 @@ impl PlayerController {
        // back to the foreground) and the lockscreen scrubber's matching shift.
        self.set_background_audio_base(0.0);
        let _ = set_lockscreen_position_offset(0.0);
+        // Different stream entirely: whatever was stuck about the last one is not
+        // this one's problem.
+        self.stream_resume.lock_safe().reset();

        self.play_item(media_item).map_err(|e| e.to_string())
    }
@@ -1769,6 +2067,84 @@ mod tests {
        assert_eq!(controls, vec!["play".to_string(), "pause".to_string()]);
    }

+    #[test]
+    fn test_background_audio_handoff_moves_transport_to_native_backend() {
+        // Lockscreen pause while playing a video's audio in the background.
+        //
+        // The handoff tears the WebView <video> down AFTER native audio starts,
+        // and that teardown fires a DOM `pause` the frontend dutifully reports.
+        // That report used to leave `html5_playing = Some(false)`, so transport
+        // kept being aimed at an element that no longer exists: the lockscreen
+        // pause emitted a ControlCommand into the void and the audio played on.
+        let controller = PlayerController::default();
+        let emitter = Arc::new(CapturingEmitter::new());
+        controller.set_event_emitter(emitter.clone());
+
+        // Video was playing in the webview.
+        controller.report_html5_state("playing".to_string(), Some("ep-1".to_string()));
+        assert!(controller.is_html5_active());
+
+        // Hand off to the native audio player, then tear the element down.
+        controller.enter_background_audio(1200.0);
+        controller.report_html5_state("paused".to_string(), Some("ep-1".to_string()));
+
+        assert!(
+            !controller.is_html5_active(),
+            "native audio owns transport during a background-audio handoff"
+        );
+
+        controller.pause().unwrap();
+        let controls: Vec<_> = emitter
+            .events()
+            .into_iter()
+            .filter_map(|e| match e {
+                PlayerStatusEvent::ControlCommand { action, .. } => Some(action),
+                _ => None,
+            })
+            .collect();
+        assert!(
+            controls.is_empty(),
+            "pause must drive the native backend, not a torn-down element: {:?}",
+            controls
+        );
+    }
+
+    #[test]
+    fn test_background_audio_handoff_suppresses_stale_element_events() {
+        // The dying element's pause/position reports describe the video, not the
+        // audio now playing — re-emitting them flips the UI to paused and yanks
+        // the position backwards while native audio keeps going.
+        let controller = PlayerController::default();
+        let emitter = Arc::new(CapturingEmitter::new());
+        controller.set_event_emitter(emitter.clone());
+
+        controller.enter_background_audio(1200.0);
+        controller.report_html5_state("paused".to_string(), Some("ep-1".to_string()));
+        controller.report_html5_position(1200.0, 2400.0);
+
+        assert!(
+            emitter.events().is_empty(),
+            "stale webview reports must not reach the event pipeline: {:?}",
+            emitter.events()
+        );
+    }
+
+    #[test]
+    fn test_exit_background_audio_returns_transport_to_the_webview() {
+        // Back in the foreground the <video> is the player again, so its reports
+        // must be honoured — and the base offset still comes back for the resume.
+        let controller = PlayerController::default();
+        let emitter = Arc::new(CapturingEmitter::new());
+        controller.set_event_emitter(emitter.clone());
+
+        controller.enter_background_audio(1200.0);
+        assert_eq!(controller.exit_background_audio(), 1200.0);
+
+        controller.report_html5_state("playing".to_string(), Some("ep-1".to_string()));
+        assert!(controller.is_html5_active());
+        assert!(controller.html5_is_playing());
+    }
+
    #[test]
    fn test_html5_stopped_report_releases_transport_to_native_backend() {
        // When webview video goes away, transport must fall back to the native
@@ -2862,9 +3238,19 @@ mod tests {
        async fn unmark_favorite(&self, _: &str) -> Result<(), repo_types::RepoError> {
            unimplemented!()
        }
+        async fn get_favorites(
+            &self,
+            _: repo_types::SearchScope,
+            _: Option<repo_types::GetItemsOptions>,
+        ) -> Result<repo_types::SearchResult, repo_types::RepoError> {
+            unimplemented!()
+        }
        async fn clear_watch_history(&self, _: &str) -> Result<(), repo_types::RepoError> {
            unimplemented!()
        }
+        async fn mark_played(&self, _: &str) -> Result<(), repo_types::RepoError> {
+            unimplemented!()
+        }
        async fn get_person(
            &self,
            _: &str,
@@ -3018,6 +3404,7 @@ mod tests {
            item_type: Some("Episode".to_string()),
            media_type: MediaType::Audio, // audio-only handoff, not Video
            series_id: Some("series1".to_string()),
+            duration: Some(180.0),
            source: MediaSource::Remote {
                stream_url: "http://example.com/ep2-audio.m3u8".to_string(),
                jellyfin_item_id: "ep2".to_string(),
@@ -3026,6 +3413,8 @@ mod tests {
        };
        controller.play_queue(vec![episode], 0).unwrap();

+        // Played through to the end — a natural finish, not a stream cut short.
+        controller.seek(180.0).unwrap();
        // Clear the NewTrackLoaded reason to simulate natural track end.
        controller.take_end_reason();

@@ -3158,6 +3547,328 @@ mod tests {
        assert!(controller.current_is_audio_episode());
    }

+    /// Build the audio-only episode the background handoff loads: a video item
+    /// played through the native audio path, with a known runtime and a stream
+    /// URL carrying the handoff position.
+    fn audio_only_episode(runtime_seconds: f64) -> MediaItem {
+        MediaItem {
+            id: "ep2".to_string(),
+            item_type: Some("Episode".to_string()),
+            media_type: MediaType::Audio,
+            series_id: Some("series1".to_string()),
+            duration: Some(runtime_seconds),
+            source: MediaSource::Remote {
+                stream_url:
+                    "http://s/Audio/ep2/universal?api_key=k&AudioStreamIndex=2&StartTimeTicks=0"
+                        .to_string(),
+                jellyfin_item_id: "ep2".to_string(),
+            },
+            ..create_test_items(1).remove(0)
+        }
+    }
+
+    /// A flaky connection truncates the progressive mp3 transcode that carries
+    /// background audio-only playback. ExoPlayer sees end-of-input on a stream
+    /// with no reliable length, so it reports STATE_ENDED ten minutes into a
+    /// twenty-five minute episode — indistinguishable, to the player, from the
+    /// real end.
+    ///
+    /// Treating that as "the episode finished" is what the user experiences as
+    /// the episode randomly restarting: playback parks in STATE_ENDED and the
+    /// next play intent (lockscreen, notification, Bluetooth reconnect) seeks an
+    /// ended player to position 0 before playing. The runtime we already know
+    /// says the stream died early, so the decision must be to resume it.
+    #[tokio::test]
+    async fn test_truncated_background_audio_stream_resumes_instead_of_ending() {
+        let controller = PlayerController::default();
+        controller.set_repository(Arc::new(MockEpisodeRepo::season(3)));
+
+        controller
+            .play_queue(vec![audio_only_episode(1500.0)], 0)
+            .unwrap();
+        // The connection dropped 10 minutes into a 25-minute episode.
+        controller.seek(600.0).unwrap();
+        controller.take_end_reason();
+
+        let decision = controller.on_playback_ended().await.unwrap();
+
+        match decision {
+            AutoplayDecision::ResumeStream { position } => {
+                assert_eq!(position, 600.0, "must resume where the stream died");
+            }
+            other => panic!(
+                "a stream that ended 15 minutes short of the runtime must resume, \
+                 not run end-of-episode logic; got {:?}",
+                other
+            ),
+        }
+    }
+
+    /// The handoff stream's timeline starts at the handoff position, so the
+    /// player reports a *relative* position. The runtime it is compared against
+    /// is absolute — the base has to be added back, or every handoff looks like a
+    /// truncation.
+    #[tokio::test]
+    async fn test_truncated_check_uses_the_absolute_position() {
+        let controller = PlayerController::default();
+        controller.set_repository(Arc::new(MockEpisodeRepo::season(3)));
+
+        controller
+            .play_queue(vec![audio_only_episode(1500.0)], 0)
+            .unwrap();
+        // Handed off at 24:00; the stream then played its last 56 seconds out.
+        controller.set_background_audio_base(1440.0);
+        controller.seek(56.0).unwrap();
+        controller.take_end_reason();
+
+        let decision = controller.on_playback_ended().await.unwrap();
+
+        assert!(
+            matches!(decision, AutoplayDecision::ShowNextEpisodePopup { .. }),
+            "24:56 of a 25:00 episode is the real end, not a truncation; got {:?}",
+            decision
+        );
+    }
+
+    /// The resume re-opens the same URL, so a server that is actually gone would
+    /// otherwise end → resume → end forever. After the budget runs out the
+    /// decision falls back to normal end-of-item handling.
+    #[tokio::test]
+    async fn test_repeated_truncation_at_the_same_position_gives_up() {
+        let controller = PlayerController::default();
+        controller.set_repository(Arc::new(MockEpisodeRepo::season(3)));
+
+        controller
+            .play_queue(vec![audio_only_episode(1500.0)], 0)
+            .unwrap();
+        controller.seek(600.0).unwrap();
+
+        for attempt in 1..=stream_end::MAX_STALLED_RESUME_ATTEMPTS {
+            controller.take_end_reason();
+            let decision = controller.on_playback_ended().await.unwrap();
+            assert!(
+                matches!(decision, AutoplayDecision::ResumeStream { .. }),
+                "attempt {} should still resume, got {:?}",
+                attempt,
+                decision
+            );
+        }
+
+        controller.take_end_reason();
+        let decision = controller.on_playback_ended().await.unwrap();
+        assert!(
+            !matches!(decision, AutoplayDecision::ResumeStream { .. }),
+            "a stream stuck at the same position must stop retrying, got {:?}",
+            decision
+        );
+    }
+
+    /// Ordinary music is not covered: its streams are not the length-less
+    /// progressive transcode this guards, and a short track legitimately ends
+    /// well before a stale duration would suggest.
+    #[tokio::test]
+    async fn test_truncation_check_does_not_touch_plain_audio_tracks() {
+        let controller = PlayerController::default();
+
+        let mut items = create_test_items(2);
+        items[0].duration = Some(1500.0);
+        controller.play_queue(items, 0).unwrap();
+        controller.seek(60.0).unwrap();
+        controller.take_end_reason();
+
+        let decision = controller.on_playback_ended().await.unwrap();
+        assert!(
+            matches!(decision, AutoplayDecision::AdvanceToNext),
+            "plain queue audio must keep advancing, got {:?}",
+            decision
+        );
+    }
+
+    /// Music and video stream from URLs that declare their own length (a static
+    /// file with byte ranges, an HLS playlist), so a truncation reaches the
+    /// player as an *error* rather than a phantom end. It is the same network
+    /// failure, and the same recovery applies — the previous behaviour turned it
+    /// into `playerStop()` and silence.
+    #[tokio::test]
+    async fn test_recoverable_error_resumes_a_music_track() {
+        let controller = PlayerController::default();
+
+        let mut items = create_test_items(3);
+        for item in &mut items {
+            item.source = MediaSource::Remote {
+                stream_url: format!("http://s/Audio/{}/stream?Static=true", item.id),
+                jellyfin_item_id: item.id.clone(),
+            };
+        }
+        controller.play_queue(items, 1).unwrap();
+        controller.seek(45.0).unwrap();
+
+        let (position, _) = controller
+            .recoverable_error_resume()
+            .expect("a streamed music track must be resumable after a network error");
+        assert_eq!(position, 45.0);
+    }
+
+    /// The resume must reload the failed track IN PLACE. `play_item` replaces the
+    /// whole queue with a single item, so recovering a track that way would throw
+    /// away the rest of the album — turning a network blip into lost state.
+    #[tokio::test]
+    async fn test_resume_keeps_the_rest_of_the_queue() {
+        let controller = PlayerController::default();
+
+        let mut items = create_test_items(3);
+        for item in &mut items {
+            item.source = MediaSource::Remote {
+                stream_url: format!("http://s/Audio/{}/stream?Static=true", item.id),
+                jellyfin_item_id: item.id.clone(),
+            };
+        }
+        controller.play_queue(items, 1).unwrap();
+
+        controller
+            .resume_stream_at(45.0)
+            .await
+            .expect("resume should succeed");
+
+        let queue = controller.queue.lock_safe();
+        assert_eq!(queue.items().len(), 3, "the queue must survive a resume");
+        assert_eq!(queue.current_index(), Some(1), "still on the same track");
+        assert_eq!(queue.current().unwrap().id, "item_1");
+    }
+
+    /// A seekable stream is re-opened by re-preparing the URL it already has and
+    /// seeking — its timeline is intact, and rewriting the URL would restart a
+    /// transcode session for no reason.
+    #[tokio::test]
+    async fn test_resume_seeks_a_seekable_stream_rather_than_rewriting_its_url() {
+        let controller = PlayerController::default();
+
+        let mut items = create_test_items(1);
+        items[0].source = MediaSource::Remote {
+            stream_url: "http://s/Audio/item_0/stream?Static=true".to_string(),
+            jellyfin_item_id: "item_0".to_string(),
+        };
+        controller.play_queue(items, 0).unwrap();
+
+        controller.resume_stream_at(45.0).await.unwrap();
+
+        match &controller.queue.lock_safe().current().unwrap().source {
+            MediaSource::Remote { stream_url, .. } => {
+                assert_eq!(
+                    stream_url, "http://s/Audio/item_0/stream?Static=true",
+                    "a seekable stream's URL must be left alone"
+                );
+            }
+            other => panic!("expected Remote source, got {:?}", other),
+        }
+        assert_eq!(
+            controller.position(),
+            45.0,
+            "and it must land at the position"
+        );
+    }
+
+    /// Downloaded media cannot fail from the network, and re-opening a local file
+    /// would paper over a real read error.
+    #[tokio::test]
+    async fn test_recoverable_error_ignores_local_media() {
+        let controller = PlayerController::default();
+
+        let mut items = create_test_items(1);
+        items[0].source = MediaSource::Local {
+            file_path: "/music/track.flac".into(),
+            jellyfin_item_id: Some("item_0".to_string()),
+        };
+        controller.play_queue(items, 0).unwrap();
+        controller.seek(45.0).unwrap();
+
+        assert!(controller.recoverable_error_resume().is_none());
+    }
+
+    /// A recoverable error during background audio-only playback is the network,
+    /// not the media — the previous behaviour (surface it, frontend stops the
+    /// player) turned a hiccup into silence. Retrying must also back off, or the
+    /// three attempts are spent inside a second and the outage outlives them.
+    #[tokio::test]
+    async fn test_recoverable_error_during_audio_only_resumes_with_backoff() {
+        let controller = PlayerController::default();
+
+        controller
+            .play_queue(vec![audio_only_episode(1500.0)], 0)
+            .unwrap();
+        controller.seek(600.0).unwrap();
+
+        let mut waits = Vec::new();
+        for attempt in 1..=stream_end::MAX_STALLED_RESUME_ATTEMPTS {
+            let (position, delay) = controller
+                .recoverable_error_resume()
+                .unwrap_or_else(|| panic!("attempt {} should still retry", attempt));
+            assert_eq!(position, 600.0);
+            waits.push(delay);
+        }
+        assert_eq!(waits, vec![2, 4, 6], "the wait must grow between attempts");
+        assert!(
+            controller.recoverable_error_resume().is_none(),
+            "a stream that keeps failing at the same spot must surface the error"
+        );
+    }
+
+    /// Plugin/channel `DirectUrl` sources are somebody else's endpoint with no
+    /// Jellyfin item behind them, so the resume has nothing to re-request.
+    #[tokio::test]
+    async fn test_recoverable_error_ignores_direct_url_playback() {
+        let controller = PlayerController::default();
+        controller.play_queue(create_test_items(2), 0).unwrap();
+
+        assert!(controller.recoverable_error_resume().is_none());
+    }
+
+    /// Re-opening the stream must land where it died and keep playing, with the
+    /// handoff base moved to the new stream's zero so returning to the
+    /// foreground still resolves an absolute position.
+    #[tokio::test]
+    async fn test_resume_truncated_stream_reloads_at_position() {
+        let controller = PlayerController::default();
+
+        controller
+            .play_queue(vec![audio_only_episode(1500.0)], 0)
+            .unwrap();
+        controller.set_background_audio_base(0.0);
+
+        controller
+            .resume_stream_at(600.0)
+            .await
+            .expect("resume should succeed");
+
+        let current = controller
+            .queue
+            .lock_safe()
+            .current()
+            .cloned()
+            .expect("the same item should still be loaded");
+        assert_eq!(current.id, "ep2", "resume must not change the item");
+        match &current.source {
+            MediaSource::Remote { stream_url, .. } => {
+                assert!(
+                    stream_url.contains("StartTimeTicks=6000000000"),
+                    "stream must re-open at 600s, got {}",
+                    stream_url
+                );
+                assert!(
+                    stream_url.contains("AudioStreamIndex=2"),
+                    "the selected audio track must survive the resume, got {}",
+                    stream_url
+                );
+            }
+            other => panic!("expected Remote source, got {:?}", other),
+        }
+        assert_eq!(
+            controller.take_background_audio_base(),
+            600.0,
+            "the re-opened stream's zero is the resume position"
+        );
+    }
+
    /// Foreground video playback keeps the countdown-driven advance: the frontend
    /// owns the navigation there, so the backend must NOT load the next episode
    /// itself (that would race the page transition and double-start playback).
@@ -2,6 +2,7 @@ use super::backend::{PlayerBackend, PlayerError};
 use super::events::{PlayerEventEmitter, PlayerStatusEvent};
 use super::media::{MediaItem, MediaSource};
 use super::state::PlayerState;
+use super::stream_end::ObservedTime;
 use crate::playback_reporting::{EventThrottler, PlaybackOperation, PlaybackReporter};
 use crate::settings::{AudioSettings, VolumeLevel, EQ_BANDS};
 use crate::utils::conversions::{seconds_to_ticks, volume_to_percent};
@@ -26,6 +27,13 @@ pub struct MpvBackend {
    playback_reporter: Arc<TokioMutex<Option<PlaybackReporter>>>,
    position_throttler: Arc<EventThrottler>,
    last_seek_time: Arc<AtomicU64>,
+    /// Last position/duration seen while a file was loaded.
+    ///
+    /// `time-pos` and `duration` are live properties of the *loaded* file: at
+    /// EOF MPV unloads it and both stop resolving, so reading them straight
+    /// through reported 0.0 / unknown exactly when end-of-file handling needed to
+    /// know where playback reached. See [`ObservedTime`].
+    observed: Arc<Mutex<ObservedTime>>,
 }

 struct InternalState {
@@ -139,6 +147,31 @@ impl MpvBackend {
                message: format!("Failed to set initial volume: {:?}", e),
            })?;

+        // Survive a flaky connection instead of dying on it. Without these,
+        // ffmpeg's HTTP demuxer gives up the moment a read fails and MPV raises
+        // EndFile(ERROR) — a blip on wifi kills the track outright. Reconnecting
+        // in the demuxer handles the common case entirely below our level, so
+        // most outages never reach the recovery in `player_recover_stream`.
+        //
+        // Non-fatal: these are ffmpeg-side options whose availability varies with
+        // the libmpv/ffmpeg build, and losing resilience is not a reason to
+        // refuse to play anything (graceful backend init, CLAUDE.md).
+        mpv.set_property(
+            "stream-lavf-o",
+            "reconnect=1,reconnect_streamed=1,reconnect_on_network_error=1,reconnect_delay_max=5",
+        )
+        .unwrap_or_else(|e| {
+            warn!(
+                "[MpvBackend] Could not enable stream reconnection: {:?} — \
+                 playback will not survive network interruptions",
+                e
+            );
+        });
+        mpv.set_property("network-timeout", 15i64)
+            .unwrap_or_else(|e| {
+                warn!("[MpvBackend] Could not set network timeout: {:?}", e);
+            });
+
        let state = Arc::new(Mutex::new(InternalState {
            current_media: None,
            volume: 1.0,
@@ -152,6 +185,7 @@ impl MpvBackend {
            playback_reporter,
            position_throttler,
            last_seek_time: Arc::new(AtomicU64::new(0)),
+            observed: Arc::new(Mutex::new(ObservedTime::default())),
        };

        // Start event loop in background thread
@@ -250,8 +284,22 @@ impl MpvBackend {
                                debug!("[MpvBackend] Player quitting, NOT emitting PlaybackEnded");
                                // Don't emit - player is shutting down
                            } else if reason == MPV_END_FILE_REASON_ERROR {
-                                warn!("[MpvBackend] Track ended with error, NOT emitting PlaybackEnded");
-                                // Don't emit - we should handle errors separately
+                                // NOT PlaybackEnded — the track did not finish, so
+                                // autoplay must not advance. It is an error, and it
+                                // has to be *said*: emitting nothing here left
+                                // playback halted with the UI still showing
+                                // "playing" and no way back. Marked recoverable so
+                                // the frontend echoes it into player_recover_stream,
+                                // which re-opens the stream where it stopped —
+                                // MPV's own reconnect handles shorter blips before
+                                // they ever get this far.
+                                warn!("[MpvBackend] Track ended with an error — reporting as recoverable");
+                                if let Some(emitter) = &event_emitter {
+                                    emitter.emit(PlayerStatusEvent::Error {
+                                        message: "Playback stream failed".to_string(),
+                                        recoverable: true,
+                                    });
+                                }
                            } else {
                                debug!("[MpvBackend] Unknown end file reason {}, NOT emitting PlaybackEnded", reason);
                            }
@@ -283,6 +331,7 @@ impl MpvBackend {
        let reporter_for_position = reporter.clone();
        let throttler_for_position = throttler.clone();
        let last_seek_time_for_position = self.last_seek_time.clone();
+        let observed_for_position = self.observed.clone();

        std::thread::spawn(move || {
            loop {
@@ -294,6 +343,13 @@ impl MpvBackend {
                    mpv_for_position.get_property::<f64>("time-pos"),
                    mpv_for_position.get_property::<f64>("duration"),
                ) {
+                    // Remember it: both properties belong to the *loaded* file and
+                    // stop resolving the instant MPV unloads it at EOF, which is
+                    // exactly when end-of-file handling asks where playback got to.
+                    // Recorded before the post-seek skip below so a track that ends
+                    // right after a seek still reports the seek target, not zero.
+                    observed_for_position.lock_safe().record(pos, dur);
+
                    // Check if we recently seeked - skip position updates briefly after seeks
                    // to avoid "jumping to zero" visual glitches while MPV is seeking
                    let now = SystemTime::now()
@@ -404,6 +460,9 @@ impl PlayerBackend for MpvBackend {
            let mut state = self.state.lock_safe();
            state.current_media = Some(media.clone());
        }
+        // A different file: the previous one's timestamp must not survive as this
+        // one's "last observed" position.
+        self.observed.lock_safe().reset();

        // Load the media file
        self.mpv
@@ -469,6 +528,10 @@ impl PlayerBackend for MpvBackend {
                message: format!("Failed to seek: {:?}", e),
            })?;

+        // The poll thread suppresses updates for 150ms after a seek, so without
+        // this a file ending inside that window would report the pre-seek time.
+        self.observed.lock_safe().record_position(position);
+
        Ok(())
    }

@@ -491,15 +554,26 @@ impl PlayerBackend for MpvBackend {
        Ok(())
    }

+    /// Current position — the live `time-pos`, or the last one observed while a
+    /// file was loaded.
+    ///
+    /// The fallback is the point: `time-pos` is a property of the *loaded* file,
+    /// so at EOF it stops resolving and a bare `unwrap_or(0.0)` reported 0:00 at
+    /// exactly the moment end-of-file handling asks where playback reached.
+    ///
+    /// TRACES: UR-005 | DR-130 | UT-121
    fn position(&self) -> f64 {
-        self.mpv.get_property::<f64>("time-pos").unwrap_or(0.0)
+        let live = self.mpv.get_property::<f64>("time-pos").ok();
+        self.observed.lock_safe().position_or_last(live)
    }

+    /// Total duration — live, or the last one observed. Unloaded at EOF for the
+    /// same reason as `position`.
+    ///
+    /// TRACES: UR-005 | DR-130 | UT-121
    fn duration(&self) -> Option<f64> {
-        self.mpv
-            .get_property::<f64>("duration")
-            .ok()
-            .filter(|d| *d > 0.0)
+        let live = self.mpv.get_property::<f64>("duration").ok();
+        self.observed.lock_safe().duration_or_last(live)
    }

    fn state(&self) -> PlayerState {
@@ -0,0 +1,373 @@
+//! Telling a *finished* stream apart from a *truncated* one.
+//!
+//! TRACES: UR-040 | DR-129 | UT-117
+//!
+//! Background audio-only playback of a video item streams a **progressive mp3
+//! transcode over plain HTTP** (see
+//! `OnlineRepository::build_audio_only_stream_url_for_video`). That response has
+//! no reliable length — a live transcode is chunked — so when the connection
+//! drops mid-episode the data source simply sees end-of-input. ExoPlayer cannot
+//! distinguish that from the real end of the media and reports
+//! `Player.STATE_ENDED`, which the app then treats as "the episode finished".
+//!
+//! The user-visible damage is not the missed advance itself. Playback parks in
+//! ExoPlayer's `STATE_ENDED`, and the next play intent from the lockscreen,
+//! notification or a Bluetooth reconnect goes through media3's
+//! `Util.handlePlayButtonAction`, which seeks an ENDED player to its default
+//! position before playing — so **the episode starts over from 0:00**. On a
+//! flaky connection that reads as "it randomly restarts the episode".
+//!
+//! The player itself has no way to know; the *duration* does. Jellyfin gives us
+//! the item's real runtime, so an end reported well short of it is a truncation,
+//! not a finish — and the right response is to re-open the stream where it died,
+//! which is the "buffer and resume" the user expects.
+
+/// How far short of the item's runtime a stream may end and still count as a
+/// natural finish.
+///
+/// Sized to swallow the two sources of slack in the comparison — the position
+/// poll is up to 250 ms stale, and Jellyfin's reported runtime can disagree with
+/// the transcoded output by a second or two — while staying far below the
+/// minutes-long gap a dropped connection leaves. Erring long is the safe
+/// direction: a false "finished" is the bug we are fixing, whereas a false
+/// "truncated" only re-opens the stream for its last few seconds and then ends
+/// again normally.
+pub const TRUNCATED_STREAM_TOLERANCE_SECS: f64 = 10.0;
+
+/// Consecutive resume attempts allowed at the same position before giving up.
+///
+/// A resume re-opens the same URL, so a server that is genuinely gone would
+/// otherwise end → resume → end forever. Progress past the last attempt resets
+/// the budget (see [`ResumeTracker`]), so this only bounds *stuck* retries.
+pub const MAX_STALLED_RESUME_ATTEMPTS: u32 = 3;
+
+/// Position change that counts as "this is a different playback context" —
+/// either the resume made progress, or a different item is loaded.
+const RESUME_PROGRESS_EPSILON_SECS: f64 = 1.0;
+
+/// Did this end-of-stream happen far enough short of the item's runtime to be a
+/// truncation rather than a finish?
+///
+/// `position` and `duration` must be on the same timeline — for a handoff stream
+/// built with `StartTimeTicks`, that means the *absolute* position (handoff base
+/// + the player's relative position) against the item's full runtime.
+///
+/// An unknown or non-positive `duration` answers `false`: with nothing to
+/// compare against, the reported end is taken at face value (previous behaviour).
+pub fn is_truncated_end(position: f64, duration: Option<f64>, tolerance: f64) -> bool {
+    let Some(duration) = duration else {
+        return false;
+    };
+    if duration <= 0.0 {
+        return false;
+    }
+    position.max(0.0) + tolerance < duration
+}
+
+/// Rewrite an audio-only stream URL to start at `position_seconds`.
+///
+/// Resuming re-opens *the stream we were already playing*, so the URL is edited
+/// in place rather than rebuilt from the repository: every other parameter —
+/// `AudioStreamIndex` (the track the user picked in the video player),
+/// `MediaSourceId`, `api_key` — is carried over untouched, and no network call
+/// is needed to recover from a network failure.
+pub fn with_start_time(url: &str, position_seconds: f64) -> String {
+    let ticks = (position_seconds.max(0.0) * 10_000_000.0) as i64;
+    let param = format!("StartTimeTicks={}", ticks);
+
+    let (base, query) = match url.split_once('?') {
+        Some((base, query)) => (base, query),
+        // No query string at all: the URL was not built by us, but appending the
+        // parameter is still the correct request to make.
+        None => return format!("{}?{}", url, param),
+    };
+
+    let mut replaced = false;
+    let mut parts: Vec<String> = query
+        .split('&')
+        .map(|part| {
+            if part.split('=').next() == Some("StartTimeTicks") {
+                replaced = true;
+                param.clone()
+            } else {
+                part.to_string()
+            }
+        })
+        .collect();
+
+    if !replaced {
+        parts.push(param);
+    }
+
+    format!("{}?{}", base, parts.join("&"))
+}
+
+/// The last playback time actually observed while media was loaded.
+///
+/// Some backends expose position and duration as **live** properties of the
+/// loaded file — MPV's `time-pos` and `duration` stop resolving the moment it
+/// unloads the file at EOF. Reading them straight through means that at exactly
+/// the moment end-of-file handling wants to know where playback got to, the
+/// answer is `0.0` / unknown: the player appears to rewind to 0:00 as it ends.
+///
+/// The polling thread records here, and the accessors fall back to it, so an EOF
+/// reads as the last timestamp rather than as zero.
+#[derive(Debug, Default, Clone, Copy)]
+pub struct ObservedTime {
+    position: f64,
+    duration: Option<f64>,
+}
+
+impl ObservedTime {
+    /// Record a live reading. Non-positive durations are treated as unknown —
+    /// that is how a backend reports "not established yet", not a real zero.
+    pub fn record(&mut self, position: f64, duration: f64) {
+        self.position = position.max(0.0);
+        if duration > 0.0 {
+            self.duration = Some(duration);
+        }
+    }
+
+    /// Record a position alone, e.g. straight after a seek, before the next poll.
+    pub fn record_position(&mut self, position: f64) {
+        self.position = position.max(0.0);
+    }
+
+    /// Forget everything — a different file is loading, and the previous one's
+    /// timestamp must not leak into it.
+    pub fn reset(&mut self) {
+        *self = Self::default();
+    }
+
+    /// The live reading if there is one, else the last observed value.
+    pub fn position_or_last(&self, live: Option<f64>) -> f64 {
+        live.filter(|p| *p >= 0.0).unwrap_or(self.position)
+    }
+
+    /// The live reading if there is one, else the last observed value.
+    pub fn duration_or_last(&self, live: Option<f64>) -> Option<f64> {
+        live.filter(|d| *d > 0.0).or(self.duration)
+    }
+}
+
+/// Budget for consecutive resume attempts that make no progress.
+///
+/// Held by the player controller across ends of the *same* stream. Any position
+/// change larger than [`RESUME_PROGRESS_EPSILON_SECS`] — the resume played on,
+/// or a different item was loaded — is a fresh context and refills the budget.
+#[derive(Debug, Default)]
+pub struct ResumeTracker {
+    last_position: Option<f64>,
+    attempts: u32,
+}
+
+impl ResumeTracker {
+    /// Record an attempt at `position`, returning its 1-based number — or `None`
+    /// once the budget is spent. Callers use the number to back off: a stream
+    /// that failed twice at the same spot is waiting on something slower than an
+    /// immediate retry can outrun.
+    pub fn allow_attempt(&mut self, position: f64) -> Option<u32> {
+        let progressed = match self.last_position {
+            Some(last) => (position - last).abs() > RESUME_PROGRESS_EPSILON_SECS,
+            None => true,
+        };
+        if progressed {
+            self.attempts = 0;
+        }
+        self.last_position = Some(position);
+        self.attempts += 1;
+        (self.attempts <= MAX_STALLED_RESUME_ATTEMPTS).then_some(self.attempts)
+    }
+
+    /// Forget the budget — a new item is playing, so nothing is stuck.
+    pub fn reset(&mut self) {
+        self.last_position = None;
+        self.attempts = 0;
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_end_near_duration_is_a_natural_finish() {
+        // Episode runtime 25:00, stream ended at 24:56 — that is the end.
+        assert!(!is_truncated_end(
+            1496.0,
+            Some(1500.0),
+            TRUNCATED_STREAM_TOLERANCE_SECS
+        ));
+    }
+
+    #[test]
+    fn test_end_far_short_of_duration_is_truncated() {
+        // Episode runtime 25:00, stream died at 10:00 — the connection dropped.
+        assert!(is_truncated_end(
+            600.0,
+            Some(1500.0),
+            TRUNCATED_STREAM_TOLERANCE_SECS
+        ));
+    }
+
+    #[test]
+    fn test_unknown_duration_is_taken_at_face_value() {
+        // Nothing to compare against: keep the previous end-of-track behaviour
+        // rather than resuming a stream that may really have finished.
+        assert!(!is_truncated_end(
+            600.0,
+            None,
+            TRUNCATED_STREAM_TOLERANCE_SECS
+        ));
+        assert!(!is_truncated_end(
+            600.0,
+            Some(0.0),
+            TRUNCATED_STREAM_TOLERANCE_SECS
+        ));
+    }
+
+    #[test]
+    fn test_tolerance_boundary() {
+        // Exactly one tolerance short still counts as finished, so poll staleness
+        // and runtime rounding never fabricate a truncation.
+        assert!(!is_truncated_end(1490.0, Some(1500.0), 10.0));
+        assert!(is_truncated_end(1489.0, Some(1500.0), 10.0));
+    }
+
+    #[test]
+    fn test_with_start_time_replaces_existing_ticks() {
+        let url = "http://s/Audio/ep2/universal?api_key=k&AudioStreamIndex=2&StartTimeTicks=1200000000&Container=mp3";
+        let out = with_start_time(url, 600.0);
+        assert_eq!(
+            out,
+            "http://s/Audio/ep2/universal?api_key=k&AudioStreamIndex=2&StartTimeTicks=6000000000&Container=mp3"
+        );
+    }
+
+    #[test]
+    fn test_with_start_time_appends_when_absent() {
+        // The next-episode stream is built without StartTimeTicks.
+        let url = "http://s/Audio/ep3/universal?api_key=k&AudioStreamIndex=0";
+        let out = with_start_time(url, 90.0);
+        assert_eq!(
+            out,
+            "http://s/Audio/ep3/universal?api_key=k&AudioStreamIndex=0&StartTimeTicks=900000000"
+        );
+    }
+
+    #[test]
+    fn test_with_start_time_preserves_selected_audio_track() {
+        // The whole point of editing the URL instead of rebuilding it: the track
+        // the user chose in the video player survives the resume.
+        let url = "http://s/Audio/ep2/universal?AudioStreamIndex=3&MediaSourceId=src-1";
+        let out = with_start_time(url, 10.0);
+        assert!(out.contains("AudioStreamIndex=3"));
+        assert!(out.contains("MediaSourceId=src-1"));
+    }
+
+    #[test]
+    fn test_with_start_time_without_query() {
+        assert_eq!(
+            with_start_time("http://s/Audio/ep2/universal", 1.0),
+            "http://s/Audio/ep2/universal?StartTimeTicks=10000000"
+        );
+    }
+
+    /// The bug: MPV unloads the file at EOF, so `time-pos` stops resolving and a
+    /// straight read reports 0.0 — the position collapses to zero at precisely
+    /// the moment end-of-file handling needs to know where playback reached.
+    #[test]
+    fn test_eof_reads_as_the_last_observed_timestamp() {
+        let mut observed = ObservedTime::default();
+        observed.record(178.0, 180.0);
+
+        // The file is gone: both live properties fail.
+        assert_eq!(observed.position_or_last(None), 178.0);
+        assert_eq!(observed.duration_or_last(None), Some(180.0));
+    }
+
+    #[test]
+    fn test_live_readings_win_while_the_file_is_loaded() {
+        let mut observed = ObservedTime::default();
+        observed.record(178.0, 180.0);
+
+        assert_eq!(observed.position_or_last(Some(12.0)), 12.0);
+        assert_eq!(observed.duration_or_last(Some(240.0)), Some(240.0));
+    }
+
+    #[test]
+    fn test_unestablished_duration_is_not_recorded_as_zero() {
+        let mut observed = ObservedTime::default();
+        // A backend reports 0.0 for "duration not known yet", not a real zero.
+        observed.record(5.0, 0.0);
+        assert_eq!(observed.duration_or_last(None), None);
+        assert_eq!(observed.position_or_last(None), 5.0);
+
+        observed.record(6.0, 180.0);
+        assert_eq!(observed.duration_or_last(Some(0.0)), Some(180.0));
+    }
+
+    #[test]
+    fn test_reset_stops_the_previous_file_leaking_into_the_next() {
+        let mut observed = ObservedTime::default();
+        observed.record(178.0, 180.0);
+        observed.reset();
+
+        assert_eq!(observed.position_or_last(None), 0.0);
+        assert_eq!(observed.duration_or_last(None), None);
+    }
+
+    #[test]
+    fn test_seek_updates_the_last_position_before_the_next_poll() {
+        let mut observed = ObservedTime::default();
+        observed.record(10.0, 180.0);
+        observed.record_position(120.0);
+
+        assert_eq!(observed.position_or_last(None), 120.0);
+        assert_eq!(
+            observed.duration_or_last(None),
+            Some(180.0),
+            "seeking does not change how long the file is"
+        );
+    }
+
+    #[test]
+    fn test_resume_tracker_bounds_stalled_retries() {
+        let mut tracker = ResumeTracker::default();
+        // Same position over and over: the stream is not recovering.
+        for n in 1..=MAX_STALLED_RESUME_ATTEMPTS {
+            assert_eq!(
+                tracker.allow_attempt(600.0),
+                Some(n),
+                "attempts are numbered so callers can back off"
+            );
+        }
+        assert_eq!(
+            tracker.allow_attempt(600.0),
+            None,
+            "a stream that ends at the same position every time must stop retrying"
+        );
+    }
+
+    #[test]
+    fn test_resume_tracker_refills_after_progress() {
+        let mut tracker = ResumeTracker::default();
+        for _ in 0..MAX_STALLED_RESUME_ATTEMPTS {
+            tracker.allow_attempt(600.0);
+        }
+        assert_eq!(tracker.allow_attempt(600.0), None);
+        // The next drop happened further in — the resumes are working, so the
+        // budget must not be exhausted by earlier trouble.
+        assert_eq!(tracker.allow_attempt(900.0), Some(1));
+    }
+
+    #[test]
+    fn test_resume_tracker_reset() {
+        let mut tracker = ResumeTracker::default();
+        for _ in 0..=MAX_STALLED_RESUME_ATTEMPTS {
+            tracker.allow_attempt(600.0);
+        }
+        tracker.reset();
+        assert_eq!(tracker.allow_attempt(600.0), Some(1));
+    }
+}
@@ -0,0 +1,95 @@
+//! Device-profile policy: turning what a device *reports* about its audio
+//! output into the constraints we send Jellyfin.
+//!
+//! The platform layer reports raw facts (what `MediaCodecList` enumerates, how
+//! many channels the current audio route accepts); deciding what those facts
+//! mean for a `DeviceProfile` is domain logic and lives here, on the Rust side
+//! of the boundary, where it is testable without a device.
+
+/// Channel count assumed when the platform cannot tell us — every audio route
+/// can voice stereo, so it is the only safe floor.
+const FALLBACK_AUDIO_CHANNELS: u32 = 2;
+
+/// Upper bound we are willing to claim. Jellyfin profiles top out at 7.1, and a
+/// nonsense reading from a driver should not become a nonsense profile.
+const MAX_SUPPORTED_AUDIO_CHANNELS: u32 = 8;
+
+/// Decide the `MaxAudioChannels` to advertise, given what the current audio
+/// route reported.
+///
+/// Without this constraint Jellyfin is free to direct-play a 5.1 or 7.1 track to
+/// a sink that only has two channels. What the user hears then is device
+/// dependent and rarely correct — a failed `AudioSink` configuration (silence),
+/// or centre-channel dialogue folded away to near-inaudibility. Naming the real
+/// channel count makes the server downmix instead, which is always audible.
+///
+/// A missing or zero reading means "route not established yet", not "no audio":
+/// fall back to stereo rather than claiming a capability we have not seen.
+///
+/// TRACES: UR-004 | DR-141 | UT-141
+pub fn clamp_max_audio_channels(reported: Option<u32>) -> u32 {
+    match reported {
+        Some(channels) if channels >= 1 => channels.min(MAX_SUPPORTED_AUDIO_CHANNELS),
+        _ => FALLBACK_AUDIO_CHANNELS,
+    }
+}
+
+/// The channel cap for this device, reading the platform's report where one
+/// exists.
+///
+/// TRACES: UR-004 | DR-141 | UT-141
+pub fn max_audio_channels() -> u32 {
+    #[cfg(target_os = "android")]
+    let reported = crate::player::get_detected_codecs().and_then(|(_, _, channels)| channels);
+
+    // Desktop plays video through the WebKitGTK HTML5 <video> element, which we
+    // do not interrogate for a channel count; stereo is the safe assumption.
+    #[cfg(not(target_os = "android"))]
+    let reported: Option<u32> = None;
+
+    clamp_max_audio_channels(reported)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn an_unknown_route_falls_back_to_stereo() {
+        // Codec detection has not run yet, or the platform has no answer. Never
+        // claim surround we have not seen — every sink can do stereo.
+        assert_eq!(clamp_max_audio_channels(None), 2);
+    }
+
+    #[test]
+    fn a_zero_reading_is_not_a_capability() {
+        // A route that has not been established reports 0; taking that literally
+        // would advertise a device with no audio at all.
+        assert_eq!(clamp_max_audio_channels(Some(0)), 2);
+    }
+
+    #[test]
+    fn a_stereo_sink_is_reported_as_stereo() {
+        // The phone speaker / Bluetooth headset case: the server must downmix
+        // 5.1 rather than direct-play it.
+        assert_eq!(clamp_max_audio_channels(Some(2)), 2);
+    }
+
+    #[test]
+    fn a_surround_route_keeps_its_channels() {
+        // HDMI to an AVR: 5.1 and 7.1 direct play stay available.
+        assert_eq!(clamp_max_audio_channels(Some(6)), 6);
+        assert_eq!(clamp_max_audio_channels(Some(8)), 8);
+    }
+
+    #[test]
+    fn an_absurd_reading_is_capped_rather_than_forwarded() {
+        // Some drivers report the AudioTrack maximum rather than the route's.
+        assert_eq!(clamp_max_audio_channels(Some(32)), 8);
+    }
+
+    #[test]
+    fn a_mono_route_is_taken_at_its_word() {
+        assert_eq!(clamp_max_audio_channels(Some(1)), 1);
+    }
+}
@@ -41,12 +41,34 @@ impl HybridRepository {
        }
    }

+    /// The signed-in user this repository acts for.
+    ///
+    /// TRACES: UR-069 | DR-120
+    pub fn user_id(&self) -> &str {
+        self.online.user_id()
+    }
+
    /// Download raw bytes from a URL using the shared authenticated HTTP client.
    /// Delegates to online repository for connection reuse and proper auth.
    pub async fn download_bytes(&self, url: &str) -> Result<Vec<u8>, String> {
        self.online.download_bytes(url).await
    }

+    /// Remove catalog entries the server no longer has. Cache-only, so it goes
+    /// straight to the offline repository. Callers must only invoke this after a
+    /// crawl in which every library succeeded — see
+    /// `OfflineRepository::prune_stale_catalog` for why a partial crawl must not
+    /// sweep.
+    ///
+    /// TRACES: UR-065 | DR-110
+    pub async fn prune_stale_catalog(
+        &self,
+        cutoff: &str,
+        item_types: &[String],
+    ) -> Result<usize, RepoError> {
+        self.offline.prune_stale_catalog(cutoff, item_types).await
+    }
+
    /// Query the JRay plugin for actors on screen at time `t`. Online-only
    /// (the plugin lives on the Jellyfin server); empty when JRay isn't present.
    pub async fn get_jray_actors(
@@ -113,6 +135,41 @@ impl HybridRepository {
            .await
    }

+    /// Favourites held locally, without touching the server. Backs the instant
+    /// leg of the two-phase favourites read in the command layer.
+    ///
+    /// TRACES: UR-067 | DR-115
+    pub async fn get_favorites_cache_only(
+        &self,
+        scope: SearchScope,
+        options: Option<GetItemsOptions>,
+    ) -> Result<SearchResult, RepoError> {
+        let offline = Arc::clone(&self.offline);
+        self.cache_with_timeout(async move { offline.get_favorites(scope, options).await })
+            .await
+    }
+
+    /// Favourites straight from the server, persisted to the cache on the way
+    /// through — which is also what mirrors their favourite flags into
+    /// `user_data` (DR-114), so the next offline read agrees with the server.
+    ///
+    /// TRACES: UR-067 | DR-115
+    pub async fn get_favorites_server_only(
+        &self,
+        scope: SearchScope,
+        options: Option<GetItemsOptions>,
+    ) -> Result<SearchResult, RepoError> {
+        let result = self.online.get_favorites(scope, options).await?;
+        if !result.items.is_empty() {
+            // Favourites span libraries, so there is no single parent to file
+            // them under; the parent id is only used for stub rows.
+            if let Err(e) = self.offline.save_to_cache("favorites", &result.items).await {
+                debug!("[HybridRepo] Failed to cache favourites: {:?}", e);
+            }
+        }
+        Ok(result)
+    }
+
    /// Fetch a folder's items from the live server and persist them to the
    /// offline cache synchronously (unlike `get_items`, which saves in a
    /// fire-and-forget background task after a 100ms cache race).
@@ -755,6 +812,11 @@ impl MediaRepository for HybridRepository {
        self.online.clear_watch_history(item_id).await
    }

+    async fn mark_played(&self, item_id: &str) -> Result<(), RepoError> {
+        // Write operations go directly to server
+        self.online.mark_played(item_id).await
+    }
+
    async fn get_person(&self, person_id: &str) -> Result<MediaItem, RepoError> {
        let offline = Arc::clone(&self.offline);
        let online = Arc::clone(&self.online);
@@ -790,6 +852,41 @@ impl MediaRepository for HybridRepository {
        self.parallel_race(cache_future, server_future).await
    }

+    /// TRACES: UR-067 | DR-115
+    async fn get_favorites(
+        &self,
+        scope: SearchScope,
+        options: Option<GetItemsOptions>,
+    ) -> Result<SearchResult, RepoError> {
+        let cache_result = self.get_favorites_cache_only(scope, options.clone()).await;
+
+        // Downloads-only gate: with "Show all server media" off, an empty local
+        // result means "nothing favourited is on this device" and is
+        // authoritative. Falling through to the server here would re-pad the
+        // page with the full favourited catalog and defeat the filter (DR-080).
+        if !crate::repository::offline::include_catalog_browse() {
+            if let Ok(data) = &cache_result {
+                return Ok(data.clone());
+            }
+        }
+
+        if let Ok(data) = &cache_result {
+            if data.has_content() {
+                return Ok(data.clone());
+            }
+        }
+
+        // Cache miss — answer from the server, *saving through* on the way back.
+        // Every other read path persists what it fetches; skipping it here would
+        // mean the favourites page re-queries the server on every visit and the
+        // offline mirror (DR-114) never learns about favourites marked
+        // elsewhere, since this path is what fills it on a fresh install.
+        match self.get_favorites_server_only(scope, options).await {
+            Ok(data) => Ok(data),
+            Err(e) => cache_result.or(Err(e)),
+        }
+    }
+
    async fn get_similar_items(
        &self,
        item_id: &str,
@@ -1133,10 +1230,22 @@ mod tests {
            unimplemented!()
        }

+        async fn get_favorites(
+            &self,
+            _scope: SearchScope,
+            _options: Option<GetItemsOptions>,
+        ) -> Result<SearchResult, RepoError> {
+            unimplemented!()
+        }
+
        async fn clear_watch_history(&self, _item_id: &str) -> Result<(), RepoError> {
            unimplemented!()
        }

+        async fn mark_played(&self, _item_id: &str) -> Result<(), RepoError> {
+            unimplemented!()
+        }
+
        async fn get_person(&self, _person_id: &str) -> Result<MediaItem, RepoError> {
            unimplemented!()
        }
@@ -1395,10 +1504,22 @@ mod tests {
            unimplemented!()
        }

+        async fn get_favorites(
+            &self,
+            _scope: SearchScope,
+            _options: Option<GetItemsOptions>,
+        ) -> Result<SearchResult, RepoError> {
+            unimplemented!()
+        }
+
        async fn clear_watch_history(&self, _item_id: &str) -> Result<(), RepoError> {
            unimplemented!()
        }

+        async fn mark_played(&self, _item_id: &str) -> Result<(), RepoError> {
+            unimplemented!()
+        }
+
        async fn get_person(&self, _person_id: &str) -> Result<MediaItem, RepoError> {
            unimplemented!()
        }
@@ -1,3 +1,4 @@
+pub mod device_profile;
 pub mod hybrid;
 pub mod offline;
 pub mod online;
@@ -212,6 +213,20 @@ pub trait MediaRepository: Send + Sync {
    /// Unmark item as favorite
    async fn unmark_favorite(&self, item_id: &str) -> Result<(), RepoError>;

+    /// Everything the viewer has favourited, across every library.
+    ///
+    /// Separate from `get_items` because favourites span libraries and
+    /// `get_items` is `ParentId`-shaped. `scope` is the opaque enum the
+    /// frontend sends; this layer expands it to item types (DR-063) so no
+    /// Jellyfin taxonomy is needed on the other side of the IPC boundary.
+    ///
+    /// TRACES: UR-067 | DR-115, JA-033 | UT-100, UT-101
+    async fn get_favorites(
+        &self,
+        scope: SearchScope,
+        options: Option<GetItemsOptions>,
+    ) -> Result<SearchResult, RepoError>;
+
    /// Erase the viewer's watch history for an item: clear its played flag and
    /// its resume position. On a container (series, season) this applies to
    /// everything inside it, so a series is returned to "never watched" and
@@ -220,6 +235,14 @@ pub trait MediaRepository: Send + Sync {
    /// TRACES: UR-064 | DR-106
    async fn clear_watch_history(&self, item_id: &str) -> Result<(), RepoError>;

+    /// Mark an item played — the inverse of `clear_watch_history`. Needed by the
+    /// sync-queue drain, which replays `mark_played` rows queued while the
+    /// server was unreachable; reporting a stop at a made-up position was the
+    /// previous stand-in and does not set the played flag reliably.
+    ///
+    /// TRACES: UR-025 | DR-131 | JA-035
+    async fn mark_played(&self, item_id: &str) -> Result<(), RepoError>;
+
    /// Get person details
    async fn get_person(&self, person_id: &str) -> Result<MediaItem, RepoError>;

@@ -48,6 +48,12 @@ pub struct OnlineRepository {
 }

 impl OnlineRepository {
+    /// The signed-in user these requests are made as. Needed by the favourites
+    /// drain, which reads this user's queued rows. TRACES: UR-069 | DR-120
+    pub fn user_id(&self) -> &str {
+        &self.user_id
+    }
+
    pub fn new(
        http_client: Arc<HttpClient>,
        server_url: String,
@@ -376,6 +382,8 @@ impl OnlineRepository {
    /// forces the server to transcode the whole file before playback can begin —
    /// which manifests as playback never starting. `StartTimeTicks` makes the
    /// server begin the transcode at the requested position.
+    ///
+    /// TRACES: UR-004 | DR-140 | UT-130
    pub async fn get_video_stream_url(
        &self,
        item_id: &str,
@@ -386,9 +394,6 @@ impl OnlineRepository {
        // Convert seconds to ticks (10,000,000 ticks per second)
        let start_time_ticks = start_time_seconds.map(|seconds| (seconds * 10_000_000.0) as i64);

-        // Use provided audio stream index, or default to 0
-        let audio_index = audio_stream_index.unwrap_or(0).to_string();
-
        // Build an HLS transcode URL. VideoCodec lists h264 first so the server
        // transcodes HEVC/10-bit/unsupported sources to h264 the WebView can decode.
        let mut params = vec![
@@ -396,16 +401,28 @@ impl OnlineRepository {
            ("DeviceId", "jellytau-tauri".to_string()),
            ("VideoCodec", "h264".to_string()),
            ("AudioCodec", "aac".to_string()),
-            ("AudioStreamIndex", audio_index),
            ("MaxStreamingBitrate", "20000000".to_string()),
            ("VideoBitrate", "18000000".to_string()),
            ("AudioBitrate", "384000".to_string()),
-            ("TranscodingMaxAudioChannels", "2".to_string()),
+            (
+                "TranscodingMaxAudioChannels",
+                super::device_profile::max_audio_channels().to_string(),
+            ),
            ("SegmentContainer", "ts".to_string()),
            ("TranscodingContainer", "ts".to_string()),
            ("TranscodingProtocol", "hls".to_string()),
        ];

+        // Only pin an audio track when the user actually picked one. Jellyfin's
+        // `MediaStream.Index` is global across *all* streams in a media source, so
+        // index 0 is the video stream on virtually every file — defaulting to 0
+        // asks the server to transcode the video stream as the audio track, which
+        // yields a picture with no sound. Omitting the param lets the server use
+        // the source's `DefaultAudioStreamIndex`.
+        if let Some(index) = audio_stream_index {
+            params.push(("AudioStreamIndex", index.to_string()));
+        }
+
        if let Some(source_id) = media_source_id {
            params.push(("MediaSourceId", source_id.to_string()));
        }
@@ -432,7 +449,7 @@ impl OnlineRepository {
    /// Get an **audio-only** stream URL for a *video* item, for the
    /// background-audio handoff (UR-040).
    ///
-    /// TRACES: UR-040 | JA-032 | UT-059
+    /// TRACES: UR-040 | JA-032, DR-140 | UT-059, UT-130
    ///
    /// This deliberately targets `/Audio/{id}/universal`, NOT the video stream:
    /// the server extracts/transcodes only the item's audio track and streams
@@ -457,13 +474,10 @@ impl OnlineRepository {
        start_time_seconds: Option<f64>,
        audio_stream_index: Option<i32>,
    ) -> Result<String, RepoError> {
-        let audio_index = audio_stream_index.unwrap_or(0).to_string();
-
        let mut params = vec![
            ("UserId", self.user_id.clone()),
            ("api_key", self.access_token.clone()),
            ("DeviceId", "jellytau-tauri".to_string()),
-            ("AudioStreamIndex", audio_index),
            // Progressive mp3 over HTTP — ExoPlayer-friendly; no HLS/ts.
            ("Container", "mp3".to_string()),
            ("AudioCodec", "mp3".to_string()),
@@ -472,6 +486,12 @@ impl OnlineRepository {
            ("MaxStreamingBitrate", "384000".to_string()),
        ];

+        // Carry the track over only if one was actually selected — index 0 is the
+        // video stream, not "the first audio track" (see `get_video_stream_url`).
+        if let Some(index) = audio_stream_index {
+            params.push(("AudioStreamIndex", index.to_string()));
+        }
+
        if let Some(source_id) = media_source_id {
            params.push(("MediaSourceId", source_id.to_string()));
        }
@@ -560,6 +580,138 @@ struct JellyfinItem {
    media_streams: Option<Vec<JellyfinMediaStream>>,
    media_sources: Option<Vec<JellyfinMediaSource>>,
    people: Option<Vec<crate::repository::types::Person>>,
+    user_data: Option<JellyfinUserData>,
+}
+
+/// Per-user state Jellyfin attaches to an item (favourite, played, resume).
+///
+/// Returned on every `/Users/{uid}/Items*` response; we additionally name
+/// `UserData` in the `Fields=` list so the shape is explicit rather than
+/// dependent on the server's default field set.
+///
+/// TRACES: UR-069 | DR-113, JA-034 | UT-099
+#[derive(Debug, Deserialize, Clone)]
+#[serde(rename_all = "PascalCase")]
+struct JellyfinUserData {
+    playback_position_ticks: Option<i64>,
+    #[serde(rename = "Played")]
+    is_played: Option<bool>,
+    is_favorite: Option<bool>,
+    play_count: Option<i32>,
+    last_played_date: Option<String>,
+}
+
+impl From<JellyfinUserData> for UserData {
+    fn from(jf: JellyfinUserData) -> Self {
+        UserData {
+            playback_position_ticks: jf.playback_position_ticks,
+            playback_position_ms: jf.playback_position_ticks.map(crate::domain::ticks_to_ms),
+            is_played: jf.is_played,
+            is_favorite: jf.is_favorite,
+            play_count: jf.play_count,
+            last_played_date: jf.last_played_date,
+            playback_context_type: None,
+            playback_context_id: None,
+        }
+    }
+}
+
+/// Build the Jellyfin endpoint for a folder listing.
+///
+/// Extracted from `get_items` so the query it produces — in particular the
+/// favourites filter — can be asserted without standing up an HTTP server.
+///
+/// TRACES: UR-007, UR-067 | DR-116 | UT-104
+fn build_get_items_endpoint(
+    user_id: &str,
+    parent_id: &str,
+    options: Option<&GetItemsOptions>,
+) -> String {
+    let mut endpoint = format!("/Users/{}/Items?ParentId={}", user_id, parent_id);
+
+    if let Some(opts) = options {
+        if let Some(limit) = opts.limit {
+            endpoint.push_str(&format!("&Limit={}", limit));
+        }
+        if let Some(start_index) = opts.start_index {
+            endpoint.push_str(&format!("&StartIndex={}", start_index));
+        }
+        if let Some(types) = &opts.include_item_types {
+            endpoint.push_str(&format!("&IncludeItemTypes={}", types.join(",")));
+        }
+        if let Some(sort_by) = &opts.sort_by {
+            endpoint.push_str(&format!("&SortBy={}", sort_by));
+        }
+        if let Some(sort_order) = &opts.sort_order {
+            endpoint.push_str(&format!("&SortOrder={}", sort_order));
+        }
+        if let Some(recursive) = opts.recursive {
+            endpoint.push_str(&format!("&Recursive={}", recursive));
+        }
+        if let Some(genres) = &opts.genres {
+            if !genres.is_empty() {
+                // Genre names may contain spaces/ampersands, so percent-encode each.
+                let encoded: Vec<String> = genres
+                    .iter()
+                    .map(|g| urlencoding::encode(g).into_owned())
+                    .collect();
+                endpoint.push_str(&format!("&Genres={}", encoded.join("|")));
+            }
+        }
+        // TRACES: UR-067 | DR-116 | UT-104
+        if opts.favorites_only == Some(true) {
+            endpoint.push_str("&Filters=IsFavorite");
+        }
+    }
+
+    // Request image fields for list views (People only needed in get_item
+    // detail view). Genres is needed so cached items carry their genres,
+    // which lets the offline store derive genre lists + per-genre counts.
+    endpoint
+        .push_str("&Fields=BackdropImageTags,ParentBackdropImageTags,Genres,PremiereDate,UserData");
+    endpoint
+}
+
+/// Build the Jellyfin endpoint for a favourites listing.
+///
+/// Pulled out of `get_favorites` so the query can be asserted without an HTTP
+/// server. `scope` is expanded here — `SearchScope::All` yields `None`, and the
+/// `IncludeItemTypes` filter is then **omitted entirely** rather than sent as a
+/// union, which would silently drop every type nobody enumerated (see
+/// `SearchScope::item_types`).
+///
+/// TRACES: UR-067 | DR-115, JA-033 | UT-100
+fn build_favorites_endpoint(
+    user_id: &str,
+    scope: SearchScope,
+    options: Option<&GetItemsOptions>,
+) -> String {
+    let mut endpoint = format!("/Users/{}/Items?Filters=IsFavorite&Recursive=true", user_id);
+
+    if let Some(types) = scope.item_types() {
+        endpoint.push_str(&format!("&IncludeItemTypes={}", types.join(",")));
+    }
+
+    // Jellyfin has no "date favourited", so name order is the only stable sort
+    // available; callers may still override it.
+    let sort_by = options
+        .and_then(|o| o.sort_by.as_deref())
+        .unwrap_or("SortName");
+    let sort_order = options
+        .and_then(|o| o.sort_order.as_deref())
+        .unwrap_or("Ascending");
+    endpoint.push_str(&format!("&SortBy={}&SortOrder={}", sort_by, sort_order));
+
+    if let Some(limit) = options.and_then(|o| o.limit) {
+        endpoint.push_str(&format!("&Limit={}", limit));
+    }
+    if let Some(start_index) = options.and_then(|o| o.start_index) {
+        endpoint.push_str(&format!("&StartIndex={}", start_index));
+    }
+
+    endpoint
+        .push_str("&Fields=BackdropImageTags,ParentBackdropImageTags,Genres,PremiereDate,UserData");
+    endpoint
 }

 // ImageTags from Jellyfin API - can be a HashMap with various image type keys
@@ -653,7 +805,9 @@ impl JellyfinItem {
            series_name: self.series_name,
            season_id: self.season_id,
            season_name: self.season_name,
-            user_data: None, // User data not included in basic item responses
+            // Favourite/played/resume state as the server sees it. TRACES:
+            // UR-069 | DR-113, JA-034
+            user_data: self.user_data.map(UserData::from),
            media_streams: self.media_streams.map(|streams| {
                streams
                    .into_iter()
@@ -728,43 +882,7 @@ impl MediaRepository for OnlineRepository {
        parent_id: &str,
        options: Option<GetItemsOptions>,
    ) -> Result<SearchResult, RepoError> {
-        let mut endpoint = format!("/Users/{}/Items?ParentId={}", self.user_id, parent_id);
-
-        if let Some(opts) = options {
-            if let Some(limit) = opts.limit {
-                endpoint.push_str(&format!("&Limit={}", limit));
-            }
-            if let Some(start_index) = opts.start_index {
-                endpoint.push_str(&format!("&StartIndex={}", start_index));
-            }
-            if let Some(types) = opts.include_item_types {
-                endpoint.push_str(&format!("&IncludeItemTypes={}", types.join(",")));
-            }
-            if let Some(sort_by) = opts.sort_by {
-                endpoint.push_str(&format!("&SortBy={}", sort_by));
-            }
-            if let Some(sort_order) = opts.sort_order {
-                endpoint.push_str(&format!("&SortOrder={}", sort_order));
-            }
-            if let Some(recursive) = opts.recursive {
-                endpoint.push_str(&format!("&Recursive={}", recursive));
-            }
-            if let Some(genres) = opts.genres {
-                if !genres.is_empty() {
-                    // Genre names may contain spaces/ampersands, so percent-encode each.
-                    let encoded: Vec<String> = genres
-                        .iter()
-                        .map(|g| urlencoding::encode(g).into_owned())
-                        .collect();
-                    endpoint.push_str(&format!("&Genres={}", encoded.join("|")));
-                }
-            }
-        }
-
-        // Request image fields for list views (People only needed in get_item
-        // detail view). Genres is needed so cached items carry their genres,
-        // which lets the offline store derive genre lists + per-genre counts.
-        endpoint.push_str("&Fields=BackdropImageTags,ParentBackdropImageTags,Genres,PremiereDate");
+        let endpoint = build_get_items_endpoint(&self.user_id, parent_id, options.as_ref());

        let response: ItemsResponse = self.get_json(&endpoint).await?;

@@ -779,7 +897,7 @@ impl MediaRepository for OnlineRepository {
    }

    async fn get_item(&self, item_id: &str) -> Result<MediaItem, RepoError> {
-        let endpoint = format!("/Users/{}/Items/{}?Fields=BackdropImageTags,ParentBackdropImageTags,People,MediaStreams,MediaSources,PremiereDate", self.user_id, item_id);
+        let endpoint = format!("/Users/{}/Items/{}?Fields=BackdropImageTags,ParentBackdropImageTags,People,MediaStreams,MediaSources,PremiereDate,UserData", self.user_id, item_id);

        let item: JellyfinItem = self.get_json(&endpoint).await?;
        let media_item = item.to_media_item(self.user_id.clone());
@@ -794,7 +912,7 @@ impl MediaRepository for OnlineRepository {
    ) -> Result<Vec<MediaItem>, RepoError> {
        let limit_str = limit.unwrap_or(16);
        let endpoint = format!(
-            "/Users/{}/Items/Latest?ParentId={}&Limit={}&Fields=BackdropImageTags,ParentBackdropImageTags",
+            "/Users/{}/Items/Latest?ParentId={}&Limit={}&Fields=BackdropImageTags,ParentBackdropImageTags,UserData",
            self.user_id, parent_id, limit_str
        );

@@ -812,7 +930,7 @@ impl MediaRepository for OnlineRepository {
    ) -> Result<Vec<MediaItem>, RepoError> {
        let limit_str = limit.unwrap_or(16);
        let mut endpoint = format!(
-            "/Users/{}/Items/Resume?Limit={}&MediaTypes=Video&Fields=BackdropImageTags,ParentBackdropImageTags",
+            "/Users/{}/Items/Resume?Limit={}&MediaTypes=Video&Fields=BackdropImageTags,ParentBackdropImageTags,UserData",
            self.user_id, limit_str
        );

@@ -835,7 +953,7 @@ impl MediaRepository for OnlineRepository {
    ) -> Result<Vec<MediaItem>, RepoError> {
        let limit_str = limit.unwrap_or(16);
        let mut endpoint = format!(
-            "/Shows/NextUp?UserId={}&Limit={}&Fields=BackdropImageTags,ParentBackdropImageTags",
+            "/Shows/NextUp?UserId={}&Limit={}&Fields=BackdropImageTags,ParentBackdropImageTags,UserData",
            self.user_id, limit_str
        );

@@ -859,7 +977,7 @@ impl MediaRepository for OnlineRepository {
        // Fetch more items to account for grouping reducing the count
        let fetch_limit = limit_val * 3;
        let endpoint = format!(
-            "/Users/{}/Items?SortBy=DatePlayed&SortOrder=Descending&IncludeItemTypes=Audio&Limit={}&Recursive=true&Filters=IsPlayed&Fields=BackdropImageTags,ParentBackdropImageTags",
+            "/Users/{}/Items?SortBy=DatePlayed&SortOrder=Descending&IncludeItemTypes=Audio&Limit={}&Recursive=true&Filters=IsPlayed&Fields=BackdropImageTags,ParentBackdropImageTags,UserData",
            self.user_id, fetch_limit
        );

@@ -993,7 +1111,7 @@ impl MediaRepository for OnlineRepository {
        // Filters=IsPlayed keeps only albums the user has actually listened to,
        // and SortBy=DatePlayed ascending surfaces the ones they've neglected.
        let mut endpoint = format!(
-            "/Users/{}/Items?SortBy=DatePlayed&SortOrder=Ascending&IncludeItemTypes=MusicAlbum&Limit={}&Recursive=true&Filters=IsPlayed&Fields=BackdropImageTags,ParentBackdropImageTags",
+            "/Users/{}/Items?SortBy=DatePlayed&SortOrder=Ascending&IncludeItemTypes=MusicAlbum&Limit={}&Recursive=true&Filters=IsPlayed&Fields=BackdropImageTags,ParentBackdropImageTags,UserData",
            self.user_id, limit_val
        );

@@ -1012,7 +1130,7 @@ impl MediaRepository for OnlineRepository {
    async fn get_resume_movies(&self, limit: Option<usize>) -> Result<Vec<MediaItem>, RepoError> {
        let limit_str = limit.unwrap_or(16);
        let endpoint = format!(
-            "/Users/{}/Items/Resume?Limit={}&MediaTypes=Video&IncludeItemTypes=Movie&Fields=BackdropImageTags,ParentBackdropImageTags",
+            "/Users/{}/Items/Resume?Limit={}&MediaTypes=Video&IncludeItemTypes=Movie&Fields=BackdropImageTags,ParentBackdropImageTags,UserData",
            self.user_id, limit_str
        );

@@ -1113,7 +1231,9 @@ impl MediaRepository for OnlineRepository {

        // Request image fields for list views (plus Genres so cached items
        // carry genres for offline genre lists/counts).
-        endpoint.push_str("&Fields=BackdropImageTags,ParentBackdropImageTags,Genres,PremiereDate");
+        endpoint.push_str(
+            "&Fields=BackdropImageTags,ParentBackdropImageTags,Genres,PremiereDate,UserData",
+        );

        let response: ItemsResponse = self.get_json(&endpoint).await?;
        Ok(SearchResult {
@@ -1133,7 +1253,11 @@ impl MediaRepository for OnlineRepository {
        #[serde(rename_all = "PascalCase")]
        struct PlaybackInfoRequest {
            user_id: String,
-            audio_stream_index: i32,
+            /// Omitted so the server resolves the source's default audio stream.
+            /// Never send 0 here: the index is global across all streams, so 0 is
+            /// the video stream and the negotiated source comes back soundless.
+            #[serde(skip_serializing_if = "Option::is_none")]
+            audio_stream_index: Option<i32>,
            #[serde(skip_serializing_if = "Option::is_none")]
            subtitle_stream_index: Option<i32>,
            start_time_ticks: i64,
@@ -1150,6 +1274,10 @@ impl MediaRepository for OnlineRepository {
            name: String,
            max_streaming_bitrate: i64,
            max_static_bitrate: i64,
+            /// Channels the device's audio route can actually voice. Without it
+            /// the server may direct-play a 5.1 track to a two-channel sink,
+            /// which is silence or inaudible dialogue depending on the device.
+            max_audio_channels: String,
            direct_play_profiles: Vec<DirectPlayProfile>,
            transcoding_profiles: Vec<TranscodingProfile>,
            subtitle_profiles: Vec<SubtitleProfile>,
@@ -1177,6 +1305,7 @@ impl MediaRepository for OnlineRepository {
            #[serde(skip_serializing_if = "Option::is_none")]
            video_codec: Option<String>,
            audio_codec: String,
+            max_audio_channels: String,
        }

        #[derive(Debug, Serialize)]
@@ -1217,8 +1346,9 @@ impl MediaRepository for OnlineRepository {

        // Get detected codecs from Android MediaCodecList or use platform defaults
        #[cfg(target_os = "android")]
-        let (video_codecs, audio_codecs) =
-            crate::player::get_detected_codecs().unwrap_or_else(|| {
+        let (video_codecs, audio_codecs) = crate::player::get_detected_codecs()
+            .map(|(video, audio, _channels)| (video, audio))
+            .unwrap_or_else(|| {
                warn!("[DeviceProfile] Codec detection not complete, using conservative defaults");
                ("h264,hevc".to_string(), "aac,mp3".to_string())
            });
@@ -1241,11 +1371,18 @@ impl MediaRepository for OnlineRepository {
        info!("[DeviceProfile] Using video codecs: {}", video_codecs);
        info!("[DeviceProfile] Using audio codecs: {}", audio_codecs);

+        // Bound every profile by what the audio route can actually voice, so a
+        // multichannel track is downmixed by the server rather than direct-played
+        // into a sink that has nowhere to put the extra channels.
+        let max_audio_channels = super::device_profile::max_audio_channels().to_string();
+        info!("[DeviceProfile] Max audio channels: {}", max_audio_channels);
+
        // Create device profile with detected hardware capabilities
        let device_profile = DeviceProfile {
            name: "JellyTau Native Player".to_string(),
            max_streaming_bitrate: 999_999_999,
            max_static_bitrate: 999_999_999,
+            max_audio_channels: max_audio_channels.clone(),
            direct_play_profiles: vec![
                DirectPlayProfile {
                    profile_type: "Video".to_string(),
@@ -1268,6 +1405,7 @@ impl MediaRepository for OnlineRepository {
                    container: "ts".to_string(),
                    video_codec: Some("h264,hevc".to_string()),
                    audio_codec: "aac,mp3".to_string(),
+                    max_audio_channels: max_audio_channels.clone(),
                },
                TranscodingProfile {
                    profile_type: "Audio".to_string(),
@@ -1276,6 +1414,7 @@ impl MediaRepository for OnlineRepository {
                    container: "mp3".to_string(),
                    video_codec: None,
                    audio_codec: "mp3".to_string(),
+                    max_audio_channels: max_audio_channels.clone(),
                },
            ],
            subtitle_profiles: vec![
@@ -1293,7 +1432,7 @@ impl MediaRepository for OnlineRepository {
        // POST to PlaybackInfo with device profile containing detected codecs
        let request_body = PlaybackInfoRequest {
            user_id: self.user_id.clone(),
-            audio_stream_index: 0, // Request first audio stream
+            audio_stream_index: None, // Let the server pick the source default
            subtitle_stream_index: None,
            start_time_ticks: 0,
            is_playback: true,
@@ -1324,9 +1463,11 @@ impl MediaRepository for OnlineRepository {
        let stream_url = if let Some(transcoding_url) = &source.transcoding_url {
            format!("{}{}", self.server_url, transcoding_url)
        } else {
-            // Fall back to direct stream URL
+            // Fall back to direct stream URL. No audioStreamIndex: static=true
+            // serves the original file untouched, and pinning index 0 (the video
+            // stream) only misleads servers that do honour it.
            format!(
-                "{}/Videos/{}/stream?static=true&container=mp4&mediaSourceId={}&deviceId=jellytau&api_key={}&audioStreamIndex=0&userId={}",
+                "{}/Videos/{}/stream?static=true&container=mp4&mediaSourceId={}&deviceId=jellytau&api_key={}&userId={}",
                self.server_url,
                item_id,
                source.id,
@@ -1654,6 +1795,25 @@ impl MediaRepository for OnlineRepository {
        self.post_json(&endpoint, &serde_json::json!({})).await
    }

+    /// TRACES: UR-067 | DR-115, JA-033 | UT-100
+    async fn get_favorites(
+        &self,
+        scope: SearchScope,
+        options: Option<GetItemsOptions>,
+    ) -> Result<SearchResult, RepoError> {
+        let endpoint = build_favorites_endpoint(&self.user_id, scope, options.as_ref());
+        let response: ItemsResponse = self.get_json(&endpoint).await?;
+
+        Ok(SearchResult {
+            items: response
+                .items
+                .into_iter()
+                .map(|item| item.to_media_item(self.user_id.clone()))
+                .collect(),
+            total_record_count: response.total_record_count,
+        })
+    }
+
    async fn unmark_favorite(&self, item_id: &str) -> Result<(), RepoError> {
        let endpoint = format!("/Users/{}/FavoriteItems/{}", self.user_id, item_id);
        let url = format!("{}{}", self.server_url, endpoint);
@@ -1733,6 +1893,48 @@ impl MediaRepository for OnlineRepository {
        result
    }

+    /// `POST /Users/{userId}/PlayedItems/{itemId}` — the mirror image of
+    /// `clear_watch_history`.
+    ///
+    /// TRACES: UR-025 | DR-131 | JA-035
+    async fn mark_played(&self, item_id: &str) -> Result<(), RepoError> {
+        let endpoint = format!("/Users/{}/PlayedItems/{}", self.user_id, item_id);
+        let url = format!("{}{}", self.server_url, endpoint);
+
+        let result = async {
+            let request = self
+                .http_client
+                .client
+                .post(&url)
+                .header("X-Emby-Authorization", self.auth_header())
+                .header("Content-Length", "0")
+                .build()
+                .map_err(|e| RepoError::Network {
+                    message: format!("Failed to build request: {}", e),
+                })?;
+
+            let response = self
+                .http_client
+                .request_with_retry(request)
+                .await
+                .map_err(|e| RepoError::Network {
+                    message: e.to_string(),
+                })?;
+
+            if !response.status().is_success() {
+                return Err(RepoError::Server {
+                    message: format!("HTTP {}", response.status()),
+                });
+            }
+
+            Ok(())
+        }
+        .await;
+
+        self.report_outcome(&result).await;
+        result
+    }
+
    async fn get_person(&self, person_id: &str) -> Result<MediaItem, RepoError> {
        let endpoint = format!("/Users/{}/Items/{}", self.user_id, person_id);
        let item: JellyfinItem = self.get_json(&endpoint).await?;
@@ -1747,7 +1949,7 @@ impl MediaRepository for OnlineRepository {
        let limit = options.as_ref().and_then(|o| o.limit).unwrap_or(100);

        let mut endpoint = format!(
-            "/Users/{}/Items?PersonIds={}&Limit={}&Recursive=true&Fields=BackdropImageTags,ParentBackdropImageTags",
+            "/Users/{}/Items?PersonIds={}&Limit={}&Recursive=true&Fields=BackdropImageTags,ParentBackdropImageTags,UserData",
            self.user_id, person_id, limit
        );

@@ -1781,7 +1983,7 @@ impl MediaRepository for OnlineRepository {

        // Try the /Similar endpoint which works for most items
        let endpoint = format!(
-            "/Items/{}/Similar?UserId={}&Limit={}&Fields=BackdropImageTags,ParentBackdropImageTags",
+            "/Items/{}/Similar?UserId={}&Limit={}&Fields=BackdropImageTags,ParentBackdropImageTags,UserData",
            item_id, self.user_id, limit_str
        );

@@ -2142,8 +2344,14 @@ mod tests {
        assert!(url.starts_with("https://test.server.com/Videos/vid-1/master.m3u8?"));
        assert!(!url.contains("StartTimeTicks"));
        assert!(!url.contains("MediaSourceId"));
-        // Defaults to first audio stream
-        assert!(url.contains("AudioStreamIndex=0"));
+        // With no track chosen, the param must be OMITTED so the server picks the
+        // source's DefaultAudioStreamIndex. `MediaStream.Index` is global across
+        // all streams of a source, so index 0 is the *video* stream on virtually
+        // every file — sending it asks for a "audio track" that has no audio.
+        assert!(
+            !url.contains("AudioStreamIndex"),
+            "must not pin an audio index when none was chosen: {url}"
+        );
    }

    #[tokio::test]
@@ -2200,8 +2408,12 @@ mod tests {
        assert!(url.starts_with("https://test.server.com/Audio/vid-1/universal?"));
        assert!(!url.contains("StartTimeTicks"));
        assert!(!url.contains("MediaSourceId"));
-        // Defaults to first audio stream.
-        assert!(url.contains("AudioStreamIndex=0"));
+        // Same as the video path: omit rather than pin index 0 (the video stream),
+        // and let the server fall back to the source's default audio stream.
+        assert!(
+            !url.contains("AudioStreamIndex"),
+            "must not pin an audio index when none was chosen: {url}"
+        );
    }

    #[tokio::test]
@@ -2369,6 +2581,140 @@ mod tests {
        );
    }

+    /// UT-100 — the favourites endpoint asks the server for favourites, scoped.
+    ///
+    /// TRACES: UR-067 | DR-115, JA-033 | UT-100
+    #[test]
+    fn test_build_favorites_endpoint_scopes_and_filters() {
+        let movies = build_favorites_endpoint("u1", SearchScope::Movies, None);
+        assert!(movies.starts_with("/Users/u1/Items?Filters=IsFavorite&Recursive=true"));
+        assert!(movies.contains("&IncludeItemTypes=Movie"));
+        // Jellyfin has no favourite timestamp, so name order is the default.
+        assert!(movies.contains("&SortBy=SortName&SortOrder=Ascending"));
+        // Hearts must render on the returned cards.
+        assert!(movies.contains("UserData"));
+
+        // Tv covers both the show and any individually favourited episode.
+        let tv = build_favorites_endpoint("u1", SearchScope::Tv, None);
+        assert!(tv.contains("&IncludeItemTypes=Series,Episode"));
+
+        let music = build_favorites_endpoint("u1", SearchScope::Music, None);
+        assert!(music.contains("&IncludeItemTypes=MusicAlbum,MusicArtist,Audio,Playlist"));
+    }
+
+    /// `All` must omit the type filter entirely rather than send a union, which
+    /// would silently drop every type nobody enumerated.
+    ///
+    /// TRACES: UR-067 | DR-115 | UT-100
+    #[test]
+    fn test_build_favorites_endpoint_all_scope_omits_type_filter() {
+        let all = build_favorites_endpoint("u1", SearchScope::All, None);
+        assert!(!all.contains("IncludeItemTypes"));
+    }
+
+    /// Paging and an explicit sort still reach the server.
+    ///
+    /// TRACES: UR-067 | DR-115 | UT-100
+    #[test]
+    fn test_build_favorites_endpoint_honours_paging_and_sort() {
+        let endpoint = build_favorites_endpoint(
+            "u1",
+            SearchScope::All,
+            Some(&GetItemsOptions {
+                limit: Some(20),
+                start_index: Some(40),
+                sort_by: Some("Random".to_string()),
+                sort_order: Some("Descending".to_string()),
+                ..Default::default()
+            }),
+        );
+        assert!(endpoint.contains("&Limit=20"));
+        assert!(endpoint.contains("&StartIndex=40"));
+        assert!(endpoint.contains("&SortBy=Random&SortOrder=Descending"));
+    }
+
+    /// UT-104 — the in-library favourites toggle reaches the server as
+    /// `Filters=IsFavorite`, and is absent unless asked for.
+    ///
+    /// TRACES: UR-067 | DR-116 | UT-104
+    #[test]
+    fn test_get_items_endpoint_applies_favorites_only() {
+        let plain = build_get_items_endpoint("u1", "lib-1", None);
+        assert!(!plain.contains("Filters=IsFavorite"));
+
+        let filtered = build_get_items_endpoint(
+            "u1",
+            "lib-1",
+            Some(&GetItemsOptions {
+                favorites_only: Some(true),
+                include_item_types: Some(vec!["Movie".to_string()]),
+                ..Default::default()
+            }),
+        );
+        assert!(filtered.contains("&Filters=IsFavorite"));
+        // Composes with the filters already there rather than replacing them.
+        assert!(filtered.contains("&IncludeItemTypes=Movie"));
+        assert!(filtered.contains("ParentId=lib-1"));
+
+        // Explicitly false is not a request to filter.
+        let off = build_get_items_endpoint(
+            "u1",
+            "lib-1",
+            Some(&GetItemsOptions {
+                favorites_only: Some(false),
+                ..Default::default()
+            }),
+        );
+        assert!(!off.contains("Filters=IsFavorite"));
+    }
+
+    /// UT-099 — a Jellyfin item's `UserData` reaches `MediaItem.user_data`.
+    ///
+    /// Before DR-113 this mapping was hardcoded to `None`, so nothing outside
+    /// the mini player could know an item was favourited.
+    ///
+    /// TRACES: UR-069 | DR-113, JA-034 | UT-099
+    #[test]
+    fn test_jellyfin_item_maps_user_data_favorite() {
+        let json = r#"{
+            "Id": "movie123",
+            "Name": "Test Movie",
+            "Type": "Movie",
+            "UserData": {
+                "PlaybackPositionTicks": 6000000000,
+                "Played": false,
+                "IsFavorite": true,
+                "PlayCount": 2,
+                "LastPlayedDate": "2026-08-01T12:00:00Z"
+            }
+        }"#;
+
+        let item: JellyfinItem = serde_json::from_str(json).expect("item should deserialize");
+        let media = item.to_media_item("server1".to_string());
+
+        let user_data = media.user_data.expect("user data should be mapped");
+        assert_eq!(user_data.is_favorite, Some(true));
+        assert_eq!(user_data.is_played, Some(false));
+        assert_eq!(user_data.play_count, Some(2));
+        assert_eq!(user_data.playback_position_ticks, Some(6_000_000_000));
+        // Ticks are converted for the frontend, which never divides them itself.
+        assert_eq!(user_data.playback_position_ms, Some(600_000));
+    }
+
+    /// An item without `UserData` still maps — the field is optional, and every
+    /// non-user-scoped endpoint omits it.
+    ///
+    /// TRACES: UR-069 | DR-113 | UT-099
+    #[test]
+    fn test_jellyfin_item_without_user_data_maps_to_none() {
+        let json = r#"{"Id": "x", "Name": "No User Data", "Type": "Movie"}"#;
+
+        let item: JellyfinItem = serde_json::from_str(json).expect("item should deserialize");
+        let media = item.to_media_item("server1".to_string());
+
+        assert!(media.user_data.is_none());
+    }
+
    #[test]
    fn test_jellyfin_item_deserialize_with_artist_items() {
        // Test that ArtistItems with PascalCase fields deserialize correctly
@@ -292,6 +292,12 @@ pub struct GetItemsOptions {
    pub fields: Option<Vec<String>>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub genres: Option<Vec<String>>,
+    /// Restrict the listing to favourited items. Backs the per-library
+    /// favourites toggle; composes with every other filter here.
+    ///
+    /// TRACES: UR-067 | DR-116 | UT-104
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub favorites_only: Option<bool>,
 }

 /// An opaque search scope the frontend selects; Rust owns what it *means*.
@@ -25,6 +25,9 @@ pub const MIGRATIONS: &[(&str, &str)] = &[
    ("018_items_is_folder", MIGRATION_018),
    ("019_genres_cache", MIGRATION_019),
    ("020_items_season_index", MIGRATION_020),
+    ("021_rebuild_items_fts", MIGRATION_021),
+    ("022_people_fts", MIGRATION_022),
+    ("023_downloads_expiry", MIGRATION_023),
 ];

 /// Initial schema migration
@@ -728,3 +731,91 @@ CREATE INDEX IF NOT EXISTS idx_genres_scope ON genres(server_id, library_id);
 const MIGRATION_020: &str = r#"
 CREATE INDEX IF NOT EXISTS idx_items_season ON items(season_id);
 "#;
+
+/// Discard and rebuild the FTS index from the `items` table.
+///
+/// Until DR-110, `save_to_cache` used `INSERT OR REPLACE INTO items`. REPLACE
+/// deletes the conflicting row and inserts a new one, but SQLite only fires
+/// `AFTER DELETE` triggers on that implicit delete when `recursive_triggers` is
+/// enabled — it is not (storage/mod.rs sets only `foreign_keys` and
+/// `journal_mode`), so `items_ad` never ran and the old index row was orphaned.
+/// Worse, `items.id` is a `TEXT PRIMARY KEY`, so the replacement row also took a
+/// *fresh rowid* and `items_ai` appended a second entry. Every catalog pass
+/// therefore left another duplicate behind, and existing installs carry one
+/// stale entry per item per sync since the database was created.
+///
+/// This was invisible in results — the `JOIN items_fts fts ON fts.rowid =
+/// i.rowid` drops rowids that no longer exist — but it degrades `MATCH`
+/// permanently, and it becomes a *correctness* problem the moment rowids are
+/// freed and reused: a new item landing on a freed rowid inherits the orphan's
+/// index entry and matches queries for the deleted item's title. The DR-110
+/// deletion sweep frees rowids, so this rebuild must run before it.
+///
+/// `'rebuild'` is the FTS5 command for exactly this: it truncates the index and
+/// repopulates it from the external content table.
+///
+/// TRACES: UR-065 | DR-110
+const MIGRATION_021: &str = r#"
+INSERT INTO items_fts(items_fts) VALUES('rebuild');
+"#;
+
+/// Full-text index over `people`, mirroring `items_fts`.
+///
+/// People live in their own table (migration 009) rather than in `items`, and
+/// had no FTS index at all — so the People group UR-060 requires could only ever
+/// be filled by the server leg of search. With the local index now answering
+/// first, an actor's name has to be findable offline too.
+///
+/// TRACES: UR-065, UR-060 | DR-111
+const MIGRATION_022: &str = r#"
+CREATE VIRTUAL TABLE IF NOT EXISTS people_fts USING fts5(
+    name,
+    overview,
+    content='people',
+    content_rowid='rowid'
+);
+
+CREATE TRIGGER IF NOT EXISTS people_ai AFTER INSERT ON people BEGIN
+    INSERT INTO people_fts(rowid, name, overview)
+    VALUES (new.rowid, new.name, new.overview);
+END;
+
+CREATE TRIGGER IF NOT EXISTS people_ad AFTER DELETE ON people BEGIN
+    INSERT INTO people_fts(people_fts, rowid, name, overview)
+    VALUES('delete', old.rowid, old.name, old.overview);
+END;
+
+CREATE TRIGGER IF NOT EXISTS people_au AFTER UPDATE ON people BEGIN
+    INSERT INTO people_fts(people_fts, rowid, name, overview)
+    VALUES('delete', old.rowid, old.name, old.overview);
+    INSERT INTO people_fts(rowid, name, overview)
+    VALUES (new.rowid, new.name, new.overview);
+END;
+
+-- Backfill for rows cached before this index existed.
+INSERT INTO people_fts(people_fts) VALUES('rebuild');
+"#;
+
+/// Give temporary downloads a life limit.
+///
+/// A cache entry is not a different kind of object from a download — it is a
+/// download with a shorter life. Modelling it as one `downloads` row with an
+/// expiry (rather than a parallel cache store) means there is a single storage
+/// accounting, a single eviction path, and no way for a cache and a download
+/// library to disagree about what is on disk.
+///
+/// `expires_at` is NULL for permanent rows, which is every row that exists
+/// today: `download_source` defaults to `'user'`, and a user's own download
+/// never expires. Only `'auto'` rows get a timestamp, and they are reclaimed by
+/// whichever comes first — the expiry passing, or LRU eviction under space
+/// pressure (DR-126).
+///
+/// TRACES: UR-071 | DR-127
+const MIGRATION_023: &str = r#"
+ALTER TABLE downloads ADD COLUMN expires_at TEXT;
+
+-- Reclaim scans filter on expiry among 'auto' rows; index both so the sweep
+-- stays cheap as the cache tier grows.
+CREATE INDEX IF NOT EXISTS idx_downloads_expiry
+    ON downloads(download_source, expires_at);
+"#;
@@ -1,7 +1,7 @@
 {
  "$schema": "https://schema.tauri.app/config/2",
  "productName": "jellytau",
-  "version": "0.3.0",
+  "version": "0.4.6",
  "identifier": "com.dtourolle.jellytau",
  "build": {
    "beforeDevCommand": "bun run dev",
@@ -18,7 +18,11 @@
      }
    ],
    "security": {
-      "csp": null
+      "csp": null,
+      "assetProtocol": {
+        "enable": true,
+        "scope": ["$APPDATA/**"]
+      }
    }
  },
  "bundle": {
@@ -14,6 +14,37 @@
  --color-surface-hover: #252525;
 }

+/* Safe-area insets — the single source of edge padding for the whole app.
+ *
+ * TRACES: UR-066 | DR-112
+ *
+ * Two independent sources have to be folded together:
+ *
+ *  - `env(safe-area-inset-*)` — iOS/desktop, and the *display cutout* on
+ *    Android. Requires `viewport-fit=cover` (see src/app.html) or it is 0px.
+ *  - `var(--jt-inset-*)` — real Android `WindowInsets` (status bar, navigation/
+ *    gesture bar, cutout) pushed in from Kotlin, because Android WebView never
+ *    reports the *system bars* through `env()`. See WindowInsetsBridge.kt and
+ *    $lib/utils/safeArea.ts.
+ *
+ * `max()` takes whichever is real on this platform; both are 0 on desktop.
+ * Consumers must use `--safe-*` and never `env()` directly — a bare `env()` is
+ * silently 0 for the Android system bars, which is what put the bottom nav
+ * under the navigation bar on 3-button-nav devices.
+ *
+ * Applied at the edges that own them: the app shell (top/left/right) and
+ * BottomUi (bottom, so its surface colour extends behind the gesture bar).
+ * Deliberately NOT applied to `body` — the shell is `h-screen`, and body
+ * padding would push 100vh past the viewport, and `position: fixed` overlays
+ * (the video/audio players) ignore body padding anyway.
+ */
+:root {
+  --safe-top: max(env(safe-area-inset-top, 0px), var(--jt-inset-top, 0px));
+  --safe-right: max(env(safe-area-inset-right, 0px), var(--jt-inset-right, 0px));
+  --safe-bottom: max(env(safe-area-inset-bottom, 0px), var(--jt-inset-bottom, 0px));
+  --safe-left: max(env(safe-area-inset-left, 0px), var(--jt-inset-left, 0px));
+}
+
 /* Global styles */
 html, body {
  @apply h-full;
@@ -23,9 +54,4 @@ html, body {
 body {
  @apply text-white antialiased;
  font-family: system-ui, -apple-system, sans-serif;
-  /* Handle safe areas for mobile devices (status bar, notches, etc.) */
-  padding-top: env(safe-area-inset-top);
-  padding-bottom: env(safe-area-inset-bottom);
-  padding-left: env(safe-area-inset-left);
-  padding-right: env(safe-area-inset-right);
 }
@@ -3,7 +3,16 @@
  <head>
    <meta charset="utf-8" />
    <link rel="icon" href="%sveltekit.assets%/favicon.png" />
-    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <!--
+      `viewport-fit=cover` is REQUIRED: without it every `env(safe-area-inset-*)`
+      resolves to 0px, so the safe-area padding in app.css/BottomUi is a no-op
+      and the bottom nav renders under the Android navigation bar. See
+      $lib/utils/safeArea.ts for the other half (native WindowInsets → CSS vars).
+    -->
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1, viewport-fit=cover"
+    />
    <title>JellyTau</title>
    %sveltekit.head%
  </head>
@@ -238,11 +238,34 @@ async playerPlayNextEpisode(item: PlayItemRequest) : Promise<PlayerStatus> {
 * - Frontend when audio track ends via backend event - no itemId/repositoryHandle needed
 * - Android JNI callback also triggers this logic directly
 * 
- * TRACES: UR-023, UR-026, UR-040 | DR-047, DR-052
+ * TRACES: UR-023, UR-026, UR-040 | DR-047, DR-052, DR-129
 */
 async playerOnPlaybackEnded(itemId: string | null, repositoryHandle: string | null) : Promise<null> {
    return await TAURI_INVOKE("player_on_playback_ended", { itemId, repositoryHandle });
 },
+/**
+ * Try to recover playback after a **recoverable** player error, reporting
+ * whether it was handled.
+ * 
+ * The frontend's error handler stops the player, which is right for a real
+ * failure and wrong for a network blip — it turned every hiccup into "playback
+ * died". This is the echo path for backends that cannot decide in-process:
+ * MpvBackend is constructed before `PlayerController` exists ([`lib.rs`]), so
+ * its event thread has no controller to ask. It emits the error, the frontend
+ * echoes it here, and the decision stays in Rust — the same shape as
+ * `PlaybackEnded` → `player_on_playback_ended`.
+ * 
+ * Returns `true` when the stream was re-opened and the caller must NOT stop the
+ * player; `false` when the error is real and should be surfaced as before.
+ * Android decides inside its JNI callback and only emits errors it has already
+ * declined to recover, so this reports `false` for those without a second
+ * opinion — the shared attempt budget is spent by then either way.
+ * 
+ * TRACES: UR-004, UR-040 | DR-130 | UT-117
+ */
+async playerRecoverStream() : Promise<boolean> {
+    return await TAURI_INVOKE("player_recover_stream");
+},
 /**
 * Report an HTML5 <video> state change (playing/paused/loading/stopped/idle).
 */
@@ -262,6 +285,23 @@ async playerReportPosition(position: number, duration: number) : Promise<null> {
 async playerReportMediaLoaded(duration: number) : Promise<null> {
    return await TAURI_INVOKE("player_report_media_loaded", { duration });
 },
+/**
+ * The on-disk path for a downloaded item, for playback surfaces that resolve
+ * their own source rather than going through the queue.
+ * 
+ * The video player is the reason this exists: audio has preferred local files
+ * since queue construction, but video asks the repository for a stream URL and
+ * never consults `downloads`, so a downloaded film was still streamed — costing
+ * bandwidth that had already been spent and failing outright when offline.
+ * 
+ * Returns `None` when nothing is downloaded *or* the file is missing, so the
+ * caller falls back to streaming.
+ * 
+ * TRACES: UR-071 | DR-123 | UT-116
+ */
+async playerLocalMediaPath(itemId: string) : Promise<string | null> {
+    return await TAURI_INVOKE("player_local_media_path", { itemId });
+},
 /**
 * Preload upcoming tracks from the queue
 * This queues background downloads for the next N tracks that aren't already downloaded
@@ -833,6 +873,22 @@ async markDownloadCompleted(downloadId: number, bytesDownloaded: number, filePat
 async markDownloadFailed(downloadId: number, errorMessage: string) : Promise<null> {
    return await TAURI_INVOKE("mark_download_failed", { downloadId, errorMessage });
 },
+/**
+ * A playable URL for a downloaded file on disk.
+ * 
+ * Local media is served over a loopback HTTP server rather than handed to the
+ * webview as a `file://`/asset URL, because the asset protocol cannot stream a
+ * large file — it answers a range-less request with the whole thing, which
+ * Chromium abandons. See `media_server` for why real HTTP is used.
+ * 
+ * The returned URL carries the server's per-session token, so it is only valid
+ * for this run of the app and must not be persisted.
+ * 
+ * TRACES: UR-071 | DR-137
+ */
+async mediaLocalUrl(path: string) : Promise<string> {
+    return await TAURI_INVOKE("media_local_url", { path });
+},
 /**
 * Start downloading a file immediately
 * This command actually downloads the file using the worker
@@ -1090,6 +1146,14 @@ async syncMarkFailed(id: number, error: string) : Promise<null> {
 async syncGetPendingCount(userId: string) : Promise<number> {
    return await TAURI_INVOKE("sync_get_pending_count", { userId });
 },
+/**
+ * Push the queue now, on the user's say-so, instead of waiting for a reconnect.
+ * 
+ * TRACES: UR-025 | DR-132
+ */
+async syncProcessPending() : Promise<DrainReport> {
+    return await TAURI_INVOKE("sync_process_pending");
+},
 /**
 * Delete completed sync operations older than specified days
 */
@@ -1422,6 +1486,20 @@ async repositoryMarkFavorite(handle: string, itemId: string) : Promise<null> {
 async repositoryUnmarkFavorite(handle: string, itemId: string) : Promise<null> {
    return await TAURI_INVOKE("repository_unmark_favorite", { handle, itemId });
 },
+/**
+ * Everything the viewer has favourited, across libraries, narrowed by scope.
+ * 
+ * Two-phase like `repository_search`: the local answer returns immediately and
+ * a background server pass emits `favorites-changed` when the server's set
+ * differs. Without the second phase a favourite marked in another client shows
+ * up only on the *second* visit to the page, since the cache-first read hands
+ * back local rows and the refresh is invisible to the frontend.
+ * 
+ * TRACES: UR-067 | DR-115, DR-120, JA-033 | UT-107
+ */
+async repositoryGetFavorites(handle: string, scope: SearchScope, options: GetItemsOptions | null) : Promise<SearchResult> {
+    return await TAURI_INVOKE("repository_get_favorites", { handle, scope, options });
+},
 /**
 * Get person details
 */
@@ -1704,7 +1782,15 @@ storageLimit: number;
 /**
 * Only cache on WiFi
 */
-wifiOnly: boolean }
+wifiOnly: boolean; 
+/**
+ * How long a temporary (`download_source = 'auto'`) download lives before
+ * it is reclaimed, in hours. 0 disables expiry, leaving space pressure as
+ * the only reclaim trigger.
+ * 
+ * TRACES: UR-071 | DR-127
+ */
+temporaryTtlHours: number }
 /**
 * Cached media item returned to frontend
 */
@@ -1729,7 +1815,12 @@ itemsCached: number;
 /**
 * Libraries that failed to sync (e.g. server hiccup); best-effort.
 */
-librariesFailed: number }
+librariesFailed: number; 
+/**
+ * Entries removed because the server no longer has them. Always 0 when any
+ * library failed, since a partial crawl cannot prove an item is gone.
+ */
+itemsPruned: number }
 export type CatalogSyncStatus = { 
 /**
 * RFC-3339 timestamp of the last successful sync, if any.
@@ -1812,6 +1903,26 @@ export type DownloadVideoRequest = { itemId: string; userId: string; filePath: s
 * Enhanced response with pre-computed stats
 */
 export type DownloadsResponse = { downloads: DownloadInfo[]; stats: DownloadStats }
+/**
+ * What a drain did, for logging and for the frontend's "Sync now" button.
+ */
+export type DrainReport = { 
+/**
+ * Rows that reached the server and are now `completed`.
+ */
+pushed: number; 
+/**
+ * Rows that failed and will be retried on the next reconnect.
+ */
+deferred: number; 
+/**
+ * Rows that exhausted `MAX_SYNC_ATTEMPTS` and were given up on.
+ */
+abandoned: number; 
+/**
+ * Rows still waiting afterwards (what the badge counts).
+ */
+remaining: number }
 /**
 * Built-in equalizer presets. A preset *is* a gain curve defined by the band
 * layout above (a domain concept), not a mere label — the curve numbers live
@@ -1837,7 +1948,14 @@ export type GetImageRequest = { itemId: string; imageType: string; maxWidth?: nu
 /**
 * Options for querying items
 */
-export type GetItemsOptions = { startIndex?: number | null; limit?: number | null; sortBy?: string | null; sortOrder?: string | null; includeItemTypes?: string[] | null; recursive?: boolean | null; fields?: string[] | null; genres?: string[] | null }
+export type GetItemsOptions = { startIndex?: number | null; limit?: number | null; sortBy?: string | null; sortOrder?: string | null; includeItemTypes?: string[] | null; recursive?: boolean | null; fields?: string[] | null; genres?: string[] | null; 
+/**
+ * Restrict the listing to favourited items. Backs the per-library
+ * favourites toggle; composes with every other filter here.
+ * 
+ * TRACES: UR-067 | DR-116 | UT-104
+ */
+favoritesOnly?: boolean | null }
 /**
 * Image options
 */
@@ -2676,7 +2794,15 @@ mime_type: string }
 /**
 * Sync queue item returned to frontend
 */
-export type SyncQueueItem = { id: number; userId: string; operation: string; itemId: string | null; payload: string | null; status: string; retryCount: number; createdAt: string | null; errorMessage: string | null }
+export type SyncQueueItem = { id: number; userId: string; operation: string; itemId: string | null; payload: string | null; status: string; retryCount: number; createdAt: string | null; errorMessage: string | null; 
+/**
+ * Cached title of the item the operation is about, when the catalog knows
+ * it. Resolved here rather than by a per-row frontend fetch — the queue
+ * list is otherwise a wall of opaque ids.
+ * 
+ * TRACES: UR-025 | DR-132
+ */
+itemName: string | null }
 /**
 * Statistics about the thumbnail cache
 */
@@ -3,7 +3,7 @@
 // NO direct HTTP calls - everything routes through Rust backend

 import { commands } from "./bindings";
-import type { JRayActor, DownloadDiskUsage } from "./bindings";
+import type { JRayActor, DownloadDiskUsage, SearchScope } from "./bindings";
 import type { QualityPreset } from "./quality-presets";
 import type {
  Library,
@@ -311,6 +311,20 @@ export class RepositoryClient {
    await commands.repositoryUnmarkFavorite(this.ensureHandle(), itemId);
  }

+  /**
+   * Everything favourited, across libraries, narrowed by an opaque scope the
+   * backend expands into item types. The frontend never names a Jellyfin type
+   * here — see docs/specs/scoped-search-boundary.md.
+   *
+   * Resolves with the local answer; a later `favorites-changed` event reports
+   * ids the server disagreed with.
+   *
+   * TRACES: UR-067 | DR-115
+   */
+  async getFavorites(scope: SearchScope, options?: GetItemsOptions): Promise<SearchResult> {
+    return commands.repositoryGetFavorites(this.ensureHandle(), scope, options ?? null);
+  }
+
  // ===== Person Methods (via Rust) =====

  async getPerson(personId: string): Promise<MediaItem> {
@@ -1,19 +1,22 @@
 <!--
  Shared application header. Lifted out of the library layout so the account
  menu (and desktop nav) are available on every authenticated, non-immersive
-  screen, not only under /library. Routes that need in-header search (the
-  library layout) pass it in via the `search` snippet; other routes omit it.
+  screen, not only under /library.
+
+  The search box is owned here rather than passed in by a layout, so the same
+  bar renders on the library routes and on /search — searching from the header
+  no longer hands you to a screen with a different input.

  TRACES: UR-054 | DR-076
 -->
 <script lang="ts">
-  import type { Snippet } from "svelte";
  import { page } from "$app/stores";
  import AccountMenu from "$lib/components/account/AccountMenu.svelte";
-
-  let { search }: { search?: Snippet } = $props();
+  import HeaderSearch from "$lib/components/search/HeaderSearch.svelte";
+  import { showHeaderSearch } from "$lib/utils/layoutShell";

  const pathname = $derived($page.url.pathname);
+  const withSearch = $derived(showHeaderSearch({ pathname }));
 </script>

 <header class="sticky top-0 z-50 bg-[var(--color-background)]/95 backdrop-blur border-b border-gray-800 flex-shrink-0">
@@ -51,10 +54,10 @@
      </a>
    </nav>

-    <!-- Optional in-header search (library layout supplies it). -->
-    {#if search}
-      <div class="flex-1 max-w-md hidden md:block space-y-2">
-        {@render search()}
+    <!-- In-header search: the single md+ search input (library + /search). -->
+    {#if withSearch}
+      <div class="flex-1 max-w-md hidden md:block">
+        <HeaderSearch />
      </div>
    {/if}

@@ -11,9 +11,16 @@
  "last row hidden behind the nav" bug. There is nothing to measure or reserve:
  the browser's flex layout does it exactly, every frame.

-  The Android system gesture bar is cleared via `env(safe-area-inset-bottom)`.
+  The Android navigation/gesture bar is cleared via `--safe-bottom` (see
+  app.css). The padding sits INSIDE this element's `bg-surface` box on purpose,
+  so the surface colour extends behind the gesture bar instead of leaving a
+  strip of page background under the nav.

-  TRACES: UR-005 | DR-009
+  Never pad from a bare CSS `env()` safe-area value here: Android WebView does
+  not report the system bars that way, so it is always 0 and the nav ends up
+  under the navigation bar (UR-066).
+
+  TRACES: UR-005, UR-066 | DR-009, DR-112
 -->
 <script lang="ts">
  import { goto } from "$app/navigation";
@@ -41,7 +48,7 @@
 </script>

 <!-- flex-shrink-0 so it keeps its natural height; the scroller sibling flexes. -->
-<div class="flex-shrink-0 pb-[env(safe-area-inset-bottom)] bg-[var(--color-surface)]">
+<div class="flex-shrink-0 pb-[var(--safe-bottom)] bg-[var(--color-surface)]">
  {#if showMiniPlayer}
    <MiniPlayer
      media={$currentMedia}
@@ -1,27 +1,60 @@
+<!-- TRACES: UR-017, UR-068 | DR-021, DR-119 -->
 <script lang="ts">
  import { toggleFavorite } from "$lib/services/favorites";
  import { haptics } from "$lib/utils/haptics";
  import { toast } from "$lib/stores/toast";
+  import { favoriteOverrides } from "$lib/stores/favorites";

  interface Props {
    itemId: string;
    isFavorite?: boolean;
    size?: "sm" | "md" | "lg";
    className?: string;
+    /**
+     * "button" (default) is the standalone control used in header/hero rows;
+     * "overlay" is the artwork corner variant used on cards, which needs its
+     * own scrim to stay legible over any poster.
+     */
+    variant?: "button" | "overlay";
+    /** Stop the click reaching a parent card/row that would navigate or play. */
+    stopPropagation?: boolean;
  }

-  let { itemId, isFavorite = $bindable(false), size = "md", className = "" }: Props = $props();
+  let {
+    itemId,
+    isFavorite = $bindable(false),
+    size = "md",
+    className = "",
+    variant = "button",
+    stopPropagation = false,
+  }: Props = $props();

  let isLoading = $state(false);
  let isAnimating = $state(false);

+  // A toggle from any other surface (or the backend's `favorites-changed`
+  // refresh) wins over the prop we were mounted with — otherwise a heart tapped
+  // on a card would still read empty on the detail page behind it.
+  $effect(() => {
+    const override = $favoriteOverrides.get(itemId);
+    if (override !== undefined && override !== isFavorite) {
+      isFavorite = override;
+    }
+  });
+
  const sizeClasses = {
    sm: "w-4 h-4",
    md: "w-5 h-5",
    lg: "w-6 h-6",
  };

-  async function handleToggle() {
+  async function handleToggle(event: MouseEvent) {
+    // On a card the heart sits inside a clickable tile; without this, hearting
+    // an item would also open (or play) it.
+    if (stopPropagation) {
+      event.stopPropagation();
+      event.preventDefault();
+    }
    if (isLoading) return;

    isLoading = true;
@@ -55,8 +88,15 @@

  // Compute button classes
  const buttonClass = $derived.by(() => {
-    const baseClasses = "p-2 rounded-full transition-all";
-    const colorClasses = isFavorite ? "text-red-500 hover:text-red-400" : "text-gray-400 hover:text-white";
+    const baseClasses =
+      variant === "overlay"
+        ? "p-1.5 rounded-full transition-all bg-black/50 backdrop-blur-sm hover:bg-black/70"
+        : "p-2 rounded-full transition-all";
+    const colorClasses = isFavorite
+      ? "text-red-500 hover:text-red-400"
+      : variant === "overlay"
+        ? "text-white/80 hover:text-white"
+        : "text-gray-400 hover:text-white";
    const loadingClasses = isLoading ? "opacity-50 cursor-wait" : "";
    return `${baseClasses} ${colorClasses} ${loadingClasses} ${className}`.trim();
  });
@@ -3,9 +3,16 @@
    value?: string;
    placeholder?: string;
    onSearch?: (query: string) => void;
+    /** Exposed so a parent can focus/position the caret (see HeaderSearch). */
+    inputEl?: HTMLInputElement | null;
  }

-  let { value = $bindable(""), placeholder = "Search...", onSearch }: Props = $props();
+  let {
+    value = $bindable(""),
+    placeholder = "Search...",
+    onSearch,
+    inputEl = $bindable(null),
+  }: Props = $props();

  let debounceTimer: ReturnType<typeof setTimeout>;

@@ -39,6 +46,7 @@
  </div>

  <input
+    bind:this={inputEl}
    type="text"
    {value}
    {placeholder}
@@ -6,6 +6,8 @@
  import LibraryGrid from "./LibraryGrid.svelte";
  import TrackList from "./TrackList.svelte";
  import CachedImage from "$lib/components/common/CachedImage.svelte";
+  import FavoriteButton from "$lib/components/FavoriteButton.svelte";
+  import { favoriteOverrides, resolveIsFavorite } from "$lib/stores/favorites";

  interface Props {
    artist: MediaItem;
@@ -126,7 +128,15 @@
      {/if}

      <!-- Artist Name -->
-      <h1 class="text-4xl font-bold text-white mb-4">{artist.name}</h1>
+      <div class="flex items-center gap-2 mb-4">
+        <h1 class="text-4xl font-bold text-white">{artist.name}</h1>
+        <!-- TRACES: UR-068 | DR-119 -->
+        <FavoriteButton
+          itemId={artist.id}
+          isFavorite={resolveIsFavorite(artist, $favoriteOverrides)}
+          size="lg"
+        />
+      </div>

      <!-- Bio -->
      {#if artist.overview}
@@ -1,9 +1,23 @@
-<!-- TRACES: UR-048 | DR-061, DR-062 -->
+<!--
+  The one and only episode surface (ux-flows §5B.1) — so it carries everything
+  an episode can do, not just Play. A bare Episode page used to exist alongside
+  it with a *different* set of affordances (download, breadcrumbs, cast), which
+  meant opening an episode from Continue Watching silently lost them.
+
+  TRACES: UR-048, UR-058 | DR-061, DR-062, DR-142
+-->
 <script lang="ts">
  import { goto } from "$app/navigation";
  import { truncateMiddle } from "$lib/utils/truncateMiddle";
  import type { MediaItem } from "$lib/api/types";
  import CachedImage from "$lib/components/common/CachedImage.svelte";
+  import FavoriteButton from "$lib/components/FavoriteButton.svelte";
+  import VideoDownloadButton from "./VideoDownloadButton.svelte";
+  import CastSection from "./CastSection.svelte";
+  import GenreTags from "./GenreTags.svelte";
+  import RelatedItemsSection from "./RelatedItemsSection.svelte";
+  import { favoriteOverrides, resolveIsFavorite } from "$lib/stores/favorites";
+  import { seasonAnchorId } from "./seriesNavigation";
  import {
    isCurrentEpisode as isSameEpisode,
    adjacentEpisodes as computeAdjacent,
@@ -12,12 +26,17 @@

  interface Props {
    episode: MediaItem;
-    series: MediaItem;
-    allEpisodes: MediaItem[];
+    /**
+     * The parent series. `null` only for an episode that carries no `seriesId`
+     * (a deep link into a stale cache) — the view still renders, minus the
+     * affordances that need series context.
+     */
+    series?: MediaItem | null;
+    allEpisodes?: MediaItem[];
    onBack?: () => void;
  }

-  let { episode, series, allEpisodes, onBack }: Props = $props();
+  let { episode, series = null, allEpisodes = [], onBack }: Props = $props();

  // Pure logic lives in ./episodeStrip.ts (unit-tested). Wrap for local use.
  function isCurrentEpisode(ep: MediaItem): boolean {
@@ -26,6 +45,10 @@

  const adjacentEpisodes = $derived(() => computeAdjacent(episode, allEpisodes));

+  // A strip of exactly one card is the current episode talking to itself — the
+  // spec wants the *next* episodes, so with no siblings there is nothing to show.
+  const hasEpisodeStrip = $derived(adjacentEpisodes().length > 1);
+
  // Compute best backdrop source (no fetch, pure derivation)
  const backdropSource = $derived.by(() => {
    if (episode.backdropImageTags?.[0]) {
@@ -34,12 +57,28 @@
    if (episode.imageId) {
      return { itemId: episode.id, imageType: "Primary" as const, tag: episode.imageId };
    }
-    if (series.backdropImageTags?.[0]) {
+    if (series?.backdropImageTags?.[0]) {
      return { itemId: series.id, imageType: "Backdrop" as const, tag: series.backdropImageTags[0] };
    }
    return null;
  });

+  // Cast and genres are the episode's own when the server sent them, else the
+  // series' — a list-level episode fetch often carries neither, and an empty
+  // Cast row on an episode of a show with a known cast reads as broken.
+  const people = $derived(episode.people?.length ? episode.people : series?.people ?? []);
+  const genres = $derived(episode.genres?.length ? episode.genres : series?.genres ?? []);
+
+  // "More Like This" on an episode means similar *shows* (UR-048), so it keys
+  // off the series rather than the episode.
+  const seriesName = $derived(series?.name ?? episode.seriesName ?? null);
+  const seriesHref = $derived(series ? `/library/${series.id}` : null);
+  const seasonHref = $derived(
+    series && episode.parentIndexNumber != null
+      ? `/library/${series.id}#${seasonAnchorId(episode.parentIndexNumber)}`
+      : null
+  );
+
  function formatDuration(ms?: number | null): string {
    if (!ms) return "";
    const seconds = Math.floor(ms / 1000);
@@ -64,6 +103,7 @@
  }

  function handleEpisodeClick(ep: MediaItem) {
+    if (!series) return;
    goto(`/library/${series.id}?episode=${ep.id}`);
  }

@@ -110,8 +150,19 @@
    <!-- Content -->
    <div class="relative h-full flex flex-col justify-end p-8 max-w-3xl">
      <div class="space-y-4">
-        <!-- Series name -->
-        <p class="text-gray-300 text-lg">{series.name}</p>
+        <!-- Series name — a link, so the episode page is a navigable hub
+             rather than a dead end (UR-058). -->
+        {#if seriesName}
+          <p class="text-lg">
+            {#if seriesHref}
+              <a href={seriesHref} class="text-gray-300 hover:text-white hover:underline transition-colors">
+                {seriesName}
+              </a>
+            {:else}
+              <span class="text-gray-300">{seriesName}</span>
+            {/if}
+          </p>
+        {/if}

        <!-- Episode title -->
        <h1 class="text-4xl font-bold text-white drop-shadow-lg">
@@ -120,9 +171,20 @@

        <!-- Metadata -->
        <div class="flex items-center gap-4 text-sm text-gray-200">
-          <span class="px-2 py-1 bg-[var(--color-jellyfin)] rounded font-semibold">
-            {episodeLabel}
-          </span>
+          <!-- The badge links to the season's place in the series list —
+               seasons have no page of their own (DR-103). -->
+          {#if seasonHref}
+            <a
+              href={seasonHref}
+              class="px-2 py-1 bg-[var(--color-jellyfin)] rounded font-semibold hover:brightness-110 transition-all"
+            >
+              {episodeLabel}
+            </a>
+          {:else}
+            <span class="px-2 py-1 bg-[var(--color-jellyfin)] rounded font-semibold">
+              {episodeLabel}
+            </span>
+          {/if}
          {#if duration}
            <span>{duration}</span>
          {/if}
@@ -166,8 +228,9 @@
          </div>
        {/if}

-        <!-- Play button -->
-        <div class="pt-2">
+        <!-- Play / Download / Favourite — the full hero action row of
+             ux-flows §5B.2. TRACES: UR-058, UR-068 | DR-119, DR-142 -->
+        <div class="pt-2 flex items-center gap-3">
          <button
            onclick={handlePlay}
            class="px-8 py-3 bg-white text-black hover:bg-white/90 rounded-lg font-semibold text-lg flex items-center gap-2 transition-colors"
@@ -177,12 +240,30 @@
            </svg>
            {progress > 0 && progress < 95 ? "Resume" : "Play"}
          </button>
+          <VideoDownloadButton
+            itemId={episode.id}
+            itemName={episode.name}
+            isMovie={false}
+            seriesName={seriesName ?? undefined}
+            seasonName={episode.seasonName ?? undefined}
+            seasonNumber={episode.parentIndexNumber ?? undefined}
+            episodeNumber={episode.indexNumber ?? undefined}
+            size="lg"
+          />
+          <FavoriteButton
+            itemId={episode.id}
+            isFavorite={resolveIsFavorite(episode, $favoriteOverrides)}
+            size="lg"
+          />
        </div>
      </div>
    </div>
  </div>

-  <!-- Adjacent episodes -->
+  <!-- Adjacent episodes. Nothing may be inserted between the hero and this
+       strip — continuation content comes before discovery content
+       (ux-flows §5B.2). TRACES: UR-048 | DR-061, DR-062 -->
+  {#if hasEpisodeStrip}
  <div class="space-y-4">
    <h2 class="text-xl font-semibold text-white">More Episodes</h2>

@@ -266,4 +347,27 @@
      {/each}
    </div>
  </div>
+  {/if}
+
+  <!-- Discovery content, strictly below the episode strip (ux-flows §5B.2:
+       hero → strip → cast → similar). TRACES: UR-048 | DR-062, DR-142 -->
+  {#if genres.length}
+    <GenreTags {genres} maxShow={6} itemKind="episode" />
+  {/if}
+
+  {#if people.length}
+    <CastSection {people} />
+  {/if}
+
+  <!-- "More Like This" on an episode means similar shows, so it keys off the
+       series. Skipped for a series-less episode, which has nothing to match on. -->
+  {#if series && (series.genres?.length || series.people?.length)}
+    <RelatedItemsSection
+      currentItemId={series.id}
+      itemKind="series"
+      genres={series.genres ?? undefined}
+      people={series.people ?? undefined}
+      limit={12}
+    />
+  {/if}
 </div>
@@ -0,0 +1,175 @@
+// The Episode Focus View is the *only* episode surface (ux-flows §5B.1), so it
+// has to carry everything the bare Episode page used to: download, breadcrumbs
+// back to the series/season, cast and similar shows. It shipped with only Play
+// and Favourite, which is why "open an episode from Continue Watching" lost the
+// download affordance.
+//
+// TRACES: UR-048, UR-058 | DR-062, DR-142 | UT-131, UT-132, UT-133, UT-134, UT-135
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { render, screen } from "@testing-library/svelte";
+import type { MediaItem } from "$lib/api/types";
+
+const h = vi.hoisted(() => {
+  function shim<T>(initial: T) {
+    let value = initial;
+    const subs = new Set<(v: T) => void>();
+    return {
+      set(v: T) {
+        value = v;
+        subs.forEach((fn) => fn(value));
+      },
+      subscribe(fn: (v: T) => void) {
+        subs.add(fn);
+        fn(value);
+        return () => subs.delete(fn);
+      },
+    };
+  }
+  return {
+    downloadsStore: shim({ downloads: {} as Record<string, unknown> }),
+    favoriteOverridesStore: shim(new Map<string, boolean>()),
+    getSimilarItems: vi.fn(async () => ({ items: [] as MediaItem[] })),
+    search: vi.fn(async () => ({ items: [] as MediaItem[] })),
+  };
+});
+
+vi.mock("$lib/stores/downloads", () => ({
+  downloads: {
+    subscribe: h.downloadsStore.subscribe,
+    downloadVideo: vi.fn(),
+    pinItem: vi.fn(),
+    unpinItem: vi.fn(),
+    delete: vi.fn(),
+    cancel: vi.fn(),
+  },
+}));
+
+vi.mock("$lib/stores/favorites", async () => {
+  const actual = await vi.importActual<typeof import("$lib/stores/favorites")>(
+    "$lib/stores/favorites"
+  );
+  return { ...actual, favoriteOverrides: { subscribe: h.favoriteOverridesStore.subscribe } };
+});
+
+vi.mock("$lib/stores/auth", () => ({
+  auth: {
+    getRepository: () => ({ getSimilarItems: h.getSimilarItems, search: h.search }),
+    getUserId: () => "user-1",
+  },
+  user: { subscribe: (fn: (v: unknown) => void) => (fn({ id: "user-1" }), () => {}) },
+}));
+
+// CachedImage does async repo/image work irrelevant to these tests.
+vi.mock("$lib/components/common/CachedImage.svelte", async () => ({
+  default: (await import("./__mocks__/StubImage.svelte")).default,
+}));
+
+import EpisodeFocusView from "./EpisodeFocusView.svelte";
+
+const SERIES: MediaItem = {
+  id: "series-1",
+  name: "The Show",
+  kind: "series",
+  genres: ["Drama"],
+  people: [{ id: "p-1", name: "Lead Actor", type: "Actor" }],
+} as unknown as MediaItem;
+
+function episode(overrides: Partial<MediaItem> = {}): MediaItem {
+  return {
+    id: "ep-4",
+    name: "The Fourth One",
+    kind: "episode",
+    seriesId: "series-1",
+    seriesName: "The Show",
+    parentIndexNumber: 2,
+    indexNumber: 4,
+    durationMs: 2_880_000,
+    overview: "Something happens.",
+    genres: ["Drama"],
+    people: [{ id: "p-1", name: "Lead Actor", type: "Actor" }],
+    ...overrides,
+  } as unknown as MediaItem;
+}
+
+function sibling(id: string, number: number): MediaItem {
+  return {
+    id,
+    name: `Episode ${number}`,
+    kind: "episode",
+    seriesId: "series-1",
+    parentIndexNumber: 2,
+    indexNumber: number,
+  } as unknown as MediaItem;
+}
+
+const allEpisodes = [sibling("ep-3", 3), episode(), sibling("ep-5", 5)];
+
+describe("EpisodeFocusView — full episode functionality (DR-142)", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    h.downloadsStore.set({ downloads: {} });
+    h.favoriteOverridesStore.set(new Map());
+  });
+
+  it("offers a download control in the hero", () => {
+    render(EpisodeFocusView, {
+      props: { episode: episode(), series: SERIES, allEpisodes },
+    });
+
+    expect(screen.getByLabelText(/Download for offline playback/i)).toBeTruthy();
+  });
+
+  it("links the series name back to the series page", () => {
+    render(EpisodeFocusView, {
+      props: { episode: episode(), series: SERIES, allEpisodes },
+    });
+
+    const link = screen.getByRole("link", { name: "The Show" });
+    expect(link.getAttribute("href")).toBe("/library/series-1");
+  });
+
+  it("links the season badge to the season's place in the series list", () => {
+    render(EpisodeFocusView, {
+      props: { episode: episode(), series: SERIES, allEpisodes },
+    });
+
+    const link = screen.getByRole("link", { name: "S2E4" });
+    expect(link.getAttribute("href")).toBe("/library/series-1#season-2");
+  });
+
+  it("renders cast below the episode strip, never above it (DR-062)", () => {
+    const { container } = render(EpisodeFocusView, {
+      props: { episode: episode(), series: SERIES, allEpisodes },
+    });
+
+    const headings = [...container.querySelectorAll("h2")].map((h2) => h2.textContent?.trim());
+    const strip = headings.indexOf("More Episodes");
+    const cast = headings.findIndex((t) => t?.startsWith("Cast"));
+
+    expect(strip).toBeGreaterThanOrEqual(0);
+    expect(cast).toBeGreaterThan(strip);
+  });
+
+  it("hides the episode strip when the episode has no siblings", () => {
+    render(EpisodeFocusView, {
+      props: { episode: episode(), series: SERIES, allEpisodes: [] },
+    });
+
+    expect(screen.queryByText("More Episodes")).toBeNull();
+  });
+
+  it("renders without a series for an episode that carries no seriesId", () => {
+    render(EpisodeFocusView, {
+      props: {
+        episode: episode({ seriesId: null, seriesName: null }),
+        series: null,
+        allEpisodes: [],
+      },
+    });
+
+    // Still a complete surface: title, play and download all present.
+    expect(screen.getByText("The Fourth One")).toBeTruthy();
+    expect(screen.getByLabelText(/Download for offline playback/i)).toBeTruthy();
+    expect(screen.queryByRole("link", { name: "The Show" })).toBeNull();
+  });
+});
@@ -11,6 +11,7 @@
  import ResultsCounter from "$lib/components/common/ResultsCounter.svelte";
  import CachedImage from "$lib/components/common/CachedImage.svelte";
  import { useServerReachabilityReload } from "$lib/composables/useServerReachabilityReload";
+  import { useOfflineFilterReload } from "$lib/composables/useOfflineFilterReload";
  import type { Genre, MediaItem, ItemType } from "$lib/api/types";

  /**
@@ -52,12 +53,16 @@
  let selectedGenre = $state<Genre | null>(null);
  let genreItems = $state<MediaItem[]>([]);
  let loadingItems = $state(false);
-  const { markLoaded } = useServerReachabilityReload(async () => {
+  async function reloadGenreBrowse() {
    await loadGenres();
    if (selectedGenre) {
      await loadGenreItems(selectedGenre);
    }
-  });
+  }
+
+  const { markLoaded } = useServerReachabilityReload(reloadGenreBrowse);
+  // Re-query when the offline downloaded-only gate changes. TRACES: UR-052 | DR-143
+  useOfflineFilterReload(reloadGenreBrowse);

  onMount(async () => {
    await loadGenres();
@@ -1,4 +1,4 @@
-<!-- TRACES: UR-007, UR-029, UR-030 | DR-007, DR-032, DR-033 -->
+<!-- TRACES: UR-007, UR-029, UR-030, UR-067 | DR-007, DR-032, DR-033, DR-116 -->
 <script lang="ts">
  import { onMount, onDestroy } from "svelte";
  import { listen, type UnlistenFn } from "@tauri-apps/api/event";
@@ -14,6 +14,7 @@
  import BackButton from "$lib/components/common/BackButton.svelte";
  import ResultsCounter from "$lib/components/common/ResultsCounter.svelte";
  import { useServerReachabilityReload } from "$lib/composables/useServerReachabilityReload";
+  import { useOfflineFilterReload } from "$lib/composables/useOfflineFilterReload";
  import type { MediaItem, Library, ItemType, SearchResult } from "$lib/api/types";
  import LibraryGrid from "./LibraryGrid.svelte";
  import TrackList from "./TrackList.svelte";
@@ -56,6 +57,7 @@
  let gridWrapper = $state<HTMLDivElement | null>(null);
  let searchQuery = $state("");
  let debouncedSearchQuery = $state("");
+  let favoritesOnly = $state(false);
  let sortBy = $state<string>("");
  let sortOrder = $state<"Ascending" | "Descending">("Ascending");
  let searchTimeout: ReturnType<typeof setTimeout> | null = null;
@@ -94,6 +96,11 @@
    await loadItems();
  });

+  // Re-query when the offline downloaded-only gate changes — going offline, or
+  // toggling "Show all server media". Without this the listing kept whatever it
+  // was first loaded with and the toggle only greyed cards. TRACES: UR-052 | DR-143
+  useOfflineFilterReload(() => loadItems());
+
  onMount(async () => {
    await loadItems();
    markLoaded();
@@ -140,6 +147,9 @@
          sortOrder,
          recursive: true,
          limit: 10000,
+          // Narrows the listing in place; the backend owns what "favourite"
+          // resolves to online vs offline. TRACES: UR-067 | DR-116
+          favoritesOnly: favoritesOnly ? true : undefined,
        });
        items = excludePodcasts(result.items);
      }
@@ -154,6 +164,12 @@
    searchQuery = query;
  }

+  /// TRACES: UR-067 | DR-116
+  function toggleFavoritesOnly() {
+    favoritesOnly = !favoritesOnly;
+    loadItems();
+  }
+
  // Debounce search input (300ms delay) - skip initial mount to avoid duplicate load
  $effect(() => {
    const _query = searchQuery; // track for reactivity
@@ -266,6 +282,33 @@
      <SearchBar value={searchQuery} placeholder={searchPlaceholder} onInput={handleSearch} />
    </div>

+    <!-- Favourites filter. Session-scoped on purpose: a persisted filter that
+         hides most of a library reads as data loss on the next launch
+         (ux-flows §5C.2). Hidden while searching, which has no favourites
+         filter of its own. TRACES: UR-067 | DR-116 -->
+    {#if !debouncedSearchQuery.trim()}
+      <button
+        onclick={toggleFavoritesOnly}
+        aria-pressed={favoritesOnly}
+        class="px-3 py-2 rounded-lg text-sm font-medium flex items-center gap-2 transition-colors
+               {favoritesOnly
+                 ? 'bg-[var(--color-jellyfin)] text-white'
+                 : 'bg-[var(--color-surface)] text-gray-400 hover:text-white'}"
+        title={favoritesOnly ? "Showing favourites only" : "Show favourites only"}
+      >
+        <svg
+          class="w-4 h-4"
+          fill={favoritesOnly ? "currentColor" : "none"}
+          stroke="currentColor"
+          viewBox="0 0 24 24"
+          stroke-width="2"
+        >
+          <path stroke-linecap="round" stroke-linejoin="round" d="M4.318 6.318a4.5 4.5 0 000 6.364L12 20.364l7.682-7.682a4.5 4.5 0 00-6.364-6.364L12 7.636l-1.318-1.318a4.5 4.5 0 00-6.364 0z" />
+        </svg>
+        Favourites
+      </button>
+    {/if}
+
    <!-- Sort (only show if there are sort options) -->
    {#if config.sortOptions.length > 0}
      <SortButtonGroup options={config.sortOptions} selected={sortBy} onSelect={handleSort} />
@@ -1,4 +1,4 @@
-<!-- TRACES: UR-051, UR-052 | DR-068, DR-078 -->
+<!-- TRACES: UR-051, UR-052, UR-068 | DR-068, DR-078, DR-119 -->
 <script lang="ts">
  import type { MediaItem, Library } from "$lib/api/types";
  import { truncateMiddle } from "$lib/utils/truncateMiddle";
@@ -7,6 +7,8 @@
  import { showServerCatalog } from "$lib/services/offlineCatalog";
  import { auth } from "$lib/stores/auth";
  import CachedImage from "$lib/components/common/CachedImage.svelte";
+  import FavoriteButton from "$lib/components/FavoriteButton.svelte";
+  import { favoriteOverrides, resolveIsFavorite } from "$lib/stores/favorites";

  interface Props {
    item: MediaItem | Library;
@@ -37,9 +39,15 @@
     * TRACES: UR-058 | DR-087
     */
    onLongPress?: () => void;
+    /**
+     * Show the favourite heart on the artwork. On by default for media items;
+     * surfaces that are not about the item itself can opt out.
+     * TRACES: UR-068 | DR-119
+     */
+    showFavorite?: boolean;
  }

-  let { item, size = "medium", showProgress = false, showDownloadStatus = true, sizeLabel, downloadedBadge, onRemove, onclick, onLongPress }: Props = $props();
+  let { item, size = "medium", showProgress = false, showDownloadStatus = true, sizeLabel, downloadedBadge, onRemove, onclick, onLongPress, showFavorite = true }: Props = $props();

  // Long-press detection. We arm a timer on pointerdown; if it fires before the
  // pointer is released (or moves too far), we treat it as a long press and set a
@@ -120,6 +128,13 @@
    isMediaItem && !$isConnected && $showServerCatalog && !isDownloaded && !isActivelyDownloading
  );

+  // The heart is about an item, so libraries never get one, and a greyed
+  // server-only card has nothing actionable to offer. TRACES: UR-068 | DR-119
+  const showHeart = $derived(showFavorite && isMediaItem && !isServerOnly);
+  const isFavorited = $derived(
+    isMediaItem ? resolveIsFavorite(item as MediaItem, $favoriteOverrides) : false
+  );
+
  let queueError = $state<string | null>(null);

  // Queue this item for download on next reconnect. Offline, this just persists
@@ -250,12 +265,34 @@
      </div>
    {/if}

-    <!-- Played indicator -->
-    {#if "userData" in item && item.userData?.isPlayed}
-      <div class="absolute top-2 right-2">
-        <svg class="w-5 h-5 text-[var(--color-jellyfin)]" fill="currentColor" viewBox="0 0 24 24">
-          <path d="M9 16.17L4.83 12l-1.42 1.41L9 19 21 7l-1.41-1.41z"/>
-        </svg>
+    <!-- Top-right status stack: played tick, then the favourite heart. Grouped
+         so the two never land on the same pixels when both apply. -->
+    {#if ("userData" in item && item.userData?.isPlayed) || showHeart}
+      <div class="absolute top-2 right-2 flex flex-col items-end gap-1">
+        {#if "userData" in item && item.userData?.isPlayed}
+          <svg class="w-5 h-5 text-[var(--color-jellyfin)]" fill="currentColor" viewBox="0 0 24 24">
+            <path d="M9 16.17L4.83 12l-1.42 1.41L9 19 21 7l-1.41-1.41z"/>
+          </svg>
+        {/if}
+        {#if showHeart}
+          <!-- Always visible on touch (no hover to reveal it); on pointer
+               devices an unfavourited heart stays out of the way until the card
+               is hovered or focused. A favourited one is always shown — it is
+               state, not an affordance. TRACES: UR-068 | DR-119 -->
+          <div
+            class="transition-opacity {isFavorited
+              ? ''
+              : 'opacity-100 [@media(hover:hover)]:opacity-0 [@media(hover:hover)]:group-hover/card:opacity-100 [@media(hover:hover)]:group-focus-within/card:opacity-100'}"
+          >
+            <FavoriteButton
+              itemId={item.id}
+              isFavorite={isFavorited}
+              size="sm"
+              variant="overlay"
+              stopPropagation
+            />
+          </div>
+        {/if}
      </div>
    {/if}

@@ -7,6 +7,8 @@
  import { toast } from "$lib/stores/toast";
  import TrackList from "./TrackList.svelte";
  import CachedImage from "$lib/components/common/CachedImage.svelte";
+  import FavoriteButton from "$lib/components/FavoriteButton.svelte";
+  import { favoriteOverrides } from "$lib/stores/favorites";
  import { formatDuration } from "$lib/utils/duration";

  interface Props {
@@ -214,6 +216,13 @@
          </svg>
          Shuffle
        </button>
+        <!-- TRACES: UR-068 | DR-119 -->
+        <FavoriteButton
+          itemId={playlist.id}
+          isFavorite={$favoriteOverrides.get(playlist.id) ?? false}
+          size="lg"
+          className="self-center"
+        />
        <button
          onclick={() => showDeleteConfirm = true}
          class="px-4 py-2 bg-[var(--color-surface)] hover:bg-red-900/50 text-red-400 hover:text-red-300 rounded-lg font-medium flex items-center gap-2 transition-colors"
@@ -1,9 +1,11 @@
+// TRACES: UR-062 | DR-102, DR-103, DR-142 | UT-136
 import { describe, it, expect } from "vitest";
 import type { MediaItem } from "$lib/api/types";
 import {
  seasonAnchorId,
  seasonRedirectTarget,
  episodeFocusHref,
+  episodeRedirectTarget,
  seriesPlayHref,
  seriesPlayLabel,
  groupEpisodesBySeason,
@@ -103,6 +105,17 @@ describe("episodeFocusHref", () => {
  });
 });

+describe("episodeRedirectTarget", () => {
+  it("sends a bare episode page to the episode inside its series", () => {
+    expect(episodeRedirectTarget(ep("s1e2", 1, 2))).toBe("/library/series-1?episode=s1e2");
+  });
+
+  it("does not redirect an episode that has no series to fall back on", () => {
+    const orphan = { ...ep("lone", 1, 2), seriesId: undefined } as MediaItem;
+    expect(episodeRedirectTarget(orphan)).toBeNull();
+  });
+});
+
 describe("groupEpisodesBySeason", () => {
  it("groups episodes under their season headers, in season order", () => {
    const seasons = [seasonHeader(2), seasonHeader(1)];
@@ -10,7 +10,7 @@
 // lives in Rust (`repository_get_series_current_episode`); this module only
 // renders and routes around the answer.
 //
-// TRACES: UR-062 | DR-102, DR-103
+// TRACES: UR-062 | DR-102, DR-103, DR-142
 import type { MediaItem } from "$lib/api/types";

 export interface SeasonData {
@@ -57,6 +57,21 @@ export function episodeFocusHref(episode: MediaItem): string {
  return `/library/${episode.seriesId}?episode=${episode.id}`;
 }

+/**
+ * Where a bare `/library/<episodeId>` should actually land — the same rule
+ * seasons follow (DR-103). An episode is never a page of its own, so a deep
+ * link, a stale bookmark, or any caller that missed `episodeFocusHref` is
+ * redirected into the series' Episode Focus View.
+ *
+ * Returns `null` for an episode with no `seriesId` (a deep link into a stale
+ * cache): there is nothing to redirect *to*, so the caller renders the Focus
+ * View series-less rather than stranding the user (ux-flows §5B.1).
+ */
+export function episodeRedirectTarget(episode: MediaItem): string | null {
+  if (!episode.seriesId) return null;
+  return episodeFocusHref(episode);
+}
+
 /**
 * Where the series hero button goes.
 *
@@ -154,8 +154,16 @@
      <div class="fixed inset-0 z-0 bg-[var(--color-background)]"></div>
    {/if}

-    <!-- Content overlay -->
-    <div class="relative z-10 flex flex-col h-full">
+    <!-- Content overlay. The blurred artwork behind it stays edge-to-edge; only
+         this layer is inset, so the close button clears the status bar and the
+         transport controls clear the Android gesture bar. (UR-066) -->
+    <div
+      class="relative z-10 flex flex-col h-full"
+      style:padding-top="var(--safe-top)"
+      style:padding-bottom="var(--safe-bottom)"
+      style:padding-left="var(--safe-left)"
+      style:padding-right="var(--safe-right)"
+    >
    <!-- Header -->
    <div class="flex items-center justify-between p-4 flex-shrink-0">
      <button
@@ -329,8 +337,12 @@
      aria-label="Close queue"
    ></button>

-    <!-- Queue Panel -->
-    <div class="absolute bottom-0 left-0 right-0 max-h-[70vh] animate-slide-up">
+    <!-- Queue Panel. Slides up from the very bottom, so it owns the bottom
+         inset — its last row would otherwise sit under the gesture bar. -->
+    <div
+      class="absolute bottom-0 left-0 right-0 max-h-[70vh] animate-slide-up"
+      style:padding-bottom="var(--safe-bottom)"
+    >
      <Queue
        items={$queueItems}
        currentIndex={$currentQueueIndex}
@@ -1,6 +1,7 @@
 <!-- TRACES: UR-003, UR-005, UR-020, UR-021, UR-026, UR-040, UR-061 | DR-010, DR-023, DR-024, DR-051, DR-052, DR-092, DR-098, DR-099 -->
 <script lang="ts">
  import { onMount, onDestroy, untrack } from "svelte";
+  import { get } from "svelte/store";
  import { goto } from "$app/navigation";
  import { commands } from "$lib/api/bindings";
  import type { JRayActor } from "$lib/api/bindings";
@@ -14,7 +15,7 @@
  import CachedImage from "../common/CachedImage.svelte";
  import { videoFitClass } from "./videoFit";
  import { sleepTimerActive, sleepTimerExpiredSignal } from "$lib/stores/sleepTimer";
-  import { playbackPosition } from "$lib/stores/player";
+  import { playbackPosition, playerState } from "$lib/stores/player";
  import * as html5Adapter from "$lib/player/html5Adapter";
  import { playerController } from "$lib/player";
  import { Html5PlayerAdapter, type Html5ElementBridge } from "$lib/player/adapters";
@@ -42,6 +43,7 @@
    initialHandoffState,
    shouldEnterBackgroundAudio,
    shouldExitBackgroundAudio,
+    shouldResumeOnForeground,
    type BackgroundAudioState,
  } from "./backgroundAudioHandoff";

@@ -1333,7 +1335,11 @@
  // the position native reached, and restore play/pause.
  async function exitBackgroundAudioHandoff() {
    if (!shouldExitBackgroundAudio(handoffState)) return;
-    const wasPlaying = handoffState.wasPlaying;
+    // Read the native player's state BEFORE exiting — the exit stops it. If the
+    // user hit pause on the lockscreen while backgrounded, that pause must
+    // survive the return to video rather than being overwritten by whatever the
+    // <video> was doing when we handed off.
+    const wasPlaying = shouldResumeOnForeground(handoffState.wasPlaying, get(playerState).kind);
    handoffState = { ...initialHandoffState };
    try {
      // Absolute position the native audio reached (base offset applied in Rust).
@@ -1869,7 +1875,13 @@
         returned actors for the current timestamp. Tapping an actor with a
         resolved Jellyfin Person id opens their library page. -->
    {#if !isPlaying && !isSeeking && jrayActors.length > 0}
-      <div class="absolute top-4 right-4 max-w-xs bg-black/70 rounded-lg p-3 backdrop-blur-sm pointer-events-auto">
+      <!-- Offset by the safe-area insets so the card clears the status bar and,
+           in landscape, the display cutout. (UR-066) -->
+      <div
+        class="absolute top-4 right-4 max-w-xs bg-black/70 rounded-lg p-3 backdrop-blur-sm pointer-events-auto"
+        style:top="calc(1rem + var(--safe-top))"
+        style:right="calc(1rem + var(--safe-right))"
+      >
        <div class="text-white/60 text-xs font-medium uppercase tracking-wide mb-2">On screen</div>
        <div class="flex flex-col gap-2">
          {#each jrayActors as actor (actor.name + actor.jellyfin_id)}
@@ -1905,10 +1917,19 @@
  </div>

  <!-- Controls. `data-player-controls` marks this subtree as interactive so
-       container-level tap gestures ignore touches here (see DR-098). -->
+       container-level tap gestures ignore touches here (see DR-098).
+
+       The video itself deliberately fills the whole screen (edge-to-edge, under
+       the cutout), but every interactive control lives in here — so this box,
+       not the video, carries the safe-area insets. Without them the scrub bar
+       and the close/fullscreen buttons sit under the Android gesture bar, and
+       in landscape under the display cutout. (UR-066) -->
  <div
    data-player-controls
    class="absolute bottom-0 left-0 right-0 bg-gradient-to-t from-black/80 to-transparent p-4 transition-opacity duration-300"
+    style:padding-bottom="calc(1rem + var(--safe-bottom))"
+    style:padding-left="calc(1rem + var(--safe-left))"
+    style:padding-right="calc(1rem + var(--safe-right))"
    class:opacity-0={!showControls}
    class:pointer-events-none={!showControls}
  >
@@ -4,6 +4,7 @@ import {
  initialHandoffState,
  shouldEnterBackgroundAudio,
  shouldExitBackgroundAudio,
+  shouldResumeOnForeground,
  type BackgroundAudioState,
 } from "./backgroundAudioHandoff";

@@ -58,4 +59,27 @@ describe("backgroundAudioHandoff", () => {
      expect(shouldExitBackgroundAudio(active)).toBe(true);
    });
  });
+
+  describe("shouldResumeOnForeground", () => {
+    it("resumes when it was playing and the native audio still is", () => {
+      expect(shouldResumeOnForeground(true, "playing")).toBe(true);
+    });
+
+    it("stays paused when the lockscreen paused the native audio", () => {
+      // The whole point of the lockscreen pause: coming back to the app must not
+      // undo it just because the video was playing when we handed off.
+      expect(shouldResumeOnForeground(true, "paused")).toBe(false);
+    });
+
+    it("stays paused when the video was already paused at handoff", () => {
+      expect(shouldResumeOnForeground(false, "playing")).toBe(false);
+    });
+
+    it("falls back to the captured state when native state is unknown", () => {
+      // Loading/seeking/idle say nothing about intent — the handoff snapshot is
+      // the best evidence we have, so a playing video still resumes.
+      expect(shouldResumeOnForeground(true, "loading")).toBe(true);
+      expect(shouldResumeOnForeground(true, undefined)).toBe(true);
+    });
+  });
 });
@@ -55,3 +55,22 @@ export function shouldEnterBackgroundAudio(
 export function shouldExitBackgroundAudio(state: BackgroundAudioState): boolean {
  return state.active;
 }
+
+/**
+ * Whether the `<video>` should start playing again once it reloads on foreground.
+ *
+ * `wasPlaying` is what the video was doing when we handed off, but the native
+ * audio player kept going after that — and the lockscreen/notification can pause
+ * it while backgrounded. The player is the authoritative source of play/pause,
+ * so an explicit `paused` from it overrides the handoff snapshot; anything less
+ * definite (loading, seeking, already-stopped, no state at all) falls back to
+ * the snapshot.
+ *
+ * TRACES: UR-040, UR-005 | DR-052 | UT-060
+ */
+export function shouldResumeOnForeground(
+  wasPlaying: boolean,
+  nativeStateKind: string | undefined
+): boolean {
+  return wasPlaying && nativeStateKind !== "paused";
+}
@@ -0,0 +1,88 @@
+<!--
+  The header search box (md+ only; below md the bottom-nav Search tab and the
+  /search page's own input serve that role).
+
+  One box, one results surface. The bar renders on the library routes *and on
+  /search itself*, so searching from the header no longer swaps you onto a
+  screen whose input is somewhere else: the box you typed in stays where it is
+  and keeps driving the results. Off /search it navigates there (the only
+  surface that renders results); on /search it republishes the query into the
+  URL, which the page consumes.
+
+  TRACES: UR-049, UR-054 | DR-063, DR-064, DR-147
+-->
+<script lang="ts">
+  import { onMount, tick } from "svelte";
+  import { goto } from "$app/navigation";
+  import { page } from "$app/stores";
+  import { library } from "$lib/stores/library";
+  import Search from "$lib/components/Search.svelte";
+  import {
+    isSearchRoute,
+    parseSearchScope,
+    resolveSearchScope,
+    searchRouteUrl,
+    type SearchScope,
+  } from "$lib/utils/searchScope";
+
+  // Seeded from the URL, then owned by the user. A navigation to /search
+  // remounts this component (library and root render their own AppHeader), so
+  // reading `?q=` here is what carries a half-typed query across that hop.
+  let value = $state($page.url.searchParams.get("q") ?? "");
+  let inputEl = $state<HTMLInputElement | null>(null);
+
+  let scope = $state<SearchScope>(
+    isSearchRoute($page.url.pathname)
+      ? parseSearchScope($page.url.searchParams.get("scope"))
+      : resolveSearchScope($page.url.pathname)
+  );
+
+  $effect(() => {
+    const url = $page.url;
+    if (isSearchRoute(url.pathname)) {
+      // On /search the scope chips own the scope and publish it in the URL, so
+      // the bar follows rather than overriding it on the next keystroke.
+      scope = parseSearchScope(url.searchParams.get("scope"));
+    } else if (!value.trim()) {
+      // Elsewhere the route seeds the scope, but only while no search is
+      // active: navigating must not snap a widened search back to the section
+      // the user happens to be in.
+      scope = resolveSearchScope(url.pathname);
+    }
+  });
+
+  // Landing on /search with a seeded query means the user was mid-type in the
+  // previous route's header. That box is gone; put the caret back in this one
+  // so their next keystroke lands in the search field and not nowhere.
+  onMount(async () => {
+    if (!value) return;
+    await tick();
+    inputEl?.focus();
+    inputEl?.setSelectionRange(value.length, value.length);
+  });
+
+  async function handleSearch(query: string) {
+    if (isSearchRoute($page.url.pathname)) {
+      // Already on the results surface — republish in place. replaceState keeps
+      // a whole session of typing to a single history entry.
+      await goto(searchRouteUrl(query, scope), {
+        replaceState: true,
+        keepFocus: true,
+        noScroll: true,
+      });
+      return;
+    }
+    if (!query.trim()) {
+      library.clearSearch();
+      return;
+    }
+    await goto(searchRouteUrl(query, scope));
+  }
+</script>
+
+<Search
+  bind:value
+  bind:inputEl
+  placeholder="Search your library..."
+  onSearch={handleSearch}
+/>
@@ -0,0 +1,110 @@
+/**
+ * The header search bar is the single md+ search input.
+ *
+ * Off /search it navigates there (the only surface that renders results); on
+ * /search it stays put and republishes the query into the URL, so the user goes
+ * on typing in the same box instead of being handed to a second input owned by
+ * the page.
+ *
+ * TRACES: UR-049, UR-054 | DR-147
+ */
+
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { render, screen, fireEvent, waitFor } from "@testing-library/svelte";
+
+const { pageStore, goto, clearSearch } = vi.hoisted(() => {
+  const { writable } = require("svelte/store");
+  return {
+    pageStore: writable({ url: new URL("http://localhost/library/music") }),
+    goto: vi.fn(),
+    clearSearch: vi.fn(),
+  };
+});
+
+vi.mock("$app/stores", () => ({ page: pageStore, navigating: { subscribe: () => () => {} } }));
+vi.mock("$app/navigation", () => ({ goto, afterNavigate: vi.fn(), beforeNavigate: vi.fn() }));
+vi.mock("$lib/stores/library", () => ({
+  library: { subscribe: () => () => {}, search: vi.fn(), clearSearch },
+}));
+
+import HeaderSearch from "./HeaderSearch.svelte";
+
+const afterDebounce = () => new Promise((resolve) => setTimeout(resolve, 450));
+
+function input(): HTMLInputElement {
+  return screen.getByPlaceholderText("Search your library...") as HTMLInputElement;
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  pageStore.set({ url: new URL("http://localhost/library/music") });
+});
+
+describe("from a library route", () => {
+  it("routes to /search with the query and the route's scope", async () => {
+    render(HeaderSearch);
+
+    await fireEvent.input(input(), { target: { value: "jazz" } });
+    await afterDebounce();
+
+    expect(goto).toHaveBeenCalledWith("/search?q=jazz&scope=music");
+  });
+
+  it("clears the results rather than navigating on an empty query", async () => {
+    render(HeaderSearch);
+
+    await fireEvent.input(input(), { target: { value: "jazz" } });
+    await afterDebounce();
+    goto.mockClear();
+
+    await fireEvent.input(input(), { target: { value: "" } });
+    await afterDebounce();
+
+    expect(goto).not.toHaveBeenCalled();
+    expect(clearSearch).toHaveBeenCalled();
+  });
+});
+
+describe("on /search", () => {
+  beforeEach(() => {
+    pageStore.set({ url: new URL("http://localhost/search?q=jazz&scope=music") });
+  });
+
+  it("carries the query over from the URL and puts the caret back in the box", async () => {
+    render(HeaderSearch);
+
+    await waitFor(() => expect(document.activeElement).toBe(input()));
+    expect(input().value).toBe("jazz");
+    expect(input().selectionStart).toBe(4);
+  });
+
+  it("republishes in place instead of pushing a second results screen", async () => {
+    render(HeaderSearch);
+
+    await fireEvent.input(input(), { target: { value: "jazzy" } });
+    await afterDebounce();
+
+    expect(goto).toHaveBeenCalledWith("/search?q=jazzy&scope=music", {
+      replaceState: true,
+      keepFocus: true,
+      noScroll: true,
+    });
+    // The box the user is typing in keeps its text — nothing re-seeds it.
+    expect(input().value).toBe("jazzy");
+  });
+
+  it("searches with the scope the page's chips published, not the route default", async () => {
+    // A chip pick lands in the URL; the bar must adopt it or the next keystroke
+    // would silently widen the search back to All.
+    pageStore.set({ url: new URL("http://localhost/search?q=jazz&scope=tv") });
+    render(HeaderSearch);
+
+    await fireEvent.input(input(), { target: { value: "jazzy" } });
+    await afterDebounce();
+
+    expect(goto).toHaveBeenCalledWith(
+      "/search?q=jazzy&scope=tv",
+      expect.objectContaining({ replaceState: true })
+    );
+  });
+});
@@ -0,0 +1,137 @@
+<!--
+  What the "N waiting to sync" badge actually stands for.
+
+  These are outgoing changes — watch positions, watched flags — made while the
+  server was unreachable and still waiting to reach Jellyfin. They are *not*
+  downloads, which is where the badge used to send people looking: the Downloads
+  page lists the `downloads` table and structurally cannot show these.
+
+  Rows push themselves on reconnect (DR-131); "Sync now" only asks for that to
+  happen immediately.
+
+  TRACES: UR-025 | DR-132
+-->
+<script lang="ts">
+  import { onMount } from "svelte";
+  import { commands, type SyncQueueItem } from "$lib/api/bindings";
+  import { syncService } from "$lib/services/syncService";
+  import { pendingSyncCount } from "$lib/stores/appState";
+  import { isConnected } from "$lib/stores/connectivity";
+  import {
+    describeOperation,
+    describeSubject,
+    isStuck,
+    summarize,
+    sortForDisplay,
+  } from "$lib/services/pendingSync.logic";
+
+  let items = $state<SyncQueueItem[]>([]);
+  let loading = $state(true);
+  let syncing = $state(false);
+  let error = $state<string | null>(null);
+  let lastResult = $state<string | null>(null);
+
+  const summary = $derived(summarize(items));
+
+  export async function refresh() {
+    try {
+      loading = true;
+      error = null;
+      items = sortForDisplay(await syncService.getPending());
+      pendingSyncCount.set(items.length);
+    } catch (err) {
+      error = err instanceof Error ? err.message : String(err);
+    } finally {
+      loading = false;
+    }
+  }
+
+  onMount(refresh);
+
+  async function syncNow() {
+    try {
+      syncing = true;
+      error = null;
+      const report = await commands.syncProcessPending();
+      lastResult =
+        report.pushed > 0
+          ? `Sent ${report.pushed} update${report.pushed === 1 ? "" : "s"}.`
+          : "Nothing could be sent — the server is still unreachable.";
+      await refresh();
+    } catch (err) {
+      error = err instanceof Error ? err.message : String(err);
+    } finally {
+      syncing = false;
+    }
+  }
+
+  function formatQueuedAt(createdAt: string | null): string {
+    if (!createdAt) return "";
+    const parsed = Date.parse(createdAt);
+    return Number.isNaN(parsed) ? "" : new Date(parsed).toLocaleString();
+  }
+</script>
+
+<div class="space-y-4">
+  <p class="text-sm text-gray-400">
+    Changes made while the server was unreachable — watch positions and watched
+    flags — waiting to reach Jellyfin. They send themselves when the server comes
+    back. This is not the download queue; downloaded media lives under Downloads.
+  </p>
+
+  {#if loading}
+    <p class="py-6 text-center text-sm text-gray-400">Loading queued updates…</p>
+  {:else if items.length === 0}
+    <p class="py-6 text-center text-sm text-gray-500">Everything is synced.</p>
+  {:else}
+    <div class="flex flex-wrap items-center gap-3">
+      <button
+        onclick={syncNow}
+        disabled={syncing || !$isConnected}
+        class="rounded-lg bg-[var(--color-jellyfin)] px-4 py-2 text-sm font-medium text-white transition hover:opacity-90 disabled:cursor-not-allowed disabled:opacity-40"
+        title={$isConnected ? "Send these now" : "Needs a reachable server"}
+      >
+        {syncing ? "Sending…" : "Sync now"}
+      </button>
+      {#if summary.stuck > 0}
+        <span class="text-xs text-amber-400">
+          {summary.stuck} failed and will be retried
+        </span>
+      {/if}
+      {#if lastResult}
+        <span class="text-xs text-gray-400">{lastResult}</span>
+      {/if}
+    </div>
+
+    <ul class="space-y-2">
+      {#each items as item (item.id)}
+        <li
+          class="rounded-lg border-l-4 bg-[var(--color-surface)] p-3 {isStuck(item)
+            ? 'border-amber-500/60'
+            : 'border-gray-600/60'}"
+        >
+          <div class="flex items-start justify-between gap-3">
+            <div class="min-w-0">
+              <p class="truncate text-sm font-medium text-white">
+                {describeOperation(item.operation)}
+              </p>
+              <p class="truncate text-xs text-gray-400">{describeSubject(item)}</p>
+              {#if item.errorMessage}
+                <p class="mt-1 text-xs text-amber-400">
+                  {item.errorMessage}{item.retryCount > 0 ? ` (attempt ${item.retryCount})` : ""}
+                </p>
+              {/if}
+            </div>
+            <span class="shrink-0 text-[11px] text-gray-500">
+              {formatQueuedAt(item.createdAt)}
+            </span>
+          </div>
+        </li>
+      {/each}
+    </ul>
+  {/if}
+
+  {#if error}
+    <p class="text-sm text-red-400">{error}</p>
+  {/if}
+</div>
@@ -0,0 +1,57 @@
+<!--
+  Modal wrapper for the pending-sync queue, opened from the offline banner's
+  badge so the count is answerable where the user reads it.
+
+  TRACES: UR-025 | DR-132
+-->
+<script lang="ts">
+  import PendingSyncList from "./PendingSyncList.svelte";
+
+  interface Props {
+    isOpen: boolean;
+    onClose: () => void;
+  }
+
+  let { isOpen, onClose }: Props = $props();
+
+  function handleBackdropClick(event: MouseEvent) {
+    if (event.target === event.currentTarget) onClose();
+  }
+</script>
+
+{#if isOpen}
+  <div
+    class="fixed inset-0 z-50 flex items-end justify-center bg-black/60 p-0 sm:items-center sm:p-4"
+    onclick={handleBackdropClick}
+    onkeydown={(e) => { if (e.key === "Escape") onClose(); }}
+    role="dialog"
+    aria-modal="true"
+    aria-labelledby="pending-sync-title"
+    tabindex="-1"
+  >
+    <div
+      class="flex max-h-[80vh] w-full flex-col rounded-t-2xl bg-[var(--color-surface)] shadow-2xl sm:max-h-[70vh] sm:max-w-lg sm:rounded-2xl"
+      onclick={(e) => e.stopPropagation()}
+      role="none"
+    >
+      <div class="flex items-center justify-between border-b border-gray-800 px-6 py-4">
+        <h2 id="pending-sync-title" class="text-lg font-semibold text-white">
+          Waiting to sync
+        </h2>
+        <button
+          onclick={onClose}
+          class="-m-2 p-2 text-gray-400 transition-colors hover:text-white"
+          aria-label="Close"
+        >
+          <svg class="h-5 w-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M6 18L18 6M6 6l12 12" />
+          </svg>
+        </button>
+      </div>
+
+      <div class="flex-1 overflow-y-auto p-6">
+        <PendingSyncList />
+      </div>
+    </div>
+  </div>
+{/if}
@@ -0,0 +1,55 @@
+// TRACES: UR-052 | DR-143 | UT-140
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { writable } from "svelte/store";
+
+const h = vi.hoisted(() => ({
+  version: null as ReturnType<typeof import("svelte/store").writable<number>> | null,
+  destroyFns: [] as Array<() => void>,
+}));
+
+vi.mock("svelte", () => ({
+  onDestroy: (fn: () => void) => h.destroyFns.push(fn),
+}));
+
+vi.mock("$lib/services/offlineCatalog", () => ({
+  get catalogFilterVersion() {
+    return h.version;
+  },
+}));
+
+import { useOfflineFilterReload } from "./useOfflineFilterReload";
+
+describe("useOfflineFilterReload (DR-143)", () => {
+  beforeEach(() => {
+    h.version = writable(0);
+    h.destroyFns.length = 0;
+  });
+
+  it("does not reload for the value the page already loaded under", () => {
+    const reload = vi.fn();
+    useOfflineFilterReload(reload);
+
+    expect(reload).not.toHaveBeenCalled();
+  });
+
+  it("reloads once each time the gate settles into a new state", () => {
+    const reload = vi.fn();
+    useOfflineFilterReload(reload);
+
+    h.version!.set(1);
+    expect(reload).toHaveBeenCalledTimes(1);
+
+    h.version!.set(2);
+    expect(reload).toHaveBeenCalledTimes(2);
+  });
+
+  it("stops reloading a page that has been destroyed", () => {
+    const reload = vi.fn();
+    useOfflineFilterReload(reload);
+
+    h.destroyFns.forEach((fn) => fn());
+    h.version!.set(1);
+
+    expect(reload).not.toHaveBeenCalled();
+  });
+});
@@ -0,0 +1,47 @@
+/**
+ * Re-query a listing when the offline "downloaded only" gate changes.
+ *
+ * The gate is a process-wide flag in Rust, consulted only while a query runs,
+ * so flipping it has no effect on rows already on screen. Library pages loaded
+ * once on mount and reloaded only on the offline → online transition
+ * (`useServerReachabilityReload`), which left two gaps the user sees as a broken
+ * filter:
+ *
+ *  - going *offline* never reloaded, so the full server catalog stayed on
+ *    screen under a now-closed gate;
+ *  - toggling "Show all server media" never reloaded, so it only greyed the
+ *    cards already listed instead of adding or removing any.
+ *
+ * `catalogFilterVersion` bumps once the backend has accepted the new gate, so
+ * the reload this triggers always queries under the intended filter.
+ *
+ * Call during component initialisation, like `useServerReachabilityReload`:
+ *
+ * ```svelte
+ * <script>
+ *   useOfflineFilterReload(() => loadItems());
+ * </script>
+ * ```
+ *
+ * TRACES: UR-052 | DR-143
+ */
+import { onDestroy } from "svelte";
+import { catalogFilterVersion } from "$lib/services/offlineCatalog";
+
+export function useOfflineFilterReload(reloadFn: () => void | Promise<void>): void {
+  // The value the page is already showing. Seeded from the first subscription
+  // callback (stores emit synchronously on subscribe) so mounting never
+  // triggers a redundant second load of what onMount just fetched.
+  let applied: number | null = null;
+
+  const unsubscribe = catalogFilterVersion.subscribe((version) => {
+    if (applied === null || version === applied) {
+      applied = version;
+      return;
+    }
+    applied = version;
+    void reloadFn();
+  });
+
+  onDestroy(unsubscribe);
+}
@@ -0,0 +1,102 @@
+import { describe, it, expect } from "vitest";
+import { downloadedFilePath, resolveVideoSource } from "./localSource";
+
+describe("downloadedFilePath", () => {
+  // The download worker rewrites `downloads.file_path` to the absolute path it
+  // actually wrote once the transfer completes, so a completed row is already
+  // rooted. Joining it onto the storage root again produced
+  // `/data/user/0/app//data/user/0/app/videos/x.mp4`, which the asset protocol
+  // cannot open — offline video died with MEDIA_ERR_SRC_NOT_SUPPORTED while
+  // audio, which resolves the same column through Rust, played fine.
+  it("leaves a completed download's absolute path alone", () => {
+    const root = "/data/user/0/com.dtourolle.jellytau";
+    const stored = `${root}/videos/Taming of the Shrew.mp4`;
+
+    expect(downloadedFilePath(root, stored)).toBe(stored);
+  });
+
+  it("roots a path that is still relative to the storage directory", () => {
+    // Rows only hold a relative path before the worker completes them, but a
+    // half-migrated database can still carry one.
+    expect(downloadedFilePath("/var/data/jellytau", "videos/film.mp4")).toBe(
+      "/var/data/jellytau/videos/film.mp4"
+    );
+  });
+
+  it("leaves an absolute Windows path alone", () => {
+    const stored = "C:\\Users\\u\\AppData\\jellytau\\videos\\film.mp4";
+
+    expect(downloadedFilePath("C:\\Users\\u\\AppData\\jellytau", stored)).toBe(stored);
+  });
+});
+
+// A stand-in for Tauri's convertFileSrc, so the module stays pure.
+const toAssetUrl = (p: string) => `asset://localhost/${encodeURIComponent(p)}`;
+
+describe("resolveVideoSource", () => {
+  it("plays the downloaded file when one exists", () => {
+    const decision = resolveVideoSource({
+      localPath: "/home/u/.local/share/jellytau/movie.mp4",
+      remoteUrl: "https://server/Videos/abc/master.m3u8",
+      remoteNeedsTranscoding: true,
+      toAssetUrl,
+    });
+
+    expect(decision.isLocal).toBe(true);
+    expect(decision.url).toBe(toAssetUrl("/home/u/.local/share/jellytau/movie.mp4"));
+  });
+
+  it("never marks a local file as needing transcoding, even when the remote did", () => {
+    // The transcoded path re-requests a whole new stream URL on every seek.
+    // A local file seeks natively; sending it down that route would ask the
+    // server for a stream we deliberately avoided.
+    const decision = resolveVideoSource({
+      localPath: "/downloads/film.mkv",
+      remoteUrl: "https://server/Videos/abc/master.m3u8",
+      remoteNeedsTranscoding: true,
+      toAssetUrl,
+    });
+
+    expect(decision.needsTranscoding).toBe(false);
+  });
+
+  it("streams when nothing is downloaded, preserving the transcoding flag", () => {
+    const decision = resolveVideoSource({
+      localPath: null,
+      remoteUrl: "https://server/Videos/abc/master.m3u8",
+      remoteNeedsTranscoding: true,
+      toAssetUrl,
+    });
+
+    expect(decision).toEqual({
+      url: "https://server/Videos/abc/master.m3u8",
+      needsTranscoding: true,
+      isLocal: false,
+    });
+  });
+
+  it("streams a direct-play remote without claiming it transcodes", () => {
+    const decision = resolveVideoSource({
+      localPath: null,
+      remoteUrl: "https://server/Videos/abc/stream.mp4",
+      remoteNeedsTranscoding: false,
+      toAssetUrl,
+    });
+
+    expect(decision.needsTranscoding).toBe(false);
+    expect(decision.isLocal).toBe(false);
+  });
+
+  it("falls back to streaming for a blank path rather than building a dead asset URL", () => {
+    for (const localPath of ["", "   "]) {
+      const decision = resolveVideoSource({
+        localPath,
+        remoteUrl: "https://server/stream",
+        remoteNeedsTranscoding: false,
+        toAssetUrl,
+      });
+      expect(decision.isLocal).toBe(false);
+      expect(decision.url).toBe("https://server/stream");
+    }
+  });
+});
@@ -0,0 +1,71 @@
+/**
+ * Choosing between a downloaded file and a server stream for video playback.
+ *
+ * Audio has preferred local files since the queue is built (the Rust queue
+ * resolves `MediaSource::Local`), but video asks the repository for a stream URL
+ * and never consults `downloads` — so a downloaded film was streamed anyway,
+ * spending bandwidth that had already been spent and failing outright offline.
+ *
+ * Pure so it can be unit-tested: the component only supplies the two inputs and
+ * the asset-URL converter.
+ *
+ * TRACES: UR-071 | DR-123 | UT-118
+ */
+
+export interface VideoSourceInputs {
+  /** Absolute on-disk path of a completed download, or null to stream. */
+  localPath: string | null;
+  /** Stream URL the repository resolved (already transcoded if it had to be). */
+  remoteUrl: string;
+  /** Whether the *remote* stream is a transcode. */
+  remoteNeedsTranscoding: boolean;
+  /** Usually Tauri's `convertFileSrc`; injected so this module stays pure. */
+  toAssetUrl: (path: string) => string;
+}
+
+export interface VideoSourceDecision {
+  /** What to hand the `<video>` element. */
+  url: string;
+  /**
+   * Local files are never transcodes, so this is always false for them. It
+   * matters because the transcoded path re-requests a whole new stream URL on
+   * every seek; a local file seeks natively and must not go down that route.
+   */
+  needsTranscoding: boolean;
+  /** True when playing from disk — for logging and the offline badge. */
+  isLocal: boolean;
+}
+
+/** Absolute on POSIX (`/…`), Windows (`C:\…`, `C:/…`) or a UNC share (`\\…`). */
+function isAbsolute(path: string): boolean {
+  return path.startsWith("/") || path.startsWith("\\") || /^[A-Za-z]:[\\/]/.test(path);
+}
+
+/**
+ * The on-disk path of a row in the `downloads` store.
+ *
+ * `downloads.file_path` is stored relative to the storage root while a download
+ * is queued, but the worker rewrites it to the absolute path it actually wrote
+ * once the transfer completes — so a *completed* row is already rooted. Joining
+ * it onto the storage root a second time produced
+ * `/data/user/0/app//data/user/0/app/videos/x.mp4`; the asset protocol could not
+ * open that, so offline video failed with `MEDIA_ERR_SRC_NOT_SUPPORTED` while
+ * audio, which resolves the same column through Rust, played fine.
+ *
+ * TRACES: UR-071 | DR-133 | UT-124
+ */
+export function downloadedFilePath(storageRoot: string, filePath: string): string {
+  return isAbsolute(filePath) ? filePath : `${storageRoot}/${filePath}`;
+}
+
+export function resolveVideoSource(inputs: VideoSourceInputs): VideoSourceDecision {
+  const { localPath, remoteUrl, remoteNeedsTranscoding, toAssetUrl } = inputs;
+
+  // Treat blank/whitespace paths as absent — a malformed `downloads` row must
+  // not produce an asset URL pointing at nothing.
+  if (localPath && localPath.trim() !== "") {
+    return { url: toAssetUrl(localPath), needsTranscoding: false, isLocal: true };
+  }
+
+  return { url: remoteUrl, needsTranscoding: remoteNeedsTranscoding, isLocal: false };
+}
@@ -1,10 +1,11 @@
 // Favorites service - Handles toggling favorite status with optimistic updates
-// TRACES: UR-017 | DR-021
+// TRACES: UR-017, UR-068 | DR-021, DR-119

 import { get } from "svelte/store";
 import { commands } from "$lib/api/bindings";
 import { auth } from "$lib/stores/auth";
 import { isConnected } from "$lib/stores/connectivity";
+import { setFavorite } from "$lib/stores/favorites";

 /**
 * Toggle the favorite status of an item.
@@ -33,6 +34,10 @@ export async function toggleFavorite(
  // 1. Update local database first (optimistic update)
  await commands.storageToggleFavorite(userId, itemId, newIsFavorite);

+  // Publish to every mounted view at once, so the heart on a card, the detail
+  // page and the Favourites grid never disagree. TRACES: UR-068 | DR-119
+  setFavorite(itemId, newIsFavorite);
+
  // 2. Sync to Jellyfin server.
  //
  // Only attempt this when we're actually connected. When offline, the server
@@ -0,0 +1,162 @@
+// The offline "downloaded only" gate is a *backend* flag, so flipping it only
+// changes what the user sees if the listing is re-queried afterwards. Nothing
+// re-queried: the toggle greyed cards instantly (a pure frontend derivation in
+// MediaCard) while the item list stayed exactly as it was loaded, which is why
+// the filter read as "shows everything until I toggle, then greys some of it".
+//
+// `catalogFilterVersion` is the refetch signal, and it must bump only once the
+// backend has actually accepted the new flag — a reload racing the push would
+// re-query under the old gate and land back where it started.
+//
+// TRACES: UR-052 | DR-078, DR-143 | UT-137, UT-138, UT-139
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { get } from "svelte/store";
+
+const h = vi.hoisted(() => {
+  function shim<T>(initial: T) {
+    let value = initial;
+    const subs = new Set<(v: T) => void>();
+    return {
+      set(v: T) {
+        value = v;
+        subs.forEach((fn) => fn(value));
+      },
+      subscribe(fn: (v: T) => void) {
+        subs.add(fn);
+        fn(value);
+        return () => subs.delete(fn);
+      },
+      /**
+       * Drop subscribers from previously imported copies of the module.
+       * `vi.resetModules()` gives each test a fresh module instance, but this
+       * store outlives them all — without this the stale instances keep
+       * consuming `mockImplementationOnce` and pushing their own state.
+       */
+      reset(v: T) {
+        subs.clear();
+        value = v;
+      },
+    };
+  }
+  return {
+    isConnectedStore: shim(true),
+    // Resolution is deferred so a test can observe the window between "command
+    // issued" and "command accepted".
+    pending: [] as Array<() => void>,
+    setShowServerCatalog: vi.fn(
+      () => new Promise<void>((resolve) => h.pending.push(() => resolve()))
+    ),
+  };
+});
+
+vi.mock("$lib/stores/connectivity", () => ({
+  isConnected: { subscribe: h.isConnectedStore.subscribe },
+}));
+
+vi.mock("$lib/api/bindings", () => ({
+  commands: {
+    setShowServerCatalog: h.setShowServerCatalog,
+    syncFullCatalog: vi.fn(),
+    resumeQueuedDownloads: vi.fn(),
+    catalogSyncStatus: vi.fn(),
+  },
+}));
+
+vi.mock("$lib/stores/auth", () => ({
+  auth: { getRepository: () => ({ getHandle: () => "handle-1" }) },
+}));
+
+/** Let every issued setShowServerCatalog settle. */
+async function settle() {
+  h.pending.splice(0).forEach((resolve) => resolve());
+  await Promise.resolve();
+  await Promise.resolve();
+}
+
+describe("offline filter refetch signal (DR-143)", () => {
+  beforeEach(() => {
+    h.setShowServerCatalog.mockReset();
+    h.setShowServerCatalog.mockImplementation(
+      () => new Promise<void>((resolve) => h.pending.push(() => resolve()))
+    );
+    h.pending.length = 0;
+    h.isConnectedStore.reset(true);
+    vi.resetModules();
+  });
+
+  it("bumps the version when going offline closes the gate", async () => {
+    const mod = await import("./offlineCatalog");
+    await settle();
+    const before = get(mod.catalogFilterVersion);
+
+    h.isConnectedStore.set(false); // include: true → false
+    await settle();
+
+    expect(h.setShowServerCatalog).toHaveBeenLastCalledWith(false);
+    expect(get(mod.catalogFilterVersion)).toBeGreaterThan(before);
+  });
+
+  it("bumps only after the backend accepts the flag, never before", async () => {
+    const mod = await import("./offlineCatalog");
+    await settle();
+    const before = get(mod.catalogFilterVersion);
+
+    h.isConnectedStore.set(false);
+    await Promise.resolve(); // command issued, not yet resolved
+
+    expect(h.setShowServerCatalog).toHaveBeenLastCalledWith(false);
+    expect(get(mod.catalogFilterVersion)).toBe(before);
+
+    await settle();
+    expect(get(mod.catalogFilterVersion)).toBeGreaterThan(before);
+  });
+
+  it("bumps both ways as the offline toggle is flipped", async () => {
+    const mod = await import("./offlineCatalog");
+    h.isConnectedStore.set(false);
+    await settle();
+    const offlineGated = get(mod.catalogFilterVersion);
+
+    mod.showServerCatalog.set(true); // reveal the server catalog
+    await settle();
+    expect(h.setShowServerCatalog).toHaveBeenLastCalledWith(true);
+    const revealed = get(mod.catalogFilterVersion);
+    expect(revealed).toBeGreaterThan(offlineGated);
+
+    mod.showServerCatalog.set(false); // back to downloaded-only
+    await settle();
+    expect(h.setShowServerCatalog).toHaveBeenLastCalledWith(false);
+    expect(get(mod.catalogFilterVersion)).toBeGreaterThan(revealed);
+  });
+
+  it("does not bump when the effective gate is unchanged", async () => {
+    const mod = await import("./offlineCatalog");
+    await settle();
+    const before = get(mod.catalogFilterVersion);
+
+    // Online, the toggle cannot close the gate — browsing reads the same cache.
+    mod.showServerCatalog.set(true);
+    await settle();
+
+    expect(get(mod.catalogFilterVersion)).toBe(before);
+  });
+
+  it("retries the push after a failed one rather than latching the old gate", async () => {
+    const mod = await import("./offlineCatalog");
+    await settle();
+    const before = get(mod.catalogFilterVersion);
+
+    h.setShowServerCatalog.mockImplementationOnce(() => Promise.reject(new Error("ipc down")));
+    h.isConnectedStore.set(false);
+    await settle();
+    expect(get(mod.catalogFilterVersion)).toBe(before); // nothing to reload for
+
+    // The same transition must be attempted again, not skipped as "already sent".
+    h.isConnectedStore.set(true);
+    await settle();
+    h.isConnectedStore.set(false);
+    await settle();
+    expect(h.setShowServerCatalog).toHaveBeenLastCalledWith(false);
+    expect(get(mod.catalogFilterVersion)).toBeGreaterThan(before);
+  });
+});
@@ -25,30 +25,62 @@ import { isConnected } from "$lib/stores/connectivity";
 */
 export const showServerCatalog: Writable<boolean> = writable(false);

+/**
+ * Bumped every time the backend's downloads-only gate *settles* into a new
+ * state. Library pages watch it and re-query.
+ *
+ * The gate lives in Rust and is only consulted when a query runs, so flipping
+ * it changes nothing already on screen. Without this signal the toggle merely
+ * greyed cards — `MediaCard.isServerOnly` is a pure frontend derivation and
+ * updates instantly — while the item list stayed as first loaded. That is the
+ * "shows everything until I filter" behaviour: the listing had never been
+ * re-queried under the closed gate. Going offline had the same problem, since
+ * nothing reloads on the online → offline transition either.
+ *
+ * It bumps *after* the command resolves, never before: a reload racing the push
+ * would re-query under the old gate and undo itself.
+ *
+ * TRACES: UR-052 | DR-143
+ */
+export const catalogFilterVersion: Writable<number> = writable(0);
+
 // Keep the backend's offline library queries in sync with the UI toggle. The
 // offline cache holds the whole synced catalog, so `get_items` would otherwise
 // return every server item even offline with the toggle off. Include the
 // non-downloaded catalog only when online (fast browsing reads the same cache)
 // or when the "Show all server media" toggle is on.
 let lastIncludeCatalog: boolean | null = null;
-function pushCatalogVisibility(connected: boolean, showCatalog: boolean): void {
+async function pushCatalogVisibility(connected: boolean, showCatalog: boolean): Promise<void> {
  const include = connected || showCatalog;
  if (include === lastIncludeCatalog) return;
  lastIncludeCatalog = include;
-  commands.setShowServerCatalog(include).catch((err) => {
+
+  try {
+    await commands.setShowServerCatalog(include);
+  } catch (err) {
    console.warn("[OfflineCatalog] Failed to set catalog visibility:", err);
-  });
+    // The backend is still on the old gate, so forget that we sent this —
+    // otherwise the next identical transition is skipped as a no-op and the
+    // frontend and backend disagree about the filter for the rest of the
+    // session. No version bump: there is nothing new to re-query under.
+    lastIncludeCatalog = null;
+    return;
+  }
+
+  catalogFilterVersion.update((n) => n + 1);
 }

 let connectedNow = true;
 let showCatalogNow = false;
+// Fire-and-forget on purpose: the push handles its own failure, and subscribers
+// must not block. Consumers wait on `catalogFilterVersion` instead.
 isConnected.subscribe((v) => {
  connectedNow = v;
-  pushCatalogVisibility(connectedNow, showCatalogNow);
+  void pushCatalogVisibility(connectedNow, showCatalogNow);
 });
 showServerCatalog.subscribe((v) => {
  showCatalogNow = v;
-  pushCatalogVisibility(connectedNow, showCatalogNow);
+  void pushCatalogVisibility(connectedNow, showCatalogNow);
 });

 /** Last time a full catalog sync completed, for a UI hint. */
@@ -66,9 +98,14 @@ function currentHandle(): string | null {
 }

 /**
- * Walk every library and cache the full catalog. Best-effort and non-blocking:
- * safe to call on startup (while online) and on reconnect. No-ops if not
- * connected or a sync is already running.
+ * Force a full re-index now, ignoring freshness.
+ *
+ * Routine scheduling is the Rust indexer's job (DR-109) — this is the manual
+ * override, for a "re-index now" affordance. It is deliberately *not* called on
+ * startup or reconnect any more: doing so forced a full crawl on every launch
+ * regardless of how fresh the index was.
+ *
+ * The backend refuses overlapping passes, so this is safe to call at any time.
 */
 export async function syncCatalog(): Promise<void> {
  if (syncInProgress) return;
@@ -124,6 +161,8 @@ export async function refreshSyncStatus(): Promise<void> {
 */
 export async function onReconnected(): Promise<void> {
  await resumeQueued();
-  // Fire-and-forget: don't block reconnection handling on a potentially long walk.
-  void syncCatalog();
+  // Re-indexing on reconnect is the Rust indexer's job (DR-109) — it re-checks
+  // staleness every tick, so it picks this up without a nudge from here. Queued
+  // downloads still need resolving from the frontend, which is why this
+  // function remains.
 }
@@ -0,0 +1,85 @@
+// TRACES: UR-025 | DR-132 | UT-123
+import { describe, it, expect } from "vitest";
+import type { SyncQueueItem } from "$lib/api/bindings";
+import {
+  describeOperation,
+  describeSubject,
+  isStuck,
+  summarize,
+  sortForDisplay,
+} from "./pendingSync.logic";
+
+function row(overrides: Partial<SyncQueueItem> = {}): SyncQueueItem {
+  return {
+    id: 1,
+    userId: "u1",
+    operation: "report_playback_stopped",
+    itemId: "ep1",
+    payload: null,
+    status: "pending",
+    retryCount: 0,
+    createdAt: "2026-08-01T10:00:00Z",
+    errorMessage: null,
+    itemName: null,
+    ...overrides,
+  } as SyncQueueItem;
+}
+
+describe("pending sync row description", () => {
+  it("labels the operations the backend can queue", () => {
+    expect(describeOperation("report_playback_stopped")).toBe("Watch position");
+    expect(describeOperation("mark_played")).toBe("Marked as watched");
+    expect(describeOperation("report_playback_start")).toBe("Playback started");
+  });
+
+  it("still renders an operation it has no label for", () => {
+    // An unlabelled row is the one heading for abandonment — it must not
+    // render blank, which is the failure this whole surface exists to fix.
+    expect(describeOperation("teleport_item")).toBe("teleport item");
+  });
+
+  it("names the item when the catalog knows it, and falls back to the id", () => {
+    expect(describeSubject(row({ itemName: "The Expanse S01E01" }))).toBe(
+      "The Expanse S01E01",
+    );
+    expect(describeSubject(row({ itemName: null, itemId: "abc123" }))).toBe("abc123");
+    expect(describeSubject(row({ itemName: null, itemId: null }))).toBe("Unknown item");
+  });
+});
+
+describe("stuck rows", () => {
+  it("treats a failed or retried row as stuck", () => {
+    expect(isStuck(row({ status: "failed", retryCount: 1 }))).toBe(true);
+    expect(isStuck(row({ status: "pending", retryCount: 2 }))).toBe(true);
+    expect(isStuck(row())).toBe(false);
+  });
+
+  it("summarizes a mixed queue", () => {
+    const summary = summarize([row(), row({ id: 2, status: "failed", retryCount: 1 })]);
+    expect(summary).toEqual({ total: 2, stuck: 1, allStuck: false });
+  });
+
+  it("reports allStuck only when every row has failed", () => {
+    expect(summarize([row({ status: "failed", retryCount: 3 })]).allStuck).toBe(true);
+    expect(summarize([]).allStuck).toBe(false);
+  });
+});
+
+describe("display order", () => {
+  it("lists oldest first — the order they will be replayed in", () => {
+    const sorted = sortForDisplay([
+      row({ id: 3, createdAt: "2026-08-01T12:00:00Z" }),
+      row({ id: 1, createdAt: "2026-08-01T10:00:00Z" }),
+      row({ id: 2, createdAt: "2026-08-01T11:00:00Z" }),
+    ]);
+    expect(sorted.map((r) => r.id)).toEqual([1, 2, 3]);
+  });
+
+  it("keeps timestamp-less rows instead of dropping them", () => {
+    const sorted = sortForDisplay([
+      row({ id: 2, createdAt: null }),
+      row({ id: 1, createdAt: "2026-08-01T10:00:00Z" }),
+    ]);
+    expect(sorted.map((r) => r.id)).toEqual([1, 2]);
+  });
+});
@@ -0,0 +1,79 @@
+// Presentation logic for the pending-sync queue.
+//
+// The queue's *meaning* lives in Rust (which operations exist, how they push,
+// when one is abandoned — DR-131). What lives here is purely how a row reads on
+// screen: its label, its subtitle, and whether it is currently erroring. Kept
+// out of the component so it can be unit-tested, the same pattern as
+// episodeStrip.ts.
+//
+// TRACES: UR-025 | DR-132 | UT-123
+
+import type { SyncQueueItem } from "$lib/api/bindings";
+
+/** How each queued operation reads in the list. */
+const OPERATION_LABELS: Record<string, string> = {
+  report_playback_start: "Playback started",
+  report_playback_stopped: "Watch position",
+  update_progress: "Watch position",
+  mark_played: "Marked as watched",
+  mark_favorite: "Added to favourites",
+  unmark_favorite: "Removed from favourites",
+  playlist_create: "Playlist created",
+  playlist_delete: "Playlist deleted",
+  playlist_rename: "Playlist renamed",
+  playlist_add_items: "Added to playlist",
+  playlist_remove_items: "Removed from playlist",
+  playlist_reorder_item: "Playlist reordered",
+};
+
+/**
+ * A human label for a queued operation. An operation this build has no label
+ * for still reads as something — an unknown row is the case most worth showing,
+ * since it is the one that will end up abandoned.
+ */
+export function describeOperation(operation: string): string {
+  return OPERATION_LABELS[operation] ?? operation.replace(/_/g, " ");
+}
+
+/** What the row is about: the item's title if the catalog knows it, else its id. */
+export function describeSubject(item: SyncQueueItem): string {
+  return item.itemName ?? item.itemId ?? "Unknown item";
+}
+
+/**
+ * A row is "stuck" once it has failed at least once — that is what justifies
+ * showing its error, and what a Retry button acts on.
+ */
+export function isStuck(item: SyncQueueItem): boolean {
+  return item.status === "failed" || item.retryCount > 0;
+}
+
+export interface PendingSyncSummary {
+  total: number;
+  stuck: number;
+  /** True when every queued row has already failed — retrying needs the server. */
+  allStuck: boolean;
+}
+
+export function summarize(items: SyncQueueItem[]): PendingSyncSummary {
+  const stuck = items.filter(isStuck).length;
+  return {
+    total: items.length,
+    stuck,
+    allStuck: items.length > 0 && stuck === items.length,
+  };
+}
+
+/**
+ * Oldest first — the order they will be replayed in, so the list reads as the
+ * queue it is. Rows without a timestamp sort last rather than being dropped.
+ */
+export function sortForDisplay(items: SyncQueueItem[]): SyncQueueItem[] {
+  return [...items].sort((a, b) => {
+    if (!a.createdAt && !b.createdAt) return a.id - b.id;
+    if (!a.createdAt) return 1;
+    if (!b.createdAt) return -1;
+    const diff = Date.parse(a.createdAt) - Date.parse(b.createdAt);
+    return diff !== 0 ? diff : a.id - b.id;
+  });
+}
@@ -145,3 +145,76 @@ describe("Player Events — pause must not zero the slider duration", () => {
    expect(get(playbackDuration)).toBe(70);
  });
 });
+
+/**
+ * A recoverable error is a network hiccup, not the end of playback. The handler
+ * used to stop the player unconditionally, so a blip on wifi killed the track —
+ * on Linux especially, where MPV's EndFile(ERROR) is the only signal a stream
+ * died and there is no in-process controller for the backend to consult.
+ *
+ * TRACES: UR-004, UR-040 | DR-130
+ */
+describe("Player Events — recoverable errors get one chance before stopping", () => {
+  beforeEach(async () => {
+    const { cleanupPlayerEvents } = await import("./playerEvents");
+    const { player } = await import("$lib/stores/player");
+    cleanupPlayerEvents();
+    player.setIdle();
+    vi.clearAllMocks();
+    registeredHandler = null;
+    currentQueueItemStore.set(null);
+  });
+
+  it("does not stop the player when Rust re-opened the stream", async () => {
+    const { invoke } = await import("@tauri-apps/api/core");
+    vi.mocked(invoke).mockImplementation(async (cmd: string) =>
+      cmd === "player_recover_stream" ? true : null
+    );
+
+    const { initPlayerEvents } = await import("./playerEvents");
+    const { player } = await import("$lib/stores/player");
+    await initPlayerEvents();
+    await fire({ type: "state_changed", state: "playing", media_id: "track-1" });
+
+    await fire({ type: "error", message: "Playback stream failed", recoverable: true });
+
+    const calls = vi.mocked(invoke).mock.calls.map(([cmd]) => cmd);
+    expect(calls).toContain("player_recover_stream");
+    expect(calls).not.toContain("player_stop");
+    expect(get(player).state.kind).not.toBe("error");
+  });
+
+  it("stops the player when recovery declines", async () => {
+    const { invoke } = await import("@tauri-apps/api/core");
+    vi.mocked(invoke).mockImplementation(async (cmd: string) =>
+      cmd === "player_recover_stream" ? false : null
+    );
+
+    const { initPlayerEvents } = await import("./playerEvents");
+    await initPlayerEvents();
+
+    await fire({ type: "error", message: "Playback stream failed", recoverable: true });
+    await Promise.resolve();
+
+    const calls = vi.mocked(invoke).mock.calls.map(([cmd]) => cmd);
+    expect(calls).toContain("player_recover_stream");
+    expect(calls).toContain("player_stop");
+  });
+
+  it("does not attempt recovery for an unrecoverable error", async () => {
+    // Android decides in its JNI callback and reports the errors it already
+    // declined as unrecoverable, so this must not ask a second time.
+    const { invoke } = await import("@tauri-apps/api/core");
+    vi.mocked(invoke).mockResolvedValue(null);
+
+    const { initPlayerEvents } = await import("./playerEvents");
+    await initPlayerEvents();
+
+    await fire({ type: "error", message: "Decoder failed", recoverable: false });
+    await Promise.resolve();
+
+    const calls = vi.mocked(invoke).mock.calls.map(([cmd]) => cmd);
+    expect(calls).not.toContain("player_recover_stream");
+    expect(calls).toContain("player_stop");
+  });
+});
@@ -276,9 +276,32 @@ async function handlePlaybackEnded(): Promise<void> {

 /**
 * Handle error events.
+ *
+ * A recoverable error gets one chance at recovery before anything is torn down.
+ * Backends whose event thread cannot reach the controller (MpvBackend is built
+ * before PlayerController exists) report the failure and rely on this echo to
+ * put the decision back in Rust — the same shape as PlaybackEnded →
+ * playerOnPlaybackEnded. Nothing is decided here: if Rust re-opened the stream
+ * it says so, and stopping the player would kill the playback it just restored.
+ *
+ * TRACES: UR-004, UR-040 | DR-130
 */
 async function handleError(message: string, recoverable: boolean): Promise<void> {
  console.error(`Playback error (recoverable: ${recoverable}): ${message}`);
+
+  if (recoverable) {
+    try {
+      if (await commands.playerRecoverStream()) {
+        console.log("Stream re-opened after a recoverable error - not stopping");
+        return;
+      }
+    } catch (e) {
+      // Fall through to the normal stop: a failed recovery attempt is still an
+      // error, and leaving the player running would strand it mid-failure.
+      console.error("Stream recovery attempt failed:", e);
+    }
+  }
+
  player.setError(message);

  // Stop backend player to prevent orphaned playback
@@ -17,6 +17,7 @@ function makeConfig(overrides: Partial<CacheConfig> = {}): CacheConfig {
    albumAffinityThreshold: 0.75,
    storageLimit: 2 * 1024 * 1024 * 1024,
    wifiOnly: false,
+    temporaryTtlHours: 24 * 7,
    ...overrides,
  };
 }
@@ -177,14 +178,7 @@ describe("preload service", () => {
    });

    it("should support all config options", async () => {
-      const config = {
-        queuePrecacheEnabled: true,
-        queuePrecacheCount: 5,
-        albumAffinityEnabled: false,
-        albumAffinityThreshold: 0.75,
-        storageLimit: 2 * 1024 * 1024 * 1024,
-        wifiOnly: true,
-      };
+      const config = makeConfig({ wifiOnly: true, albumAffinityEnabled: false });

      await expect(updateCacheConfig(config)).resolves.toBeUndefined();
    });
@@ -9,18 +9,11 @@
 import { commands } from "$lib/api/bindings";
 import { auth } from "$lib/stores/auth";

-// Types matching Rust structs
-export interface SyncQueueItem {
-  id: number;
-  userId: string;
-  operation: string;
-  itemId: string | null;
-  payload: string | null;
-  status: string;
-  retryCount: number;
-  createdAt: string | null;
-  errorMessage: string | null;
-}
+// The queue row shape comes from the generated bindings rather than a
+// hand-written mirror — the mirror had already drifted (it predates `itemName`),
+// and a drifted duplicate is how a field silently stops reaching the UI.
+import type { SyncQueueItem } from "$lib/api/bindings";
+export type { SyncQueueItem };

 export type SyncOperation =
  | "mark_played"
@@ -84,19 +77,10 @@ class SyncService {
    return id;
  }

-  /**
-   * Queue a favorite toggle
-   * Also updates local state immediately
-   */
-  async queueFavorite(itemId: string, isFavorite: boolean): Promise<number> {
-    // Update local state first
-    await commands.storageToggleFavorite(auth.getUserId() ?? "", itemId, isFavorite);
-
-    return this.queueMutation(
-      isFavorite ? "mark_favorite" : "unmark_favorite",
-      itemId
-    );
-  }
+  // NOTE: `queueFavorite` is gone. Favourites are drained by Rust on the
+  // `connectivity:reconnected` signal (DR-120) — the local write already sets
+  // `pending_sync`, and a second queue here would push the same change twice.
+  // See src-tauri/src/commands/favorites.rs.

  /**
   * Queue playback progress update
@@ -0,0 +1,101 @@
+// TRACES: UR-067, UR-068 | DR-117, DR-119 | UT-105, UT-106
+
+import { describe, it, expect, beforeEach } from "vitest";
+import { get } from "svelte/store";
+import type { MediaItem } from "$lib/api/types";
+import {
+  favoriteOverrides,
+  setFavorite,
+  clearFavorite,
+  clearAllFavorites,
+  resolveIsFavorite,
+  isFavoriteNow,
+  retainFavorites,
+} from "./favorites";
+
+function item(id: string, isFavorite?: boolean): MediaItem {
+  return {
+    id,
+    name: `Item ${id}`,
+    type: "Movie",
+    kind: "movie",
+    isFolder: false,
+    serverId: "s1",
+    userData: isFavorite === undefined ? undefined : { isFavorite },
+  } as unknown as MediaItem;
+}
+
+describe("favorites store", () => {
+  beforeEach(() => clearAllFavorites());
+
+  describe("resolveIsFavorite (UT-105)", () => {
+    it("falls back to the server's userData when nothing was toggled here", () => {
+      expect(resolveIsFavorite(item("a", true), new Map())).toBe(true);
+      expect(resolveIsFavorite(item("a", false), new Map())).toBe(false);
+    });
+
+    it("treats an item with no userData as not favourited", () => {
+      expect(resolveIsFavorite(item("a"), new Map())).toBe(false);
+    });
+
+    it("lets a session override win over userData", () => {
+      // The whole point: after tapping the heart on a card, the item object
+      // still carries the server's stale value until the next fetch.
+      expect(resolveIsFavorite(item("a", false), new Map([["a", true]]))).toBe(true);
+      expect(resolveIsFavorite(item("a", true), new Map([["a", false]]))).toBe(false);
+    });
+
+    it("is false for a missing item rather than throwing", () => {
+      expect(resolveIsFavorite(null, new Map())).toBe(false);
+      expect(resolveIsFavorite(undefined, new Map())).toBe(false);
+    });
+  });
+
+  describe("overrides", () => {
+    it("publishes a toggle to subscribers", () => {
+      setFavorite("a", true);
+      expect(get(favoriteOverrides).get("a")).toBe(true);
+      expect(isFavoriteNow(item("a", false))).toBe(true);
+
+      setFavorite("a", false);
+      expect(isFavoriteNow(item("a", true))).toBe(false);
+    });
+
+    it("clearing an override hands authority back to the item's userData", () => {
+      setFavorite("a", false);
+      expect(isFavoriteNow(item("a", true))).toBe(false);
+
+      clearFavorite("a");
+      expect(isFavoriteNow(item("a", true))).toBe(true);
+    });
+
+    it("replaces the map so Svelte sees a new reference", () => {
+      const before = get(favoriteOverrides);
+      setFavorite("a", true);
+      expect(get(favoriteOverrides)).not.toBe(before);
+    });
+  });
+
+  describe("retainFavorites (UT-106)", () => {
+    it("drops an item un-favourited during this session", () => {
+      const items = [item("a", true), item("b", true)];
+      const kept = retainFavorites(items, new Map([["a", false]]));
+      expect(kept.map((i) => i.id)).toEqual(["b"]);
+    });
+
+    it("keeps everything when nothing was toggled", () => {
+      const items = [item("a", true), item("b", true)];
+      expect(retainFavorites(items, new Map())).toHaveLength(2);
+    });
+
+    it("keeps an item favourited during this session even if the server said otherwise", () => {
+      const items = [item("a", false)];
+      expect(retainFavorites(items, new Map([["a", true]]))).toHaveLength(1);
+    });
+
+    it("drops items the server never marked as favourites", () => {
+      // A listing fetched with a stale scope should not keep non-favourites.
+      expect(retainFavorites([item("a")], new Map())).toHaveLength(0);
+    });
+  });
+});
@@ -0,0 +1,89 @@
+// Favourites overlay — in-session heart state shared across every surface.
+//
+// The durable record lives in Rust (local `user_data` + the Jellyfin server).
+// This store holds only what the *current session* has changed, so a heart
+// tapped on a card is reflected on the detail page and the item vanishes from
+// the Favourites grid without anyone refetching. It is view state, not truth.
+//
+// TRACES: UR-068 | DR-119 | UT-105
+
+import { derived, get, writable } from "svelte/store";
+import type { MediaItem } from "$lib/api/types";
+
+/** Item id → favourite state set during this session. */
+const overrides = writable<Map<string, boolean>>(new Map());
+
+export const favoriteOverrides = { subscribe: overrides.subscribe };
+
+/**
+ * Record a favourite state locally so every mounted view agrees immediately.
+ * Called by the toggle service after the optimistic local write.
+ */
+export function setFavorite(itemId: string, isFavorite: boolean): void {
+  overrides.update((map) => {
+    const next = new Map(map);
+    next.set(itemId, isFavorite);
+    return next;
+  });
+}
+
+/**
+ * Forget a session override, so the item's own `userData` is authoritative
+ * again. Used when the backend reports the server's state changed underneath
+ * us (`favorites-changed`) — the fresh fetch that follows carries the truth.
+ */
+export function clearFavorite(itemId: string): void {
+  overrides.update((map) => {
+    if (!map.has(itemId)) return map;
+    const next = new Map(map);
+    next.delete(itemId);
+    return next;
+  });
+}
+
+export function clearAllFavorites(): void {
+  overrides.set(new Map());
+}
+
+/**
+ * Resolution order: a session override wins, then the item's own server-sent
+ * `userData`, then "not favourited".
+ *
+ * The override has to win, or tapping the heart on a card would flip back the
+ * moment the (unchanged) item object re-rendered.
+ *
+ * TRACES: UR-068 | DR-119 | UT-105
+ */
+export function resolveIsFavorite(
+  item: Pick<MediaItem, "id" | "userData"> | null | undefined,
+  overrideMap: Map<string, boolean>
+): boolean {
+  if (!item) return false;
+  const override = overrideMap.get(item.id);
+  if (override !== undefined) return override;
+  return item.userData?.isFavorite ?? false;
+}
+
+/** Non-reactive read, for call sites outside a component. */
+export function isFavoriteNow(item: Pick<MediaItem, "id" | "userData">): boolean {
+  return resolveIsFavorite(item, get(overrides));
+}
+
+/**
+ * Drop the items a listing should no longer show once un-favourited.
+ *
+ * Pure so it can be unit-tested without mounting the page: un-hearting on the
+ * Favourites grid must remove the card, while a *newly* favourited item is
+ * left alone (it belongs to whatever scope the caller fetched).
+ *
+ * TRACES: UR-067 | DR-117, DR-119 | UT-106
+ */
+export function retainFavorites<T extends Pick<MediaItem, "id" | "userData">>(
+  items: T[],
+  overrideMap: Map<string, boolean>
+): T[] {
+  return items.filter((item) => resolveIsFavorite(item, overrideMap));
+}
+
+/** Count of items still favourited, for "hide the row when empty" decisions. */
+export const hasOverrides = derived(overrides, ($o) => $o.size > 0);
@@ -1,5 +1,5 @@
 // Home screen data store - featured items, continue watching, recently added
-// TRACES: UR-023, UR-024, UR-034, UR-059 | DR-026, DR-027, DR-038, DR-039, DR-089
+// TRACES: UR-023, UR-024, UR-034, UR-059, UR-067 | DR-026, DR-027, DR-038, DR-039, DR-089, DR-118
 import { writable, derived } from "svelte/store";
 import type { MediaItem } from "$lib/api/types";
 import { auth } from "./auth";
@@ -12,6 +12,10 @@ interface HomeState {
  latestItems: MediaItem[];
  recentlyPlayedAudio: MediaItem[];
  resumeMovies: MediaItem[];
+  /** Favourites per scope. Empty rows are not rendered. TRACES: UR-067 | DR-118 */
+  favoriteMovies: MediaItem[];
+  favoriteShows: MediaItem[];
+  favoriteMusic: MediaItem[];
  isLoading: boolean;
  error: string | null;
 }
@@ -24,6 +28,9 @@ function createHomeStore() {
    latestItems: [],
    recentlyPlayedAudio: [],
    resumeMovies: [],
+    favoriteMovies: [],
+    favoriteShows: [],
+    favoriteMusic: [],
    isLoading: false,
    error: null,
  };
@@ -46,6 +53,11 @@ function createHomeStore() {
        repo.getLatestItems("", 16),
        repo.getRecentlyPlayedAudio(12), // Backend now handles intelligent grouping
        repo.getResumeMovies(12),
+        // Favourites, one request per row. The scope is opaque — Rust decides
+        // which item types it covers. TRACES: UR-067 | DR-118
+        repo.getFavorites("movies", { limit: 20 }),
+        repo.getFavorites("tv", { limit: 20 }),
+        repo.getFavorites("music", { limit: 20 }),
      ]);

      const valueOr = <T>(i: number, fallback: T): T =>
@@ -60,6 +72,10 @@ function createHomeStore() {
      const latest = valueOr(2, [] as typeof initialState.latestItems);
      const recentAudio = valueOr(3, [] as typeof initialState.recentlyPlayedAudio);
      const resumeMovies = valueOr(4, [] as typeof initialState.resumeMovies);
+      const emptyResult = { items: [] as MediaItem[], totalRecordCount: 0 };
+      const favoriteMovies = valueOr(5, emptyResult).items;
+      const favoriteShows = valueOr(6, emptyResult).items;
+      const favoriteMusic = valueOr(7, emptyResult).items;

      // Use resume items or latest as hero items
      const hero = resume.length >= 3 ? resume.slice(0, 5) : latest.slice(0, 5);
@@ -72,6 +88,9 @@ function createHomeStore() {
        latestItems: latest,
        recentlyPlayedAudio: recentAudio,
        resumeMovies: resumeMovies,
+        favoriteMovies,
+        favoriteShows,
+        favoriteMusic,
        isLoading: false,
      }));
    } catch (error) {
@@ -101,4 +120,7 @@ export const nextUpItems = derived(home, $home => $home.nextUpItems);
 export const latestItems = derived(home, $home => $home.latestItems);
 export const recentlyPlayedAudio = derived(home, $home => $home.recentlyPlayedAudio);
 export const resumeMovies = derived(home, $home => $home.resumeMovies);
+export const favoriteMovies = derived(home, $home => $home.favoriteMovies);
+export const favoriteShows = derived(home, $home => $home.favoriteShows);
+export const favoriteMusic = derived(home, $home => $home.favoriteMusic);
 export const isHomeLoading = derived(home, $home => $home.isLoading);
@@ -0,0 +1,60 @@
+// TRACES: UR-067 | DR-117
+
+import { describe, it, expect } from "vitest";
+import {
+  FAVORITE_SCOPES,
+  FAVORITE_SCOPE_LABELS,
+  resolveFavoritesScope,
+  favoritesRouteUrl,
+  emptyStateMessage,
+} from "./favoritesView";
+
+describe("favoritesView", () => {
+  describe("resolveFavoritesScope", () => {
+    it("round-trips every offered tab", () => {
+      for (const scope of FAVORITE_SCOPES) {
+        expect(resolveFavoritesScope(scope)).toBe(scope);
+      }
+    });
+
+    it("defaults to All for a missing param", () => {
+      expect(resolveFavoritesScope(null)).toBe("all");
+      expect(resolveFavoritesScope(undefined)).toBe("all");
+      expect(resolveFavoritesScope("")).toBe("all");
+    });
+
+    it("defaults to All for a stale or hand-edited param rather than blanking the page", () => {
+      expect(resolveFavoritesScope("books")).toBe("all");
+      expect(resolveFavoritesScope("MOVIES")).toBe("all");
+    });
+  });
+
+  describe("favoritesRouteUrl", () => {
+    it("omits the default scope so the base URL stays clean", () => {
+      expect(favoritesRouteUrl("all")).toBe("/library/favorites");
+    });
+
+    it("addresses every other tab explicitly, and round-trips through resolve", () => {
+      for (const scope of FAVORITE_SCOPES) {
+        const url = favoritesRouteUrl(scope);
+        const param = new URL(url, "http://x").searchParams.get("scope");
+        expect(resolveFavoritesScope(param)).toBe(scope);
+      }
+    });
+  });
+
+  it("labels every scope, using the app's vocabulary rather than Jellyfin's", () => {
+    for (const scope of FAVORITE_SCOPES) {
+      expect(FAVORITE_SCOPE_LABELS[scope]).toBeTruthy();
+    }
+    // "tv" is the backend's scope name; users see "Shows".
+    expect(FAVORITE_SCOPE_LABELS.tv).toBe("Shows");
+  });
+
+  it("gives each tab its own empty state, telling the user what to do next", () => {
+    for (const scope of FAVORITE_SCOPES) {
+      expect(emptyStateMessage(scope)).toContain("heart");
+    }
+    expect(emptyStateMessage("movies")).toContain("movies");
+  });
+});
@@ -0,0 +1,54 @@
+// Favourites page presentation helpers — which scopes are offered as tabs, what
+// they are called, and how a tab is addressed in the URL.
+//
+// The *labels and tab order* are presentation and live here. What each scope
+// MEANS in Jellyfin item types is domain vocabulary and lives in Rust
+// (`SearchScope::item_types`); this file must never enumerate item types.
+//
+// TRACES: UR-067 | DR-117
+
+import type { SearchScope } from "$lib/api/bindings";
+
+/**
+ * Scopes offered as tabs, in display order. A subset of `SearchScope` chosen
+ * for presentation — the backend accepts more than a page needs to show.
+ */
+export const FAVORITE_SCOPES = ["all", "movies", "tv", "music"] as const;
+
+export type FavoritesScope = (typeof FAVORITE_SCOPES)[number];
+
+export const FAVORITE_SCOPE_LABELS: Record<FavoritesScope, string> = {
+  all: "All",
+  movies: "Movies",
+  tv: "Shows",
+  music: "Music",
+};
+
+/**
+ * Resolve the `?scope=` param to a tab, defaulting to All for anything
+ * missing or unrecognised (a hand-edited or stale URL must not blank the page).
+ */
+export function resolveFavoritesScope(raw: string | null | undefined): FavoritesScope {
+  if (!raw) return "all";
+  return (FAVORITE_SCOPES as readonly string[]).includes(raw) ? (raw as FavoritesScope) : "all";
+}
+
+/** URL for a tab. The default scope is omitted, keeping the base URL clean. */
+export function favoritesRouteUrl(scope: FavoritesScope): string {
+  return scope === "all" ? "/library/favorites" : `/library/favorites?scope=${scope}`;
+}
+
+/** Per-tab empty state copy (ux-flows §5C.2). */
+export function emptyStateMessage(scope: FavoritesScope): string {
+  const what: Record<FavoritesScope, string> = {
+    all: "Nothing favourited yet",
+    movies: "No favourite movies yet",
+    tv: "No favourite shows yet",
+    music: "No favourite music yet",
+  };
+  return `${what[scope]} — tap the heart on anything you like.`;
+}
+
+/** Compile-time guard that every tab is a scope the backend accepts. */
+const _scopesAreSearchScopes: readonly SearchScope[] = FAVORITE_SCOPES;
+void _scopesAreSearchScopes;
@@ -19,8 +19,10 @@ import {
  showBottomNav,
  showGlobalMiniPlayer,
  showGlobalHeader,
+  showHeaderSearch,
  routeOwnsLayout,
  showBottomUi,
+  shellReservesBottomInset,
 } from "./layoutShell";

 const authed = (pathname: string) => ({ pathname, isAuthenticated: true });
@@ -149,3 +151,54 @@ describe("structural invariant: every route that shows bottom UI has a scroller
    expect(routeOwnsLayout({ pathname: "/player/x" })).toBe(true);
  });
 });
+
+/**
+ * Who owns the bottom safe-area inset.
+ *
+ * TRACES: UR-066 | DR-112 | UT-098
+ *
+ * Exactly one element must reserve `--safe-bottom`, or the Android gesture bar
+ * is either ignored (nav swallowed) or double-padded (a dead strip above it).
+ * BottomUi owns it whenever it renders — the padding sits inside its surface
+ * box so the colour extends behind the bar. Routes with no BottomUi (login, the
+ * full-screen player) leave the app shell to reserve it instead.
+ */
+describe("shellReservesBottomInset", () => {
+  it("defers to BottomUi on every route that renders one", () => {
+    for (const pathname of ["/", "/search", "/downloads", "/settings", "/library"]) {
+      expect(showBottomUi(authed(pathname))).toBe(true);
+      expect(shellReservesBottomInset(authed(pathname))).toBe(false);
+    }
+  });
+
+  it("reserves the inset itself on routes with no bottom UI", () => {
+    expect(shellReservesBottomInset(authed("/login"))).toBe(true);
+    expect(shellReservesBottomInset(authed("/player/x"))).toBe(true);
+  });
+
+  it("defers on the unauthenticated shell, where the mini player still renders", () => {
+    expect(shellReservesBottomInset({ pathname: "/", isAuthenticated: false })).toBe(false);
+  });
+});
+
+describe("showHeaderSearch", () => {
+  it("renders the bar on the library routes", () => {
+    expect(showHeaderSearch({ pathname: "/library" })).toBe(true);
+    expect(showHeaderSearch({ pathname: "/library/music/albums" })).toBe(true);
+    expect(showHeaderSearch({ pathname: "/library/abc123" })).toBe(true);
+  });
+
+  it("keeps the bar on /search, so searching does not swap you to another input", () => {
+    // The regression: the bar existed only under /library, so a header search
+    // landed the user on /search with the box they were typing in gone and a
+    // different one (belonging to the page) in its place.
+    expect(showHeaderSearch({ pathname: "/search" })).toBe(true);
+    expect(showHeaderSearch({ pathname: "/search/" })).toBe(true);
+  });
+
+  it("stays off routes with nothing to search", () => {
+    expect(showHeaderSearch({ pathname: "/" })).toBe(false);
+    expect(showHeaderSearch({ pathname: "/downloads" })).toBe(false);
+    expect(showHeaderSearch({ pathname: "/settings" })).toBe(false);
+  });
+});
@@ -17,6 +17,8 @@
 * TRACES: UR-005 | DR-009
 */

+import { isSearchRoute } from "$lib/utils/searchScope";
+
 export interface BottomUiVisibilityInput {
  /** Current route pathname, e.g. `$page.url.pathname`. */
  pathname: string;
@@ -90,6 +92,21 @@ export function showGlobalHeader({
  );
 }

+/**
+ * Whether the header renders its search box on this route (md+ only; below md
+ * the bottom-nav Search tab and /search's own input serve that role).
+ *
+ * `/search` is included deliberately: the bar is the single md+ search input,
+ * so it must survive the hop onto the results page instead of being replaced by
+ * a second input belonging to that page. The library routes keep it because
+ * that is where a search is most often started.
+ *
+ * TRACES: UR-049, UR-054 | DR-063
+ */
+export function showHeaderSearch({ pathname }: { pathname: string }): boolean {
+  return pathname.startsWith("/library") || isSearchRoute(pathname);
+}
+
 /**
 * Whether any bottom UI is showing for this route (mini player, nav, or both).
 * The bottom UI is rendered in flex flow below the scroller (see BottomUi.svelte),
@@ -98,3 +115,19 @@ export function showGlobalHeader({
 export function showBottomUi(input: BottomUiVisibilityInput): boolean {
  return showBottomNav(input) || showGlobalMiniPlayer({ pathname: input.pathname });
 }
+
+/**
+ * Whether the app shell itself must reserve the bottom safe-area inset
+ * (`--safe-bottom`, i.e. the Android navigation/gesture bar).
+ *
+ * Exactly one element may reserve it. BottomUi owns it whenever it renders,
+ * because the padding belongs *inside* its surface box so the colour extends
+ * behind the bar rather than leaving a strip of page background. On routes with
+ * no bottom UI at all (login, the full-screen player) nothing else would, so
+ * the shell takes it.
+ *
+ * TRACES: UR-066 | DR-112
+ */
+export function shellReservesBottomInset(input: BottomUiVisibilityInput): boolean {
+  return !showBottomUi(input);
+}
@@ -0,0 +1,256 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { readFileSync, readdirSync } from "node:fs";
+import { resolve } from "node:path";
+import {
+  ZERO_INSETS,
+  parseNativeInsets,
+  safeAreaCssVars,
+  applySafeAreaInsets,
+  readNativeInsets,
+  initSafeArea,
+  INSETS_CHANGED_EVENT,
+} from "./safeArea";
+
+/**
+ * Safe-area (window inset) plumbing for Android.
+ *
+ * TRACES: UR-066 | IR-031, DR-112 | UT-094, UT-095, UT-096, UT-097
+ *
+ * Regression guard for "the bottom nav is off the bottom of the screen on some
+ * devices (Motorola) but not others (Fairphone)".
+ *
+ * Two independent defects produced it:
+ *
+ *  1. `src/app.html` shipped `<meta name="viewport" content="width=device-width,
+ *     initial-scale=1">` — no `viewport-fit=cover`. Per the CSS Env spec, every
+ *     `env(safe-area-inset-*)` resolves to **0px** unless the viewport opts into
+ *     `cover`. So the `env()` padding in app.css and BottomUi.svelte was a
+ *     no-op on every device.
+ *  2. Even with `viewport-fit=cover`, Android WebView only maps the **display
+ *     cutout** into `env(safe-area-inset-*)` — never the status bar or the
+ *     navigation/gesture bar. MainActivity calls `enableEdgeToEdge()` and the
+ *     app targets SDK 36 (edge-to-edge is mandatory from SDK 35 and the opt-out
+ *     is ignored from SDK 36), so the WebView always spans the full window
+ *     including the system bars. CSS alone can never learn about them.
+ *
+ * The device split was only in how much the bars intrude: a thin translucent
+ * gesture pill overlaps harmlessly, a tall opaque 3-button bar swallows the nav
+ * outright. Both devices were equally unpadded.
+ *
+ * The fix pushes real `WindowInsets` from Kotlin into CSS custom properties.
+ * These tests pin the frontend half of that contract.
+ */
+describe("parseNativeInsets", () => {
+  it("parses the JSON payload the native bridge returns", () => {
+    expect(parseNativeInsets('{"top":24,"right":0,"bottom":48,"left":0}')).toEqual({
+      top: 24,
+      right: 0,
+      bottom: 48,
+      left: 0,
+    });
+  });
+
+  it("accepts an already-parsed object", () => {
+    expect(parseNativeInsets({ top: 1, right: 2, bottom: 3, left: 4 })).toEqual({
+      top: 1,
+      right: 2,
+      bottom: 3,
+      left: 4,
+    });
+  });
+
+  it("treats missing, non-finite and negative edges as zero rather than emitting NaN", () => {
+    // A NaN would serialise to "NaNpx" and silently kill the whole padding
+    // declaration, which is exactly the failure mode being guarded against.
+    expect(parseNativeInsets('{"top":-5,"bottom":"48"}')).toEqual({
+      top: 0,
+      right: 0,
+      bottom: 48,
+      left: 0,
+    });
+    expect(parseNativeInsets({ top: Number.NaN, right: Infinity })).toEqual(ZERO_INSETS);
+  });
+
+  it("returns null for input that is not an inset payload at all", () => {
+    expect(parseNativeInsets("not json")).toBeNull();
+    expect(parseNativeInsets(null)).toBeNull();
+    expect(parseNativeInsets(undefined)).toBeNull();
+    expect(parseNativeInsets(42)).toBeNull();
+  });
+});
+
+describe("safeAreaCssVars / applySafeAreaInsets", () => {
+  it("emits px-suffixed custom properties for all four edges", () => {
+    expect(safeAreaCssVars({ top: 24, right: 0, bottom: 48, left: 12 })).toEqual({
+      "--jt-inset-top": "24px",
+      "--jt-inset-right": "0px",
+      "--jt-inset-bottom": "48px",
+      "--jt-inset-left": "12px",
+    });
+  });
+
+  it("writes the custom properties onto the target element", () => {
+    const el = document.createElement("div");
+    applySafeAreaInsets(el, { top: 24, right: 1, bottom: 48, left: 2 });
+
+    expect(el.style.getPropertyValue("--jt-inset-top")).toBe("24px");
+    expect(el.style.getPropertyValue("--jt-inset-right")).toBe("1px");
+    expect(el.style.getPropertyValue("--jt-inset-bottom")).toBe("48px");
+    expect(el.style.getPropertyValue("--jt-inset-left")).toBe("2px");
+  });
+});
+
+describe("readNativeInsets", () => {
+  beforeEach(() => {
+    delete (window as unknown as Record<string, unknown>).AndroidInsets;
+    vi.restoreAllMocks();
+  });
+
+  it("returns null when the bridge is absent (desktop, iOS, dev server)", () => {
+    expect(readNativeInsets()).toBeNull();
+  });
+
+  it("reads and parses the bridge payload", () => {
+    window.AndroidInsets = { get: () => '{"top":24,"right":0,"bottom":48,"left":0}' };
+    expect(readNativeInsets()).toEqual({ top: 24, right: 0, bottom: 48, left: 0 });
+  });
+
+  it("returns null when the bridge object is a stale WebView proxy", () => {
+    // Same failure mode as the background-audio bridge: the injected object
+    // stays truthy across a page load while its methods vanish. Must not throw
+    // out of layout init.
+    vi.spyOn(console, "warn").mockImplementation(() => {});
+    window.AndroidInsets = {} as unknown as { get(): string };
+    expect(readNativeInsets()).toBeNull();
+
+    window.AndroidInsets = {
+      get: () => {
+        throw new TypeError("get is not a function");
+      },
+    };
+    expect(readNativeInsets()).toBeNull();
+  });
+});
+
+describe("initSafeArea", () => {
+  let stop: (() => void) | null = null;
+
+  beforeEach(() => {
+    delete (window as unknown as Record<string, unknown>).AndroidInsets;
+    document.documentElement.removeAttribute("style");
+    vi.restoreAllMocks();
+  });
+
+  afterEach(() => {
+    stop?.();
+    stop = null;
+  });
+
+  it("primes the document element from the bridge on start", () => {
+    window.AndroidInsets = { get: () => '{"top":24,"right":0,"bottom":48,"left":0}' };
+
+    stop = initSafeArea();
+
+    expect(document.documentElement.style.getPropertyValue("--jt-inset-bottom")).toBe("48px");
+  });
+
+  it("re-applies insets when native reports a change (rotation, nav-mode switch)", () => {
+    let payload = '{"top":24,"right":0,"bottom":48,"left":0}';
+    window.AndroidInsets = { get: () => payload };
+
+    stop = initSafeArea();
+    expect(document.documentElement.style.getPropertyValue("--jt-inset-top")).toBe("24px");
+
+    // Rotated to landscape: the cutout moves to the left edge, the gesture bar
+    // shrinks. Native re-pushes and fires the change event.
+    payload = '{"top":0,"right":0,"bottom":24,"left":44}';
+    window.dispatchEvent(new CustomEvent(INSETS_CHANGED_EVENT));
+
+    expect(document.documentElement.style.getPropertyValue("--jt-inset-top")).toBe("0px");
+    expect(document.documentElement.style.getPropertyValue("--jt-inset-left")).toBe("44px");
+    expect(document.documentElement.style.getPropertyValue("--jt-inset-bottom")).toBe("24px");
+  });
+
+  it("leaves the custom properties unset with no bridge, so env() keeps the field", () => {
+    // On iOS/desktop the `env(safe-area-inset-*)` half of the max() must win;
+    // writing an explicit 0px here would clobber it.
+    stop = initSafeArea();
+    expect(document.documentElement.style.getPropertyValue("--jt-inset-bottom")).toBe("");
+  });
+
+  it("stops listening once torn down", () => {
+    let payload = '{"top":24,"right":0,"bottom":48,"left":0}';
+    window.AndroidInsets = { get: () => payload };
+
+    const teardown = initSafeArea();
+    teardown();
+
+    payload = '{"top":99,"right":99,"bottom":99,"left":99}';
+    window.dispatchEvent(new CustomEvent(INSETS_CHANGED_EVENT));
+
+    expect(document.documentElement.style.getPropertyValue("--jt-inset-top")).toBe("24px");
+  });
+});
+
+/**
+ * Static guards. The two root-cause defects were both single lines of markup /
+ * CSS that no runtime test could reach, so pin them at the source level.
+ */
+describe("safe-area wiring in source", () => {
+  const read = (rel: string) => readFileSync(resolve(process.cwd(), rel), "utf8");
+
+  it("app.html opts the viewport into viewport-fit=cover", () => {
+    const viewport = read("src/app.html").match(/<meta\s+name="viewport"[^>]*>/i)?.[0];
+
+    expect(viewport, "no viewport meta tag found in src/app.html").toBeTruthy();
+    expect(viewport).toMatch(/viewport-fit\s*=\s*cover/);
+  });
+
+  it("app.css derives --safe-* from both env() and the native --jt-inset-* vars", () => {
+    const css = read("src/app.css");
+
+    for (const edge of ["top", "right", "bottom", "left"]) {
+      expect(css).toMatch(
+        new RegExp(
+          `--safe-${edge}:\\s*max\\(\\s*env\\(safe-area-inset-${edge}[^)]*\\)\\s*,\\s*var\\(--jt-inset-${edge}[^)]*\\)\\s*\\)`
+        )
+      );
+    }
+  });
+
+  it("no component pads directly from env() — everything goes through --safe-*", () => {
+    // A bare env() is 0 in Android WebView for the system bars, which is the
+    // bug. app.css is the one legal place it may appear (inside the max()).
+    const offenders = [
+      "src/lib/components/BottomUi.svelte",
+      "src/routes/+layout.svelte",
+      "src/lib/components/player/VideoPlayer.svelte",
+      "src/lib/components/player/AudioPlayer.svelte",
+    ].filter((f) => read(f).includes("env(safe-area-inset"));
+
+    expect(offenders).toEqual([]);
+  });
+
+  it("the bottom UI reserves the bottom inset so the nav clears the gesture bar", () => {
+    expect(read("src/lib/components/BottomUi.svelte")).toMatch(/pb-\[var\(--safe-bottom\)\]/);
+  });
+
+  it("only the app shell measures itself against the viewport", () => {
+    // The shell is `h-screen` AND inset-padded, so its content box is
+    // `100vh - safe-top`. Any nested `h-screen`/`min-h-screen` is therefore
+    // taller than the space it was given and overflows by exactly the inset —
+    // the library column's `h-screen` clipped its own BottomUi that way. Nested
+    // full-height boxes must use `h-full`/`min-h-full` and inherit the shell's
+    // already-inset height.
+    const svelteFilesIn = (dir: string): string[] =>
+      readdirSync(resolve(process.cwd(), dir), { recursive: true, encoding: "utf8" })
+        .filter((f) => f.endsWith(".svelte"))
+        .map((f) => `${dir}/${f}`);
+
+    const offenders = [...svelteFilesIn("src/routes"), ...svelteFilesIn("src/lib/components")]
+      .filter((f) => f !== "src/routes/+layout.svelte")
+      .filter((f) => /class=[^>]*\bh-screen\b|class=[^>]*\bmin-h-screen\b/.test(read(f)));
+
+    expect(offenders).toEqual([]);
+  });
+});
@@ -0,0 +1,167 @@
+/**
+ * Safe-area (window inset) plumbing.
+ *
+ * TRACES: UR-066 | IR-031, DR-112
+ *
+ * ## Why this exists
+ *
+ * `MainActivity` calls `enableEdgeToEdge()`, and the app targets SDK 36 — from
+ * SDK 35 edge-to-edge is mandatory and from SDK 36 the opt-out is ignored — so
+ * the Tauri WebView always spans the **entire window**, underneath the status
+ * bar, the navigation/gesture bar and the display cutout.
+ *
+ * CSS cannot discover that on its own:
+ *
+ *  - `env(safe-area-inset-*)` resolves to `0px` unless the viewport declares
+ *    `viewport-fit=cover` (see `src/app.html`), and
+ *  - even then, Android WebView only maps the **display cutout** into
+ *    `env(safe-area-inset-*)`. The status bar and the navigation bar are never
+ *    reported. Unlike iOS Safari, there is no CSS-visible system-bar inset.
+ *
+ * So native reads the real `WindowInsets` (`systemBars() | displayCutout()`)
+ * and pushes them in as CSS custom properties; `src/app.css` folds them
+ * together with `env()` via `max()` so iOS/desktop keep working unchanged:
+ *
+ * ```css
+ * --safe-bottom: max(env(safe-area-inset-bottom, 0px), var(--jt-inset-bottom, 0px));
+ * ```
+ *
+ * Two delivery paths, because either alone is insufficient:
+ *
+ *  - **push** — `WindowInsetsBridge` evaluates JS into the WebView on every
+ *    inset change (rotation, nav-mode switch, PiP enter/exit). Needed because
+ *    insets change after load.
+ *  - **pull** — `initSafeArea()` reads `window.AndroidInsets.get()` at startup.
+ *    Needed because the first inset pass usually lands *before* the SvelteKit
+ *    document exists, and a page load wipes any inline style native had set.
+ */
+
+/** Window insets in CSS pixels, one per edge. */
+export interface SafeAreaInsets {
+  top: number;
+  right: number;
+  bottom: number;
+  left: number;
+}
+
+/** No insets — the desktop/dev default. */
+export const ZERO_INSETS: SafeAreaInsets = { top: 0, right: 0, bottom: 0, left: 0 };
+
+/** DOM event native fires after pushing a new set of insets. */
+export const INSETS_CHANGED_EVENT = "jellytau-insets-changed";
+
+const EDGES = ["top", "right", "bottom", "left"] as const;
+
+/** The native @JavascriptInterface installed by MainActivity (Android only). */
+interface AndroidInsetsBridge {
+  /** JSON `{top,right,bottom,left}` in CSS pixels. */
+  get(): string;
+}
+
+declare global {
+  interface Window {
+    AndroidInsets?: AndroidInsetsBridge;
+  }
+}
+
+/**
+ * Coerce one edge to a non-negative finite number.
+ *
+ * Anything else becomes 0 rather than propagating: a `NaN` would serialise to
+ * `"NaNpx"`, which invalidates the whole declaration and silently restores the
+ * original bug.
+ */
+function edge(value: unknown): number {
+  const n = typeof value === "string" ? Number(value) : value;
+  if (typeof n !== "number" || !Number.isFinite(n) || n < 0) return 0;
+  return n;
+}
+
+/**
+ * Parse a native inset payload (JSON string or already-decoded object).
+ * Returns `null` when the input is not an inset payload at all, so callers can
+ * distinguish "no insets reported" from "insets are all zero".
+ */
+export function parseNativeInsets(raw: unknown): SafeAreaInsets | null {
+  let value = raw;
+
+  if (typeof value === "string") {
+    try {
+      value = JSON.parse(value);
+    } catch {
+      return null;
+    }
+  }
+
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
+
+  const record = value as Record<string, unknown>;
+  if (!EDGES.some((e) => e in record)) return null;
+
+  return {
+    top: edge(record.top),
+    right: edge(record.right),
+    bottom: edge(record.bottom),
+    left: edge(record.left),
+  };
+}
+
+/** The CSS custom properties for a set of insets. */
+export function safeAreaCssVars(insets: SafeAreaInsets): Record<string, string> {
+  return Object.fromEntries(EDGES.map((e) => [`--jt-inset-${e}`, `${insets[e]}px`]));
+}
+
+/** Write the inset custom properties onto an element (normally `<html>`). */
+export function applySafeAreaInsets(target: HTMLElement, insets: SafeAreaInsets): void {
+  for (const [name, value] of Object.entries(safeAreaCssVars(insets))) {
+    target.style.setProperty(name, value);
+  }
+}
+
+/**
+ * Read the current insets from the native bridge, or `null` when there is none.
+ *
+ * Never throws. WebView can hand JS a *stale proxy* after a page load — the
+ * injected object stays truthy while its methods vanish (the exact failure that
+ * broke the background-audio toggle, see `MainActivity.configureWebViewForMedia`).
+ * Layout init must survive that.
+ */
+export function readNativeInsets(): SafeAreaInsets | null {
+  if (typeof window === "undefined") return null;
+
+  const bridge = window.AndroidInsets;
+  if (!bridge || typeof bridge.get !== "function") return null;
+
+  try {
+    return parseNativeInsets(bridge.get());
+  } catch (err) {
+    console.warn("[SafeArea] AndroidInsets bridge unusable:", err);
+    return null;
+  }
+}
+
+/**
+ * Prime the safe-area custom properties and keep them current.
+ *
+ * Call once, early in the root layout's `onMount` (synchronously — before any
+ * `await`, so the very first paint is already inset-correct). Returns a
+ * teardown that unsubscribes.
+ *
+ * With no native bridge this is a near no-op: it deliberately does NOT write
+ * `0px`, so the `env(safe-area-inset-*)` half of the `max()` still wins on iOS
+ * and desktop.
+ */
+export function initSafeArea(target?: HTMLElement): () => void {
+  if (typeof window === "undefined") return () => {};
+
+  const el = target ?? document.documentElement;
+
+  const sync = () => {
+    const insets = readNativeInsets();
+    if (insets) applySafeAreaInsets(el, insets);
+  };
+
+  sync();
+  window.addEventListener(INSETS_CHANGED_EVENT, sync);
+  return () => window.removeEventListener(INSETS_CHANGED_EVENT, sync);
+}
@@ -3,11 +3,14 @@ import {
  composeSearchGroups,
  DEFAULT_GROUP_ORDER,
  groupsForScope,
+  isSearchRoute,
  moveGroup,
  normalizeGroupOrder,
+  parseSearchScope,
  reorderGroups,
  resolveSearchScope,
  searchRouteUrl,
+  seedFromSearchUrl,
  shouldNavigateToSearch,
  type SearchGroupId,
 } from "./searchScope";
@@ -397,3 +400,66 @@ describe("shouldNavigateToSearch", () => {
    expect(shouldNavigateToSearch("/library/music", "  ")).toBe(false);
  });
 });
+
+describe("isSearchRoute", () => {
+  it("recognises the search surface through query strings and trailing slashes", () => {
+    expect(isSearchRoute("/search")).toBe(true);
+    expect(isSearchRoute("/search/")).toBe(true);
+    expect(isSearchRoute("/search?q=jazz&scope=music")).toBe(true);
+    expect(isSearchRoute("/library/music")).toBe(false);
+    expect(isSearchRoute("/")).toBe(false);
+  });
+});
+
+describe("parseSearchScope", () => {
+  it("accepts the known scopes", () => {
+    expect(parseSearchScope("music")).toBe("music");
+    expect(parseSearchScope("tv")).toBe("tv");
+  });
+
+  it("falls back on absent or unrecognised values", () => {
+    expect(parseSearchScope(null)).toBe("all");
+    expect(parseSearchScope("")).toBe("all");
+    expect(parseSearchScope("books")).toBe("all");
+    expect(parseSearchScope(null, "music")).toBe("music");
+  });
+});
+
+describe("seedFromSearchUrl", () => {
+  const params = (search: string) => new URL(`http://x/search${search}`).searchParams;
+
+  it("seeds a fresh page from the URL", () => {
+    expect(seedFromSearchUrl(params("?q=jazz&scope=music"), null)).toEqual({
+      query: "jazz",
+      scope: "music",
+    });
+  });
+
+  it("seeds an empty query so an emptied URL clears the page", () => {
+    expect(seedFromSearchUrl(params(""), null)).toEqual({ query: "", scope: "all" });
+    expect(seedFromSearchUrl(params(""), { query: "jazz", scope: "all" })).toEqual({
+      query: "",
+      scope: "all",
+    });
+  });
+
+  it("asks for nothing once that same URL has been applied", () => {
+    // The regression this exists for: the page must consume the URL once, not
+    // keep re-asserting it. While the seed is unchanged the user's typing and
+    // chip picks own the input — re-applying snapped it back a keystroke later.
+    const applied = { query: "jazz", scope: "music" } as const;
+    expect(seedFromSearchUrl(params("?q=jazz&scope=music"), applied)).toBeNull();
+  });
+
+  it("re-seeds when the query or the scope actually changes", () => {
+    const applied = { query: "jazz", scope: "music" } as const;
+    expect(seedFromSearchUrl(params("?q=blues&scope=music"), applied)).toEqual({
+      query: "blues",
+      scope: "music",
+    });
+    expect(seedFromSearchUrl(params("?q=jazz"), applied)).toEqual({
+      query: "jazz",
+      scope: "all",
+    });
+  });
+});
@@ -71,6 +71,16 @@ export function searchRouteUrl(query: string, scope: SearchScope): string {
  return `/search?${params.toString().replace(/\+/g, "%20")}`;
 }

+/** Normalise a pathname for comparison: drop query, hash and trailing slashes. */
+function normalizePath(pathname: string): string {
+  return pathname.split(/[?#]/)[0].replace(/\/+$/, "") || "/";
+}
+
+/** Whether `pathname` is the search surface itself. */
+export function isSearchRoute(pathname: string): boolean {
+  return normalizePath(pathname) === "/search";
+}
+
 /**
 * Whether a search typed on `pathname` must navigate to `/search` to be seen.
 *
@@ -82,8 +92,48 @@ export function searchRouteUrl(query: string, scope: SearchScope): string {
 */
 export function shouldNavigateToSearch(pathname: string, query: string): boolean {
  if (!query.trim()) return false;
-  const path = pathname.split(/[?#]/)[0].replace(/\/+$/, "") || "/";
-  return path !== "/search";
+  return !isSearchRoute(pathname);
+}
+
+/** Read a `?scope=` value, falling back when it is absent or unrecognised. */
+export function parseSearchScope(
+  raw: string | null | undefined,
+  fallback: SearchScope = "all"
+): SearchScope {
+  return SEARCH_SCOPES.includes(raw as SearchScope) ? (raw as SearchScope) : fallback;
+}
+
+/** The query + scope a `/search` URL asks the page to show. */
+export interface SearchSeed {
+  query: string;
+  scope: SearchScope;
+}
+
+/**
+ * What a `/search` URL should seed the page with, or `null` if it asks for
+ * nothing new.
+ *
+ * The URL is *consumed once per value*, not continuously reconciled against the
+ * live input. `applied` is the seed the caller last took from the URL: while it
+ * still matches, the user's own typing and chip picks govern, and only a real
+ * navigation (the header search sending a new query) re-seeds the page.
+ *
+ * Reconciling instead of consuming was the bug this replaced — the old effect
+ * compared the URL against `library.searchQuery`, so every keystroke's search
+ * re-ran it and snapped the input back to the query the header had sent.
+ *
+ * TRACES: UR-049 | DR-063, DR-064
+ */
+export function seedFromSearchUrl(
+  params: URLSearchParams,
+  applied: SearchSeed | null
+): SearchSeed | null {
+  const seed: SearchSeed = {
+    query: params.get("q") ?? "",
+    scope: parseSearchScope(params.get("scope")),
+  };
+  if (applied && applied.query === seed.query && applied.scope === seed.scope) return null;
+  return seed;
 }

 // ---------------------------------------------------------------------------
@@ -3,14 +3,17 @@
  import { get } from "svelte/store";
  import { page } from "$app/stores";
  import { platform } from "@tauri-apps/plugin-os";
+  import { listen, type UnlistenFn } from "@tauri-apps/api/event";
  import "../app.css";
+  import { commands } from "$lib/api/bindings";
  import { auth, needsReauth, isAuthenticated } from "$lib/stores/auth";
  import { connectivity, isConnected } from "$lib/stores/connectivity";
  import { initPlayerEvents, cleanupPlayerEvents } from "$lib/services/playerEvents";
  import { initWebviewAudio, cleanupWebviewAudio } from "$lib/services/webviewAudio";
  import { downloads, initDownloadEvents, cleanupDownloadEvents } from "$lib/stores/downloads";
  import { syncService } from "$lib/services/syncService";
-  import { onReconnected as onCatalogReconnected, syncCatalog, refreshSyncStatus, showServerCatalog, lastCatalogSync } from "$lib/services/offlineCatalog";
+  import { clearFavorite } from "$lib/stores/favorites";
+  import { onReconnected as onCatalogReconnected, refreshSyncStatus, showServerCatalog, lastCatalogSync } from "$lib/services/offlineCatalog";
  import { playbackMode } from "$lib/stores/playbackMode";
  import { sessions } from "$lib/stores/sessions";
  import ReauthModal from "$lib/components/auth/ReauthModal.svelte";
@@ -18,20 +21,30 @@
  import SleepTimerModal from "$lib/components/player/SleepTimerModal.svelte";
  import BottomUi from "$lib/components/BottomUi.svelte";
  import AppHeader from "$lib/components/AppHeader.svelte";
+  import PendingSyncModal from "$lib/components/sync/PendingSyncModal.svelte";
  import { isInitialized, pendingSyncCount, isAndroid, showSleepTimerModal } from "$lib/stores/appState";
  import {
    showBottomNav as computeShowBottomNav,
    showGlobalMiniPlayer as computeShowGlobalMiniPlayer,
    showGlobalHeader as computeShowGlobalHeader,
    routeOwnsLayout as computeRouteOwnsLayout,
+    shellReservesBottomInset,
  } from "$lib/utils/layoutShell";
  import { registerNavigationTracking } from "$lib/utils/navigation";
  import { startNetworkReporting } from "$lib/services/networkType";
+  import { initSafeArea } from "$lib/utils/safeArea";

  let { children } = $props();

+  /** Offline banner badge → the list of what is actually queued (DR-132). */
+  let showPendingSync = $state(false);
+
  /** Teardown for the network-transport reporter (WiFi-only gate). */
  let stopNetworkReporting: (() => void) | null = null;
+  let stopFavoritesListener: UnlistenFn | null = null;
+
+  /** Teardown for the native window-inset subscription (safe areas). */
+  let stopSafeArea: (() => void) | null = null;

  // Track in-app navigation depth so the header "back" affordance knows when a
  // real in-app Back exists (vs. a stale WebView stack after a background /
@@ -67,6 +80,14 @@
  // scroller, with the root's in-flow BottomUi as a flex sibling below it.
  const routeOwnsLayout = $derived(computeRouteOwnsLayout({ pathname }));

+  // Bottom safe-area inset (Android navigation/gesture bar): BottomUi reserves
+  // it wherever one renders, so the shell only takes it on routes that have no
+  // bottom UI at all (login, the full-screen player). Exactly one owner, or the
+  // bar is either ignored or double-padded. (UR-066)
+  const shellPadsBottom = $derived(
+    shellReservesBottomInset({ pathname, isAuthenticated: $isAuthenticated })
+  );
+
  onMount(async () => {
    // Detect platform first (synchronously, before any await) so the global
    // mini player's Android visibility gate is correct from the first render.
@@ -80,6 +101,13 @@
      console.error("Platform detection failed:", err);
    }

+    // Prime the safe-area custom properties from the native WindowInsets bridge
+    // BEFORE the first await, so the very first paint already clears the status
+    // bar and the navigation/gesture bar. Native also pushes updates directly,
+    // but a page load wipes the inline style it set, so this pull is required.
+    // No-op without the Android bridge. (UR-066)
+    stopSafeArea = initSafeArea();
+
    // Initialize auth state (restore session from secure storage)
    await auth.initialize();
    isInitialized.set(true);
@@ -95,6 +123,18 @@
    // Initialize download event listener
    await initDownloadEvents();

+    // Favourite state can change behind the UI: another Jellyfin client marks
+    // something, or the Rust drain pushes toggles queued while offline. Drop
+    // the session overrides for those ids so the next render reads the freshly
+    // cached server value rather than a stale local guess.
+    // TRACES: UR-069 | DR-120
+    stopFavoritesListener = await listen<{ itemIds: string[] }>(
+      "favorites-changed",
+      (event) => {
+        for (const id of event.payload?.itemIds ?? []) clearFavorite(id);
+      }
+    );
+
    // Report the network transport to the backend and keep it current, so the
    // WiFi-only download gate has real data to act on (UR-053). No-op on
    // desktop, where the backend defaults to unmetered.
@@ -114,10 +154,21 @@
    // Start sync service for offline mutation queue
    syncService.start();

-    // Kick off a best-effort full-catalog pre-sync so the whole server catalog
-    // is browsable (greyed out) offline, and load the last-sync hint for the
-    // offline banner. Non-blocking — no-ops when not connected.
-    void syncCatalog();
+    // Kick the queue once at startup. The Rust drain otherwise only runs on an
+    // offline→online transition, so a queue built up in a previous session sits
+    // untouched for a whole run of the app if the server was reachable the
+    // whole time. Safe when it isn't: an unreachable server leaves rows queued
+    // without spending their retry budget (DR-131).
+    if (get(auth).user?.id) {
+      commands.syncProcessPending().catch((err) =>
+        console.debug("[Layout] Startup sync drain skipped:", err)
+      );
+    }
+
+    // Load the last-sync hint for the offline banner. The catalog *index* is no
+    // longer kicked off from here: the Rust background indexer (DR-109) owns
+    // when to re-index, so a long session no longer searches a stale catalog and
+    // a restart no longer forces a full crawl regardless of freshness.
    void refreshSyncStatus();

    // Initialize playback mode and session monitoring
@@ -127,6 +178,9 @@

  onDestroy(() => {
    stopNetworkReporting?.();
+    stopFavoritesListener?.();
+    stopFavoritesListener = null;
+    stopSafeArea?.();
    cleanupPlayerEvents();
    cleanupWebviewAudio();
    cleanupDownloadEvents();
@@ -162,7 +216,9 @@
    }
  });

-  // Update pending sync count periodically
+  // Update pending sync count periodically, and immediately whenever the Rust
+  // drain (DR-131) reports it pushed or gave up on rows — otherwise the badge
+  // lags a reconnect by up to 10s and reads as if nothing happened.
  $effect(() => {
    if ($isAuthenticated) {
      const updateCount = async () => {
@@ -172,12 +228,36 @@
      updateCount();
      // Update every 10 seconds
      const interval = setInterval(updateCount, 10000);
-      return () => clearInterval(interval);
+      let unlistenDrain: UnlistenFn | null = null;
+      listen("sync-queue-changed", () => {
+        void updateCount();
+      })
+        .then((unlisten) => {
+          unlistenDrain = unlisten;
+        })
+        .catch((err) => console.debug("[Layout] sync-queue-changed listen failed:", err));
+
+      return () => {
+        clearInterval(interval);
+        unlistenDrain?.();
+      };
    }
  });
 </script>

-<div class="h-screen bg-[var(--color-background)] overflow-hidden flex flex-col">
+<!--
+  The app shell reserves the top/side safe-area insets (status bar, display
+  cutout) so no route has to. The bottom inset belongs to BottomUi wherever one
+  renders — see shellReservesBottomInset. `h-screen` is border-box, so the
+  padding is taken out of the 100vh rather than added to it.
+
+  TRACES: UR-066 | DR-112
+-->
+<div
+  class="h-screen bg-[var(--color-background)] overflow-hidden flex flex-col
+         pt-[var(--safe-top)] pl-[var(--safe-left)] pr-[var(--safe-right)]"
+  style:padding-bottom={shellPadsBottom ? "var(--safe-bottom)" : undefined}
+>
  {#if isInitialized}
    <!-- Offline indicator banner -->
    {#if $isAuthenticated && !$isConnected}
@@ -186,10 +266,19 @@
          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M18.364 5.636a9 9 0 010 12.728m0 0l-2.829-2.829m2.829 2.829L21 21M15.536 8.464a5 5 0 010 7.072m0 0l-2.829-2.829m-4.243 2.829a4.978 4.978 0 01-1.414-2.83m-1.414 5.658a9 9 0 01-2.167-9.238m7.824 2.167a1 1 0 111.414 1.414m-1.414-1.414L3 3m8.293 8.293l1.414 1.414" />
        </svg>
        <span>You're offline. Some features may be limited.</span>
+        <!-- The badge is answerable: it opens the queue it counts. Read as
+             "pending transfers" it used to send people to the Downloads page,
+             which lists a different table entirely and can never show these.
+             TRACES: UR-025 | DR-132 -->
        {#if $pendingSyncCount > 0}
-          <span class="bg-white/20 px-2 py-0.5 rounded-full text-xs">
-            {$pendingSyncCount} pending sync{$pendingSyncCount !== 1 ? 's' : ''}
-          </span>
+          <button
+            type="button"
+            onclick={() => (showPendingSync = true)}
+            class="bg-white/20 hover:bg-white/30 px-2 py-0.5 rounded-full text-xs transition-colors"
+            title="Changes waiting to reach the server"
+          >
+            {$pendingSyncCount} waiting to sync
+          </button>
        {/if}
        <button
          type="button"
@@ -248,8 +337,14 @@
      isOpen={$showSleepTimerModal}
      onClose={() => showSleepTimerModal.set(false)}
    />
+
+    <!-- What the offline banner's badge counts (DR-132) -->
+    <PendingSyncModal
+      isOpen={showPendingSync}
+      onClose={() => (showPendingSync = false)}
+    />
  {:else}
-    <div class="flex items-center justify-center h-screen">
+    <div class="flex items-center justify-center h-full">
      <div class="w-8 h-8 border-2 border-[var(--color-jellyfin)] border-t-transparent rounded-full animate-spin"></div>
    </div>
  {/if}
@@ -133,16 +133,21 @@
  const nextUpItems = $derived($home.nextUpItems);
  const latestItems = $derived($home.latestItems);
  const recentlyPlayedAudio = $derived($home.recentlyPlayedAudio);
+  // Favourite rows. Each is hidden when empty, so a fresh install shows none.
+  // TRACES: UR-067 | DR-118
+  const favoriteMovies = $derived($home.favoriteMovies);
+  const favoriteShows = $derived($home.favoriteShows);
+  const favoriteMusic = $derived($home.favoriteMusic);
  const resumeMovies = $derived($home.resumeMovies);
  const isLoading = $derived($home.isLoading);
 </script>

 {#if isLoading}
-  <div class="h-screen flex justify-center items-center">
+  <div class="h-full flex justify-center items-center">
    <div class="w-8 h-8 border-2 border-[var(--color-jellyfin)] border-t-transparent rounded-full animate-spin"></div>
  </div>
 {:else}
-  <div class="h-screen overflow-y-auto p-4 pb-16 md:pb-4 {isAndroid && $currentMedia && $currentMedia.type !== 'Movie' && $currentMedia.type !== 'Episode' ? 'pb-40' : ''}">
+  <div class="h-full overflow-y-auto p-4 pb-16 md:pb-4 {isAndroid && $currentMedia && $currentMedia.type !== 'Movie' && $currentMedia.type !== 'Episode' ? 'pb-40' : ''}">
    <div class="space-y-8">

    <!-- Hero Banner -->
@@ -218,6 +223,39 @@
      />
    {/if}

+    <!-- Favourites. Hidden entirely when a category has nothing in it —
+         empty rows on a fresh install read as broken. ux-flows §5C.2.
+         TRACES: UR-067 | DR-118 -->
+    {#if favoriteMovies.length > 0}
+      <Carousel
+        title="Favourite Movies"
+        items={favoriteMovies}
+        onItemClick={handleItemClick}
+        onItemLongPress={handleItemLongPress}
+        showAll={() => goto("/library/favorites?scope=movies")}
+      />
+    {/if}
+
+    {#if favoriteShows.length > 0}
+      <Carousel
+        title="Favourite Shows"
+        items={favoriteShows}
+        onItemClick={handleItemClick}
+        onItemLongPress={handleItemLongPress}
+        showAll={() => goto("/library/favorites?scope=tv")}
+      />
+    {/if}
+
+    {#if favoriteMusic.length > 0}
+      <Carousel
+        title="Favourite Music"
+        items={favoriteMusic}
+        onItemClick={handleItemClick}
+        onItemLongPress={handleItemLongPress}
+        showAll={() => goto("/library/favorites?scope=music")}
+      />
+    {/if}
+
    <!-- Quick Access -->
    <div class="pt-4 px-4">
      <button
@@ -1,17 +1,8 @@
 <script lang="ts">
  import { onMount, onDestroy, setContext } from "svelte";
  import { goto } from "$app/navigation";
-  import { page } from "$app/stores";
  import { isAuthenticated, isLoading as isAuthLoading } from "$lib/stores/auth";
-  import { library } from "$lib/stores/library";
  import { useScrollGuard } from "$lib/composables/useScrollGuard";
-  import Search from "$lib/components/Search.svelte";
-  import {
-    resolveSearchScope,
-    searchRouteUrl,
-    shouldNavigateToSearch,
-    type SearchScope,
-  } from "$lib/utils/searchScope";
  import AppHeader from "$lib/components/AppHeader.svelte";
  import BottomUi from "$lib/components/BottomUi.svelte";
  import SleepTimerModal from "$lib/components/player/SleepTimerModal.svelte";
@@ -22,7 +13,6 @@

  let { children } = $props();

-  let searchQuery = $state("");
  let showSleepTimerModal = $state(false);

  onMount(() => {
@@ -38,57 +28,18 @@
    }
  });

-  // The header search outlives navigation, so the route seeds the scope only
-  // while no search is active. Once the user has typed (or picked a chip),
-  // their scope governs until they clear the query — navigating must not snap
-  // a widened search back to the section they happen to be in.
-  // TRACES: UR-049 | DR-064
-  let searchScope = $state<SearchScope>(resolveSearchScope($page.url.pathname));
-
-  $effect(() => {
-    const pathname = $page.url.pathname;
-    if (!searchQuery.trim()) {
-      searchScope = resolveSearchScope(pathname);
-    }
-  });
-
-  // The header bar is a *navigator*, not a second results surface: /search is
-  // the only route that renders searchResults, so searching here routes there
-  // with the query + route-derived scope in the URL. Previously this ran
-  // library.search() in place, which was invisible on every /library/** page
-  // except /library itself.
-  // TRACES: UR-049 | DR-063
-  async function handleSearch(query: string) {
-    if (!query.trim()) {
-      library.clearSearch();
-      return;
-    }
-    if (shouldNavigateToSearch($page.url.pathname, query)) {
-      await goto(searchRouteUrl(query, searchScope));
-      // The query now lives in the URL; clear the header input so returning to
-      // a library page does not leave a stale term sitting in the box.
-      searchQuery = "";
-    }
-  }
+  // Search lives in AppHeader (see HeaderSearch.svelte) so the same bar renders
+  // here and on /search — this layout no longer owns any search state.
 </script>

 {#if $isAuthLoading}
-  <div class="min-h-screen flex items-center justify-center">
+  <div class="min-h-full flex items-center justify-center">
    <div class="w-8 h-8 border-2 border-[var(--color-jellyfin)] border-t-transparent rounded-full animate-spin"></div>
  </div>
 {:else if $isAuthenticated}
-  <div class="h-screen flex flex-col overflow-hidden">
-    <!-- Header (shared across all authenticated chrome; library supplies search) -->
-    <AppHeader search={librarySearch} />
-
-    {#snippet librarySearch()}
-      <!-- Scope chips live on /search, which owns the results. -->
-      <Search
-        bind:value={searchQuery}
-        placeholder="Search your library..."
-        onSearch={handleSearch}
-      />
-    {/snippet}
+  <div class="h-full flex flex-col overflow-hidden">
+    <!-- Header (shared across all authenticated chrome; it owns the search bar) -->
+    <AppHeader />

    <!-- Main content. The BottomUi below is an in-flow flex sibling, so this
         scroller is physically bounded above it and its last row can never
@@ -201,6 +201,20 @@
    <div>
      <div class="flex items-center justify-between mb-6">
        <h1 class="text-2xl font-bold text-white">Your Libraries</h1>
+        <div class="flex items-center gap-1">
+        <!-- Favourites cut across libraries, so they live beside the library
+             list rather than inside one. ux-flows §5C.2.
+             TRACES: UR-067 | DR-117 -->
+        <button
+          onclick={() => goto('/library/favorites')}
+          class="p-2 rounded-lg hover:bg-white/10 transition-colors text-gray-400 hover:text-white"
+          title="Favourites"
+          aria-label="Favourites"
+        >
+          <svg class="w-6 h-6" fill="none" stroke="currentColor" viewBox="0 0 24 24" stroke-width="2">
+            <path stroke-linecap="round" stroke-linejoin="round" d="M4.318 6.318a4.5 4.5 0 000 6.364L12 20.364l7.682-7.682a4.5 4.5 0 00-6.364-6.364L12 7.636l-1.318-1.318a4.5 4.5 0 00-6.364 0z" />
+          </svg>
+        </button>
        <button
          onclick={() => goto('/settings')}
          class="p-2 rounded-lg hover:bg-white/10 transition-colors text-gray-400 hover:text-white"
@@ -211,6 +225,7 @@
            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M15 12a3 3 0 11-6 0 3 3 0 016 0z" />
          </svg>
        </button>
+        </div>
      </div>

      {#if $isLibraryLoading}
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
dtourolle	1b70926c36	feat(offline): play downloaded video, and drain the offline sync queue (0.4.6) 🏗️ Build and Test JellyTau / Run Tests (push) Successful in 20m34s Details Publish Documentation / Build & publish docs to gitea-pages (push) Successful in 6m6s Details Traceability Validation / Check Requirement Traces (push) Successful in 18s Details Build & Release / Run Tests (push) Successful in 20m26s Details 🏗️ Build and Test JellyTau / Android Compile Check (push) Successful in 10m3s Details Build & Release / Build Linux (push) Successful in 37m59s Details Build & Release / Build Windows (push) Successful in 23m0s Details Build & Release / Build Android (push) Successful in 40m26s Details Build & Release / Create Release (push) Successful in 1m20s Details Bundles this session's work plus the concurrent search/offline/player changes. Every gate passes on the combined tree: 885 frontend tests, 610 Rust tests, clippy clean, boundary clean, trace coverage 86%. Offline video playback — four separate defects, each of which alone stopped it: DR-133 A completed download's file_path is already absolute (the worker rewrites it on completion), but the player rooted it a second time and handed the webview /data/user/0/app//data/user/0/app/videos/x.mp4. DR-134 The asset protocol was never enabled: no protocol-asset feature and no assetProtocol config, so convertFileSrc produced URLs nothing answered. Also silently defeated the cached-thumbnail path, which fails soft to the server copy and hid it whenever the server was reachable. DR-137 Tauri's asset protocol answers a range-less request by reading the whole file into memory, and only advertises Accept-Ranges from inside its range branch, so the first request never learns ranges exist. Chromium gave up with PIPELINE_ERROR_READ after ~31s. Local media is now served by a loopback HTTP server: bounded 4 MiB chunks streamed from the file handle, every response length-delimited, and a range-less request answered with one chunk rather than the file. Confined by a per-session token and to the app data directory, because loopback is shared between apps on Android. DR-138 Release builds set usesCleartextTraffic=false, so Android rejected the request to that server before any I/O. A network-security-config exempts 127.0.0.1 only; a remote server must still be HTTPS. Downloads: DR-135 download_item never records media_type and the reconnect resolver read that NULL as 'audio', so a movie queued from a media card had its URL resolved by get_audio_stream_url and completed as an audio-only transcode. The item's own type now decides. DR-136 Rows already downloaded that way are requeued on reconnect, since prevention alone leaves them reading "downloaded" and still unplayable. Known limitation: a download taken at `original` quality is a byte copy of the source, so it can be any container. One such file is an AVI holding XVID, which the webview cannot play in any case — the media server serves it correctly and Chromium refuses it. That needs either a transcoded download preset or the native ExoPlayer surface work, and is not addressed here. Also fixes two ID collisions between concurrent work: DR-143 defined twice (search vs offline gate) and UT-131 defined twice (Episode Focus hero vs channel cap). The search requirement is now DR-147 and the channel-cap test UT-141, with their code references and matrix rows updated.	2026-08-09 16:38:07 +02:00
dtourolle	7b531a40be	fix(player): pick a decodable track in the no-audio fallback (DR-146) When ExoPlayer selected no audio track, the recovery forced group 0 / track 0 unconditionally. But the most likely reason nothing was selected is that this very track cannot be decoded on this device, so the override reinstated the silence it was meant to fix. Scan the groups for the first isTrackSupported track and override to that. Also clear setTrackTypeDisabled(TRACK_TYPE_AUDIO), since audio may equally have been off at the type level, which an override alone does not undo. When no group holds a supported track, log it as an error — the server was expected to transcode — instead of leaving a silent video with no explanation in the log. Verified by compiling :app:compileArm64DebugKotlin. Not unit-tested: this tree has no Kotlin test source set, as noted in the previous commit.	2026-08-09 15:07:18 +02:00
dtourolle	19bc265a8d	fix(player): do not start a video before audio focus is granted (DR-145) Video manages audio focus by hand (handleAudioFocus=false, since ExoPlayer's automatic handling is reserved for the audio path), and all three outcomes of the request were treated as success. AUDIOFOCUS_ REQUEST_DELAYED — which setAcceptsDelayedFocusGain(true) explicitly invites, and which means the system is withholding our audio until it calls back — and an outright REQUEST_FAILED were logged and then followed by playWhenReady = true. The picture rolled with no sound, which to the user is indistinguishable from a broken stream. Hold playback when focus is not granted and start it from the AUDIOFOCUS_GAIN callback. An explicit play() re-requests focus instead of resuming into a stream the system is still muting, guarded by a held-focus flag so repeated plays do not leak focus requests. LOSS clears the pending flag so an unrelated later GAIN cannot start playback the user never asked for. Verified by compiling :app:compileArm64DebugKotlin. Not unit-tested: this tree has no Kotlin test source set (the Gradle project lives in the generated, gitignored gen/ tree), so the logic cannot be exercised off device without restructuring the Android build.	2026-08-09 15:06:49 +02:00
dtourolle	cc7f1cece0	fix(player): play downloaded video offline (DR-133, DR-134) Offline video never started: the <video> element reported NETWORK_NO_SOURCE one millisecond after loadstart, which the UI mislabelled as "may need transcoding" even though nothing had been fetched. Two independent causes, both required for playback. The path was doubled. `downloads.file_path` is stored relative to the storage root while a download is queued, but the worker rewrites it to the absolute path it actually wrote once the transfer completes — so a completed row is already rooted. The player's offline branch rooted it a second time, producing /data/user/0/app//data/user/0/app/videos/x.mp4. Audio was unaffected because it resolves the same column through Rust's resolve_local_media_path, which does not re-root. The join is now absolute-aware (POSIX, Windows drive letters, UNC) so rows written before completion still resolve. The asset protocol was never enabled. convertFileSrc rewrites a path to http://asset.localhost/… unconditionally, but Tauri only answers that origin when the protocol-asset cargo feature is compiled in and app.security.assetProtocol.enable is set — neither was, so even a correct path resolved to nothing. This also silently defeated the cached-thumbnail path in imageCache, which fails soft to the server copy and so hid the breakage whenever the server was reachable. Scoped to $APPDATA/** — the storage root holding the database, downloads/ and the thumbnail cache — rather than an unrestricted grant. Diagnosed from logcat on device; UT-124 reproduces the doubled path.	2026-08-09 15:05:16 +02:00
dtourolle	a53042fe80	fix(playback): bound the device profile by the audio route's channels (DR-141) MediaCodecList answers "can this device decode 5.1", which is not the question that decides whether the user hears anything: a phone decodes an AC-3 5.1 track happily and still has two channels to play it out of. The DeviceProfile carried no MaxAudioChannels, so Jellyfin was free to direct-play the multichannel track to a two-channel sink — silence or dialogue folded into surround channels that go nowhere, depending on the device. Report media3 AudioCapabilities.maxChannelCount for the current route over JNI alongside the codec lists, and bound the direct-play and transcoding profiles (and the HLS URL's TranscodingMaxAudioChannels, previously hardcoded to 2) by it. No codec is ever removed, so a device with genuine surround output keeps direct-playing it. A missing or zero reading means "route not yet established", not "no audio", and falls back to stereo.	2026-08-09 15:01:57 +02:00
dtourolle	db520c6551	fix(playback): stop pinning the video stream as the audio track (DR-140) Jellyfin's MediaStream.Index is global across every stream in a media source, so index 0 is the video stream on virtually all files. We sent AudioStreamIndex=0 as "the first audio track" on the HLS transcode URL, the background audio-only handoff URL, the direct-play fallback URL and the PlaybackInfo negotiation body — asking the server to use the video stream as audio. Servers that honour it produce a picture with no sound; only those that silently correct the index hid the bug, which is why it surfaced as "some videos have no audio". Omit the parameter unless a track was actually chosen, so the server resolves the source's DefaultAudioStreamIndex. An explicit selection from player_switch_audio_track still passes through unchanged. Dropped outright from the static=true direct-play URL, which serves the original file untouched.	2026-08-09 14:47:03 +02:00
dtourolle	1ef6180776	chore(release): bump to 0.4.1 🏗️ Build and Test JellyTau / Run Tests (push) Successful in 18m39s Details Publish Documentation / Build & publish docs to gitea-pages (push) Successful in 5m40s Details Traceability Validation / Check Requirement Traces (push) Successful in 16s Details Build & Release / Run Tests (push) Successful in 6m1s Details 🏗️ Build and Test JellyTau / Android Compile Check (push) Successful in 9m26s Details Build & Release / Build Linux (push) Successful in 19m41s Details Build & Release / Build Windows (push) Successful in 13m57s Details Build & Release / Build Android (push) Successful in 30m6s Details Build & Release / Create Release (push) Successful in 24s Details	2026-08-05 12:31:16 +02:00
dtourolle	878ac5fa59	fix(player): make lockscreen transport reach background audio (DR-097) Pausing from the lockscreen did nothing while a video's audio played in the background. The handoff starts native ExoPlayer audio and only then tears the WebView <video> down, and that teardown fires a DOM `pause` the frontend reports like any other — leaving html5_playing = Some(false). Transport therefore stayed aimed at the element: the lockscreen pause emitted a ControlCommand into a <video> that no longer existed while the native player carried on. The controller now tracks a background-audio handoff explicitly. Entering one hands transport authority to the native backend and drops the dying element's state/position/media-loaded reports, which also stop flipping the UI to paused and dragging the position backwards. Exiting restores the element as the player. A lockscreen pause also has to survive the return to the foreground: the video used to resume from a snapshot taken at handoff time, undoing the pause on the way back in. shouldResumeOnForeground() lets an explicit `paused` from the player override that snapshot. TRACES: UR-040, UR-005 \| DR-052, DR-097	2026-08-05 12:26:25 +02:00
dtourolle	6aaa80ff92	chore(release): bump to 0.4.0 🏗️ Build and Test JellyTau / Run Tests (push) Successful in 17m21s Details Publish Documentation / Build & publish docs to gitea-pages (push) Successful in 5m46s Details Traceability Validation / Check Requirement Traces (push) Successful in 16s Details Build & Release / Run Tests (push) Successful in 5m38s Details 🏗️ Build and Test JellyTau / Android Compile Check (push) Successful in 8m54s Details Build & Release / Build Linux (push) Successful in 19m22s Details Build & Release / Build Windows (push) Successful in 13m55s Details Build & Release / Build Android (push) Successful in 30m12s Details Build & Release / Create Release (push) Successful in 15s Details	2026-08-04 20:22:01 +02:00
dtourolle	f7bcfe521d	fix(favorites): save server favourites through to the cache (DR-115) The hybrid favourites read went straight to the online repository on a cache miss and dropped the result on the floor. Every other read path persists what it fetches, so this one made the favourites page re-query the server on every visit — and left the offline mirror (DR-114) empty on a fresh install, since this is the path that fills it. It now goes through get_favorites_server_only, which saves through on the way back. The command had a matching hole: with nothing cached it returned the empty result, painting "Nothing favourited yet" at a viewer whose favourites were simply marked on another client. It now asks the repository for a real answer instead of an empty state it would correct a round trip later. TRACES: UR-067 \| DR-115	2026-08-04 20:20:36 +02:00
dtourolle	30dc3ba7f6	fix(player): recover a failed stream on Linux instead of stopping (DR-130) A recoverable player error meant "playback is over": the frontend's error handler stopped the player unconditionally, so a wifi blip killed the track. Android already decides in its JNI callback, but MpvBackend is constructed before PlayerController exists, so its event thread has no controller to ask. So MPV reports the failure and the frontend echoes it into the new player_recover_stream command — the same shape as PlaybackEnded -> player_on_playback_ended, keeping the decision in Rust. The command re-opens the stream where it stopped, with the existing attempt budget and backoff, and returns whether it handled it; only a false answer falls through to the old stop path. Android now reports the errors it has already declined as unrecoverable, so the echo never asks the same question twice. TRACES: UR-004, UR-040 \| DR-130 \| UT-117	2026-08-04 20:15:28 +02:00
dtourolle	32f8de5c91	fix(player): survive a flaky stream, and don't read 0:00 at EOF Two MPV-side fixes for the same failure story — a wifi blip during playback. The demuxer gave up the moment a read failed and MPV raised EndFile(ERROR), so a momentary outage killed the track outright. Enabling ffmpeg's reconnect options handles the common case entirely below our level, so most outages never reach the recovery path at all. Set non-fatally: their availability varies with the libmpv/ffmpeg build, and losing resilience is not a reason to refuse to play anything. Separately, `time-pos` and `duration` are live properties of the loaded file: at EOF MPV unloads it and both stop resolving. Reading them straight through returned 0.0/unknown at exactly the moment end-of-file handling needed to know where playback had reached, so the player appeared to rewind to 0:00 as a track ended. `ObservedTime` records the last reading seen while media was loaded and the accessors fall back to it.	2026-08-04 19:39:14 +02:00
dtourolle	62873cab3d	feat(search): answer search from a local index; tier downloads by lifetime Search's instant leg read only downloaded items, so with no downloads it returned nothing and every keystroke fell through to a full Recursive=true server query. It now reads the whole synced catalog through the same availability CTE get_items uses, gated on the same include_catalog_browse flag so search and browse cannot diverge. (UR-065, DR-108) Also fixes three defects found while confirming that: - items_fts grew by a full duplicate index every catalog pass. INSERT OR REPLACE fires no AFTER DELETE trigger without recursive_triggers, so the old index row was orphaned, and a TEXT PRIMARY KEY meant the replacement took a fresh rowid and inserted a second entry. Now a real upsert, with migration 021 rebuilding existing indexes. (DR-110) - DELETE FROM items existed nowhere, so server-side deletions never propagated. Adds a post-crawl mark-and-sweep, scoped to crawled types, skipping downloaded items, and refusing to run after a partial crawl because items.parent_id cascades. (DR-110) - The index omitted MusicArtist, Playlist and People, which search groups results by. Adds them plus people_fts (migration 022). (DR-111) Re-indexing moves from a frontend startup call to a Rust background task with a 6h TTL, so a long session no longer searches a stale catalog and a restart no longer forces a crawl regardless of freshness. (DR-109, IR-030) Downloads gain a lifetime tier. Eviction selected every completed row by age with no download_source filter, so hitting the storage limit deleted the oldest download -- typically one saved deliberately for offline -- to make room for a precached track. It now reclaims only 'auto' rows, and expired ones are reclaimed first, before live cache is evicted. (DR-126, DR-127) Downloaded video and audio-only handoffs now play from disk instead of streaming; the video path had never consulted downloads at all. No transcode is involved: MPV runs video=no and ExoPlayer has no surface for an Audio item. (DR-123 in part, DR-128) FTS queries are built as quoted phrases so apostrophes, hyphens and slashes are data rather than operator syntax, and the item-type filter is bound rather than interpolated. Specs: docs/specs/catalog-index-search.md, docs/specs/read-through-media-cache.md Includes concurrently-developed favourites browsing and background-audio stream-end handling; the two workstreams share offline.rs, lib.rs and online.rs, so no subset of files builds independently.	2026-08-04 17:35:17 +02:00
dtourolle	c55ff45692	fix(android): clear the system bars and display cutout (UR-066) The bottom nav rendered under the Android navigation bar, and full-screen playback controls spilled into unusable screen edges. It looked device-specific (Motorola bad, Fairphone fine) but every device was equally unpadded — only the intrusion differed: a tall opaque 3-button bar swallows the nav, a thin translucent gesture pill overlaps harmlessly. None of the app's safe-area handling was ever active, for two independent reasons: 1. app.html had no `viewport-fit=cover`, so every `env(safe-area-inset-)` resolved to 0px — the padding in app.css and BottomUi was a no-op. 2. Android WebView maps only the display cutout* into `env()`; the status bar and navigation bar are never reported. With enableEdgeToEdge() and targetSdk 36 (enforced from 35, opt-out ignored from 36) the WebView always spans them, so CSS could not learn about them by any route. WindowInsetsBridge now reads `systemBars() \| displayCutout()` and publishes `--jt-inset-` CSS custom properties, both pushed on every inset change (rotation, nav-mode switch, PiP) and pullable via `AndroidInsets.get()` — the pull is required because the first inset pass lands before the document exists and a page load wipes the pushed inline style. app.css folds them with `env()` via `max()` into `--safe-`, the only thing components may pad from. Exactly one element owns each edge: the shell takes top/left/right, BottomUi takes bottom (inside its surface box, so the colour extends behind the gesture bar), and shellReservesBottomInset hands bottom back to the shell on routes with no bottom UI. The full-screen players inset their control layers only, leaving video and artwork edge-to-edge. The theme's `fitsSystemWindows=true` claimed the opposite of what actually happened — overridden at runtime, ignored at this target SDK — and is removed. Also converts six nested `h-screen`/`min-h-screen` boxes to `h-full`: the shell is `h-screen` and inset-padded, so its content box is `100vh - safe-top` and any nested 100vh box overflows by exactly the inset (the library column would have clipped its own BottomUi). A test guards against reintroduction.	2026-08-04 14:45:10 +02:00